Title: Containers

<a name="Containers-DeclaringyourContainer"></a>
# Declaring your Container

CMP Entity containers are defined with the <Container> element, under the
<openejb> 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 ctype attribute, specifially, a ctype attribute set to
CMP_ENTITY as such...

    <?xml version="1.0"?>
    <openejb>

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

    </openejb>

The really fun part is that the above configuration file is completely
legal! If you started the server and pointed to this file...
    
    ./openejb.sh start -conf example_01.conf
    
...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.
    
>     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]
> $
    
You see that. No beans, no JDBC resources, nothing but one CMP container
called "Default CMP Container".
    
# Naming your Container
    
You can call the container anything you want, just change the value of the
id attribute. Here is a container called "My PostgreSQL Contianer"
    
    <?xml version="1.0"?>
    <openejb>
    
    <Container id="My PostgreSQL Container" ctype="CMP_ENTITY"/>
    
    </openejb>


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.

> 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:

After deployment, you would end up with a configuration like this one

    <?xml version="1.0"?>
    <openejb>

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

    <Deployments jar="myCMPBean.jar" />

    </openejb>

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!
    
# Container types
    
    You can declare as many containers as you want. The available container
types are:
    	* CMP_ENTITY
    	* BMP_ENTITY
    	* STATELESS
    	* STATEFUL
    
The containers can all be of the same type, or a mix of the types.
    
    <?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>


<a name="Containers-ConfiguringyourContainer"></a>
# Configuring your Container

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.

    <?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>

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..
    
    <?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>



<a name="Containers-Configurationproperties"></a>
# Configuration properties

The actual properties that each container type accepts are different for
each type. Here is a reference for each container type.

<a name="Containers-CMP_ENTITYproperties"></a>
## CMP_ENTITY properties

<a name="Containers-PoolSize"></a>
### PoolSize


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.

Default:
bq. PoolSize 100

<a name="Containers-Global_TX_Database"></a>
### Global_TX_Database

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.

Specifies the configuration for obtaining database connections and the
mapping.xml schema which describes how beans map to the database.

Default:
bq. Global_TX_Database	conf/default.cmp_global_tx_database.xml

<a name="Containers-Local_TX_Database"></a>
### Local_TX_Database

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.

Specifies the configuration for obtaining database connections and the
mapping.xml schema which describes how beans map to the database.

Default:
bq. Local_TX_Database	conf/default.cmp_local_tx_database.xml

<a name="Containers-BMP_ENTITYproperties"></a>
## BMP_ENTITY properties

The BMP Container has no customizable properties to override.

<a name="Containers-STATEFULproperties"></a>
## STATEFUL properties

<a name="Containers-Passivator"></a>
### Passivator

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.


Known implementations:
	org.openejb.core.stateful.RAFPassivater
	org.openejb.core.stateful.SimplePassivater
Default:
bq. Passivator	 org.openejb.core.stateful.SimplePassivater

<a name="Containers-TimeOut"></a>
### TimeOut

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.

Default:
bq. TimeOut  20

<a name="Containers-PoolSize"></a>
### PoolSize

Specifies the size of the bean pools for this stateful SessionBean
container.

Default:
bq. PoolSize  100

<a name="Containers-BulkPassivate"></a>
### BulkPassivate

Property name that specifies the number of instances to passivate at one
time when doing bulk passivation. Must be less than the PoolSize.

Default:
bq. BulkPassivate  50

<a name="Containers-STATELESSproperties"></a>
## STATELESS properties

<a name="Containers-StrictPooling"></a>
### StrictPooling

Specifies the whether or not to this stateless SessionBean container should
use a strict pooling algorithm. true or false

Default:
bq. StrictPooling  true