<?xml version="1.0"?>
<document toc="none">

<properties>
<title>OpenEJB Configuration</title>
<sub-title>Containers</sub-title>
</properties>

<body>

<section title="Declaring your Container" ref-id="declare">
<p>
CMP Entity containers are defined with the &lt;Container&gt; element, 
under the &lt;openejb&gt; element.  This is actually the declaration used 
for all containers defined in the container system.  The part that 
actually makes it a cmp container is the <term>ctype</term> 
attribute, specifially, a <term>ctype</term> attribute set to 
<term>CMP_ENTITY</term> as such...
</p>

<p>
<file name="example_01.conf"><![CDATA[
<?xml version="1.0"?>
<openejb>

<Container id="Default CMP Container" ctype="CMP_ENTITY"/>

</openejb>
]]></file>
</p> 

<p>
The really fun part is that the above configuration file is completely 
legal!  If you started the server and pointed to this file...
</p> 
<p>
<command>./openejb.sh start -conf example_01.conf</command>
</p>
<p> 
...you would end up with a running server that contained only one  
container, called "Default CMP Container". You could then deploy beans 
into it and everything. There would be no other containers running in the 
server at all.  If you telnet'd into the server and typed the 'system' 
command, you could see for yourself that there is nothing else in the 
system.
</p>

<p>
<code-block>
dblevins@Miles /dev/OpenEJB
$ telnet localhost 4200
Trying 127.0.0.1...
Connected to Miles
Escape character is '^]'.
OpenEJB Remote Server Console
type 'help' for a list of commands
[openejb]$ system
Containers:
 Default CMP Container

Deployments:
[openejb]$
</code-block>
</p>
<p>
You see that. No beans, no JDBC resources, nothing but one CMP container 
called "Default CMP Container".
</p>
</section>

<section title="Naming your Container" ref-id="name">
<p>
You can call the container anything you want, just change the value of the 
<term>id</term> attribute.  Here is a container called "My PostgreSQL 
Contianer"
</p>

<p>
<file name="example_02.conf"><![CDATA[
<?xml version="1.0"?>
<openejb>

<Container id="My PostgreSQL Container" ctype="CMP_ENTITY"/>

</openejb>
]]></file>
</p> 
<p>
If you were to deploy a CMP bean into this configuration, you would see 
"My PostgreSQL Container" in the list of usable containers, in fact, it 
would be the only container in the list.
</p>
<p>
<code-block>
dblevins@Miles /dev/OpenEJB/openejb
$ ./openejb.sh deploy -conf example_02.conf myCMPBean.jar
...(skipping to step two)...

==--- Step 2 ---==

Please specify which container the bean will run in.
Available containers are:

Num     Type            ID

1       CMP_ENTITY      My PostgreSQL Container

Type the number of the container
-options to view the list again
or -help for more information.

Container:
</code-block>
</p>
<p>
After deployment, you would end up with a configuration like this one
</p>
<p>
<file name="example_02.conf"><![CDATA[
<?xml version="1.0"?>
<openejb>

<Container id="My PostgreSQL Container" ctype="CMP_ENTITY"/>

<Deployments jar="myCMPBean.jar" />

</openejb>
]]></file>
</p>
<p>
Most important, that bean will now be mapped directly to the container 
id "My PostgreSQL Container".  So if you change the name of the container 
and do not redeploy the myCMPBean.jar to point to the new container id, 
you will have big problems!
</p>
</section>

<section title="Container types" ref-id="declare.multiple">
<p>
You can declare as many containers as you want.  The available container 
types are:
<ul>
    <li>CMP_ENTITY</li>
    <li>BMP_ENTITY</li>
    <li>STATELESS</li>
    <li>STATEFUL</li>
</ul>
</p>
<p>
The containers can all be of the same type, or a mix of the types.
</p>
<p>
<file name="example_03.conf"><![CDATA[
<?xml version="1.0"?>
<openejb>

<Container id="My PostgreSQL Container" ctype="CMP_ENTITY"/>
<Container id="My MySQL Container" ctype="CMP_ENTITY"/>
<Container id="My InstantDB Container" ctype="CMP_ENTITY"/>
<Container id="My Stateful Session Container" ctype="STATEFUL"/>
<Container id="My Stateless Session Container" ctype="STATELESS"/>

</openejb>
]]></file>
</p>
</section>

<section title="Configuring your Container" ref-id="configure">

<p>
Of course, if you did have a configuration like the one above, it would 
be a bit pointless as all three of your CMP containers would be using the 
default CMP container configuration.  To acually configure a container 
differently, you simply need to specifiy new values for the properties 
that the container has.  These will override the defaults for that 
particular container declaration.  So it's possible to declare multiple 
containers of the same type, but configure each one differently.  
Let's use our CMP_ENTITY containers above as an example.
</p>

<p>
<file name="example_03.conf"><![CDATA[
<?xml version="1.0"?>
<openejb>

<Container id="My PostgreSQL Container" ctype="CMP_ENTITY">
    Global_TX_Database    conf/postgresql.cmp.global-database.xml
    Local_TX_Database     conf/postgresql.cmp.local-database.xml
</Container>

<Container id="My MySQL Container" ctype="CMP_ENTITY">
    Global_TX_Database  conf/mysql.cmp.global-database.xml
    Local_TX_Database   conf/mysql.cmp.local-database.xml
</Container>


<Container id="My InstantDB Container" ctype="CMP_ENTITY">
    Global_TX_Database  conf/instantdb.cmp.global-database.xml
    Local_TX_Database   conf/instantdb.cmp.local-database.xml
</Container>

<Container id="My Stateful Session Container" ctype="STATEFUL"/>
<Container id="My Stateless Session Container" ctype="STATELESS"/>

</openejb>
]]></file>
</p>

