svn commit: r1734842 - /openwebbeans/cms-site/trunk/content/owbconfig.mdtext

[st...@apache.org]

Author: struberg
Date: Sun Mar 13 19:20:35 2016
New Revision: 1734842

URL: http://svn.apache.org/viewvc?rev=1734842&view=rev
Log:
add allowProxying and proxy mapping documentation

Modified:
    openwebbeans/cms-site/trunk/content/owbconfig.mdtext

Modified: openwebbeans/cms-site/trunk/content/owbconfig.mdtext
URL: http://svn.apache.org/viewvc/openwebbeans/cms-site/trunk/content/owbconfig.mdtext?rev=1734842&r1=1734841&r2=1734842&view=diff
==============================================================================
--- openwebbeans/cms-site/trunk/content/owbconfig.mdtext (original)
+++ openwebbeans/cms-site/trunk/content/owbconfig.mdtext Sun Mar 13 19:20:35 2016
@@ -141,15 +141,58 @@ Boolean values can either be <code>true<
             cannot properly handle Java8 (mostly due to older Eclipse JDT versions).
         </p>
     </li>
+    <li style="border-bottom: dashed; border-width: 1px">
+        <p><code>javax.enterprise.inject.allowProxying.classes</code></p>
+        <p>
+            Environment property which comma separated list of classes which
+            should NOT fail with an UnproxyableResolutionException.
+            You only have to configure additional classes in your openwebbeans.properties file.
+            All the configured values get added together into a big List.
+        </p>
+        <p>By default we allow the following classes: <code>java.util.HashMap</code> and <code>java.util.Calendar</code>
+        </p>
+    </li>
 </ul>
 
 
 ## Proxy Mapping
 
 OpenWebBeans enables the user to define the NormalScope handlers for specific scopes.
-This allows for more aggressive caching than with the generic ``NormalScopedBeanInterceptorHandler``.
-
-TODO
+This allows for more aggressive caching than with the generic ``NormalScopedBeanInterceptorHandler`` which is the default.
+The default NormalScope handler will look up the Contextual Instance in the respective Context for each and every
+method invocation on the proxy.
+
+But sometimes we can much more aggressively cache the instances.
+
+E.g. for ``@ApplicationScoped`` beans we can keep
+the contextual instance inside the proxy, making it as fast as a pure Java instance - but still gaining
+all the benefits of CDI!
+
+For ``@RequestScoped`` and ``@SessionScoped`` we can use a NormalScope handler which caches the Contextual Instance
+in a ThreadLocal.
+
+By default the following NormalScope handlers get used:
+<pre>
+org.apache.webbeans.proxy.mapping.javax.enterprise.context.ApplicationScoped
+    =org.apache.webbeans.intercept.ApplicationScopedBeanInterceptorHandler
+org.apache.webbeans.proxy.mapping.javax.enterprise.context.RequestScoped
+    =org.apache.webbeans.intercept.RequestScopedBeanInterceptorHandler
+org.apache.webbeans.proxy.mapping.javax.enterprise.context.SessionScoped
+    =org.apache.webbeans.intercept.SessionScopedBeanInterceptorHandler
+</pre>
+
+As you can see we use a prefix ``org.apache.webbeans.proxy.mapping.`` followed by the fully qualified
+scope name as key. The value represents the fully qualified name of the handler class. This class must extend
+``org.apache.webbeans.intercept.NormalScopedBeanInterceptorHandler`` and implement the
+``Object getContextualInstance()`` method.
+
+If you have a custom scope which spans a Request or longer then you can simply reuse the
+``RequestScopedBeanInterceptorHandler`` as shown in the following example:
+
+<pre>
+org.apache.webbeans.proxy.mapping.org.apache.deltaspike.core.api.scope.ViewAccessScoped
+    =org.apache.webbeans.intercept.RequestScopedBeanInterceptorHandler
+</pre>
 
 ##Enable FailOver / Session Replication support