http://git-wip-us.apache.org/repos/asf/tomee/blob/c3f8984b/docs/containers-and-resources.mdtext ---------------------------------------------------------------------- diff --git a/docs/containers-and-resources.mdtext b/docs/containers-and-resources.mdtext deleted file mode 100644 index a568bad..0000000 --- a/docs/containers-and-resources.mdtext +++ /dev/null @@ -1,479 +0,0 @@ -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> - \ No newline at end of file
http://git-wip-us.apache.org/repos/asf/tomee/blob/c3f8984b/docs/contrib/debug/debug-intellij.mdtext ---------------------------------------------------------------------- diff --git a/docs/contrib/debug/debug-intellij.mdtext b/docs/contrib/debug/debug-intellij.mdtext deleted file mode 100644 index d2729a8..0000000 --- a/docs/contrib/debug/debug-intellij.mdtext +++ /dev/null @@ -1,129 +0,0 @@ -<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/c3f8984b/docs/custom-injection.mdtext ---------------------------------------------------------------------- diff --git a/docs/custom-injection.mdtext b/docs/custom-injection.mdtext deleted file mode 100644 index 968f846..0000000 --- a/docs/custom-injection.mdtext +++ /dev/null @@ -1,192 +0,0 @@ -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/c3f8984b/docs/datasource-config.mdtext ---------------------------------------------------------------------- diff --git a/docs/datasource-config.mdtext b/docs/datasource-config.mdtext deleted file mode 100644 index 4f19c9f..0000000 --- a/docs/datasource-config.mdtext +++ /dev/null @@ -1,537 +0,0 @@ -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/c3f8984b/docs/datasource-password-encryption.mdtext ---------------------------------------------------------------------- diff --git a/docs/datasource-password-encryption.mdtext b/docs/datasource-password-encryption.mdtext deleted file mode 100644 index cee368c..0000000 --- a/docs/datasource-password-encryption.mdtext +++ /dev/null @@ -1,124 +0,0 @@ -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/c3f8984b/docs/deamon/lin-service.mdtext ---------------------------------------------------------------------- diff --git a/docs/deamon/lin-service.mdtext b/docs/deamon/lin-service.mdtext deleted file mode 100644 index f3a59f6..0000000 --- a/docs/deamon/lin-service.mdtext +++ /dev/null @@ -1,13 +0,0 @@ -###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/c3f8984b/docs/deamon/win-service.mdtext ---------------------------------------------------------------------- diff --git a/docs/deamon/win-service.mdtext b/docs/deamon/win-service.mdtext deleted file mode 100644 index f3a59f6..0000000 --- a/docs/deamon/win-service.mdtext +++ /dev/null @@ -1,13 +0,0 @@ -###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/c3f8984b/docs/declaring-references.mdtext ---------------------------------------------------------------------- diff --git a/docs/declaring-references.mdtext b/docs/declaring-references.mdtext deleted file mode 100644 index 088e285..0000000 --- a/docs/declaring-references.mdtext +++ /dev/null @@ -1,2 +0,0 @@ -Title: Declaring References - http://git-wip-us.apache.org/repos/asf/tomee/blob/c3f8984b/docs/deploy-tool.mdtext ---------------------------------------------------------------------- diff --git a/docs/deploy-tool.mdtext b/docs/deploy-tool.mdtext deleted file mode 100644 index 8f787b1..0000000 --- a/docs/deploy-tool.mdtext +++ /dev/null @@ -1,161 +0,0 @@ -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. \ No newline at end of file http://git-wip-us.apache.org/repos/asf/tomee/blob/c3f8984b/docs/deploying-in-tomee.mdtext ---------------------------------------------------------------------- diff --git a/docs/deploying-in-tomee.mdtext b/docs/deploying-in-tomee.mdtext deleted file mode 100644 index ebad058..0000000 --- a/docs/deploying-in-tomee.mdtext +++ /dev/null @@ -1,69 +0,0 @@ -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. \ No newline at end of file http://git-wip-us.apache.org/repos/asf/tomee/blob/c3f8984b/docs/deployment-id.mdtext ---------------------------------------------------------------------- diff --git a/docs/deployment-id.mdtext b/docs/deployment-id.mdtext deleted file mode 100644 index 58c7d3d..0000000 --- a/docs/deployment-id.mdtext +++ /dev/null @@ -1,227 +0,0 @@ -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".
