User: simone
Date: 00/10/27 03:29:15
Modified: . contconf_howto.html
Log:
Added advanced cache configuration howto
Revision Changes Path
1.3 +107 -18 jbossweb/contconf_howto.html
Index: contconf_howto.html
===================================================================
RCS file: /products/cvs/ejboss/jbossweb/contconf_howto.html,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -r1.2 -r1.3
--- contconf_howto.html 2000/09/26 02:12:11 1.2
+++ contconf_howto.html 2000/10/27 10:29:15 1.3
@@ -1,18 +1,28 @@
-<html>
-<head>
-<title>
-Container Configuration
-</title>
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"><html>
+<head><TITLE>Container Configuration</TITLE>
+<META content="text/html; charset=unicode" http-equiv=Content-Type>
+<META content="MSHTML 5.00.2920.0" name=GENERATOR>
</head>
+<BODY>
<font face=arial,helvetica size=+3 color="#ffcc00">
What is a Container Configuration?
</font>
-<p>When you deploy an application, jBoss creates a container for each of your
beans. This container will be used only for this particular bean. It must be
configured according to the type of the bean (CMP Entity Bean, Stateful Session Bean,
...). Different configurations are stored in the <em>standardjboss.xml</em> file. You
may provide additional custom configurations in the <em>jboss.xml</em> file for your
application.</p>
+<p>When you deploy an application, jBoss creates a container for each of your
beans. This container will be used only for this particular bean. It must be
configured according to the type of the bean (CMP Entity Bean, Stateful Session Bean,
etc.). Different standard configurations are stored in the <em>standardjboss.xml</em>
file. You may provide additional custom configurations in the <em>jboss.xml</em> file
for your application.</p>
+<P>
+<font face=arial,helvetica size=+2 color="#ffcc00">Container Configuration
Outline</font>
+<ul>
+<li><A href="#StdConf">Standard Configurations</a>
+<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="#WhatConf">What can be configured ?</a></li>
+</ul>
+<p> <p>
<ul>
-<li><b>Standard Configurations</b><br>jBoss currently provides a standard
configuration for each type of bean. These configurations are stored in the
<em>standardjboss.xml</em> file. There are currently 8 standard configurations. If you
don't provide anything else (as we advise you to do, at least at the beginning), jBoss
will automatically choose the right standard configuration for your container. The
available configurations are the following: <ul><tt>
+<li><a name="StdConf"></a><b>Standard Configurations</b><br>jBoss currently
provides a standard configuration for each type of bean. These configurations are
stored in the <em>standardjboss.xml</em> file. There are currently 8 standard
configurations. If you don't provide anything else (as we advise you to do, at least
at the beginning), jBoss will automatically choose the right standard configuration
for your container. The available configurations are the following: <ul><tt>
<li>Standard CMP EntityBean
<li>Standard BMP EntityBean
<li>Standard Stateless SessionBean
@@ -21,10 +31,12 @@
<li>jdk1.2.2 BMP EntityBean
<li>jdk1.2.2 Stateless SessionBean
<li>jdk1.2.2 Stateful SessionBean
-</tt></ul>
+</tt></li>
+
+</ul>
<p>The first four ones are used if you run <b>jBoss</b> with a jdk1.3 JVM. The four
last ones are used if you run <b>jBoss</b> with a jdk1.2.2 JVM.</p>
-<li><b>How do I configure my bean for jdk1.2.2 clients?</b><br>If you run jBoss on
a jdk1.3 JVM, but your clients use jdk1.2.2, the standard configuration won't work
(the protocols are not backward compatible). In this case, you have to force jBoss to
use the corresponding jdk1.2.2 configuration. You do that by providing a
<em>jboss.xml</em> file. This file must be in the <em>META-INF</em> directory of your
jar file, along with <em>ejb-jar.xml</em>. In the section for your bean, simply add a
<tt><configuration-name></tt> tag. Your xml files will look like this (note that
the <tt><ejb-name></tt> tags in the 2 xml files must match)
+<li><a name="jdk12Conf"></a><b>How do I configure my bean for jdk1.2.2 clients
?</b><br>If you run jBoss on a jdk1.3 JVM, but your clients use jdk1.2.2, the standard
configuration won't work (the protocols are not backward compatible). In this case,
you have to force jBoss to use the corresponding jdk1.2.2 configuration. You do that
by providing a <em>jboss.xml</em> file. This file must be in the <em>META-INF</em>
directory of your jar file, along with <em>ejb-jar.xml</em>. In the section for your
bean, simply add a <tt><configuration-name></tt> tag. Your xml files will look
like this (note that the <tt><ejb-name></tt> tags in the 2 xml files must match)
<p>
<em>ejb-jar.xml</em>:</p>
@@ -60,7 +72,7 @@
</pre></td></tr></table></p>
-<li><b>How do I specify my own custom configuration?</b><br>You may want to provide
your own advanced configuration. For example, you may want to increase the size of
your pool, or use a different instance cache. To do this, you must define your
configuration in <em>jboss.xml</em> in the <tt><container-configurations></tt>
tag. Then you have to use your new configuration in the bean section of your
<em>jboss.xml</em> file. For example, if you want to log calls to your bean, your file
will look like this :
+<li><a name="CustConf"></a><b>How do I specify my own custom configuration
?</b><br>You may want to provide your own advanced configuration. For example, you may
want to increase the size of your pool, or use a different instance cache. To do this,
you must define your configuration in <em>jboss.xml</em> in the
<tt><container-configurations></tt> tag. Then you have to use your new
configuration in the bean section of your <em>jboss.xml</em> file. For example, if you
want to log calls to your bean, your file will look like this :
<p><table border=0 bgcolor="#80ff80" cellspacing=4><tr><td><pre>
<jboss>
@@ -76,7 +88,7 @@
<container-name><b>Logging Configuration</b></container-name>
<call-logging>true</call-logging>
<container-invoker>org.jboss.ejb.plugins.jrmp13.server.JRMPContainerInvoker</container-invoker>
-
<instance-cache>org.jboss.ejb.plugins.NoPassivationStatefulSessionInstanceCache</instance-cache>
+
<instance-cache>org.jboss.ejb.plugins.StatefulSessionInstanceCache</instance-cache>
<persistence-manager>org.jboss.ejb.plugins.StatefulSessionFilePersistenceManager</persistence-manager>
<transaction-manager>org.jboss.tm.TxManager</transaction-manager>
<container-invoker-conf>
@@ -87,8 +99,86 @@
...
</jboss>
</pre></td></tr></table></p>
+
+<li><a name="CacheConf"></a><b>How do I specify advanced cache configuration
?</b><br>
+jBoss currently provides the possibility to choose the cache configuration for each
container configuration.
+You may want to define your own cache settings, and to do so you must specify them
in <EM>jboss.xml</EM> under
+the <tt><instance-cache></tt> tag and subtags.
+Currently 2 cache algorithms have been implemented: a no passivation cache
algorithm (so that all the bean
+are kept in memory, unless the bean is an entity bean and you specified for it
commit option C), and a
+least recently used (LRU) cache algorithm (so that bean less frequently used are
passivated to save
+server resources).<br>
+Let's see how to configure both caches. The examples below are about entity beans,
but the cache settings applies as well for stateful session beans.<p>
+For the no passivation cache, <EM>jboss.xml</EM> will look like this:<br>
+<table border=0 bgcolor="#80ff80" cellspacing=4><tr><td><pre>
+<jboss>
+ <enterprise-beans>
+ <entity>
+ <ejb-name>Bean A</ejb-name>
+ <configuration-name>No Passivation
Configuration<configuration-name>
+ </entity>
+ <enterprise-beans>
+ ...
+ <container-configurations>
+ <container-configuration>
+ <container-name>No Passivation Configuration</container-name>
+ ...
+
<instance-cache>org.jboss.ejb.plugins.EntitySessionInstanceCache</instance-cache>
+ <container-cache-conf>
+
<b><cache-policy>org.jboss.ejb.plugins.NoPassivationCachePolicy</cache-policy></b>
+ </container-cache-conf>
+ ...
+ </container-configuration>
+ </container-configurations>
+ ...
+</jboss>
+</pre></td></tr></table></br>
+No further settings are available for the no passivation cache.<p>
+For the LRU cache, <EM>jboss.xml</EM> will look like this:<br>
+<table border=0 bgcolor="#80ff80" cellspacing=4><tr><td><pre>
+<jboss>
+ <enterprise-beans>
+ <entity>
+ <ejb-name>Bean A</ejb-name>
+ <configuration-name>LRU Configuration<configuration-name>
+ </entity>
+ <enterprise-beans>
+ ...
+ <container-configurations>
+ <container-configuration>
+ <container-name>LRU Configuration</container-name>
+ ...
+
<instance-cache>org.jboss.ejb.plugins.EntitySessionInstanceCache</instance-cache>
+ <container-cache-conf>
+
<b><cache-policy>org.jboss.ejb.plugins.LRUEnterpriseContextCachePolicy</cache-policy>
+ <cache-policy-conf>
+ <min-capacity>5</min-capacity>
+ <max-capacity>200</max-capacity>
+ <overager-period>300</overager-period>
+ <max-bean-age>600</max-bean-age>
+ <resizer-period>400</resizer-period>
+ <max-cache-miss-period>60</max-cache-miss-period>
+ <min-cache-miss-period>1</min-cache-miss-period>
+ <cache-load-factor>0.75</cache-load-factor>
+ </cache-policy-conf></b>
+ </container-cache-conf>
+ ...
+ </container-configuration>
+ </container-configurations>
+ ...
+</jboss>
+</pre></td></tr></table></br>
+The tag <tt><cache-policy-conf></tt> and its subtags are optional, so you can
specify none, few or all of them.<br>
+The tag <tt><min-capacity></tt> specifies the minimum capacity of the cache.
The cache can be empty, but will have room for at least 5 beans (in the above case);
this value cannot be less than 2; the resizer (see below) will shrink the cache
capacity down to but not less than this value.<br>
+The tag <tt><max-capacity></tt> specifies the maximum capacity of the cache.
The cache can be empty, but will have room for at most 200 beans (in the above case);
this value cannot be less than the minimum capacity; the resizer (see below) will
enlarge the cache capacity up to but not more than this value.<br>
+The tag <tt><overager-period></tt> specifies the period of the
<b>overager</b>, that is a periodic task that runs (in the above case) every 300
seconds. Purpose of this periodic task is to see if in the cache there are very old
beans, and to passivate them. The age at which a bean is considered too old is also
configurable (see below). While the period of this task is 300 seconds, the first run
happens at a random time between 0 and 300 seconds.<br>
+The tag <tt><max-bean-age></tt> specifies the max age a bean can have before
being passivated by the overager (in this case 600 seconds).<br>
+The tag <tt><resizer-period></tt> specifies the period of the <b>resizer</b>,
that is a periodic task that runs (in the above case) every 400 seconds. Purpose of
this periodic task is to shrink / enlarge the cache capacity upon 3 other parameters
(see below). While the period of this task is 400 seconds, the first run happens at a
random time between 0 and 400 seconds.<br>
+The tags <tt><max-cache-miss-period></tt>,
<tt><min-cache-miss-period></tt> and <tt><cache-load-factor></tt> control
the resizer in this way: the number of cache misses is internally recorded. When the
resizer runs, it sees what is the cache miss rate from the last time it ran. If there
is more than (in the above case) one cache miss every 1 second (min-cache-miss-period)
then the resizer tries to enlarge the cache; if there is less than (in this case) one
cache miss every 60 seconds (max-cache-miss-period) then the resizer tries to shrink
the cache.
+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><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><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>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.
@@ -98,10 +188,9 @@
<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 A, B or C. See the ejb specification for more
details.
-</ul>
-
-</ul>
-<hr>Author: <a href="mailto:[EMAIL PROTECTED]">S�bastien Alborini</a>
-</body>
+<li><tt>commit-option</tt> must be
+ A, B or C. See the ejb specification for more details.</li>
+</ul></li></UL>
+<hr>Author: <A href="mailto:[EMAIL PROTECTED]">Sébastien
Alborini</A>
+</BODY>
</html>
