svn commit: r885722 - in /websites/staging/olingo/trunk/content: ./ doc/tutorials/debug.html

[bu...@apache.org]

Author: buildbot
Date: Thu Nov  7 10:01:51 2013
New Revision: 885722

Log:
Staging update by buildbot for olingo

Modified:
    websites/staging/olingo/trunk/content/   (props changed)
    websites/staging/olingo/trunk/content/doc/tutorials/debug.html

Propchange: websites/staging/olingo/trunk/content/
------------------------------------------------------------------------------
--- cms:source-revision (original)
+++ cms:source-revision Thu Nov  7 10:01:51 2013
@@ -1 +1 @@
-1539572
+1539578

Modified: websites/staging/olingo/trunk/content/doc/tutorials/debug.html
==============================================================================
--- websites/staging/olingo/trunk/content/doc/tutorials/debug.html (original)
+++ websites/staging/olingo/trunk/content/doc/tutorials/debug.html Thu Nov  7 10:01:51 2013
@@ -82,7 +82,7 @@
 <p>For productive uses cases this feature is by default off. The following explains how to enable the feature and gives options to an service implementation to switch if on and off e.g. role based or by configuration.</p>
 <h5 id="debugcallback">DebugCallback</h5>
 <p>The debug feature can be enabled by the following callback implementation:</p>
