User: alborini
Date: 01/04/04 12:25:24
Modified: src/docs advconfig.xml
Log:
- better howto -> docbook translation
- updated wrt new jboss.xml features
- TODO: document the use of resource ref
Revision Changes Path
1.4 +175 -178 manual/src/docs/advconfig.xml
Index: advconfig.xml
===================================================================
RCS file: /cvsroot/jboss/manual/src/docs/advconfig.xml,v
retrieving revision 1.3
retrieving revision 1.4
diff -u -r1.3 -r1.4
--- advconfig.xml 2001/04/02 03:25:40 1.3
+++ advconfig.xml 2001/04/04 19:25:24 1.4
@@ -1,5 +1,5 @@
<chapter id="adv.config">
- <title>Advanced container configuration</title>
+ <title>Advanced container configuration : use of jboss.xml</title>
<para>Author:
<author><firstname>Sebastien</firstname><surname>Alborini</surname></author>
<email>[EMAIL PROTECTED]</email>
@@ -21,7 +21,7 @@
may be cases where
you want to add JBoss-specific information in your deployment descriptor. This
can be done by
-providing a jboss.xml in the META-INF directory.
+providing another file named jboss.xml in the META-INF directory.
</para>
<para>
Note that this file is almost NEVER required by JBoss: JBoss will always
@@ -31,27 +31,18 @@
contains the standard configuration.
</para>
<para>
-This is what you CAN do in your jboss.xml file:
+The following sections will cover most common uses of the jboss.xml file. If you
want to know all the details, you can get the DTD for jboss.xml <ulink
url="http://www.jboss.org/documentation/jboss.dtd">here</ulink>
</para>
- <para>
-Specifying a particular jndi name for deployment. See the jndi howto
-Declare external ejb references. See the ejb-ref howto
-Declare resource managers. See the resource manager howto (TBD).
-Customize the container configuration for your beans. See the container
-configuration howto.
-Get all the skinny in gorry details: jboss.xml DTD
-</para>
</section>
<section>
<title>Specifying the deployment name of your beans</title>
<para>
You have coded your beans. You now want to deploy them and be
-able to access them from your clients.
-</para>
- <para>
-Standard behaviour of jboss
+able to access them from your clients. For this, JBoss will register your beans in
the JNDI namespace. All you have to tell is the name under which they must be
registered.
</para>
- <para>
+ <section>
+ <title>Standard behaviour of jboss</title>
+ <para>
The simplest way to deploy your bean is to use the ejb-jar.xml file to give it
the same name you
call it in the client. This is done in the <![CDATA[<ejb-name>]]> tag for the
@@ -59,10 +50,10 @@
need a jboss.xml file. Your ejb-jar.xml file will look like this (this is
covered in the beginners trails):
</para>
- <para>
+ <para>
ejb-jar.xml:
</para>
- <programlisting><![CDATA[
+ <programlisting><![CDATA[
<ejb-jar>
<enterprise-beans>
@@ -80,11 +71,11 @@
...
</ejb-jar>
]]></programlisting>
- <para>
+ <para>
And your bean will be available under the "MyBeanName" in JNDI.
In your client code, your call will look like this:
</para>
- <programlisting>
+ <programlisting>
public class Client {
...
public static void main(String arg[]) {
@@ -95,28 +86,28 @@
}
}
</programlisting>
- <para>
-Here the "MyBeanName" refers to the name of your bean in the jndi namespace.
+ <para>
+Here the "MyBeanName" refers to the name of your bean in the JNDI namespace.
JBoss does not currently allow
you to use the java:comp/env namespace to call your beans from your clients.
</para>
- <para>
-If you want to give a jndi deployment name different than the ejb-name
-</para>
- <para>
-You may want to deploy your bean under another jndi name. (for example, you
+ </section>
+ <section>
+ <title>Registering a bean with a JNDI deployment name
different than the ejb-name</title>
+ <para>
+You may want to deploy your bean under another JNDI name. (for example, you
may want to deploy the same
bean under different names with different configurations). In this case, you
-must specify the jndi name
+must specify the JNDI name
in a jboss.xml file. This file must be in the META-INF directory, along with
ejb-jar.xml. Your files
will look like this (note that the <![CDATA[<ejb-name>]]>tags in the two xml
files must match):
</para>
- <para>
+ <para>
jboss.xml:
</para>
- <programlisting><![CDATA[
+ <programlisting><![CDATA[
<jboss>
<enterprise-beans>
@@ -128,18 +119,18 @@
</jboss>
]]></programlisting>
- <para>
+ <para>
(you don't need to specify the rest of the jboss.xml file, only this
information is sufficient in the
new metadata, this is what we call "differential" jboss.xml).
</para>
- <para>
+ <para>
Your bean is then available in JNDI under somePath/otherName
</para>
- <para>
+ <para>
In your client code, your call will look like this:
</para>
- <programlisting>
+ <programlisting>
public class Client {
...
public static void main(String arg[]) {
@@ -151,11 +142,12 @@
}
}
</programlisting>
+ </section>
</section>
<section>
- <title>Declaring an ejb references</title>
+ <title>Declaring an EJB reference</title>
<para>
-An ejb reference (see ejb1.1 specification, 14.3, p207) is when a bean A wants
+An EJB reference (see ejb1.1 specification, 14.3, p207) is when a bean A wants
to call methods on a bean B.
We are talking about intra-bean calls also called B2B calls. This is not for
clients (that is covered in
@@ -184,8 +176,9 @@
descriptor. This is done by an <![CDATA[<ejb-ref>]]>
tag in the bean section of the ejb-jar.xml file. 2 cases may occur:
</para>
- <para>
-Internal ejb reference: the bean B is in the same application unit as the bean
+ <section>
+ <title>Internal EJB reference</title>
+ <para>An EJB reference is called internal when the bean B is
in the same application unit as the bean
A. This means that the beans are
physically packaged in the same jar. In this case, you must provide the
<![CDATA[<ejb-link>]]> tag, and its value must
@@ -193,7 +186,7 @@
in the jboss.xml file. Your ejb-jar.xml
file will look like this:
</para>
- <programlisting><![CDATA[
+ <programlisting><![CDATA[
<ejb-jar>
<enterprise-beans>
@@ -228,26 +221,28 @@
</ejb-jar>
]]></programlisting>
- <para>
-External ejb reference: the bean B comes from another application unit, it may
+ </section>
+ <section>
+ <title>External EJB reference</title>
+ <para>An EJB reference is called external when the bean B
comes from another application unit, it may
even be deployed on another server.
This means that the beans live in different jars on different systems. In this
case, you cannot rely on the
standard <![CDATA[<ejb-link>]]> tag in ejb-jar.xml since there the beans are
not covered in the same file. Instead, you must
-provide the full jndi name of the bean B in jboss.xml. This is necessary to
+provide the full JNDI name of the bean B in jboss.xml. This is necessary to
map the names from different ejb-jar.xml
files since the 2 beans are defined in different application units. A full
name is of the form:
</para>
- <para>
+ <para>
protocol://host:1234/name/in/other/server
Note that the <![CDATA[<ejb-ref-name>]]> tags in the 2 xml files must match.
</para>
- <para>
+ <para>
ejb-jar.xml:
</para>
- <programlisting><![CDATA[
+ <programlisting><![CDATA[
<ejb-jar>
<enterprise-beans>
@@ -270,10 +265,10 @@
...
</ejb-jar>
]]></programlisting>
- <para>
+ <para>
jboss.xml:
</para>
- <programlisting><![CDATA[
+ <programlisting><![CDATA[
<jboss>
<enterprise-beans>
<session>
@@ -286,17 +281,18 @@
<enterprise-beans>
</jboss>
]]></programlisting>
- <para>
+ <para>
If bean B is deployed in another application, but on the same jboss server,
the jndi-name you provide must be
-the name under which bean B is deployed (see the jndi_howto)
+the name under which bean B is deployed.
</para>
- <para>
+ <para>
IMPORTANT NOTE: this will tell jboss where to look for bean B. You also have
to tell jboss what bean B is:
in case of an external ejb-reference, be sure to include bean B's home and
remote interface in bean A's ejb-jar.
</para>
+ </section>
</section>
<section>
<title>Container configuration</title>
@@ -309,10 +305,9 @@
standardjboss.xml file. You may provide
additional custom configurations in the jboss.xml file for your application.
</para>
- <para>
-Standard Configurations
-</para>
- <para>
+ <section>
+ <title>Standard Configurations</title>
+ <para>
JBoss currently provides a standard configuration for each type of bean. These
configurations are stored in the
standardjboss.xml file. There are currently 8 standard configurations. If you
@@ -320,24 +315,26 @@
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:
+<itemizedlist>
+ <listitem>Standard CMP EntityBean</listitem>
+ <listitem>Standard BMP EntityBean </listitem>
+ <listitem>Standard Stateless SessionBean </listitem>
+ <listitem>Standard Stateful SessionBean </listitem>
+ <listitem>jdk1.2.2 CMP EntityBean </listitem>
+ <listitem>jdk1.2.2 BMP EntityBean </listitem>
+ <listitem>jdk1.2.2 Stateless SessionBean </listitem>
+ <listitem>jdk1.2.2 Stateful SessionBean </listitem>
+</itemizedlist>
</para>
- <para>
-Standard CMP EntityBean
-Standard BMP EntityBean
-Standard Stateless SessionBean
-Standard Stateful SessionBean
-jdk1.2.2 CMP EntityBean
-jdk1.2.2 BMP EntityBean
-jdk1.2.2 Stateless SessionBean
-jdk1.2.2 Stateful SessionBean
-</para>
- <para>
+ <para>
The first four ones are used if you run JBoss with a jdk1.3 JVM. The four last
ones are used if you run JBoss with
a jdk1.2.2 JVM.
</para>
- <para>
-How do I configure my bean for jdk1.2.2 clients ?
+ </section>
+ <section>
+ <title>How do I configure my bean for jdk1.2.2 clients
?</title>
+ <para>
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
@@ -349,7 +346,7 @@
this (note that the <![CDATA[<ejb-name>]]> tags in the 2 xml files must match)
ejb-jar.xml:
</para>
- <programlisting><![CDATA[
+ <programlisting><![CDATA[
<ejb-jar>
<enterprise-beans>
@@ -368,10 +365,10 @@
...
</ejb-jar>
]]></programlisting>
- <para>
+ <para>
jboss.xml:
</para>
- <programlisting><![CDATA[
+ <programlisting><![CDATA[
<jboss>
<enterprise-beans>
<session>
@@ -382,8 +379,10 @@
<enterprise-beans>
</jboss>
]]></programlisting>
- <para>
-How do I specify my own custom configuration ?
+ </section>
+ <section>
+ <title>Custom configurations</title>
+ <para>
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
@@ -393,7 +392,7 @@
For example, if you want to log calls to your bean, your file will look like
this :
</para>
- <programlisting><![CDATA[
+ <programlisting><![CDATA[
<jboss>
<enterprise-beans>
<session>
@@ -406,12 +405,9 @@
<container-configuration>
<container-name>Logging Configuration</container-name>
<call-logging>true</call-logging>
-
-<container-invoker>org.jboss.ejb.plugins.jrmp13.server.JRMPContainerInvoker</container-invoker>
-
-<instance-cache>org.jboss.ejb.plugins.StatefulSessionInstanceCache</instance-cache>
-
-<persistence-manager>org.jboss.ejb.plugins.StatefulSessionFilePersistenceManager</persistence-manager>
+
<container-invoker>org.jboss.ejb.plugins.jrmp13.server.JRMPContainerInvoker</container-invoker>
+
<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>
<Optimized>False</Optimized>
@@ -421,10 +417,81 @@
...
</jboss>
]]></programlisting>
- <para>
-How do I specify advanced cache configuration ?
+ </section>
+ <section>
+ <title>Content of a container configuration</title>
+ <para>
+These are the different things you can customize in a
+<![CDATA[<container-configuration>]]> tag in jboss.xml. See the jboss.xml DTD
+for
+more details:
+</para>
+ <itemizedlist>
+ <listitem>
+ <para><![CDATA[<call-logging>]]> 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.
</para>
- <para>
+ </listitem>
+ <listitem>
+ <para><![CDATA[<container-invoker>]]> the
container invoker is the entry point to the container. Currently, only the RMI/JRMP
container invoker is available.
+</para>
+ </listitem>
+ <listitem>
+ <para><![CDATA[<container-interceptors>]]> the
stack of JBoss interceptors for this bean. You can add your custom interceptor here
(for expert use only)
+</para>
+ </listitem>
+ <listitem>
+ <para><![CDATA[<instance-pool>]]> 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.
+</para>
+ </listitem>
+ <listitem>
+ <para><![CDATA[<instance-cache>]]> 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.
+</para>
+ </listitem>
+ <listitem>
+ <para><![CDATA[<persistence-manager>]]> 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.
+</para>
+ </listitem>
+ <listitem>
+ <para><![CDATA[<container-invoker-conf>]]>
configuration of the container invoker.
+</para>
+ </listitem>
+ <listitem>
+ <para><![CDATA[<container-cache-conf>]]>
configuration of the cache. See below for more details.
+</para>
+ </listitem>
+ <listitem>
+ <para><![CDATA[<role-mapping-manager>,
<security-domain>, <authentication-module>]]> : security options. See the section
about JAAS based security in JBoss.</para>
+ </listitem>
+ <listitem>
+ <para><![CDATA[<container-pool-conf>]]>
configuration of the pool. Mainly,
+the size of the pool.
+</para>
+ </listitem>
+ <listitem>
+ <para><![CDATA[<commit-option>]]> must be A, B
or C. See the ejb
+specification for more details.
+</para>
+ </listitem>
+ </itemizedlist>
+ </section>
+ <section>
+ <title>Advanced cache configuration</title>
+ <para>
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
@@ -436,13 +503,13 @@
cache algorithm (so that bean less frequently used are passivated to save
server resources).
</para>
- <para>
+ <para>
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.For the no passivation cache, jboss.xml will look
like this:
</para>
- <programlisting><![CDATA[
+ <programlisting><![CDATA[
<jboss>
<enterprise-beans>
<entity>
@@ -455,11 +522,9 @@
<container-configuration>
<container-name>No Passivation Configuration</container-name>
...
-
-<instance-cache>org.jboss.ejb.plugins.EntitySessionInstanceCache</instance-cache>
+
<instance-cache>org.jboss.ejb.plugins.EntitySessionInstanceCache</instance-cache>
<container-cache-conf>
-
-<cache-policy>org.jboss.ejb.plugins.NoPassivationCachePolicy</cache-policy>
+ <cache-policy>org.jboss.ejb.plugins.NoPassivationCachePolicy</cache-policy>
</container-cache-conf>
...
</container-configuration>
@@ -467,11 +532,11 @@
...
</jboss>
]]></programlisting>
- <para>
+ <para>
No further settings are available for the no passivation cache.
For the LRU cache, jboss.xml will look like this:
</para>
- <programlisting><![CDATA[
+ <programlisting><![CDATA[
<jboss>
<enterprise-beans>
<entity>
@@ -484,11 +549,9 @@
<container-configuration>
<container-name>LRU Configuration</container-name>
...
-
-<instance-cache>org.jboss.ejb.plugins.EntitySessionInstanceCache</instance-cache>
+
<instance-cache>org.jboss.ejb.plugins.EntitySessionInstanceCache</instance-cache>
<container-cache-conf>
-
-<cache-policy>org.jboss.ejb.plugins.LRUEnterpriseContextCachePolicy</cache-policy>
+
<cache-policy>org.jboss.ejb.plugins.LRUEnterpriseContextCachePolicy</cache-policy>
<cache-policy-conf>
<min-capacity>5</min-capacity>
@@ -507,9 +570,9 @@
...
</jboss>
]]></programlisting>
- <itemizedlist>
- <listitem>
- <para><![CDATA[<cache-policy-conf>]]> and its subtags
are optional, so you
+ <itemizedlist>
+ <listitem>
+ <para><![CDATA[<cache-policy-conf>]]> and its
subtags are optional, so you
can specify none, few or all of them.
<![CDATA[<min-capacity>]]> specifies the minimum capacity of the cache. The
cache can be empty, but will have room for at least
@@ -517,17 +580,17 @@
(see below) will shrink the cache capacity
down to but not less than this value.
</para>
- </listitem>
- <listitem>
- <para><![CDATA[<max-capacity>]]> specifies the maximum
capacity of the
+ </listitem>
+ <listitem>
+ <para><![CDATA[<max-capacity>]]> 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.
</para>
- </listitem>
- <listitem>
- <para><![CDATA[<overager-period>]]> specifies the
period of the overager,
+ </listitem>
+ <listitem>
+ <para><![CDATA[<overager-period>]]> specifies
the period of the overager,
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.
@@ -536,9 +599,9 @@
a random time between 0 and 300 seconds.
To disable the overager set the period to 0.
</para>
- </listitem>
- <listitem>
- <para><![CDATA[<max-bean-age>]]> specifies the max age
a bean can have
+ </listitem>
+ <listitem>
+ <para><![CDATA[<max-bean-age>]]> specifies the
max age a bean can have
before being passivated by the overager (in this case 600 seconds).
The tag <![CDATA[<resizer-period>]]> specifies the period of the resizer, that
is a periodic task that runs (in the above case) every
@@ -548,10 +611,9 @@
random time between 0 and 400 seconds.
To disable the resizer set the period to 0.
</para>
- </listitem>
- <listitem>
-
-<para><![CDATA[<max-cache-miss-period>]]>,<![CDATA[<min-cache-miss-period>]]>
+ </listitem>
+ <listitem>
+
<para><![CDATA[<max-cache-miss-period>]]>,<![CDATA[<min-cache-miss-period>]]>
and <![CDATA[<cache-load-factor>]]> control the resizer in this way: the
number of
cache misses is internally recorded. When the resizer runs, it sees what is
@@ -570,75 +632,10 @@
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).
-</para>
- </listitem>
- </itemizedlist>
- <para>
-What can be configured ?
-</para>
- <para>
-These are the different things you can customize in a
-<![CDATA[<container-configuration>]]> tag in jboss.xml. See the jboss.xml DTD
-for
-more details:
-</para>
- <itemizedlist>
- <listitem>
- <para><![CDATA[<call-logging>]]> 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.
-</para>
- </listitem>
- <listitem>
- <para><![CDATA[<container-invoker>]]> the container invoker.
-</para>
- </listitem>
- <listitem>
- <para><![CDATA[<instance-pool>]]> 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.
-</para>
- </listitem>
- <listitem>
- <para><![CDATA[<instance-cache>]]> 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.
-</para>
- </listitem>
- <listitem>
- <para><![CDATA[<persistence-manager>]]> 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.
-</para>
- </listitem>
- <listitem>
- <para><![CDATA[<container-invoker-conf>]]> configuration of
the container
-invoker.
-</para>
- </listitem>
- <listitem>
- <para><![CDATA[<container-cache-conf>]]> configuration of the
cache. For
-example, you may specify the time interval between passivations.
-</para>
- </listitem>
- <listitem>
- <para><![CDATA[<container-pool-conf>]]> configuration of the
pool. Mainly,
-the size of the pool.
-</para>
- </listitem>
- <listitem>
- <para><![CDATA[<commit-option>]]> must be A, B or C. See the
ejb
-specification for more details.
</para>
- </listitem>
- </itemizedlist>
+ </listitem>
+ </itemizedlist>
+ </section>
</section>
</chapter>
_______________________________________________
Jboss-development mailing list
[EMAIL PROTECTED]
http://lists.sourceforge.net/lists/listinfo/jboss-development
