User: stark
Date: 01/01/29 22:58:33
Modified: documentation contconf_howto.html
Log:
Added a simple howto on inserting a log interceptor into the front of
the interceptor stack of the CMP Entity container.
Updated the configurable elements section to include the current elements.
Revision Changes Path
1.2 +94 -3 newsite/documentation/contconf_howto.html
Index: contconf_howto.html
===================================================================
RCS file: /products/cvs/ejboss/newsite/documentation/contconf_howto.html,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- contconf_howto.html 2000/11/12 20:33:28 1.1
+++ contconf_howto.html 2001/01/30 06:58:33 1.2
@@ -17,6 +17,7 @@
<li><A href="#jdk12Conf">How do I configure my bean for jdk1.2.2 clients?</a>
<li><A href="#CustConf">How do I specify my own custom configuration ?</a>
<li><A href="#CacheConf">How do I specify advanced cache configuration ?</a>
+<li><A href="#InterceptorConf">How do I specify the interceptor stack configuration
?</a>
<li><A href="#WhatConf">What can be configured ?</a></li>
</ul>
<p> <p>
@@ -27,6 +28,7 @@
<li>Standard BMP EntityBean
<li>Standard Stateless SessionBean
<li>Standard Stateful SessionBean
+<li>Standard Message Driven Bean
<li>jdk1.2.2 CMP EntityBean
<li>jdk1.2.2 BMP EntityBean
<li>jdk1.2.2 Stateless SessionBean
@@ -178,19 +180,108 @@
How much is the cache enlarged / shrinked ? Here is where the load-factor comes in
the picture. When the resizer shrinks, it tries to shrink the cache so that (in this
case) the ratio number of beans / cache capacity is 0.75; when the resizer enlarges,
it tries to enlarge the cache by a factor 1 / 0.75 == 1.333 (in the above case) plus a
correction calculated from the cache miss rate (so that the more cache miss rate you
have, the more the cache is enlarged, starting from at least 1.333; so if you really
have a lot of cache misses, the resizer may decide to enlarge the cache of a factor
2.0 instead of 1.333 - if there is room for that).<br>
<br>
+<li><A name="InterceptorConf"></a><b>How do I specify the interceptor stack
configuration ?</b>
+<p>
+The container method dispatch in JBoss is implimented by the stack of
org.jboss.ejb.Interceptor
+instances that are associated with a container. The Interceptor interface is:
+<pre>
+public interface Interceptor extends ContainerPlugin
+{
+ public void setNext(Interceptor interceptor);
+ public Interceptor getNext();
+ public Object invokeHome(MethodInvocation mi) throws Exception;
+ public Object invoke(MethodInvocation mi) throws Exception;
+}
+</pre>
+The interceptors in the default container configurations perform tasks such as
logging,
+security, statistics gathering, transaction support, etc. Configuration of a
containers
+interceptor stack is generally only done by "kernel container hackers" as
misconfiguration
+of the interceptor stack can completely break the container. Several examples of
+interceptors can be found in the org.jboss.ejb.plugins package.
+</p>
+
+<p>
+With that warning heeded, let's look at how you can insert your own custom logging
+interceptor at the front of a CMP entity bean. Start by creating your application
+jboss.xml file bye copying the container-configuration element from the
standardjboss.xml
+config file that has the Standard CMP EntityBean container-name and then remove
+everything but the container-name and container-interceptors elements. Place this
+element under a container-configurations element. You should have a file that
+looks like:
+
+<table border=0 bgcolor="#80ff80" cellspacing=4><tr><td>
+<pre>
+<jboss>
+ <container-configurations>
+ <container-configuration>
+ <container-name>Standard CMP EntityBean</container-name>
+ <container-interceptors>
+
<interceptor>org.jboss.ejb.plugins.LogInterceptor</interceptor>
+
<interceptor>org.jboss.ejb.plugins.SecurityInterceptor</interceptor>
+
<interceptor>org.jboss.ejb.plugins.TxInterceptorCMT</interceptor>
+ <interceptor
metricsEnabled="true">org.jboss.ejb.plugins.MetricsInterceptor</interceptor>
+
<interceptor>org.jboss.ejb.plugins.EntityInstanceInterceptor</interceptor>
+
<interceptor>org.jboss.ejb.plugins.EntitySynchronizationInterceptor</interceptor>
+ </container-interceptors>
+ </container-configuration>
+ </container-configurations>
+</jboss>
+</pre>
+</table>
+
+Supposing you have created a com.dot.logging.LogInterceptor that implements the
+org.jboss.ejb.Interceptor interface. You can insert this interceptor at the front of
+the interceptor chain by adding an interceptor element to the configuration:
+
+<table border=0 bgcolor="#80ff80" cellspacing=4><tr><td>
+<pre>
+<jboss>
+ <container-configurations>
+ <container-configuration>
+ <container-name>Standard CMP EntityBean</container-name>
+ <container-interceptors>
+
<interceptor>com.dot.logging.LogInterceptor</interceptor>
+
<interceptor>org.jboss.ejb.plugins.LogInterceptor</interceptor>
+
<interceptor>org.jboss.ejb.plugins.SecurityInterceptor</interceptor>
+
<interceptor>org.jboss.ejb.plugins.TxInterceptorCMT</interceptor>
+ <interceptor
metricsEnabled="true">org.jboss.ejb.plugins.MetricsInterceptor</interceptor>
+
<interceptor>org.jboss.ejb.plugins.EntityInstanceInterceptor</interceptor>
+
<interceptor>org.jboss.ejb.plugins.EntitySynchronizationInterceptor</interceptor>
+ </container-interceptors>
+ </container-configuration>
+ </container-configurations>
+</jboss>
+</pre>
+</table>
+You now have set your logging interceptor to be the first interceptor in the
+stack. Note that you have to sepcify the complete interceptor stack. There is no
+way to indicate insertion of one or more interceptors into the default stack.
+</p>
+
<li><a name="WhatConf"></a><b>What can be configured ?</b><br>These are the
different things you can customize in a <tt><container-configuration></tt> tag
in <em>jboss.xml</em>. See the <A href="jboss.dtd">jboss.xml DTD</A> for more details:
<ul>
<li><tt>call-logging</tt>: this tag must have a boolean value: true or false. It
tells the container if calls to this bean must be logged or not. It is set to false in
standard configurations.
-<li><tt>container-invoker</tt>: the container invoker is .
+<li><tt>container-invoker</tt>: the container invoker is the class name of the
+org.jboss.ejb.ContainerInvoker implementation that jboss must use for in this
configuration.
+<li><tt>container-interceptors</tt>: gives the stack of org.jboss.ejb.Interceptor
instances
+that are associated with the container.
<li><tt>instance-pool</tt>: the instance pool is a set (a "pool") of free (ie not
currently associated to a context) instances of the bean. When an instance of the bean
is no longer used, it is thrown back to the pool. This is not used for Stateful
Session Beans, since the instances are not reusable.
<li><tt>instance-cache</tt>: the cache contains the instances of a bean which are
currently associated to a context. If it grows too big, the cache may decide to
passivate some of the instances. This is not used for Stateless Session Beans, since
these are directly reusable after a call.
<li><tt>persistence-manager</tt>: the persistence manager is in charge of storing
permanent information in the instance of a bean. For BMP Entities, it will merely
transmit orders to the bean; for Stateful Sessions and CMP Entities, it has to save
the state of the bean. This is not used for Stateless Session Beans, since they don't
have a state to save.
-<li><tt>transaction-manager</tt>
+<li><tt>transaction-manager</tt>: gives the class name of the
javax.transaction.TransactionManager
+ implementation that jboss must use for in this configuration.
<li><tt>container-invoker-conf</tt>: configuration of the container invoker.
<li><tt>container-cache-conf</tt>: configuration of the cache. For example, you may
specify the time interval between passivations.
<li><tt>container-pool-conf</tt>: configuration of the pool. Mainly, the size of
the pool.
-<li><tt>commit-option</tt> must be
+<li><tt>commit-option</tt>: must be
A, B or C. See the ejb specification for more details.</li>
+<li><tt>role-mapping-manager</tt>: specifies the JNDI name of the
+ org.jboss.security.RealmMapping implementation that is to be used by the
+ container SecurityInterceptor
+<li><tt>authentication-module</tt>: specifies the JNDI name of the
+ org.jboss.security.EJBSecurityManager implementation that is to be used
+ by the container SecurityInterceptor.
</ul></li></UL>
+
<hr>Author: <A href="mailto:[EMAIL PROTECTED]">Sébastien
Alborini</A>
</BODY>
</html>