-<div class="codehilite"><pre><span class="n">public</span> <span class="n">class</span> <span class="n">ScenarioDebugCallback</span> <span class="n">implements</span> <span class="n">ODataDebugCallback</span> <span class="p">{</span>
+<div class="codehilite"><pre><span class="n">public</span> <span class="n">class</span> <span class="n">MyDebugCallback</span> <span class="n">implements</span> <span class="n">ODataDebugCallback</span> <span class="p">{</span>
   <span class="p">@</span><span class="n">Override</span>
   <span class="n">public</span> <span class="n">boolean</span> <span class="n">isDebugEnabled</span><span class="p">()</span> <span class="p">{</span>  
     <span class="n">boolean</span> <span class="n">isDebug</span> <span class="p">=</span> …<span class="p">;</span> <span class="o">//</span> <span class="n">true</span><span class="o">|</span><span class="n">configuration</span><span class="o">|</span><span class="n">user</span> <span class="n">role</span> <span class="n">check</span>
@@ -92,12 +92,13 @@
 </pre></div>
 
 
+<h5 id="register-debugcallback">Register DebugCallback</h5>
 <p>In your service factory (<code>ODataServiceFactory</code>) implement the following method to register the callback:</p>
 <div class="codehilite"><pre><span class="kr">public</span> <span class="o">&lt;</span><span class="nx">T</span> <span class="kr">extends</span> <span class="nx">ODataCallback</span><span class="o">&gt;</span> <span class="nx">T</span> <span class="nx">getCallback</span><span class="p">(</span><span class="kr">final</span> <span class="nx">Class</span><span class="cp">&lt;?</span> <span class="k">extends</span> <span class="nx">ODataCallback</span><span class="o">&gt;</span> <span class="nx">callbackInterface</span><span class="p">)</span> <span class="p">{</span> 
   <span class="nx">T</span> <span class="nx">callback</span>
 
-  <span class="k">if</span> <span class="p">(</span><span class="nx">callbackInterface</span><span class="o">.</span><span class="nx">isAssignableFrom</span><span class="p">(</span><span class="nx">ScenarioErrorCallback</span><span class="o">.</span><span class="nx">class</span><span class="p">))</span> <span class="p">{</span>
-    <span class="nx">callback</span> <span class="o">=</span> <span class="p">(</span><span class="nx">T</span><span class="p">)</span> <span class="k">new</span> <span class="nx">ScenarioErrorCallback</span><span class="p">();</span>
+  <span class="k">if</span> <span class="p">(</span><span class="nx">callbackInterface</span><span class="o">.</span><span class="nx">isAssignableFrom</span><span class="p">(</span><span class="nx">MyDebugCallback</span><span class="o">.</span><span class="nx">class</span><span class="p">))</span> <span class="p">{</span>
+    <span class="nx">callback</span> <span class="o">=</span> <span class="p">(</span><span class="nx">T</span><span class="p">)</span> <span class="k">new</span> <span class="nx">MyDebugCallback</span><span class="p">();</span>
   <span class="p">}</span> <span class="k">else</span> <span class="p">{</span>
     <span class="nx">callback</span> <span class="o">=</span> <span class="p">(</span><span class="nx">T</span><span class="p">)</span> <span class="nx">super</span><span class="o">.</span><span class="nx">getCallback</span><span class="p">(</span><span class="nx">callbackInterface</span><span class="p">);</span>
   <span class="p">}</span>
@@ -108,7 +109,7 @@
 
 
 <p>If this is in place then the url query option odata-debug=json will return detailed error information in json format for each request.</p>
-<h5 id="example">Example</h5>
+<h5 id="query-for-debug-information">Query for Debug Information</h5>
 <p>Request url: http://localhost:8080/com.sap.olingo.web/ReferenceScenario.svc/?odata-debug=json</p>
 <p>Response:</p>
 <div class="codehilite"><pre>{
@@ -165,6 +166,40 @@
 
 
 <h3 id="log-and-trace-support">Log and Trace Support</h3>
+<p>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 complient platform independent from which l&amp;t api is offered there.</p>
+<p>Anyhow log and trace is requiered for productive use and the following recommendations are given:</p>
+<h5 id="servlet-filter">Servlet Filter</h5>
+<p>For tracing the http traffic (request url, query paramteter, http headers, response code …) to and from the server it is recommended to implement a servlet filter on top of the service. This is completely independent from the Apache Olingo OData library and has no restrictions.</p>
+<h5 id="service-processore-implementation">Service Processore Implementation</h5>
+<p>To trace OData actvities (read/write activities) at the server it is recommended to do that within a custom processor implementation. </p>
+<h5 id="error-callback">Error Callback</h5>
+<p>Because of OData requires to handle error situations someone can hook into the handling and trace information there.  </p>
+<p>Simply implement another <code>ODataCallback</code> interface and register it within a <code>ODataServiceFactory</code>.</p>
+<p>Callback:</p>
+<div class="codehilite"><pre><span class="n">public</span> <span class="n">class</span> <span class="n">MyErrorCallback</span> <span class="n">implements</span> <span class="n">ODataErrorCallback</span> <span class="p">{</span>
+  <span class="p">@</span><span class="n">Override</span>
+  <span class="n">public</span> <span class="n">ODataResponse</span> <span class="n">handleError</span><span class="p">(</span><span class="n">ODataErrorContext</span> <span class="n">context</span><span class="p">)</span> <span class="n">throws</span> <span class="n">ODataApplicationException</span> <span class="p">{</span> 
+    <span class="n">LOGGER</span><span class="p">.</span><span class="n">severe</span><span class="p">(</span><span class="n">context</span><span class="p">.</span><span class="n">getException</span><span class="p">().</span><span class="n">getClass</span><span class="p">().</span><span class="n">getName</span><span class="p">()</span> <span class="o">+</span> &quot;<span class="p">:</span>&quot; <span class="o">+</span> <span class="n">context</span><span class="p">.</span><span class="n">getMessage</span><span class="p">());</span> <span class="k">return</span> <span class="n">EntityProvider</span><span class="p">.</span><span class="n">writeErrorDocument</span><span class="p">(</span><span class="n">context</span><span class="p">);</span> 
+    <span class="p">}</span>
+<span class="p">}</span>
+</pre></div>
+
+
+<p>Register Callback:</p>
+<div class="codehilite"><pre><span class="kr">public</span> <span class="o">&lt;</span><span class="nx">T</span> <span class="kr">extends</span> <span class="nx">ODataCallback</span><span class="o">&gt;</span> <span class="nx">T</span> <span class="nx">getCallback</span><span class="p">(</span><span class="kr">final</span> <span class="nx">Class</span><span class="cp">&lt;?</span> <span class="k">extends</span> <span class="nx">ODataCallback</span><span class="o">&gt;</span> <span class="nx">callbackInterface</span><span class="p">)</span> <span class="p">{</span> 
+  <span class="nx">T</span> <span class="nx">callback</span>
+
+  <span class="k">if</span> <span class="p">(</span><span class="nx">callbackInterface</span><span class="o">.</span><span class="nx">isAssignableFrom</span><span class="p">(</span><span class="nx">MyDebugCallback</span><span class="o">.</span><span class="nx">class</span><span class="p">))</span> <span class="p">{</span>
+    <span class="nx">callback</span> <span class="o">=</span> <span class="p">(</span><span class="nx">T</span><span class="p">)</span> <span class="k">new</span> <span class="nx">MyDebugCallback</span><span class="p">();</span>
+  <span class="p">}</span> <span class="k">else</span> <span class="k">if</span> <span class="p">(</span><span class="nx">callbackInterface</span><span class="o">.</span><span class="nx">isAssignableFrom</span><span class="p">(</span><span class="nx">MyErrorCallback</span><span class="o">.</span><span class="nx">class</span><span class="p">))</span> <span class="p">{</span>
+    <span class="nx">callback</span> <span class="o">=</span> <span class="p">(</span><span class="nx">T</span><span class="p">)</span> <span class="k">new</span> <span class="nx">MyErrorCallback</span><span class="p">();</span>
+  <span class="p">}</span> <span class="k">else</span> <span class="p">{</span>
+    <span class="nx">callback</span> <span class="o">=</span> <span class="p">(</span><span class="nx">T</span><span class="p">)</span> <span class="nx">super</span><span class="o">.</span><span class="nx">getCallback</span><span class="p">(</span><span class="nx">callbackInterface</span><span class="p">);</span>
+  <span class="p">}</span>
+
+  <span class="k">return</span> <span class="nx">callback</span><span class="p">;</span>
+<span class="p">}</span>
+</pre></div>