http://git-wip-us.apache.org/repos/asf/tomee/blob/b93bd755/docs/containers-and-resources.md ---------------------------------------------------------------------- diff --git a/docs/containers-and-resources.md b/docs/containers-and-resources.md new file mode 100644 index 0000000..2dd4cf5 --- /dev/null +++ b/docs/containers-and-resources.md @@ -0,0 +1,483 @@ +index-group=Unrevised +type=page +status=published +title=Containers and Resources +~~~~~~ + +<div id="PageContent"> + <p><a name="ContainersandResources-containers"></a></p> +<p><a name="ContainersandResources-DefaultCMPContainercontainer"></a></p> +<h2><a name="ContainersandResources-CMPENTITY"></a>CMP_ENTITY</h2> +<p>Declarable in tomee.xml via</p> +<div style="border-width: 1px;" class="code panel"><div class="codeContent panelContent"> +<pre class="code-xml"><span class="code-tag"><Container id=<span class="code-quote">"Foo"</span> type=<span class="code-quote">"CMP_ENTITY"</span>></span> +<span class="code-tag"></Container></span> +</pre> +</div></div> +<p>Declarable in properties via</p> +<div style="border-width: 1px;" class="panel"><div class="panelContent"> +<p>Foo = new://Container?type=CMP_ENTITY</p> +</div></div> +<p>Supports the following properties</p> +<div class="table-wrap"> +<table class="mdtable"> <tbody> +<tr> +<th > Property Name </th> +<th > Description </th> +</tr> +<tr> +<td > CmpEngineFactory </td> +<td > Default value is <em>org.apache.openejb.core.cmp.jpa.JpaCmpEngineFactory</em>.</td> +</tr> +</tbody></table> +</div> + +<p><a name="ContainersandResources-TransactionManager"></a></p> +<h2><a name="ContainersandResources-TxMgr"></a>TransactionManager</h2> +<p>Declarable in tomee.xml via</p> +<div style="border-width: 1px;" class="code panel"><div class="codeContent panelContent"> +<pre class="code-xml"><span class="code-tag"><TransactionManager type=<span class="code-quote">"javax.transaction.TransactionManager"</span>></span> +<span class="code-tag"></TransactionManager></span> +</pre> +</div></div> +<p>Supports the following properties</p> +<div class="table-wrap"> +<table class="mdtable"> <tbody> +<tr> +<th > Property Name </th> +<th > Description </th> +</tr> +<tr> +<td > defaultTransactionTimeoutSeconds </td> +<td > Default value is <em>10 minutes</em>.</td> +</tr> +</tbody></table> +</div> + + +<p><a name="ContainersandResources-DefaultBMPContainercontainer"></a></p> +<h2><a name="ContainersandResources-BMPENTITY"></a>BMP_ENTITY</h2> +<p>Declarable in tomee.xml via</p> +<div style="border-width: 1px;" class="code panel"><div class="codeContent panelContent"> +<pre class="code-xml"><span class="code-tag"><Container id=<span class="code-quote">"Foo"</span> type=<span class="code-quote">"BMP_ENTITY"</span>></span> +<span class="code-tag"></Container></span> +</pre> +</div></div> +<p>Declarable in properties via</p> +<div style="border-width: 1px;" class="panel"><div class="panelContent"> +<p>Foo = new://Container?type=BMP_ENTITY</p> +</div></div> +<p>Supports the following properties</p> +<div class="table-wrap"> +<table class="mdtable"> <tbody> +<tr> +<th > Property Name </th> +<th > Description </th> +</tr> +<tr> +<td > PoolSize </td> +<td > Specifies the size of the bean pools for this<br class="atl-forced-newline"> bmp entity container.<br class="atl-forced-newline"> <br class="atl-forced-newline"> Default value is <em>10</em>.</td> +</tr> +</tbody></table> +</div> + + +<p><a name="ContainersandResources-DefaultStatelessContainercontainer"></a></p> +<h2><a name="ContainersandResources-STATELESS"></a>STATELESS</h2> +<p>Declarable in tomee.xml via</p> +<div style="border-width: 1px;" class="code panel"><div class="codeContent panelContent"> +<pre class="code-xml"><span class="code-tag"><Container id=<span class="code-quote">"Foo"</span> type=<span class="code-quote">"STATELESS"</span>></span> +<span class="code-tag"></Container></span> +</pre> +</div></div> +<p>Declarable in properties via</p> +<div style="border-width: 1px;" class="panel"><div class="panelContent"> +<p>Foo = new://Container?type=STATELESS</p> +</div></div> +<p>Supports the following properties</p> +<div class="table-wrap"> +<table class="mdtable"> <tbody> +<tr> +<th > Property Name </th> +<th > Description </th> +</tr> +<tr> +<td > TimeOut </td> +<td > Specifies the time to wait between invocations. This<br class="atl-forced-newline"> value is measured in milliseconds. A value of 5 would<br class="atl-forced-newline"> result in a time-out of 5 milliseconds between invocations.<br class="atl-forced-newline"> A value of zero would mean no timeout.<br class="atl-forced-newline"> <br class="atl-forced-newline"> Default value is <em>0</em>.</td> +</tr> +<tr> +<td > PoolSize </td> +<td > Specifies the size of the bean pools for this<br class="atl-forced-newline"> stateless SessionBean container.<br class="atl-forced-newline"> <br class="atl-forced-newline"> Default value is <em>10</em>.</td> +</tr> +<tr> +<td > StrictPooling </td> +<td > StrictPooling tells the container what to do when the pool<br class="atl-forced-newline"> reaches it's maximum size and there are incoming requests<br class="atl-forced-newline"> that need instances.<br class="atl-forced-newline"> <br class="atl-forced-newline"> With strict pooling, requests will have to wait for instances<br class="atl-forced-newline"> to become available. The pool size will never grow beyond the<br class="atl-forced-newline"> the set PoolSize value.<br class="atl-forced-newline"> <br class="atl-forced-newline"> Without strict pooling, the container will create temporary<br class="atl-forced-newline"> instances to meet demand. The instances will last for just one<br class="atl-forced-newline"> method invocation and then are removed.<br class="atl-forced-newline"> <br class="atl-forced-newline"> Default value is <em>true</em>.</td> +</tr> +</tbody></table> +</div> + + +<p><a name="ContainersandResources-DefaultStatefulContainercontainer"></a></p> +<h2><a name="ContainersandResources-STATEFUL"></a>STATEFUL</h2> +<p>Declarable in tomee.xml via</p> +<div style="border-width: 1px;" class="code panel"><div class="codeContent panelContent"> +<pre class="code-xml"><span class="code-tag"><Container id=<span class="code-quote">"Foo"</span> type=<span class="code-quote">"STATEFUL"</span>></span> +<span class="code-tag"></Container></span> +</pre> +</div></div> +<p>Declarable in properties via</p> +<div style="border-width: 1px;" class="panel"><div class="panelContent"> +<p>Foo = new://Container?type=STATEFUL</p> +</div></div> +<p>Supports the following properties</p> +<div class="table-wrap"> +<table class="mdtable"> <tbody> +<tr> +<th > Property Name </th> +<th > Description </th> +</tr> +<tr> +<td > Passivator </td> +<td > The passivator is responsible for writing beans to disk<br class="atl-forced-newline"> at passivation time. Different passivators can be used<br class="atl-forced-newline"> by setting this property to the fully qualified class name<br class="atl-forced-newline"> of the PassivationStrategy implementation. The passivator<br class="atl-forced-newline"> is not responsible for invoking any callbacks or other<br class="atl-forced-newline"> processing, its only responsibly is to write the bean state<br class="atl-forced-newline"> to disk.<br class="atl-forced-newline"> <br class="atl-forced-newline"> Known implementations:<br class="atl-forced-newline"> org.apache.openejb.core.stateful.RAFPassivater<br class="atl-forced-newline"> org.apache.openejb.core.stateful.SimplePassivater<br class="atl-forced-newline"> <br class="atl-forced-newline"> Default value is <em>org.apache.openejb.core.stateful.SimplePassivater</em>.</td> +</tr> +<tr> +<td > TimeOut </td> +<td > Specifies the time to wait between invocations. This<br class="atl-forced-newline"> value is measured in minutes. A value of 5 would<br class="atl-forced-newline"> result in a time-out of 5 minutes between invocations.<br class="atl-forced-newline"> A value of zero would mean no timeout.<br class="atl-forced-newline"> <br class="atl-forced-newline"> Default value is <em>20</em>.</td> +</tr> +<tr> +<td > PoolSize </td> +<td > Specifies the size of the bean pools for this<br class="atl-forced-newline"> stateful SessionBean container.<br class="atl-forced-newline"> <br class="atl-forced-newline"> Default value is <em>1000</em>.</td> +</tr> +<tr> +<td > BulkPassivate </td> +<td > Property name that specifies the number of instances<br class="atl-forced-newline"> to passivate at one time when doing bulk passivation.<br class="atl-forced-newline"> <br class="atl-forced-newline"> Default value is <em>100</em>.</td> +</tr> +</tbody></table> +</div> + + +<p><a name="ContainersandResources-DefaultMDBContainercontainer"></a></p> +<h2><a name="ContainersandResources-MESSAGE"></a>MESSAGE</h2> +<p>Declarable in tomee.xml via</p> +<div style="border-width: 1px;" class="code panel"><div class="codeContent panelContent"> +<pre class="code-xml"><span class="code-tag"><Container id=<span class="code-quote">"Foo"</span> type=<span class="code-quote">"MESSAGE"</span>></span> +<span class="code-tag"></Container></span> +</pre> +</div></div> +<p>Declarable in properties via</p> +<div style="border-width: 1px;" class="panel"><div class="panelContent"> +<p>Foo = new://Container?type=MESSAGE</p> +</div></div> +<p>Supports the following properties</p> +<div class="table-wrap"> +<table class="mdtable"> <tbody> +<tr> +<th > Property Name </th> +<th > Description </th> +</tr> +<tr> +<td > ResourceAdapter </td> +<td > The resource adapter delivers messages to the container<br class="atl-forced-newline"> <br class="atl-forced-newline"> Default value is <em>Default JMS Resource Adapter</em>.</td> +</tr> +<tr> +<td > MessageListenerInterface </td> +<td > Specifies the message listener interface handled by this container<br class="atl-forced-newline"> <br class="atl-forced-newline"> Default value is <em>javax.jms.MessageListener</em>.</td> +</tr> +<tr> +<td > ActivationSpecClass </td> +<td > Specifies the activation spec class<br class="atl-forced-newline"> <br class="atl-forced-newline"> Default value is <em>org.apache.activemq.ra.ActiveMQActivationSpec</em>.</td> +</tr> +<tr> +<td > InstanceLimit </td> +<td > Specifies the maximum number of bean instances that are<br class="atl-forced-newline"> allowed to exist for each MDB deployment.<br class="atl-forced-newline"> <br class="atl-forced-newline"> Default value is <em>10</em>.</td> +</tr> +</tbody></table> +</div> + + + +<p><a name="ContainersandResources-resources"></a></p> +<h1><a name="ContainersandResources-Resources"></a>Resources</h1> +<p><a name="ContainersandResources-DefaultJDBCDatabaseresource"></a></p> +<h2><a name="ContainersandResources-javax.sql.DataSource"></a>javax.sql.DataSource</h2> +<p>Declarable in tomee.xml via</p> +<div style="border-width: 1px;" class="code panel"><div class="codeContent panelContent"> +<pre class="code-xml"><span class="code-tag"><Resource id=<span class="code-quote">"Foo"</span> type=<span class="code-quote">"javax.sql.DataSource"</span>></span> +<span class="code-tag"></Resource></span> +</pre> +</div></div> +<p>Declarable in properties via</p> +<div style="border-width: 1px;" class="panel"><div class="panelContent"> +<p>Foo = new://Resource?type=javax.sql.DataSource</p> +</div></div> +<p>Supports the following properties</p> +<div class="table-wrap"> +<table class="mdtable"> <tbody> +<tr> +<th > Property Name </th> +<th > Description </th> +</tr> +<tr> +<td > JtaManaged </td> +<td > Determines wether or not this data source should be JTA managed<br class="atl-forced-newline"> or user managed. If set to 'true' it will automatically be enrolled<br class="atl-forced-newline"> in any ongoing transactions. Calling begin/commit/rollback or setAutoCommit<br class="atl-forced-newline"> on the datasource or connection will not be allowed. If you need to perform<br class="atl-forced-newline"> these functions yourself, set JtaManaged to 'false'<br class="atl-forced-newline"> <br class="atl-forced-newline"> In terms of JPA persistence.xml:<br class="atl-forced-newline"> "JtaManaged=true" can be used as a 'jta-data-source'<br class="atl-forced-newline"> "JtaManaged=false" can be used as a 'non-jta-data-source'<br class="atl-forced-newline"> <br class="atl-forced-newline"> Default value is <em>true</em>.</td> +</tr> +<tr> +<td > JdbcDriver </td> +<td > Driver class name<br class="atl-forced-newline"> <br class="atl-forced-newline"> Default value is <em>org.hsqldb.jdbcDriver</em>.</td> +</tr> +<tr> +<td > JdbcUrl </td> +<td > Url for creating connections<br class="atl-forced-newline"> <br class="atl-forced-newline"> Default value is <em>jdbc:hsqldb:file:data/hsqldb/hsqldb</em>.</td> +</tr> +<tr> +<td > UserName </td> +<td > Default user name<br class="atl-forced-newline"> <br class="atl-forced-newline"> Default value is <em>sa</em>.</td> +</tr> +<tr> +<td > Password </td> +<td > Default password</td> +</tr> +<tr> +<td > ConnectionProperties </td> +<td > The connection properties that will be sent to the JDBC<br class="atl-forced-newline"> driver when establishing new connections<br class="atl-forced-newline"> <br class="atl-forced-newline"> Format of the string must be [propertyName=property;]*<br class="atl-forced-newline"> <br class="atl-forced-newline"> NOTE - The "user" and "password" properties will be passed<br class="atl-forced-newline"> explicitly, so they do not need to be included here.</td> +</tr> +<tr> +<td > DefaultAutoCommit </td> +<td > The default auto-commit state of new connections<br class="atl-forced-newline"> <br class="atl-forced-newline"> Default value is <em>true</em>.</td> +</tr> +<tr> +<td > DefaultReadOnly </td> +<td > The default read-only state of new connections<br class="atl-forced-newline"> If not set then the setReadOnly method will not be called.<br class="atl-forced-newline"> (Some drivers don't support read only mode, ex: Informix)</td> +</tr> +<tr> +<td > DefaultTransactionIsolation </td> +<td > The default TransactionIsolation state of new connections<br class="atl-forced-newline"> If not set then the setTransactionIsolation method will not<br class="atl-forced-newline"> be called. The allowed values for this property are:<br class="atl-forced-newline"> NONE<br class="atl-forced-newline"> READ_COMMITTED<br class="atl-forced-newline"> READ_UNCOMMITTED<br class="atl-forced-newline"> REPEATABLE_READ<br class="atl-forced-newline"> SERIALIZABLE<br class="atl-forced-newline"> <br class="atl-forced-newline"> Note: Most JDBC drivers do not support all isolation levels</td> +</tr> +<tr> +<td > InitialSize </td> +<td > The initial number of connections that are created when the<br class="atl-forced-newline"> pool is started<br class="atl-forced-newline"> <br class="atl-forced-newline"> Default value is <em>0</em>.</td> +</tr> +<tr> +<td > MaxActive </td> +<td > The maximum number of active connections that can be<br class="atl-forced-newline"> allocated from this pool at the same time, or a negative<br class="atl-forced-newline"> number for no limit.<br class="atl-forced-newline"> <br class="atl-forced-newline"> Default value is <em>20</em>.</td> +</tr> +<tr> +<td > MaxIdle </td> +<td > The maximum number of connections that can remain idle in<br class="atl-forced-newline"> the pool, without extra ones being released, or a negative<br class="atl-forced-newline"> number for no limit.<br class="atl-forced-newline"> <br class="atl-forced-newline"> Default value is <em>20</em>.</td> +</tr> +<tr> +<td > MinIdle </td> +<td > The minimum number of connections that can remain idle in<br class="atl-forced-newline"> the pool, without extra ones being created, or zero to<br class="atl-forced-newline"> create none.<br class="atl-forced-newline"> <br class="atl-forced-newline"> Default value is <em>0</em>.</td> +</tr> +<tr> +<td > MaxWait </td> +<td > The maximum number of milliseconds that the pool will wait<br class="atl-forced-newline"> (when there are no available connections) for a connection<br class="atl-forced-newline"> to be returned before throwing an exception, or -1 to wait<br class="atl-forced-newline"> indefinitely.<br class="atl-forced-newline"> <br class="atl-forced-newline"> Default value is <em>-1</em>.</td> +</tr> +<tr> +<td > ValidationQuery </td> +<td > The SQL query that will be used to validate connections from<br class="atl-forced-newline"> this pool before returning them to the caller. If specified,<br class="atl-forced-newline"> this query MUST be an SQL SELECT statement that returns at<br class="atl-forced-newline"> least one row.</td> +</tr> +<tr> +<td > TestOnBorrow </td> +<td > If true connections will be validated before being borrowed<br class="atl-forced-newline"> from the pool. If the validation fails, the connection is<br class="atl-forced-newline"> destroyed, and a new conection will be retrieved from the<br class="atl-forced-newline"> pool (and validated).<br class="atl-forced-newline"> <br class="atl-forced-newline"> NOTE - for a true value to have any effect, the<br class="atl-forced-newline"> ValidationQuery parameter must be set.<br class="atl-forced-newline"> <br class="atl-forced-newline"> Default value is <em>true</em>.</td> +</tr> +<tr> +<td > TestOnReturn </td> +<td > If true connections will be validated before being returned<br class="atl-forced-newline"> to the pool. If the validation fails, the connection is<br class="atl-forced-newline"> destroyed instead of being returned to the pool.<br class="atl-forced-newline"> <br class="atl-forced-newline"> NOTE - for a true value to have any effect, the<br class="atl-forced-newline"> ValidationQuery parameter must be set.<br class="atl-forced-newline"> <br class="atl-forced-newline"> Default value is <em>false</em>.</td> +</tr> +<tr> +<td > TestWhileIdle </td> +<td > If true connections will be validated by the idle connection<br class="atl-forced-newline"> evictor (if any). If the validation fails, the connection is<br class="atl-forced-newline"> destroyed and removed from the pool<br class="atl-forced-newline"> <br class="atl-forced-newline"> NOTE - for a true value to have any effect, the<br class="atl-forced-newline"> timeBetweenEvictionRunsMillis property must be a positive<br class="atl-forced-newline"> number and the ValidationQuery parameter must be set.<br class="atl-forced-newline"> <br class="atl-forced-newline"> Default value is <em>false</em>.</td> +</tr> +<tr> +<td > TimeBetweenEvictionRunsMillis </td> +<td > The number of milliseconds to sleep between runs of the idle<br class="atl-forced-newline"> connection evictor thread. When set to a negative number, no<br class="atl-forced-newline"> idle connection evictor thread will be run.<br class="atl-forced-newline"> <br class="atl-forced-newline"> Default value is <em>-1</em>.</td> +</tr> +<tr> +<td > NumTestsPerEvictionRun </td> +<td > The number of connectionss to examine during each run of the<br class="atl-forced-newline"> idle connection evictor thread (if any).<br class="atl-forced-newline"> <br class="atl-forced-newline"> Default value is <em>3</em>.</td> +</tr> +<tr> +<td > MinEvictableIdleTimeMillis </td> +<td > The minimum amount of time a connection may sit idle in the<br class="atl-forced-newline"> pool before it is eligable for eviction by the idle<br class="atl-forced-newline"> connection evictor (if any).<br class="atl-forced-newline"> <br class="atl-forced-newline"> Default value is <em>1800000</em>.</td> +</tr> +<tr> +<td > PoolPreparedStatements </td> +<td > If true, a statement pool is created for each Connection and<br class="atl-forced-newline"> PreparedStatements created by one of the following methods are<br class="atl-forced-newline"> pooled:<br class="atl-forced-newline"> public PreparedStatement prepareStatement(String sql);<br class="atl-forced-newline"> public PreparedStatement prepareStatement(String sql,<br class="atl-forced-newline"> int resultSetType,<br class="atl-forced-newline"> int resultSetConcurrency)<br class="atl-forced-newline"> <br class="atl-forced-newline"> Default value is <em>false</em>.</td> +</tr> +<tr> +<td > MaxOpenPreparedStatements </td> +<td > The maximum number of open statements that can be allocated<br class="atl-forced-newline"> from the statement pool at the same time, or zero for no<br class="atl-forced-newline"> limit.<br class="atl-forced-newline"> <br class="atl-forced-newline"> NOTE - Some drivers have limits on the number of open<br class="atl-forced-newline"> statements, so make sure there are some resources left<br class="atl-forced-newline"> for the other (non-prepared) statements.<br class="atl-forced-newline"> <br class="atl-forced-newline"> Default value is <em>0</em>.</td> +</tr> +<tr> +<td > AccessToUnderlyingConnectionAllowed </td> +<td > If true the raw physical connection to the database can be<br class="atl-forced-newline"> accessed using the following construct:<br class="atl-forced-newline"> Connection conn = ds.getConnection();<br class="atl-forced-newline"> Connection rawConn = ((DelegatingConnection) conn).getInnermostDelegate();<br class="atl-forced-newline"> ...<br class="atl-forced-newline"> conn.close()<br class="atl-forced-newline"> <br class="atl-forced-newline"> Default is false, because misbehaving programs can do harmfull<br class="atl-forced-newline"> things to the raw connection shuch as closing the raw<br class="atl-forced-newline"> connection or continuing to use the raw connection after it<br class="atl-forced-newline"> has been assigned to another logical connection. Be carefull<br class="atl-forced-newline"> and only use when you need direct access to driver specific<br class="atl-f orced-newline"> extentions.<br class="atl-forced-newline"> <br class="atl-forced-newline"> NOTE: Do NOT close the underlying connection, only the<br class="atl-forced-newline"> original logical connection wrapper.<br class="atl-forced-newline"> <br class="atl-forced-newline"> Default value is <em>false</em>.</td> +</tr> +</tbody></table> +</div> + + +<p><a name="ContainersandResources-DefaultJMSResourceAdapterresource"></a></p> +<h2><a name="ContainersandResources-ActiveMQResourceAdapter"></a>ActiveMQResourceAdapter</h2> +<p>Declarable in tomee.xml via</p> +<div style="border-width: 1px;" class="code panel"><div class="codeContent panelContent"> +<pre class="code-xml"><span class="code-tag"><Resource id=<span class="code-quote">"Foo"</span> type=<span class="code-quote">"ActiveMQResourceAdapter"</span>></span> +<span class="code-tag"></Resource></span> +</pre> +</div></div> +<p>Declarable in properties via</p> +<div style="border-width: 1px;" class="panel"><div class="panelContent"> +<p>Foo = new://Resource?type=ActiveMQResourceAdapter</p> +</div></div> +<p>Supports the following properties</p> +<div class="table-wrap"> +<table class="mdtable"> <tbody> +<tr> +<th > Property Name </th> +<th > Description </th> +</tr> +<tr> +<td > BrokerXmlConfig </td> +<td > Broker configuration<br class="atl-forced-newline"> <br class="atl-forced-newline"> Default value is <em>broker:(tcp://localhost:61616)?useJmx=false</em>.</td> +</tr> +<tr> +<td > ServerUrl </td> +<td > Broker address<br class="atl-forced-newline"> <br class="atl-forced-newline"> Default value is <em>vm://localhost?async=true</em>.</td> +</tr> +<tr> +<td > DataSource </td> +<td > DataSource for persistence messages<br class="atl-forced-newline"> <br class="atl-forced-newline"> Default value is <em>Default Unmanaged JDBC Database</em>.</td> +</tr> +</tbody></table> +</div> + + +<p><a name="ContainersandResources-DefaultJMSConnectionFactoryresource"></a></p> +<h2><a name="ContainersandResources-javax.jms.ConnectionFactory"></a>javax.jms.ConnectionFactory</h2> +<p>Declarable in tomee.xml via</p> +<div style="border-width: 1px;" class="code panel"><div class="codeContent panelContent"> +<pre class="code-xml"><span class="code-tag"><Resource id=<span class="code-quote">"Foo"</span> type=<span class="code-quote">"javax.jms.ConnectionFactory"</span>></span> +<span class="code-tag"></Resource></span> +</pre> +</div></div> +<p>Declarable in properties via</p> +<div style="border-width: 1px;" class="panel"><div class="panelContent"> +<p>Foo = new://Resource?type=javax.jms.ConnectionFactory</p> +</div></div> +<p>Supports the following properties</p> +<div class="table-wrap"> +<table class="mdtable"> <tbody> +<tr> +<th > Property Name </th> +<th > Description </th> +</tr> +<tr> +<td > ResourceAdapter </td> +<td > Default value is <em>Default JMS Resource Adapter</em>.</td> +</tr> +<tr> +<td > TransactionSupport </td> +<td > Specifies if the connection is enrolled in global transaction<br class="atl-forced-newline"> allowed values: xa, local or none<br class="atl-forced-newline"> <br class="atl-forced-newline"> Default value is <em>xa</em>.</td> +</tr> +<tr> +<td > PoolMaxSize </td> +<td > Maximum number of physical connection to the ActiveMQ broker<br class="atl-forced-newline"> <br class="atl-forced-newline"> Default value is <em>10</em>.</td> +</tr> +<tr> +<td > PoolMinSize </td> +<td > Minimum number of physical connection to the ActiveMQ broker<br class="atl-forced-newline"> <br class="atl-forced-newline"> Default value is <em>0</em>.</td> +</tr> +<tr> +<td > ConnectionMaxWaitMilliseconds </td> +<td > Maximum amount of time to wait for a connection<br class="atl-forced-newline"> <br class="atl-forced-newline"> Default value is <em>5000</em>.</td> +</tr> +<tr> +<td > ConnectionMaxIdleMinutes </td> +<td > Maximum amount of time a connection can be idle before being reclaimed<br class="atl-forced-newline"> <br class="atl-forced-newline"> Default value is <em>15</em>.</td> +</tr> +</tbody></table> +</div> + + +<p><a name="ContainersandResources-DefaultQueueresource"></a></p> +<h2><a name="ContainersandResources-javax.jms.Queue"></a>javax.jms.Queue</h2> +<p>Declarable in tomee.xml via</p> +<div style="border-width: 1px;" class="code panel"><div class="codeContent panelContent"> +<pre class="code-xml"><span class="code-tag"><Resource id=<span class="code-quote">"Foo"</span> type=<span class="code-quote">"javax.jms.Queue"</span>></span> +<span class="code-tag"></Resource></span> +</pre> +</div></div> +<p>Declarable in properties via</p> +<div style="border-width: 1px;" class="panel"><div class="panelContent"> +<p>Foo = new://Resource?type=javax.jms.Queue</p> +</div></div> +<p>Supports the following properties</p> +<div class="table-wrap"> +<table class="mdtable"> <tbody> +<tr> +<th > Property Name </th> +<th > Description </th> +</tr> +<tr> +<td > destination </td> +<td > Specifies the name of the queue</td> +</tr> +</tbody></table> +</div> + + +<p><a name="ContainersandResources-DefaultTopicresource"></a></p> +<h2><a name="ContainersandResources-javax.jms.Topic"></a>javax.jms.Topic</h2> +<p>Declarable in tomee.xml via</p> +<div style="border-width: 1px;" class="code panel"><div class="codeContent panelContent"> +<pre class="code-xml"><span class="code-tag"><Resource id=<span class="code-quote">"Foo"</span> type=<span class="code-quote">"javax.jms.Topic"</span>></span> +<span class="code-tag"></Resource></span> +</pre> +</div></div> +<p>Declarable in properties via</p> +<div style="border-width: 1px;" class="panel"><div class="panelContent"> +<p>Foo = new://Resource?type=javax.jms.Topic</p> +</div></div> +<p>Supports the following properties</p> +<div class="table-wrap"> +<table class="mdtable"> <tbody> +<tr> +<th > Property Name </th> +<th > Description </th> +</tr> +<tr> +<td > destination </td> +<td > Specifies the name of the topic</td> +</tr> +</tbody></table> +</div> + + +<p><a name="ContainersandResources-DefaultORBresource"></a></p> +<h2><a name="ContainersandResources-org.omg.CORBA.ORB"></a>org.omg.CORBA.ORB</h2> +<p>Declarable in tomee.xml via</p> +<div style="border-width: 1px;" class="code panel"><div class="codeContent panelContent"> +<pre class="code-xml"><span class="code-tag"><Resource id=<span class="code-quote">"Foo"</span> type=<span class="code-quote">"org.omg.CORBA.ORB"</span>></span> +<span class="code-tag"></Resource></span> +</pre> +</div></div> +<p>Declarable in properties via</p> +<div style="border-width: 1px;" class="panel"><div class="panelContent"> +<p>Foo = new://Resource?type=org.omg.CORBA.ORB</p> +</div></div> +<p>No properties.</p> + +<p><a name="ContainersandResources-DefaultMailSessionresource"></a></p> +<h2><a name="ContainersandResources-javax.mail.Session"></a>javax.mail.Session</h2> +<p>Declarable in tomee.xml via</p> +<div style="border-width: 1px;" class="code panel"><div class="codeContent panelContent"> +<pre class="code-xml"><span class="code-tag"><Resource id=<span class="code-quote">"Foo"</span> type=<span class="code-quote">"javax.mail.Session"</span>></span> +<span class="code-tag"></Resource></span> +</pre> +</div></div> +<p>Declarable in properties via</p> +<div style="border-width: 1px;" class="panel"><div class="panelContent"> +<p>Foo = new://Resource?type=javax.mail.Session</p> +</div></div> +<p>No properties.</p> +
http://git-wip-us.apache.org/repos/asf/tomee/blob/b93bd755/docs/contrib/debug/debug-intellij.md ---------------------------------------------------------------------- diff --git a/docs/contrib/debug/debug-intellij.md b/docs/contrib/debug/debug-intellij.md new file mode 100644 index 0000000..3450ee1 --- /dev/null +++ b/docs/contrib/debug/debug-intellij.md @@ -0,0 +1,133 @@ +index-group=Unrevised +type=page +status=published +~~~~~~ +<a name='DEBUGIDE'></a> +#Debugging an Apache TomEE App in Intellij IDEA + +Stepping through the [TomEE](http://tomee.apache.org/apache-tomee.html) source code is a must-to-follow step if you want to understand how TomEE works and later contribute. This is a guide to quickly start your debugging session with TomEE as a TomEE developer. + +This guide assumes that: + + - Linux is the OS + - IntelliJ IDEA 13.1.3 is the IDE + - Maven 3.0.5 or better is installed + + +###Download the Source Code + +For beginners it is recommended not to start with the trunk, because it is common to have some blockers or non-stable functionality which could bring your learning to a halt. So first start with the latest stable released source code. Move to trunk once you are ready to do some code modification on TomEE. + +[Click here to download TomEE 1.7.1 Source code](http://www.apache.org/dyn/closer.cgi/tomee/tomee-1.7.1/openejb-4.7.1-source-release.zip) + +###Build the Source Code + +First extract the zip file named **openejb-4.7.1-source-release.zip** to any location. Lets assume it is your home folder. + +> unzip openejb-4.7.1-source-release -d ~ + +The above command will create the **openejb-4.7.1** directory in your home directory. + +Even though you can do a full build, We will run the following command to do a quick build so that you can have your meal before your hunger kills you. + +> mvn -Pquick -Dsurefire.useFile=false -DdisableXmlReport=true -DuniqueVersion=false -ff -Dassemble -DskipTests -DfailIfNoTests=false clean install + +More details about building the product from the source can be found [here](http://tomee.apache.org/dev/source-code.html). + +###Deploy TomEE + +The TomEE build builds several distributions (zip & war files) to cater the different needs of different users. Here we discuss about the tomee plus distribution & TomEE war distribution only. TomEE+ is the full feature packed distribution from TomEE. + +TomEE+ zip location: + +> ~/openejb-4.7.1/tomee/apache-tomee/target/apache-tomee-plus-1.7.1.zip + +Unzip the zip into your home directory (or any other location) + +> unzip ~/openejb-4.7.1/tomee/apache-tomee/target/apache-tomee-plus-1.7.1.zip -d ~ + +You will find the directory **apache-tomee-plus-1.7.1** in your home folder. Lets run the TomEE. + +> cd ~/apache-tomee-plus-1.7.1/bin <br /> +> ./catalina.sh run <br /> + +"INFO: Server startup in xxxx ms" is the Green light! + +###Prepare your IDE + +Lets prepare our IntelliJ IDEA for the debugging session. + +Start IntelliJ IDEA and Click the Import Project link + + + +Select the ~/openejb-4.7.1 directory and press OK + +Select import project from external model & Maven as the external model. + + + +Press Next on this screen. + + + +Select the main profile. + + + +Select the org.apache.openejb:openejb:4.7.1 + + + +Select the JDK you want to use with. + + + +Give the project a name and press Finish. + + + +Now your IDE will load the project. + +###First Breakpoint + +Next step is to put a breakpoint at the place where the code is triggered. Lets understand how the code is triggered. + +TomEE+ is created on top of Tomcat. TomEE registers a Tomcat Lifecycle Listener **"org.apache.tomee.catalina.ServerListener"** on **server.xml** file. + +All the Tomcat lifecycle events i.e. before_init, after_init, start, before_stop etc... are received by the **lifecycleEvent** method of the ServerListener. + +The execution of TomEE code starts in this lifecycleEvent method. So the first breakpoint should be on the lifecycleEvent method. + +###Run TomEE+ in debug mode + +If you simply run **catalina.sh jpda run** in the bin folder of tomee deployment, the server starts in the debug mode but it will quckly pass your breakpoint before you attach your IDE to the server process. + +So we set** JPDA_SUSPEND="y"** before we start our debugging. This will tell the server "Do not proceed until the Debugger tool is attached to the process" + +The convenient way of doing this is adding this line to catalina.sh file right after the #!/bin/sh line. + +> \#!/bin/sh +> JPDA_SUSPEND="y" +> +Now to time to run TomEE+ on debug mode. + +> ~/apache-tomee-plus-1.7.1/bin/catalina.sh jpda run + +The terminal should hang with the message **"Listening for transport dt_socket at address: 8000"** + +###Attach IntelliJ IDEA debugger + +* Menu Bar > Run > Edit Configurations +* Press the "**+**" button on the top left corner to get the Add new configuration menu +* Select "Remote" from the Add new configuration menu +* Give a name (I gave "TomEE DEBUG") to this new configuration and set the Port to 8000 +* Click OK. + +</div> + +To start debugging your TomEE+ + +Main Menu > Run > Debug TomEE DEBUG + +Congratulations! You hit the break point you put at the startup of the TomEE code. Carry on with your debugging session to learn more. \ No newline at end of file http://git-wip-us.apache.org/repos/asf/tomee/blob/b93bd755/docs/custom-injection.md ---------------------------------------------------------------------- diff --git a/docs/custom-injection.md b/docs/custom-injection.md new file mode 100644 index 0000000..2a46922 --- /dev/null +++ b/docs/custom-injection.md @@ -0,0 +1,193 @@ +index-group=Unrevised +type=page +status=published +title=Custom Injection +~~~~~~ +# Overview + +As noted in the [Injection of env-entry Example](injection-of-env-entry-example.html) +, the EJB 3.0 supported env-entry types are fairly limited. Also the use +of several <env-entry> tags in an ejb-jar.xml can get a bit verbose. + +OpenEJB does not restrict you to just these data types or require you to +use an ejb-jar.xml to declare them. + + - `@Resource` can be used on any type for which there is +`java.beans.PropertyEditor` + - You may `install your own` PropertyEditors and package them with your +app. + - Java Generics are supported (e.g. List<URI> myURIs) + - You may use a `META-INF/env-entries.properties` file as an alternative +to an ejb-jar.xml + +See [Built-in Type Converters](built-in-type-converters.html) +for a full list of supported env-entry types. + +The source for this example is the "custom-injection" directory located in +the [openejb-examples.zip](downloads.html) +available on the [download page](http://tomee.apache.org/downloads.html). + +<a name="CustomInjection-TheCode"></a> +# The Code + +<a name="CustomInjection-BeanClass"></a> +## Bean Class + + @Stateless + public class Stratocaster { + + @Resource(name = "pickups") + private List<Pickup> pickups; + + @Resource(name = "style") + private Style style; + + @Resource(name = "dateCreated") + private Date dateCreated; + + @Resource(name = "guitarStringGuages") + private Map<String, Float> guitarStringGuages; + + @Resource(name = "certificateOfAuthenticity") + private File certificateOfAuthenticity; + + public Date getDateCreated() { + return dateCreated; + } + + /** + * Gets the guage of the electric guitar strings + * used in this guitar. + * + * @param string + * @return + */ + public float getStringGuage(String string) { + return guitarStringGuages.get(string); + } + + public List<Pickup> getPickups() { + return pickups; + } + + public Style getStyle() { + return style; + } + + public File getCertificateOfAuthenticity() { + return certificateOfAuthenticity; + } + } + +<a name="CustomInjection-TheMETA-INF/env-entries.propertiesfile"></a> +## The META-INF/env-entries.properties file + + guitarStringGuages=E1=0.052\nA=0.042\nD=0.030\nG=0.017\nB=0.013\nE=0.010 + certificateOfAuthenticity=/tmp/strat-certificate.txt + dateCreated=1962-03-01 + pickups=S,S,S + style=VINTAGE + +<a name="CustomInjection-TheCustomTypeandEditor"></a> +## The Custom Type and Editor + +Support for java.lang.Enum types is already built-in, but we've decided +we'd like to allow abbreviated versions of the enum constants to be usable. + We do this by creating a custom PropertyEditor for our Pickup enum like +so: + + public class PickupEditor extends java.beans.PropertyEditorSupport { + public void setAsText(String text) throws IllegalArgumentException { + text = text.trim(); + + if (text.equalsIgnoreCase("H")) setValue(Pickup.HUMBUCKER); + else if (text.equalsIgnoreCase("S")) setValue(Pickup.SINGLE_COIL); + else throw new IllegalStateException("H and S are the only supported Pickup aliases"); + } + } + +We cleverly install this PropertyEditor in a static block in the Pickup +class that will be executed should someone actually reference the Pickup +type. + + public enum Pickup { + + HUMBUCKER, + SINGLE_COIL; + + // Here's the little magic where we register the PickupEditor + // which knows how to create this object from a string. + // You can add any of your own Property Editors in the same way. + static { + PropertyEditorManager.registerEditor(Pickup.class, PickupEditor.class); + } + } + +<a name="CustomInjection-TestCase"></a> +# Test Case + + public class StratocasterTest extends TestCase { + + @EJB + private Stratocaster strat; + + public void test() throws Exception { + EJBContainer.createEJBContainer().getContext().bind("inject", this); + + Date date = DateFormat.getDateInstance(DateFormat.MEDIUM, Locale.US).parse("Mar 1, 1962"); + assertEquals("Strat.getDateCreated()", date, strat.getDateCreated()); + + List<Pickup> pickups = asList(Pickup.SINGLE_COIL, Pickup.SINGLE_COIL, Pickup.SINGLE_COIL); + assertEquals("Strat.getPickups()", pickups, strat.getPickups()); + + assertEquals("Strat.getStyle()", Style.VINTAGE, strat.getStyle()); + + assertEquals("Strat.getStringGuage(\"E1\")", 0.052F, strat.getStringGuage("E1")); + assertEquals("Strat.getStringGuage(\"A\")", 0.042F, strat.getStringGuage("A")); + assertEquals("Strat.getStringGuage(\"D\")", 0.030F, strat.getStringGuage("D")); + assertEquals("Strat.getStringGuage(\"G\")", 0.017F, strat.getStringGuage("G")); + assertEquals("Strat.getStringGuage(\"B\")", 0.013F, strat.getStringGuage("B")); + assertEquals("Strat.getStringGuage(\"E\")", 0.010F, strat.getStringGuage("E")); + + File file = new File("/tmp/strat-certificate.txt"); + assertEquals("Strat.getCertificateOfAuthenticity()", file,strat.getCertificateOfAuthenticity()); + + + } + } + +<a name="CustomInjection-Runningit"></a> +# Running it + +Running the example is fairly simple. In the "custom-injection" directory of the [examples zip](openejb:download.html), just run: + +> $ mvn clean install + +Which should create output like the following. + + + ------------------------------------------------------- + T E S T S + ------------------------------------------------------- + Running org.superbiz.enventries.StratocasterTest + Apache OpenEJB 3.1-SNAPSHOT build: 20080409-12:05 + http://tomee.apache.org/ + INFO - openejb.home = /Users/dblevins/work/openejb3/examples/custom-injection + INFO - openejb.base = /Users/dblevins/work/openejb3/examples/custom-injection + INFO - Configuring Service(id=Default Security Service, type=SecurityService, provider-id=Default Security Service) + INFO - Configuring Service(id=Default Transaction Manager, type=TransactionManager, provider-id=Default Transaction Manager) + INFO - Configuring Service(id=Default JDK 1.3 ProxyFactory, type=ProxyFactory, provider-id=Default JDK 1.3 ProxyFactory) + INFO - Found EjbModule in classpath: /Users/dblevins/work/openejb3/examples/custom-injection/target/classes + INFO - Configuring app: /Users/dblevins/work/openejb3/examples/custom-injection/target/classes + INFO - Configuring Service(id=Default Stateless Container, type=Container, provider-id=Default Stateless Container) + INFO - Auto-creating a container for bean StratocasterImpl: Container(type=STATELESS, id=Default Stateless Container) + INFO - Loaded Module: /Users/dblevins/work/openejb3/examples/custom-injection/target/classes + INFO - Assembling app: /Users/dblevins/work/openejb3/examples/custom-injection/target/classes + INFO - Jndi(name=StratocasterImplLocal) --> Ejb(deployment-id=StratocasterImpl) + INFO - Created Ejb(deployment-id=StratocasterImpl, ejb-name=StratocasterImpl, container=Default Stateless Container) + INFO - Deployed Application(path=/Users/dblevins/work/openejb3/examples/custom-injection/target/classes) + Tests run: 1, Failures: 0, Errors: 0, Skipped: 0, Time elapsed: 0.705 sec + + Results : + + Tests run: 1, Failures: 0, Errors: 0, Skipped: 0 http://git-wip-us.apache.org/repos/asf/tomee/blob/b93bd755/docs/datasource-config.md ---------------------------------------------------------------------- diff --git a/docs/datasource-config.md b/docs/datasource-config.md new file mode 100644 index 0000000..3e218a7 --- /dev/null +++ b/docs/datasource-config.md @@ -0,0 +1,541 @@ +index-group=Unrevised +type=page +status=published +title=DataSource Configuration +~~~~~~ + +A DataSource can be declared via xml in the `<tomee-home>/conf/tomee.xml` file or in a `WEB-INF/resources.xml` file using a declaration like the following. All properties in the element body are optional. + + <Resource id="myDataSource" type="javax.sql.DataSource"> + accessToUnderlyingConnectionAllowed = false + alternateUsernameAllowed = false + connectionProperties = + defaultAutoCommit = true + defaultReadOnly = + definition = + ignoreDefaultValues = false + initialSize = 0 + jdbcDriver = org.hsqldb.jdbcDriver + jdbcUrl = jdbc:hsqldb:mem:hsqldb + jtaManaged = true + maxActive = 20 + maxIdle = 20 + maxOpenPreparedStatements = 0 + maxWaitTime = -1 millisecond + minEvictableIdleTime = 30 minutes + minIdle = 0 + numTestsPerEvictionRun = 3 + password = + passwordCipher = PlainText + poolPreparedStatements = false + serviceId = + testOnBorrow = true + testOnReturn = false + testWhileIdle = false + timeBetweenEvictionRuns = -1 millisecond + userName = sa + validationQuery = + </Resource> + +Alternatively, a DataSource can be declared via properties in the `<tomee-home>/conf/system.properties` file or via Java VirtualMachine `-D` properties. The properties can also be used when embedding TomEE via the `javax.ejb.embeddable.EJBContainer` API or `InitialContext` + + myDataSource = new://Resource?type=javax.sql.DataSource + myDataSource.accessToUnderlyingConnectionAllowed = false + myDataSource.alternateUsernameAllowed = false + myDataSource.connectionProperties = + myDataSource.defaultAutoCommit = true + myDataSource.defaultReadOnly = + myDataSource.definition = + myDataSource.ignoreDefaultValues = false + myDataSource.initialSize = 0 + myDataSource.jdbcDriver = org.hsqldb.jdbcDriver + myDataSource.jdbcUrl = jdbc:hsqldb:mem:hsqldb + myDataSource.jtaManaged = true + myDataSource.maxActive = 20 + myDataSource.maxIdle = 20 + myDataSource.maxOpenPreparedStatements = 0 + myDataSource.maxWaitTime = -1 millisecond + myDataSource.minEvictableIdleTime = 30 minutes + myDataSource.minIdle = 0 + myDataSource.numTestsPerEvictionRun = 3 + myDataSource.password = + myDataSource.passwordCipher = PlainText + myDataSource.poolPreparedStatements = false + myDataSource.serviceId = + myDataSource.testOnBorrow = true + myDataSource.testOnReturn = false + myDataSource.testWhileIdle = false + myDataSource.timeBetweenEvictionRuns = -1 millisecond + myDataSource.userName = sa + myDataSource.validationQuery = + +Properties and xml can be mixed. Properties will override the xml allowing for easy configuration change without the need for ${} style variable substitution. Properties are not case sensitive. If a property is specified that is not supported by the declared DataSource a warning will be logged. If a DataSource is needed by the application and one is not declared, TomEE will create one dynamically using default settings. Multiple DataSource declarations are allowed. + +See the [Common DataSource Configurations](common-datasource-configurations.html) page for examples of configuring datasources for Derby, MySQL, Oracle and other common databases. + +# Supported Properties +<table class="mdtable"> +<tr> +<th>Property</th> +<th>Type</th> +<th>Default</th> +<th>Description</th> +</tr> +<tr> + <td><a href="#accessToUnderlyingConnectionAllowed">accessToUnderlyingConnectionAllowed</a></td> + <td>boolean</td> + <td>false</td> + <td> +If true the raw physical connection to the database can be +accessed +</td> +</tr> +</tr> +<tr> + <td><a href="#alternateUsernameAllowed">alternateUsernameAllowed</a></td> + <td>boolean</td> + <td>false</td> + <td> +If true allow an alternate username and password to be specified on the connection, rather than those specified in the DataSource definition.. +</td> +</tr> +<tr> + <td><a href="#connectionProperties">connectionProperties</a></td> + <td>String</td> + <td></td> + <td> +The connection properties that will be sent to the JDBC +driver when establishing new connections +</td> +</tr> +<tr> + <td>defaultAutoCommit</td> + <td>boolean</td> + <td>true</td> + <td> +The default auto-commit state of new connections +</td> +</tr> +<tr> + <td>defaultReadOnly</td> + <td>String</td> + <td></td> + <td> +The default read-only state of new connections +If not set then the setReadOnly method will not be called. +(Some drivers don't support read only mode, ex: Informix) +</td> +</tr> +<tr> + <td>definition</td> + <td>String</td> + <td></td> + <td> + +</td> +</tr> +<tr> + <td>ignoreDefaultValues</td> + <td>boolean</td> + <td>false</td> + <td> +use only all set values in this config +will need a lot of properties but allow to not set some values +</td> +</tr> +<tr> + <td><a href="#initialSize">initialSize</a></td> + <td>int</td> + <td>0</td> + <td> +The size to reach when creating the datasource. +</td> +</tr> +<tr> + <td>jdbcDriver</td> + <td>String</td> + <td>org.hsqldb.jdbcDriver</td> + <td> +Driver class name +</td> +</tr> +<tr> + <td>jdbcUrl</td> + <td>java.net.URI</td> + <td>jdbc:hsqldb:mem:hsqldb</td> + <td> +Url for creating connections +</td> +</tr> +<tr> + <td><a href="#jtaManaged">jtaManaged</a></td> + <td>boolean</td> + <td>true</td> + <td> +Determines wether or not this data source should be JTA managed +or user managed. +</td> +</tr> +<tr> + <td>maxActive</td> + <td>int</td> + <td>20</td> + <td> +The maximum number of active connections that can be +allocated from this pool at the same time, or a negative +number for no limit. N.B. When using dbcp2 with TomEE 7 ("DataSourceCreator dbcp"), "MaxTotal" should be used as opposed to "MaxActive". +</td> +</tr> +<tr> + <td>maxIdle</td> + <td>int</td> + <td>20</td> + <td> +The maximum number of connections that can remain idle in +the pool, without extra ones being released, or a negative +number for no limit. +</td> +</tr> +<tr> + <td><a href="#maxOpenPreparedStatements">maxOpenPreparedStatements</a></td> + <td>int</td> + <td>0</td> + <td> +The maximum number of open statements that can be allocated +from the statement pool at the same time, or zero for no +limit. +</td> +</tr> +<tr> + <td>maxWaitTime</td> + <td><a href="configuring-durations.html">time</a></td> + <td>-1 millisecond</td> + <td> +The maximum number of time that the pool will wait +(when there are no available connections) for a connection +to be returned before throwing an exception, or -1 to wait +indefinitely. +</td> +</tr> +<tr> + <td>minEvictableIdleTime</td> + <td><a href="configuring-durations.html">time</a></td> + <td>30 minutes</td> + <td> +The minimum amount of time a connection may sit idle in the +pool before it is eligable for eviction by the idle +connection evictor (if any). +</td> +</tr> +<tr> + <td>minIdle</td> + <td>int</td> + <td>0</td> + <td> +The minimum number of connections that can remain idle in +the pool, without extra ones being created, or zero to +create none. +</td> +</tr> +<tr> + <td>numTestsPerEvictionRun</td> + <td>int</td> + <td>3</td> + <td> +The number of connectionss to examine during each run of the +idle connection evictor thread (if any). +</td> +</tr> +<tr> + <td>password</td> + <td>String</td> + <td></td> + <td> +Default password +</td> +</tr> +<tr> + <td>passwordCipher</td> + <td>String</td> + <td>PlainText</td> + <td> + +</td> +</tr> +<tr> + <td><a href="#poolPreparedStatements">poolPreparedStatements</a></td> + <td>boolean</td> + <td>false</td> + <td> +If true, a statement pool is created for each Connection and +PreparedStatements created by one of the following methods are +pooled: +</td> +</tr> +<tr> + <td>serviceId</td> + <td>String</td> + <td></td> + <td> + +</td> +</tr> +<tr> + <td><a href="#testOnBorrow">testOnBorrow</a></td> + <td>boolean</td> + <td>true</td> + <td> +If true connections will be validated before being returned +from the pool. If the validation fails, the connection is +destroyed, and a new conection will be retrieved from the +pool (and validated). +</td> +</tr> +<tr> + <td><a href="#testOnReturn">testOnReturn</a></td> + <td>boolean</td> + <td>false</td> + <td> +If true connections will be validated before being returned +to the pool. If the validation fails, the connection is +destroyed instead of being returned to the pool. +</td> +</tr> +<tr> + <td><a href="#testWhileIdle">testWhileIdle</a></td> + <td>boolean</td> + <td>false</td> + <td> +If true connections will be validated by the idle connection +evictor (if any). If the validation fails, the connection is +destroyed and removed from the pool +</td> +</tr> +<tr> + <td>timeBetweenEvictionRuns</td> + <td><a href="configuring-durations.html">time</a></td> + <td>-1 millisecond</td> + <td> +The number of milliseconds to sleep between runs of the idle +connection evictor thread. When set to a negative number, no +idle connection evictor thread will be run. +</td> +</tr> +<tr> + <td>userName</td> + <td>String</td> + <td>sa</td> + <td> +Default user name +</td> +</tr> +<tr> + <td>validationQuery</td> + <td>String</td> + <td></td> + <td> +The SQL query that will be used to validate connections from +this pool before returning them to the caller. If specified, +this query MUST be an SQL SELECT statement that returns at +least one row. +</td> +</tr> +<tr> +<td>LogSql</td> +<td>boolean</td> +<td>false</td> +<td>Wether SQL queries should be logged or not</td> +</tr> +</table> + + + +<a name="accessToUnderlyingConnectionAllowed"></a> +## accessToUnderlyingConnectionAllowed + +If true the raw physical connection to the database can be +accessed using the following construct: + + Connection conn = ds.getConnection(); + Connection rawConn = ((DelegatingConnection) conn).getInnermostDelegate(); + ... + conn.close() + +Default is false, because misbehaving programs can do harmfull +things to the raw connection shuch as closing the raw +connection or continuing to use the raw connection after it +has been assigned to another logical connection. Be careful +and only use when you need direct access to driver specific +extensions. + +NOTE: Do NOT close the underlying connection, only the +original logical connection wrapper. + + +<a name="connectionProperties"></a> +## connectionProperties + +The connection properties that will be sent to the JDBC +driver when establishing new connections + +Format of the string must be [propertyName=property;]* + +NOTE - The "user" and "password" properties will be passed +explicitly, so they do not need to be included here. + + +<a name="TransactionIsolation"></a> +## TransactionIsolation + + +The default TransactionIsolation state of new connections. + +If not set then the `setTransactionIsolation` method will not +be called. The allowed values for this property are: + +- `NONE` +- `READ_COMMITTED` +- `READ_UNCOMMITTED` +- `REPEATABLE_READ` +- `SERIALIZABLE` + +Note: Most JDBC drivers do not support all isolation levels +DefaultTransactionIsolation + +<a name="initialSize"></a> +## initialSize + +The initial size to initialize the pool of connections. + +<a name="jtaManaged"></a> +## jtaManaged + +Determines wether or not this data source should be JTA managed +or user managed. + +If set to 'true' it will automatically be enrolled +in any ongoing transactions. Calling begin/commit/rollback or setAutoCommit +on the datasource or connection will not be allowed. If you need to perform +these functions yourself, set `JtaManaged` to `false` + +In terms of JPA persistence.xml: + +- `JtaManaged=true` can be used as a 'jta-data-source' +- `JtaManaged=false` can be used as a 'non-jta-data-source' + + +<a name="maxOpenPreparedStatements"></a> +## maxOpenPreparedStatements + +The maximum number of open statements that can be allocated +from the statement pool at the same time, or zero for no +limit. + +NOTE - Some drivers have limits on the number of open +statements, so make sure there are some resources left +for the other (non-prepared) statements. + + +<a name="poolPreparedStatements"></a> +## poolPreparedStatements + +If true, a statement pool is created for each Connection and +PreparedStatements created by one of the following methods are +pooled: + + public PreparedStatement prepareStatement(String sql); + public PreparedStatement prepareStatement(String sql, int resultSetType, int resultSetConcurrency) + + +<a name="testOnBorrow"></a> +## testOnBorrow + +If true connections will be validated before being returned +from the pool. If the validation fails, the connection is +destroyed, and a new conection will be retrieved from the +pool (and validated). + +NOTE - for a true value to have any effect, the +ValidationQuery parameter must be set. + + +<a name="testOnReturn"></a> +## testOnReturn + +If true connections will be validated before being returned +to the pool. If the validation fails, the connection is +destroyed instead of being returned to the pool. + +NOTE - for a true value to have any effect, the +ValidationQuery parameter must be set. + + +<a name="testWhileIdle"></a> +## testWhileIdle + +If true connections will be validated by the idle connection +evictor (if any). If the validation fails, the connection is +destroyed and removed from the pool + +NOTE - for a true value to have any effect, the +timeBetweenEvictionRunsMillis property must be a positive +number and the ValidationQuery parameter must be set. + +# XADataSource + +There are several ways to configure a XADataSource. Depending the underlying datasource (Oracle, MySQL one or the other +solution can be more adapted. + +This part deals with `JtaManaged` XaDataSource since a not managed XaDataSource can be defined as a standard +resource using `class-name`. + +## Single definition + +First solution is to define as `JdbcDriver` an XADataSource: + + <Resource id="myXaDs" type="DataSource"> + JdbcDriver = org.foo.MyXaDataSource + + myXaProperty = value + + myPoolProperty = 10 + </Resource> + +This solution merges properties for the XaDataSource and the pool (tomcat-jdbc for TomEE, dbcp for OpenEJB by default +but still configurable with DataSourceCreator). + +Note: in this case for Oracle for instance you'll define UserName for the pool and User for the datasource which +can look weird if you don't know properties are used for 2 instances (pool and datasource). + +Note: this solution uses the same logic than @DataSourceDefinition factory mecanism. + +## Two resources definition + +An alternative is to define a resource for the XaDataSource: + + <Resource id="myXa" class-name="org.foo.MyXaDataSource"> + myXaProperty = value + </Resource> + +And then wrap it in the pool: + + <Resource id="myXaDs" type="DataSource"> + DataSourceCreator = [dbcp|dbcp-alternative] + myPoolProperty = 10 + </Resource> + +Note: `dbcp` is more adapted than `dbcp-alternative` in most of the case because it is reusing direct dbcp JTA management. + +## Known issues + +For TomEE 1.7.0/1.7.1 you can need to add the property: + + openejb.datasource.pool = true + +in resource properties to ensure the resource is pooled. + + +## Details about DataSource and their factories (advanced configuration) + + +[Configuration by creator](datasource-configuration-by-creator.html) http://git-wip-us.apache.org/repos/asf/tomee/blob/b93bd755/docs/datasource-password-encryption.md ---------------------------------------------------------------------- diff --git a/docs/datasource-password-encryption.md b/docs/datasource-password-encryption.md new file mode 100644 index 0000000..f8aa7cc --- /dev/null +++ b/docs/datasource-password-encryption.md @@ -0,0 +1,128 @@ +index-group=Unrevised +type=page +status=published +title=DataSource Password Encryption +~~~~~~ +_Apache OpenEJB 3.1.2 or later required_ + +_TomEE 1.5.0 switched from Apache Commons-DBCP to Tomcat-pool. On that specific version, password encryption is not +available. You can still switch back to Apache Commons DBCP buy adding the following property: DataSourceCreator dbcp. +On all following versions, the database encryption will be ported and hence available on Tomcat-pool as well._ + +<a name="DataSourcePasswordEncryption-Cipheringpasswords"></a> +# Ciphering passwords +Apache OpenEJB now provides an easy and extensible way to cipher databases +passwords. Not that by default, this feature is not activated so plain +passwords are used. + +<a name="DataSourcePasswordEncryption-Usage"></a> +## Usage + +Default Plain text password example: + + <Resource id="MySQL Database" type="DataSource"> + # MySQL example + # + # This connector will not work until you download the driver at: + # http://www.mysql.com/downloads/api-jdbc-stable.html + + JdbcDriver com.mysql.jdbc.Driver + JdbcUrl jdbc:mysql://localhost/test + UserName test + Password Passw0rd + </Resource> + + +3DES ciphered password example. + +Note that the built in 3DES implementation uses *a static key* to +encode/decode your password. _It's only meant to be a sample on how to implement a Codec. On a real +enterprise life, you should implement your how relying on an HSM for example._ +The easiest way to do it is to implement the *org.apache.openejb.resource.jdbc.cipher.PasswordCipher* interface. + + <Resource id="MySQL Database" type="DataSource"> + # MySQL example + # + # This connector will not work until you download the driver at: + # http://www.mysql.com/downloads/api-jdbc-stable.html + + JdbcDriver com.mysql.jdbc.Driver + JdbcUrl jdbc:mysql://localhost/test + UserName test + + # ciphered value for Passw0rd using Static3DES codec is + xMH5uM1V9vQzVUv5LG7YLA== + Password xMH5uM1V9vQzVUv5LG7YLA== + PasswordCipher Static3DES + </Resource> + + +# Hint +You can plug your own algorithm to extend Apache OpenEJB built in ones. To +do such, you just need to implement the + +## Command line tool + +Apache OpenEJB also provides a command line tool allowing password cipher +algorithm. Actually, it's useful to get the ciphered value of a plain text +value using a given algorithm. + +### NAME + +openejb cipher - OpenEJB Cypher Tool + +### SYNOPSIS + + openejb cipher [#options] + +### DESCRIPTION + +The OpenEJB Cipher tool is an OPTIONAL tool that allows you to use +`PasswordCipher` algorithm to encode/decode values. + +*This tool isn't package by default on TomEE 1.5.0. It's only available on the standalone distribution. After 1.5.0, it's in TomEE as well.* + +The OpenEJB Cipher tool can be executed from any directory as long as +`<OPENEJB_HOME>/bin` is in the system PATH. Before running this tool you need +to set the environment variable OPENEJB_HOME to the path of the directory +where you unpacked the OpenEJB installation. For for the remainder of this +document we will assume you unpacked OpenEJB into the directory +C:\openejb-3.1.2. + +In Windows, the cipher tool can be executed as follows: + + `C:\openejb-3.1.2> bin\openejb cipher --help` + +In UNIX, Linux, or Mac OS X, the cipher tool can be executed as follows: + + `\[user@host openejb-3.1.2]# bin/openejb cipher --help` + +Depending on your OpenEJB version, you may need to change execution bits to +make the scripts executable. You can do this with the following command. + + `\[user@host openejb-3.1.2]# chmod 755 bin/openejb` + +From here on out, it will be assumed that you know how to execute the right +openejb script for your operating system and commands will appear in +shorthand as show below. + + `openejb cipher --help` + +### OPTIONS + +<table class="mdtable"> +<tr><td>-h, --_help_ <td></td>Lists these options and exit.</td></tr> +<tr><td>-c, --_cipher_ <td></td>Specifies the password cipher implementation to use (default is Static3DES).</td></tr> +<tr><td>-d, --_decrypt_ <td></td>Switches command line tool to decrypt.</td></tr> +<tr><td>-e, --_encrypt_ <td></td>Switches command line tool to encrypt (default).</td></tr> +</table> + +### EXAMPLES + +Encrypt a plain password using the default algorithm. + + `openejb cipher Passw0rd` + +Output + + xMH5uM1V9vQzVUv5LG7YLA== http://git-wip-us.apache.org/repos/asf/tomee/blob/b93bd755/docs/deamon/lin-service.md ---------------------------------------------------------------------- diff --git a/docs/deamon/lin-service.md b/docs/deamon/lin-service.md new file mode 100644 index 0000000..f5bc18c --- /dev/null +++ b/docs/deamon/lin-service.md @@ -0,0 +1,17 @@ +index-group=Unrevised +type=page +status=published +~~~~~~ +###Installing TomEE as a Windows® Service + +The different architecture exe's are as follows (so always use the one that matches your system): + +TomEE.amd64.exe = 64bit OS +TomEE.ia64.exe = Itanium OS +TomEE.x86.exe = 32bit OS + +The only difference to Tomcat is that they ship with 'like named' binaries, but in sub-directories - Or offer separate downloads for your OS. We just modified the batch files to detect your arch-type and use the correct binaries. Everything is all in the 'bin' directory so we only have a one zip fits all approach. + +Definitive documentation can be found here: + +http://commons.apache.org/proper/commons-daemon/procrun.html \ No newline at end of file http://git-wip-us.apache.org/repos/asf/tomee/blob/b93bd755/docs/deamon/win-service.md ---------------------------------------------------------------------- diff --git a/docs/deamon/win-service.md b/docs/deamon/win-service.md new file mode 100644 index 0000000..f5bc18c --- /dev/null +++ b/docs/deamon/win-service.md @@ -0,0 +1,17 @@ +index-group=Unrevised +type=page +status=published +~~~~~~ +###Installing TomEE as a Windows® Service + +The different architecture exe's are as follows (so always use the one that matches your system): + +TomEE.amd64.exe = 64bit OS +TomEE.ia64.exe = Itanium OS +TomEE.x86.exe = 32bit OS + +The only difference to Tomcat is that they ship with 'like named' binaries, but in sub-directories - Or offer separate downloads for your OS. We just modified the batch files to detect your arch-type and use the correct binaries. Everything is all in the 'bin' directory so we only have a one zip fits all approach. + +Definitive documentation can be found here: + +http://commons.apache.org/proper/commons-daemon/procrun.html \ No newline at end of file http://git-wip-us.apache.org/repos/asf/tomee/blob/b93bd755/docs/declaring-references.md ---------------------------------------------------------------------- diff --git a/docs/declaring-references.md b/docs/declaring-references.md new file mode 100644 index 0000000..5cfabca --- /dev/null +++ b/docs/declaring-references.md @@ -0,0 +1,6 @@ +index-group=Unrevised +type=page +status=published +title=Declaring References +~~~~~~ + http://git-wip-us.apache.org/repos/asf/tomee/blob/b93bd755/docs/deploy-tool.md ---------------------------------------------------------------------- diff --git a/docs/deploy-tool.md b/docs/deploy-tool.md new file mode 100644 index 0000000..0ea4849 --- /dev/null +++ b/docs/deploy-tool.md @@ -0,0 +1,165 @@ +index-group=Unrevised +type=page +status=published +title=Deploy Tool +~~~~~~ + +<a name="DeployTool-NAME"></a> +# NAME + +openejb deploy - OpenEJB Deploy Tool + +<a name="DeployTool-SYNOPSIS"></a> +# SYNOPSIS + +> openejb deploy [options](#DeployTool-OPTIONS) <file> \[<file> ...\] + +<a name="DeployTool-NOTE"></a> +# NOTE + + +The OpenEJB Deploy tool is an OPTIONAL tool that allows you to deploy into +a running server and get feedback as if the app was deployed and how it was +deployed (deploymentIds, jndi names, etc.). + +It can be used to deploy into an offline server, however in this scenario +it simply copies the archive into the deployment directory (by default `openejb.base/apps`) which is +something that can be done manually with a simple copy command or drag and +drop. + +The OpenEJB Deploy tool can be executed from any directory as long as +`openejb.home/bin` is in the system PATH. `openejb.home` is the directory +where OpenEJB was installed or unpacked. For for the remainder of this +document we will assume you unpacked OpenEJB into the directory +`C:\openejb-3.0` under Windows. + +In Windows, the deploy tool can be executed as follows: + +> C:\openejb-3.0> bin\openejb deploy --help + +In UNIX, Linux, or Mac OS X, the deploy tool can be executed as follows: + +> user@host# bin/openejb deploy --help + +Depending on your OpenEJB version, you may need to change execution bits to +make the scripts executable. You can do this with the following command. + +> user@host# chmod +x bin/openejb + +From here on out, it will be assumed that you know how to execute the right +openejb script for your operating system and commands will appear in +shorthand as show below. + +> openejb deploy --help + + +<a name="DeployTool-DESCRIPTION"></a> +# DESCRIPTION + +The files passed to the Deploy Tool can be any combination of the +following: + +* EJB 1.1, 2.0, 2.1, 3.0 or 3.1 jar +* application client jar +* EAR file containing only libraries, EJBs and application clients -- +everything else will be ignored. + +The type of the files passed is determined as follows: + +* Archives ending in `.ear` or containing a `META-INF/application.xml` are +assumed to be EAR files. +* Archives containing a `META-INF/ejb-jar.xml` file or any classes annotated +with `@Stateless`, `@Stateful` or `@MessageDriven`, are assumed to be *EJB* +applications. EJB applications older that EJB 3.0 should contain a +complete `META-INF/ejb-jar.xml` inside the jar, however we do not strictly +enforce that -- the act of it being incomplete makes it an EJB 3.0 +application by nature. +* Archives containing a `META-INF/application-client.xml` or with a +`META-INF/MANIFEST.MF` containing the `Main-Class` attribute, are assumed to +be *Application Client* archives. + + +<a name="DeployTool-OPTIONS"></a> +# OPTIONS + +<table class="mdtable"> +<tr> +<td>-d, --debug </td> +<td>Increases the level of detail on validation errors and +deployment summary.</td> +</tr> + +<tr><td>--dir </td> +<td>Sets the destination directory where the app will be deployed. +The default is <OPENEJB_HOME>/apps/ directory. Note when changing this +setting make sure the directory is listed in the openejb.xml via a +<Deployments dir=""/> tag or the app will not be picked up again on +restart. +</tr> + +<tr><td>-conf file </td> +<td>Sets the OpenEJB configuration to the specified file.</td></tr> + +<tr><td>-h, --help </td> +<td>Lists these options and exit.</td></tr> + +<tr><td>-o, --offline</td> +<td>Deploys the app to an offline server by copying the +archive into the server's apps/ directory. The app will be deployed when +the server is started. The default is online.</td></tr> + +<tr><td>-q, --quiet </td> +<td> Decreases the level of detail on validation and skips the +deployment summary.</td></tr> + +<tr><td>-s, --server-url <url> </td> +<td> Sets the url of the OpenEJB server to which +the app will be deployed. The value should be the same as the JNDI +Provider URL used to lookup EJBs. The default is 'ejbd://localhost:4201'. +</td></tr> + +<tr><td>-v, --version</td> +<td> Prints the OpenEJB version and exits. </td></tr> +</table> + + +<a name="DeployTool-EXAMPLES"></a> +# EXAMPLES + + +<a name="DeployTool-Deployingmultiplejarfiles"></a> +## Deploying multiple jar files + + +> openejb deploy myapp\fooEjbs.jar myapp\barEjbs.jar + + +Deploys the beans in the fooEjbs.jar first, then deploys the beans in the +barEjbs.jar. Wildcards can be used as well. + +> openejb deploy myapp\*.jar + + +<a name="DeployTool-OUTPUT"></a> +# OUTPUT + +On running the deploy tool with a valid EJB jar the following output is +printed on the console + + + Application deployed successfully at {0} + App(id=C:\samples\Calculator-new\hello-addservice.jar) + EjbJar(id=hello-addservice.jar, path=C:\samples\Calculator-new\hello-addservice.jar) + Ejb(ejb-name=HelloBean, id=HelloBean) + Jndi(name=HelloBean) + Jndi(name=HelloBeanLocal) + + Ejb(ejb-name=AddServiceBean, id=AddServiceBean) + Jndi(name=AddServiceBean) + Jndi(name=AddServiceBeanLocal) + + +Note: In the above case the command used is: +> openejb deploy hello-addservice.jar + +The JAR file contains two EJBs: AddServiceBean and HelloBean. http://git-wip-us.apache.org/repos/asf/tomee/blob/b93bd755/docs/deploying-in-tomee.md ---------------------------------------------------------------------- diff --git a/docs/deploying-in-tomee.md b/docs/deploying-in-tomee.md new file mode 100644 index 0000000..0054b59 --- /dev/null +++ b/docs/deploying-in-tomee.md @@ -0,0 +1,73 @@ +index-group=Unrevised +type=page +status=published +title= +~~~~~~ +Notice: Licensed to the Apache Software Foundation (ASF) under one + or more contributor license agreements. See the NOTICE file + distributed with this work for additional information + regarding copyright ownership. The ASF licenses this file + to you under the Apache License, Version 2.0 (the + "License"); you may not use this file except in compliance + with the License. You may obtain a copy of the License at + . + http://www.apache.org/licenses/LICENSE-2.0 + . + Unless required by applicable law or agreed to in writing, + software distributed under the License is distributed on an + "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + KIND, either express or implied. See the License for the + specific language governing permissions and limitations + under the License. + +#Deploying in TomEE + +Deploying applications in TomEE is as simple as deploying them in Tomcat. + +You could deploy your application in Eclipse just like how you would deploy with Tomcat. For an example, [tomee-and-eclipse](tomee-and-eclipse.html) shows how to use TomEE with Eclipse. + +Or you can simply package your application as a standard **WAR** file and copy it to the **[TomEE]/webapps** folder, or as an **EAR** file and copy it to the **[TomEE]/apps** folder. + +Read on to learn more about packaging EJBs in a WAR file. + + +### Packaging + +<a name="CollapsedEAR-Onearchive"></a> +#### One archive + +The basic idea of this approach is that your Servlets and EJBs are together in your WAR file as one application. + + - No classloader boundaries between Servlets and EJBs + + - EJBs and Servlets can share all third-party libraries (like Spring\!) + + - No EAR required. + + - Can put the web.xml and ejb-jar.xml in the same archive (the WAR file) + + - EJBs can see Servlet classes and vice versa + +<a name="CollapsedEAR-NotquiteJ2EE(itistrulyJava EE6)"></a> +#### Not quite J2EE (But it is Java EE 6) + +This is very different than J2EE or Java EE 5 as there are not several levels of separation and classloader hierarchy any more. +This may take some getting used to and it is important to understand that this style of packaging is **not** J2EE compliant. +You should not worry though, as it is an accepted feature of Java EE 6. + +#### J2EE classloading rules: + - You cannot ever have EJBs and Servlets in the same classloader. + + - Three classloader minimum; a classloader for the ear, one for each +ejb-jar, and one for each WAR file. + + - Servlets can see EJBs, but EJBs cannot see Servlets. + + To pull that off, J2EE has to kill you on packaging: + - You cannot have EJB classes and Servlet classes in the same archive. + + - You need at least three archives to combine Servlets and EJBs; 1 EAR containing 1 EJB jar and 1 Servlet WAR. + + - Shared libraries must go in the EAR and be included in a specially formatted 'Class-Path' entry in the EAR's MANIFEST file. + + Critically speaking, forcing more than one classloader on an application is where J2EE "jumps the shark" for a large majority of people's needs. http://git-wip-us.apache.org/repos/asf/tomee/blob/b93bd755/docs/deployment-id.md ---------------------------------------------------------------------- diff --git a/docs/deployment-id.md b/docs/deployment-id.md new file mode 100644 index 0000000..533a16d --- /dev/null +++ b/docs/deployment-id.md @@ -0,0 +1,231 @@ +index-group=Unrevised +type=page +status=published +title=Deployment ID +~~~~~~ + +<a name="DeploymentID-WhatisaDeploymentID?"></a> +# What is a Deployment ID? + +Every bean deployed in OpenEJB has a unique deployment-id that identifies +it within the scope of the entire container system. The server and +container system refer beans at run-time using the bean's deployment id. + +<a name="DeploymentID-Likeejb-name"></a> +## Like ejb-name + +This deployment id is much like the <ejb-name> element of the ejb-jar.xml , +with one very important difference. The <ejb-name> is only required to be +unique within the scope of the ejb-jar.xml in the bean's jar. The +deployment id is required to be unique across all beans and jars in +OpenEJB. This is a subtle, but important, distinction. + +Remember that the EJB specification was designed so that enterprise beans +could be create, packaged, and sold by vendors (EJB Providers). +Furthermore, users should be able to buy a packaged set of beans (a jar +with an ejb-jar.xml in it) and deploy it into an EJB Container without +modification. + +<a name="DeploymentID-Theejb-nameisnotunique"></a> +## The ejb-name is not unique + +Let's consider this, what happens if two vendors each sell a package (jar) +that contains a bean with the <ejb-name> PurchaseOrder? Both are completely +different in terms functionality and are different beans in every other +respect. The EJB spec says, this is fine, ejb-names only have to unique +within the jar and that jar's ejb-jar.xml file. It's ridiculous to expect +EJB Providers to call each other up and ask, "Are you already using the +name 'PurchaseOrder' in your jar?" Remember that the EJB specification was +designed so that enterprise beans could be create, packaged, and sold by +vendors (EJB Providers). Furthermore, users should be able to buy a +packaged set of beans (a jar with an ejb-jar.xml in it) and deploy it into +an EJB Container without modification. This is all fine and dandy, but it +still leaves it up to the EJB Container/Server providers to settle the +difference. + +<a name="DeploymentID-Thedeployment-idisunique"></a> +## The deployment-id is unique + +OpenEJB solves this with the OpenEJB-specific deployment id. By requiring +that each bean deployed into OpenEJB has a unique name, we can guarantee +that we are always referring to the right bean at all times. Furthermore, it +allows you to deploy different versions of the same package several times +in the same container system, each time giving the beans new deployment +ids. + +<a name="DeploymentID-Usingejb-nameasdeployment-idanyway"></a> +## Using ejb-name as deployment-id anyway + +If you're lazy -- as any truly great programmer should be -- and don't want +to type a deployment id for each bean every time you deploy a jar, you can +use the -D option of the Deploy Tool. This will throw caution to the wind, +and automatically assign the bean's ejb-name as the value of the bean's +OpenEJB deployment id. This leaves up to you to guarantee that bean's +ejb-name will be unique across all beans and jars in the container system. +In other words, be very careful with the -D option! + +<a name="DeploymentID-Howisitused?"></a> +# How is it used? + +<a name="DeploymentID-Inthecontainersystem"></a> +## In the container system + +In the container system, the deployment id is used to index the bean in a +system-wide registry. This registry is refereed to on every call made in the +container system. Being able to safely hash and cache bean information by +id is a must. This stresses the importance of unique ids for every bean +deployed in OpenEJB. + +<a name="DeploymentID-IntheLocalServer"></a> +## In the Local Server + +The Local (IntraVM) Server is an integral part of the container system and +the two are, in many ways, inseparable. The Local Server takes care of all +bean to bean and client to bean invocations made inside the virtual +machine. For this reason, it often refered to as the IntraVM Server. + +For bean to bean communications, the Local Server must create a JNDI +namespace (JNDI ENC) for each bean as defined by the bean's <env-entry>, +<ejb-ref>, and <resource-ref> elements of the bean's ejb-jar.xml file. +Every bean literally gets its very own JNDI namespace. When a bean makes a +JNDI call, the Local Server intercepts this call and uses the deployment id +of the calling bean to retrieve that bean's private JNDI namespace from the +container system's index. The Local Server then carries out the lookup on +that bean's namespace. + +All non-bean clients share one big global namespace. Since non-bean clients +are not deployed and do not have a deployment descriptor like an +ejb-jar.xml, the Local Server is unable to taylor a namespace for each +non-bean client as it can for bean clients. The Local server cannot +identify non-bean clients as they have no deployment id. All JNDI calls +made by clients that the Local Server cannot identify go to the public, +global namespace. The public, global JNDI namespace contains all beans and +resources in the container system. name. + +Each bean is added to the public, global namespace using it's deployment id +as its JNDI lookup. For example, if a bean had a deployment-id of +"/my/bean/foo", a non-bean client could lookup that bean as follows. + + ... + Object bean = initialContext.lookup("/my/bean/Foo"); + ... + + +If a bean in the container system made the above JNDI call, the Local +Server would see the bean's identity (deployment id) hidden in the Thread, +go get the bean's private JNDI namespace and finish the lookup on that. +Since all names in bean's JNDI namespace are required start with +"java:comp/env", the lookup would fail and the bean would receive a +javax.naming.NameNotFoundException. + +In short... + +For beans: + - Each bean has it's own private, personalized JNDI namespace + - The names in it are the same names it uses in its ejb-jar.xml + - Beans can only access their private namespace, period + +For non-beans (everyone else): + - Non-bean clients share the public, global JNDI namespace + - The names in it are the deployment ids of all the beans + - Non-bean clients can only access the one global namespace + +<a name="DeploymentID-IntheRemoteServer"></a> +## In the Remote Server + +The Remote Server has a public, global namespace just as the Local Server +does. The difference being that the Remote Server only serves clients +outside the container system and outside the virtual machine. So, all +clients from the perspective of the Remote Server are non-bean clients. As +a result, the Remote Server only has the one public, global JNDI namespace. +Just as in the Local Server, the names in this namespace consist of the +deployment ids of the beans in the container system. + +Just as before, clients can lookup beans from the Remote Server using the +bean's deployment id. For example, if a bean had a deployment-id of +"/my/bean/foo", a client could lookup that bean as follows. + + ... + Object bean = initialContext.lookup("/my/bean/Foo"); + ... + + +<a name="DeploymentID-IntheCORBAAdapter"></a> +## In the CORBA Adapter + +The CORBA Adapter is separate than the Remote Server. It adapts the OpenEJB +Container System and the Local Server into OpenORB as an embedded library. +It provides users of OpenORB the ability to lookup and execute beans (EJBs) +via the RMI-IIOP protocol. All the EJBHome and EJBObject interfaces of +beans in OpenEJB are implemented by OpenORB as CORBA stubs and ties. + +The beans are exported into OpenORB's naming service by deployment id. So, +just as with the Local Server and Remote Server, clients can lookup beans +using the bean's deployment id. OpenORB has a JNDI implementation of their +naming service, so lookups can be done just as before. + + ... + String[] args = ... + + // The ORB and Object + org.omg.CORBA.ORB orb = null; + org.omg.CORBA.Object bean = null. + + // The Naming Service and Object Name + org.omg.CosNaming.NamingContext context = null; + org.omg.CosNaming.NameComponent[] name = null; + + // Get the ORB + orb = org.omg.CORBA.ORB.init( args, null ); + + // Get the Naming Service + org.omg.CORBA.Object ref = null; + ref = orb.resolve_initial_references("NameService"); + context = org.omg.CosNaming.NamingContextHelper.narrow( ref ); + + // Get the Name as a component + // Note: the string is the bean's deployment id + name = new org.omg.CosNaming.NameComponent[ 1 ]; + name[0] = new org.omg.CosNaming.NameComponent("/my/bean/foo",""); + + // Finally, get the bean as a CORBA object + // Equvalent to an InitialContext.lookup("/my/bean/foo"); + bean = context.resolve( name ); + ... + + +<a name="DeploymentID-WhathappensifthereisaduplicatedeploymentID?"></a> +# What happens if there is a duplicate deployment ID? + +The deployment ID uniquely identifies the bean in the OpenEJB container +system. Therefore, no two beans can share the same deployment ID. + +If a bean attempts to use a deployment ID that is already in use by another +bean, the second bean and all beans in it's jar will not be loaded. In +addition, the system will log a warning like the following one asking you +to redeploy the jar and choose an different deployment ID for the bean. + + WARN : Jar C:\openejb\beans\fooEjbs.jar cannot be loaded. The Deployment ID "/my/bean/foo" is already in use. Please redeploy this jar and assign a different deployment ID to the bean with the ejb-name "FooBean". + +For example, the acmeEjbs.jar contains a bean with the ejb-name +"DaffyDuckBean". The disneyEjbs.jar contains contains a bean with the +ejb-name "DonaldDuckBean". + +We deploy the acmeEjbs.jar and give the "DaffyDuckBean" the deployment ID +of "/my/favorite/duck". Sometime afterwards, we deploy the disneyEjbs.jar +and assign the "DonaldDuckBean" the deployment ID "/my/favorite/duck", +having forgotten that we already gave that unique ID to the "DaffyDuckBean" +in the acmeEjbs.jar. + +When the container system is started, the system will begin loading all the +beans one jar at a time. It will first load the acmeEjbs.jar and index each +bean by deployment ID. But, when the system reaches the disneyEjbs.jar, it +will discover that it cannot index the "DonaldDuckBean" using the +deployment ID "/my/favorite/duck" because that index is already taken. + +The system cannot load the "DonaldDuckBean" and must also ignore the rest +of the beans in the disneyEjbs.jar as they may need the "DonaldDuckBean" +bean to function properly. The disneyEjbs.jar is skipped and the following +warning is logged. + + WARN : Jar C:\openejb\beans\disneyEjbs.jar cannot be loaded. The Deployment ID "/my/favorite/duck" is already in use. Please redeploy this jar and assign a different deployment ID to the bean with the ejb-name "DonaldDuckBean".
