svn commit: r1582603 - /olingo/site/trunk/content/doc/tutorials/debug.mdtext

[mi...@apache.org]

Author: mibo
Date: Fri Mar 28 05:37:46 2014
New Revision: 1582603

URL: http://svn.apache.org/r1582603
Log:
Add custom debug documentation

Modified:
    olingo/site/trunk/content/doc/tutorials/debug.mdtext

Modified: olingo/site/trunk/content/doc/tutorials/debug.mdtext
URL: http://svn.apache.org/viewvc/olingo/site/trunk/content/doc/tutorials/debug.mdtext?rev=1582603&r1=1582602&r2=1582603&view=diff
==============================================================================
--- olingo/site/trunk/content/doc/tutorials/debug.mdtext (original)
+++ olingo/site/trunk/content/doc/tutorials/debug.mdtext Fri Mar 28 05:37:46 2014
@@ -51,7 +51,7 @@ The debug feature can be enabled by the 
 
 In your service factory (`ODataServiceFactory`) implement the following method to register the callback:
 
-
+	:::java
 	public <T extends ODataCallback> T getCallback(final Class<? extends ODataCallback> callbackInterface) { 
 	  T callback
 	
@@ -68,6 +68,8 @@ If this is in place then the url query o
 
 ##### Query for Debug Information
 
+** JSON Debug View**
+
 Request url: http://localhost:8080/olingo-odata2-ref-web/ReferenceScenario.svc/?odata-debug=json
 
 Response:
@@ -123,6 +125,65 @@ Response:
 	    }]
 	}
 
+** HTML Debug View**
+
+Request url: http://localhost:8080/olingo-odata2-ref-web-incubating/ReferenceScenario.svc/?odata-debug=html
+to get a self-contained HTML document with all information that is in the JSON
+output but can be viewed conveniently in a browser.
+
+#### Custom Debug Output
+
+Starting with release 1.2, it is possible to create custom debug output.
+The complete formatting of the debug-support information can be implemented
+in a callback method.
+
+Add to the already existing `getCallback` method before the line with `else` a condition check whether the given `ODataCallback` is a `DebugWrapperCallback`.
+
+	:::java
+	} else if (callbackInterface.isAssignableFrom(ODataDebugResponseWrapperCallback.class)) {
+	  callback = (T) new DebugWrapperCallback();
+	}
+
+which then results in following method
+
+	:::java
+	public <T extends ODataCallback> T getCallback(final Class<? extends ODataCallback> callbackInterface) { 
+	  T callback
+	
+	  if (callbackInterface.isAssignableFrom(MyDebugCallback.class)) {
+	    callback = (T) new MyDebugCallback();
+	  } else if (callbackInterface.isAssignableFrom(ODataDebugResponseWrapperCallback.class)) {
+	    callback = (T) new DebugWrapperCallback();
+	  } else {
+	    callback = (T) super.getCallback(callbackInterface);
+	  }
+	
+	  return callback;
+	}
+
+
+and implement the callback class
+
+	:::java
+	private final class DebugWrapperCallback implements ODataDebugResponseWrapperCallback {
+	  @Override
+	  public ODataResponse handle(final ODataContext context, final ODataRequest request, final ODataResponse response,
+	      final UriInfo uriInfo, final Exception exception) {
+	    if ("true".equals(request.getQueryParameters().get("my-debug"))) {
+	      return DebugResponseWrapper.handle(context, request, response, uriInfo, exception);
+	    } else {
+	      return response;
+	    }
+	  }
+	}
+
+
+where `DebugResponseWrapper` is a class you have to implement which does
+the real work.
+
+**Please note** that this callback is not called if the built-in debug output
+is requested as described above.
+
 ### Log and Trace Support
 
 Apache Olingo has no dependencies to any specific log and trace api (e.g. slf4j, log4j …) and with that it does not trace anything by default. This is to keep the library independent from a specific api so that it can be used on any JEE compliant platform independent from which l&t api is offered there.
@@ -167,4 +228,5 @@ Register Callback:
 	  }
 	
 	  return callback;
-	}
\ No newline at end of file
+	}
+