<p>
The format of the configuration parameters is actually just regular old 
java.util.Properties file format.  It keeps things simple and doesn't 
require you to type endless amounts of tags that are just name/value pairs 
anyway.  The java.util.Properties file format allows for spaces, tabs, 
colons, or equals signs to separate the name value pairs, so this would 
also be acceptable..</p>
<p>
<file name="example_03.conf"><![CDATA[
<?xml version="1.0"?>
<openejb>

<Container id="My PostgreSQL Container" ctype="CMP_ENTITY">
! This is a comment   
    Global_TX_Database = conf/postgresql.cmp.global-database.xml
    Local_TX_Database=conf/postgresql.cmp.local-database.xml
</Container>

<Container id="My MySQL Container" ctype="CMP_ENTITY">
# This is also a comment
    Global_TX_Database:conf/mysql.cmp.global-database.xml
    Local_TX_Database : conf/mysql.cmp.local-database.xml
</Container>


<Container id="My InstantDB Container" ctype="CMP_ENTITY">
    Global_TX_Database  conf/instantdb.cmp.global-database.xml
    Local_TX_Database           conf/instantdb.cmp.local-database.xml
</Container>

</openejb>
]]></file>
</p>
</section>

<section title="Configuration properties" ref-id="properties">
<p>
The actual properties that each container type accepts are different for 
each type.  Here is a reference for each container type.
<section title="CMP_ENTITY properties" ref-id="CMP_ENTITY.properties">
    <section title="PoolSize" ref-id="CMP_ENTITY.PoolSize">
        <p>
        The default size of the method ready bean pools. Every bean class gets its 
        own pool of this size. The value should be any integer.
        </p>
        <p>
        Default:
        <code-block>PoolSize 100</code-block>
        </p>
    </section>
    <section title="Global_TX_Database" ref-id="CMP_ENTITY.Global_TX_Database">
        <p>
The name of the database.xml file that is used for global or 
container managed transactions.  This will be used when the 
TransactionManager is managing the transaction, such as when 
the tx attribute is Supports(and there is a client tx), RequiresNew, 
Required or Manditory.
</p>

<p>
Specifies the configuration for obtaining database connections
and the mapping.xml schema which describes how beans map to 
the database.
        </p>
        <p>
        Default:
        <code-block>Global_TX_Database  conf/default.cmp_global_tx_database.xml</code-block>
        </p>
    </section>

    <section title="Local_TX_Database" ref-id="CMP_ENTITY.Local_TX_Database">
        <p>
The name of the database.xml file that is used for local or 
unspecified transaction contexts.  This will be used when 
the TransactionManager is not managing the transaction, such 
as when the tx attribute is Supports (and there is no client tx), 
NotSupported, or Never.
</p>

<p>
Specifies the configuration for obtaining database connections 
and the mapping.xml schema which describes how beans map to 
the database.
     </p>
     <p>
     Default:
     <code-block>Local_TX_Database   conf/default.cmp_local_tx_database.xml</code-block>
        </p>
    </section>
</section>
<section title="BMP_ENTITY properties" ref-id="BMP_ENTITY.properties">
<p>
The BMP Container has no customizable properties to override.                                             
</p>
</section>
<section title="STATEFUL properties" ref-id="STATEFUL.properties">
    <section title="Passivator" ref-id="STATEFUL.Passivator">
    <p>
The passivator is responsible for writing beans to disk 
at passivation time. Different passivators can be used 
by setting this property to the fully qualified class name
of the PassivationStrategy implementation. The passivator
is not responsible for invoking any callbacks or other 
processing, its only responsibly is to write the bean state
to disk.
<p>

</p>
<ul>Known implementations:
<li>org.openejb.core.stateful.RAFPassivater</li>
<li>org.openejb.core.stateful.SimplePassivater</li>
</ul>
    </p>
    <p>
    Default:
    <code-block>Passivator   org.openejb.core.stateful.SimplePassivater</code-block>
    </p>
    </section>
    <section title="TimeOut" ref-id="STATEFUL.TimeOut">
    <p>
Specifies the time to wait between invocations. This 
value is measured in minutes.  A value of 5 would 
result in a time-out of 5 minutes between invocations.
    </p>
    <p>
    Default:
    <code-block>TimeOut  20</code-block>
    </p>
    </section>
    <section title="PoolSize" ref-id="STATEFUL.PoolSize">
    <p>
Specifies the size of the bean pools for this 
stateful SessionBean container.
    </p>
    <p>
    Default:
    <code-block>PoolSize  100</code-block>
    </p>
    </section>
    <section title="BulkPassivate" ref-id="STATEFUL.BulkPassivate">
    <p>
Property name that specifies the number of instances
to passivate at one time when doing bulk passivation.
Must be less than the PoolSize.
    </p>
    <p>
    Default:
    <code-block>BulkPassivate  50</code-block>
    </p>
    </section>
</section>
<section title="STATELESS properties" ref-id="STATELESS.properties">
    <section title="StrictPooling" ref-id="STATEFUL.StrictPooling">
    <p>
Specifies the whether or not to this stateless 
SessionBean container should use a strict pooling algorithm.
true or false
    </p>
    <p>
    Default:
    <code-block>StrictPooling  true</code-block>
    </p>
    </section>
</section>
</p>
</section>
</body>
</document>
