User: starksm
Date: 01/04/04 13:37:00
Modified: src/docs advconfig.xml
Log:
Add a figure showing a graphical view of the jboss DTD.
Revision Changes Path
1.5 +154 -194 manual/src/docs/advconfig.xml
Index: advconfig.xml
===================================================================
RCS file: /cvsroot/jboss/manual/src/docs/advconfig.xml,v
retrieving revision 1.4
retrieving revision 1.5
diff -u -r1.4 -r1.5
--- advconfig.xml 2001/04/04 19:25:24 1.4
+++ advconfig.xml 2001/04/04 20:37:00 1.5
@@ -1,58 +1,57 @@
-<chapter id="adv.config">
+<?xml version = "1.0" encoding = "UTF-8"?>
+<chapter id = "adv.config">
<title>Advanced container configuration : use of jboss.xml</title>
- <para>Author:
- <author><firstname>Sebastien</firstname><surname>Alborini</surname></author>
- <email>[EMAIL PROTECTED]</email>
+ <para>Author:<author>
+ <firstname>Sebastien</firstname>
+ <surname>Alborini</surname>
+ </author>
+ <email>[EMAIL PROTECTED]</email>
</para>
<section>
<title>What is jboss.xml?</title>
- <para>
-To deploy your beans, you have to specify (nearly) everything about them in a
+ <para>To deploy your beans, you have to specify (nearly) everything
about them in a
file called ejb-jar.xml.
This file will be stored in the META-INF directory in your ejb-jar file. The
content and syntax of
this file in specified in the ejb1.1 specification (16.5 Deployment descriptor
-DTD, pp 244-259).
-</para>
- <para>
-An important point is that the specification does not allow you to add
+DTD, pp 244-259).</para>
+ <para>An important point is that the specification does not allow you
to add
vendor-specific configuration
in this file. While the ejb-jar.xml is sufficient for most applications, there
may be cases where
you want to add JBoss-specific information in your deployment descriptor. This
can be done by
-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
+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
provide a standard behaviour
when no jboss.xml file is found. JBoss does that by first processing a
standardjboss.xml file which
-contains the standard configuration.
-</para>
- <para>
-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>
+contains the standard configuration.</para>
+ <para>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>. A graphical
view of the DTD is given in <xref linkend = "adv.config.dtd"/>
+ </para>
+ <figure id = "adv.config.dtd">
+ <title>The jboss.xml DTD</title>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref = "images/jboss_dtd.jpg"/>
+ </imageobject>
+ </mediaobject>
+ </figure>
</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. 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>You have coded your beans. You now want to deploy them and be
+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>
<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
+ <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
+call it in the client. This is done in the <![CDATA[<ejb-name> tag for the
bean. In this case you DON'T
need a jboss.xml file. Your ejb-jar.xml file will look like this (this is
covered in the beginners trails):
-</para>
- <para>
-ejb-jar.xml:
-</para>
+]]></para>
+ <para>ejb-jar.xml: </para>
<programlisting><![CDATA[
<ejb-jar>
@@ -71,12 +70,9 @@
...
</ejb-jar>
]]></programlisting>
- <para>
-And your bean will be available under the "MyBeanName" in JNDI.
-In your client code, your call will look like this:
-</para>
- <programlisting>
-public class Client {
+ <para>And your bean will be available under the "MyBeanName"
in JNDI.
+In your client code, your call will look like this:</para>
+ <programlisting>public class Client {
...
public static void main(String arg[]) {
...
@@ -84,29 +80,23 @@
MyBeanHome home = (MyBeanHome) new InitialContext().lookup("MyBeanName");
...
}
-}
-</programlisting>
- <para>
-Here the "MyBeanName" refers to the name of your bean in the JNDI namespace.
+}</programlisting>
+ <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>
+you to use the java:comp/env namespace to call your beans from your clients.</para>
</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
+ <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
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
+will look like this (note that the <![CDATA[<ejb-name>tags in the two xml
files must match):
-</para>
- <para>
-jboss.xml:
-</para>
+]]></para>
+ <para>jboss.xml:</para>
<programlisting><![CDATA[
<jboss>
@@ -119,19 +109,12 @@
</jboss>
]]></programlisting>
- <para>
-(you don't need to specify the rest of the jboss.xml file, only this
+ <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>
-Your bean is then available in JNDI under somePath/otherName
-</para>
- <para>
-In your client code, your call will look like this:
-</para>
- <programlisting>
-public class Client {
+new metadata, this is what we call "differential" jboss.xml).</para>
+ <para>Your bean is then available in JNDI under
somePath/otherName</para>
+ <para>In your client code, your call will look like
this:</para>
+ <programlisting>public class Client {
...
public static void main(String arg[]) {
...
@@ -140,27 +123,21 @@
InitialContext().lookup("somePath/otherName");
...
}
-}
-</programlisting>
+}</programlisting>
</section>
</section>
<section>
<title>Declaring an EJB reference</title>
- <para>
-An EJB reference (see ejb1.1 specification, 14.3, p207) is when a bean A wants
+ <para>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
the beginner trails) this is for bean calls all on the server. Most of these
calls are done inside the
-server VM.
-</para>
- <para>
-This call will look like this: (beans running on the server must use the
-java:comp/env namespace).
-</para>
- <programlisting>
-public class ABean implements EntityBean {
+server VM.</para>
+ <para>This call will look like this: (beans running on the server must
use the
+java:comp/env namespace).</para>
+ <programlisting>public class ABean implements EntityBean {
...
public void BusinessMethod(...) {
...
@@ -169,23 +146,20 @@
B bean = home.create(pk);
...
}
-}
-</programlisting>
- <para>
-To be allowed this call, the bean A must declare it in the its deployment
-descriptor. This is done by an <![CDATA[<ejb-ref>]]>
+}</programlisting>
+ <para>To be allowed this call, the bean A must declare it in the its
deployment
+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>
<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
-match the <![CDATA[<ejb-name>]]> of bean B. You don't have to provide anything
+physically packaged in the same jar. In this case, you must provide the
<![CDATA[<ejb-link> tag, and its value must
+match the ]]><![CDATA[<ejb-name> of bean B. You don't have to provide anything
in the jboss.xml file. Your ejb-jar.xml
file will look like this:
-</para>
+]]></para>
<programlisting><![CDATA[
<ejb-jar>
<enterprise-beans>
@@ -228,20 +202,17 @@
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
+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
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>
-protocol://host:1234/name/in/other/server
-Note that the <![CDATA[<ejb-ref-name>]]> tags in the 2 xml files must match.
-</para>
- <para>
-ejb-jar.xml:
-</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>ejb-jar.xml:</para>
<programlisting><![CDATA[
<ejb-jar>
<enterprise-beans>
@@ -265,9 +236,7 @@
...
</ejb-jar>
]]></programlisting>
- <para>
-jboss.xml:
-</para>
+ <para>jboss.xml: </para>
<programlisting><![CDATA[
<jboss>
<enterprise-beans>
@@ -281,71 +250,75 @@
<enterprise-beans>
</jboss>
]]></programlisting>
- <para>
-If bean B is deployed in another application, but on the same jboss server,
+ <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.
-</para>
- <para>
-IMPORTANT NOTE: this will tell jboss where to look for bean B. You also have
+the name under which bean B is deployed.</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>
+remote interface in bean A's ejb-jar. </para>
</section>
</section>
<section>
<title>Container configuration</title>
- <para>
-When you deploy an application, JBoss creates a container for each of your
+ <para>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
standardjboss.xml file. You may provide
-additional custom configurations in the jboss.xml file for your application.
-</para>
+additional custom configurations in the jboss.xml file for your application.</para>
<section>
<title>Standard Configurations</title>
- <para>
-JBoss currently provides a standard configuration for each type of bean. These
+ <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
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:
-<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>
-The first four ones are used if you run JBoss with a jdk1.3 JVM. The four last
+your container. The available configurations are the following: <itemizedlist>
+ <listitem>
+ <para>Standard CMP EntityBean</para>
+ </listitem>
+ <listitem>
+ <para>Standard BMP EntityBean </para>
+ </listitem>
+ <listitem>
+ <para>Standard Stateless SessionBean
</para>
+ </listitem>
+ <listitem>
+ <para>Standard Stateful SessionBean
</para>
+ </listitem>
+ <listitem>
+ <para>jdk1.2.2 CMP EntityBean </para>
+ </listitem>
+ <listitem>
+ <para>jdk1.2.2 BMP EntityBean </para>
+ </listitem>
+ <listitem>
+ <para>jdk1.2.2 Stateless SessionBean
</para>
+ </listitem>
+ <listitem>
+ <para>jdk1.2.2 Stateful SessionBean
</para>
+ </listitem>
+ </itemizedlist>
+ </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>
+a jdk1.2.2 JVM.</para>
</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
+ <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
corresponding jdk1.2.2 configuration.
You do that by providing a jboss.xml file. This file must be in the META-INF
directory of your jar file, along with
-ejb-jar.xml. In the section for your bean, simply add a
-<![CDATA[<configuration-name>]]> tag. Your xml files will look like
-this (note that the <![CDATA[<ejb-name>]]> tags in the 2 xml files must match)
+ejb-jar.xml. In the section for your bean, simply add a
<![CDATA[<configuration-name> tag. Your xml files will look like
+this (note that the ]]><![CDATA[<ejb-name> tags in the 2 xml files must match)
ejb-jar.xml:
-</para>
+]]></para>
<programlisting><![CDATA[
<ejb-jar>
@@ -365,9 +338,7 @@
...
</ejb-jar>
]]></programlisting>
- <para>
-jboss.xml:
-</para>
+ <para>jboss.xml: </para>
<programlisting><![CDATA[
<jboss>
<enterprise-beans>
@@ -382,16 +353,14 @@
</section>
<section>
<title>Custom configurations</title>
- <para>
-You may want to provide your own advanced configuration. For example, you may
+ <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
-configuration in jboss.xml in the
-<![CDATA[<container-configurations>]]> tag. Then you have to use your new
+configuration in jboss.xml in the <![CDATA[<container-configurations> tag. Then you
have to use your new
configuration in the bean section of your jboss.xml file.
For example, if you want to log calls to your bean, your file will look like
this :
-</para>
+]]></para>
<programlisting><![CDATA[
<jboss>
<enterprise-beans>
@@ -420,95 +389,91 @@
</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
+ <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>
+]]></para>
+
+ <itemizedlist>
<listitem>
- <para><![CDATA[<call-logging>]]> this tag must
have a boolean value: true
+ <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>
+ <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>
+ <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
+ <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>
+]]></para>
</listitem>
<listitem>
- <para><![CDATA[<instance-cache>]]> the cache
contains the instances of a
+ <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>
+]]></para>
</listitem>
<listitem>
- <para><![CDATA[<persistence-manager>]]> the
persistence manager is in
+ <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>
+]]></para>
</listitem>
<listitem>
- <para><![CDATA[<container-invoker-conf>]]>
configuration of the container invoker.
-</para>
+ <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>
+ <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>
+ <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,
+ <para><![CDATA[<container-pool-conf>
configuration of the pool. Mainly,
the size of the pool.
-</para>
+]]></para>
</listitem>
<listitem>
- <para><![CDATA[<commit-option>]]> must be A, B
or C. See the ejb
+ <para><![CDATA[<commit-option> must be A, B or
C. See the ejb
specification for more details.
-</para>
+]]></para>
</listitem>
</itemizedlist>
</section>
<section>
<title>Advanced cache configuration</title>
- <para>
-JBoss currently provides the possibility to choose the cache configuration for
+ <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
-jboss.xml under the <![CDATA[<instance-cache>]]> tag and
+jboss.xml under the <![CDATA[<instance-cache> 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).
-</para>
- <para>
-Let's see how to configure both caches. The examples below are about entity
+]]></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>
+like this:</para>
<programlisting><![CDATA[
<jboss>
<enterprise-beans>
@@ -532,10 +497,8 @@
...
</jboss>
]]></programlisting>
- <para>
-No further settings are available for the no passivation cache.
-For the LRU cache, jboss.xml will look like this:
-</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[
<jboss>
<enterprise-beans>
@@ -572,25 +535,25 @@
]]></programlisting>
<itemizedlist>
<listitem>
- <para><![CDATA[<cache-policy-conf>]]> and its
subtags are optional, so you
+ <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
+]]><![CDATA[<min-capacity> 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.
-</para>
+]]></para>
</listitem>
<listitem>
- <para><![CDATA[<max-capacity>]]> specifies the
maximum capacity of the
+ <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>
+]]></para>
</listitem>
<listitem>
- <para><![CDATA[<overager-period>]]> specifies
the period of the overager,
+ <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.
@@ -598,23 +561,23 @@
below). While the period of this task is 300 seconds, the first run happens at
a random time between 0 and 300 seconds.
To disable the overager set the period to 0.
-</para>
+]]></para>
</listitem>
<listitem>
- <para><![CDATA[<max-bean-age>]]> specifies the
max age a bean can have
+ <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
+The tag ]]><![CDATA[<resizer-period> specifies the period of the resizer, 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.
To disable the resizer set the period to 0.
-</para>
+]]></para>
</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
+
<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
the cache miss rate from the last time it ran.
@@ -632,12 +595,9 @@
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>
+]]></para>
</listitem>
</itemizedlist>
</section>
</section>
-</chapter>
-
-
-
+</chapter>
\ No newline at end of file
_______________________________________________
Jboss-development mailing list
[EMAIL PROTECTED]
http://lists.sourceforge.net/lists/listinfo/jboss-development
