TOMEE-2316 Convert Markdown files to Asciidoc in the docs folder - 4
Project: http://git-wip-us.apache.org/repos/asf/tomee/repo Commit: http://git-wip-us.apache.org/repos/asf/tomee/commit/b45a3d00 Tree: http://git-wip-us.apache.org/repos/asf/tomee/tree/b45a3d00 Diff: http://git-wip-us.apache.org/repos/asf/tomee/diff/b45a3d00 Branch: refs/heads/master Commit: b45a3d00ad9751bc33e27af30ef6c14fb0f3c099 Parents: 388460f Author: Carlos Chacin <[email protected]> Authored: Wed Dec 5 22:07:20 2018 -0800 Committer: Carlos Chacin <[email protected]> Committed: Wed Dec 5 22:07:20 2018 -0800 ---------------------------------------------------------------------- docs/datasource-config.adoc | 527 ++++++++++++++++++++ docs/datasource-config.md | 541 --------------------- docs/datasource-configuration-by-creator.adoc | 160 ++++++ docs/datasource-configuration-by-creator.md | 155 ------ docs/datasource-password-encryption.adoc | 159 ++++++ docs/datasource-password-encryption.md | 128 ----- docs/deamon/lin-service.adoc | 24 + docs/deamon/lin-service.md | 17 - docs/deamon/win-service.adoc | 24 + docs/deamon/win-service.md | 17 - docs/declaring-references.adoc | 6 + docs/declaring-references.md | 6 - docs/deploy-tool.adoc | 167 +++++++ docs/deploy-tool.md | 165 ------- docs/deploying-in-tomee.adoc | 73 +++ docs/deploying-in-tomee.md | 73 --- docs/deployment-id.adoc | 231 +++++++++ docs/deployment-id.md | 231 --------- docs/deployments.adoc | 146 ++++++ docs/deployments.md | 135 ----- docs/details-on-openejb-jar.adoc | 152 ++++++ docs/details-on-openejb-jar.md | 156 ------ docs/documentation.adoc | 103 ++++ docs/documentation.md | 106 ---- docs/documentation.old.adoc | 98 ++++ docs/documentation.old.md | 102 ---- docs/dynamic-datasource.adoc | 219 +++++++++ docs/dynamic-datasource.md | 220 --------- 28 files changed, 2089 insertions(+), 2052 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/tomee/blob/b45a3d00/docs/datasource-config.adoc ---------------------------------------------------------------------- diff --git a/docs/datasource-config.adoc b/docs/datasource-config.adoc new file mode 100644 index 0000000..3260b89 --- /dev/null +++ b/docs/datasource-config.adoc @@ -0,0 +1,527 @@ +# DataSource Configuration +:index-group: Datasource +:jbake-date: 2018-12-05 +:jbake-type: page +:jbake-status: published + + +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 link:common-datasource-configurations.html[Common DataSource +Configurations] page for examples of configuring datasources for Derby, +MySQL, Oracle and other common databases. + +== Supported Properties + +Property + +Type + +Default + +Description + +accessToUnderlyingConnectionAllowed + +boolean + +false + +If true the raw physical connection to the database can be accessed + +alternateUsernameAllowed + +boolean + +false + +If true allow an alternate username and password to be specified on the +connection, rather than those specified in the DataSource definition.. + +connectionProperties + +String + +The connection properties that will be sent to the JDBC driver when +establishing new connections + +defaultAutoCommit + +boolean + +true + +The default auto-commit state of new connections + +defaultReadOnly + +String + +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) + +definition + +String + +ignoreDefaultValues + +boolean + +false + +use only all set values in this config will need a lot of properties but +allow to not set some values + +initialSize + +int + +0 + +The size to reach when creating the datasource. + +jdbcDriver + +String + +org.hsqldb.jdbcDriver + +Driver class name + +jdbcUrl + +java.net.URI + +jdbc:hsqldb:mem:hsqldb + +Url for creating connections + +jtaManaged + +boolean + +true + +Determines wether or not this data source should be JTA managed or user +managed. + +maxActive + +int + +20 + +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". + +maxIdle + +int + +20 + +The maximum number of connections that can remain idle in the pool, +without extra ones being released, or a negative number for no limit. + +maxOpenPreparedStatements + +int + +0 + +The maximum number of open statements that can be allocated from the +statement pool at the same time, or zero for no limit. + +maxWaitTime + +time + +-1 millisecond + +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. + +minEvictableIdleTime + +time + +30 minutes + +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). + +minIdle + +int + +0 + +The minimum number of connections that can remain idle in the pool, +without extra ones being created, or zero to create none. + +numTestsPerEvictionRun + +int + +3 + +The number of connectionss to examine during each run of the idle +connection evictor thread (if any). + +password + +String + +Default password + +passwordCipher + +String + +PlainText + +poolPreparedStatements + +boolean + +false + +If true, a statement pool is created for each Connection and +PreparedStatements created by one of the following methods are pooled: + +serviceId + +String + +testOnBorrow + +boolean + +true + +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). + +testOnReturn + +boolean + +false + +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. + +testWhileIdle + +boolean + +false + +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 + +timeBetweenEvictionRuns + +time + +-1 millisecond + +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. + +userName + +String + +sa + +Default user name + +validationQuery + +String + +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. + +LogSql + +boolean + +false + +Wether SQL queries should be logged or not + +== 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. + +== 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. + +== 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 + +== initialSize + +The initial size to initialize the pool of connections. + +== 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' + +== 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. + +== 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) +.... + +== 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. + +== 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. + +== 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) + +link:datasource-configuration-by-creator.html[Configuration by creator] http://git-wip-us.apache.org/repos/asf/tomee/blob/b45a3d00/docs/datasource-config.md ---------------------------------------------------------------------- diff --git a/docs/datasource-config.md b/docs/datasource-config.md deleted file mode 100644 index 3ad7494..0000000 --- a/docs/datasource-config.md +++ /dev/null @@ -1,541 +0,0 @@ -index-group=Datasource -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/b45a3d00/docs/datasource-configuration-by-creator.adoc ---------------------------------------------------------------------- diff --git a/docs/datasource-configuration-by-creator.adoc b/docs/datasource-configuration-by-creator.adoc new file mode 100644 index 0000000..118481b --- /dev/null +++ b/docs/datasource-configuration-by-creator.adoc @@ -0,0 +1,160 @@ +# DataSource Creator +:index-group: Datasource +:jbake-date: 2018-12-05 +:jbake-type: page +:jbake-status: published + +TomEE uses  `creator` to create the connection pool factory. In other +terms it means you can use any pool you want for DataSource in TomEE. + +Default provided pools are DBCP (default in embedded mode) and Tomcat +JDBC (default in TomEE to be aligned on Tomcat). + +Depending which one you use the accept configuration are not 100% the +same even if we try to align the most common entries to the historical +configuration (ie DBCP). + +Here are a more detailled list of accepted properties by creator. + +== DBCP2 (TomEE 7.x and 8.x) + +Note: details are at +http://tomee.apache.org/containers-and-resources.html (note: +http://commons.apache.org/proper/commons-dbcp/configuration.html uses +the latest version of DBCP but TomEE 1.7.x is not using this version). + +* AccessToUnderlyingConnectionAllowed +* ConnectionInitSqls +* ConnectionProperties +* DefaultAutoCommit +* DefaultCatalog +* DefaultReadOnly +* DefaultTransactionIsolation +* Delegate +* InitialSize +* JdbcDriver +* JdbcUrl +* LogAbandoned +* LogWriter +* LoginTimeout +* MaxActive +* MaxIdle +* MaxOpenPreparedStatements +* MaxWait +* MinEvictableIdleTimeMillis +* MinIdle +* Name +* NumTestsPerEvictionRun +* Password +* PasswordCipher +* PoolPreparedStatements +* RemoveAbandoned +* RemoveAbandonedTimeout +* TestOnBorrow +* TestOnReturn +* TestWhileIdle +* TimeBetweenEvictionRunsMillis +* UserName +* ValidationQuery +* ValidationQueryTimeout + +== Tomcat JDBC + +Note: details are at +https://tomcat.apache.org/tomcat-7.0-doc/jdbc-pool.html + +* AbandonWhenPercentageFull +* AccessToUnderlyingConnectionAllowed +* AlternateUsernameAllowed +* CommitOnReturn +* ConnectionProperties +* DataSource +* DataSourceJNDI +* DbProperties +* DefaultAutoCommit +* DefaultCatalog +* DefaultReadOnly +* DefaultTransactionIsolation +* DriverClassName +* FairQueue +* IgnoreExceptionOnPreLoad +* InitSQL +* InitialSize +* JdbcInterceptors +* JmxEnabled +* LogAbandoned +* LogValidationErrors +* LogWriter +* LoginTimeout +* MaxActive +* MaxAge +* MaxIdle +* MaxWait +* MinEvictableIdleTimeMillis +* MinIdle +* Name +* NumTestsPerEvictionRun +* Password +* PasswordCipher +* PoolProperties +* PropagateInterruptState +* RemoveAbandoned +* RemoveAbandonedTimeout +* RollbackOnReturn +* SuspectTimeout +* TestOnBorrow +* TestOnConnect +* TestOnReturn +* TestWhileIdle +* TimeBetweenEvictionRunsMillis +* Url +* UseDisposableConnectionFacade +* UseEquals +* UseLock +* Username +* ValidationInterval +* ValidationQuery +* ValidationQueryTimeout +* Validator +* ValidatorClassName + +== DBCP2 (TomEE 7.x) + +Note: details are at +http://commons.apache.org/proper/commons-dbcp/configuration.html + +* AccessToUnderlyingConnectionAllowed +* ConnectionInitSqls +* ConnectionProperties +* DefaultAutoCommit +* DefaultCatalog +* DefaultReadOnly +* DefaultTransactionIsolation +* Delegate +* InitialSize +* JdbcDriver +* JdbcUrl +* LogAbandoned +* LogWriter +* LoginTimeout +* MaxTotal +* MaxIdle +* MaxOpenPreparedStatements +* MaxWait +* MinEvictableIdleTimeMillis +* MinIdle +* Name +* NumTestsPerEvictionRun +* Password +* PasswordCipher +* PoolPreparedStatements +* RemoveAbandonedOnBorrow +* RemoveAbandonedOnMaintenance +* RemoveAbandonedTimeout +* TestOnBorrow +* TestOnReturn +* TestWhileIdle +* TimeBetweenEvictionRunsMillis +* UserName +* ValidationQuery +* ValidationQueryTimeout http://git-wip-us.apache.org/repos/asf/tomee/blob/b45a3d00/docs/datasource-configuration-by-creator.md ---------------------------------------------------------------------- diff --git a/docs/datasource-configuration-by-creator.md b/docs/datasource-configuration-by-creator.md deleted file mode 100644 index 4c3136d..0000000 --- a/docs/datasource-configuration-by-creator.md +++ /dev/null @@ -1,155 +0,0 @@ -index-group=Datasource -type=page -status=published -title=DataSource Creator -~~~~~~ - -TomEE uses  `creator` to create the connection pool factory. In other terms it means you can -use any pool you want for DataSource in TomEE. - -Default provided pools are DBCP (default in embedded mode) and Tomcat JDBC (default in TomEE to be aligned on Tomcat). - -Depending which one you use the accept configuration are not 100% the same even if we try to -align the most common entries to the historical configuration (ie DBCP). - -Here are a more detailled list of accepted properties by creator. - - -## DBCP (TomEE 1.7.x) - -Note: details are at http://tomee.apache.org/containers-and-resources.html -(note: http://commons.apache.org/proper/commons-dbcp/configuration.html uses the latest version of DBCP but TomEE 1.7.x is not using this version). - -- AccessToUnderlyingConnectionAllowed -- ConnectionInitSqls -- ConnectionProperties -- DefaultAutoCommit -- DefaultCatalog -- DefaultReadOnly -- DefaultTransactionIsolation -- Delegate -- InitialSize -- JdbcDriver -- JdbcUrl -- LogAbandoned -- LogWriter -- LoginTimeout -- MaxActive -- MaxIdle -- MaxOpenPreparedStatements -- MaxWait -- MinEvictableIdleTimeMillis -- MinIdle -- Name -- NumTestsPerEvictionRun -- Password -- PasswordCipher -- PoolPreparedStatements -- RemoveAbandoned -- RemoveAbandonedTimeout -- TestOnBorrow -- TestOnReturn -- TestWhileIdle -- TimeBetweenEvictionRunsMillis -- UserName -- ValidationQuery -- ValidationQueryTimeout - -## Tomcat JDBC - -Note: details are at https://tomcat.apache.org/tomcat-7.0-doc/jdbc-pool.html - -- AbandonWhenPercentageFull -- AccessToUnderlyingConnectionAllowed -- AlternateUsernameAllowed -- CommitOnReturn -- ConnectionProperties -- DataSource -- DataSourceJNDI -- DbProperties -- DefaultAutoCommit -- DefaultCatalog -- DefaultReadOnly -- DefaultTransactionIsolation -- DriverClassName -- FairQueue -- IgnoreExceptionOnPreLoad -- InitSQL -- InitialSize -- JdbcInterceptors -- JmxEnabled -- LogAbandoned -- LogValidationErrors -- LogWriter -- LoginTimeout -- MaxActive -- MaxAge -- MaxIdle -- MaxWait -- MinEvictableIdleTimeMillis -- MinIdle -- Name -- NumTestsPerEvictionRun -- Password -- PasswordCipher -- PoolProperties -- PropagateInterruptState -- RemoveAbandoned -- RemoveAbandonedTimeout -- RollbackOnReturn -- SuspectTimeout -- TestOnBorrow -- TestOnConnect -- TestOnReturn -- TestWhileIdle -- TimeBetweenEvictionRunsMillis -- Url -- UseDisposableConnectionFacade -- UseEquals -- UseLock -- Username -- ValidationInterval -- ValidationQuery -- ValidationQueryTimeout -- Validator -- ValidatorClassName - -## DBCP2 (TomEE 7.x and 8.x) - -Note: details are at http://commons.apache.org/proper/commons-dbcp/configuration.html - -- AccessToUnderlyingConnectionAllowed -- ConnectionInitSqls -- ConnectionProperties -- DefaultAutoCommit -- DefaultCatalog -- DefaultReadOnly -- DefaultTransactionIsolation -- Delegate -- InitialSize -- JdbcDriver -- JdbcUrl -- LogAbandoned -- LogWriter -- LoginTimeout -- MaxTotal -- MaxIdle -- MaxOpenPreparedStatements -- MaxWait -- MinEvictableIdleTimeMillis -- MinIdle -- Name -- NumTestsPerEvictionRun -- Password -- PasswordCipher -- PoolPreparedStatements -- RemoveAbandonedOnBorrow -- RemoveAbandonedOnMaintenance -- RemoveAbandonedTimeout -- TestOnBorrow -- TestOnReturn -- TestWhileIdle -- TimeBetweenEvictionRunsMillis -- UserName -- ValidationQuery -- ValidationQueryTimeout http://git-wip-us.apache.org/repos/asf/tomee/blob/b45a3d00/docs/datasource-password-encryption.adoc ---------------------------------------------------------------------- diff --git a/docs/datasource-password-encryption.adoc b/docs/datasource-password-encryption.adoc new file mode 100644 index 0000000..6d6b3bc --- /dev/null +++ b/docs/datasource-password-encryption.adoc @@ -0,0 +1,159 @@ +# DataSource Password Encryption +:index-group: Unrevised +:jbake-date: 2018-12-05 +:jbake-type: page +:jbake-status: published + +_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._ + +# 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. + +== 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:-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 + +-h, --_help_ + +Lists these options and exit. + +-c, --_cipher_ + +Specifies the password cipher implementation to use (default is +Static3DES). + +-d, --_decrypt_ + +Switches command line tool to decrypt. + +-e, --_encrypt_ + +Switches command line tool to encrypt (default). + +==== EXAMPLES + +Encrypt a plain password using the default algorithm. + +.... +`openejb cipher Passw0rd` +.... + +Output + +.... +xMH5uM1V9vQzVUv5LG7YLA== +.... http://git-wip-us.apache.org/repos/asf/tomee/blob/b45a3d00/docs/datasource-password-encryption.md ---------------------------------------------------------------------- diff --git a/docs/datasource-password-encryption.md b/docs/datasource-password-encryption.md deleted file mode 100644 index f8aa7cc..0000000 --- a/docs/datasource-password-encryption.md +++ /dev/null @@ -1,128 +0,0 @@ -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/b45a3d00/docs/deamon/lin-service.adoc ---------------------------------------------------------------------- diff --git a/docs/deamon/lin-service.adoc b/docs/deamon/lin-service.adoc new file mode 100644 index 0000000..bafa638 --- /dev/null +++ b/docs/deamon/lin-service.adoc @@ -0,0 +1,24 @@ +:index-group: Unrevised +:jbake-date: 2018-12-05 +:jbake-type: page +:jbake-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 http://git-wip-us.apache.org/repos/asf/tomee/blob/b45a3d00/docs/deamon/lin-service.md ---------------------------------------------------------------------- diff --git a/docs/deamon/lin-service.md b/docs/deamon/lin-service.md deleted file mode 100644 index f5bc18c..0000000 --- a/docs/deamon/lin-service.md +++ /dev/null @@ -1,17 +0,0 @@ -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/b45a3d00/docs/deamon/win-service.adoc ---------------------------------------------------------------------- diff --git a/docs/deamon/win-service.adoc b/docs/deamon/win-service.adoc new file mode 100644 index 0000000..bafa638 --- /dev/null +++ b/docs/deamon/win-service.adoc @@ -0,0 +1,24 @@ +:index-group: Unrevised +:jbake-date: 2018-12-05 +:jbake-type: page +:jbake-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 http://git-wip-us.apache.org/repos/asf/tomee/blob/b45a3d00/docs/deamon/win-service.md ---------------------------------------------------------------------- diff --git a/docs/deamon/win-service.md b/docs/deamon/win-service.md deleted file mode 100644 index f5bc18c..0000000 --- a/docs/deamon/win-service.md +++ /dev/null @@ -1,17 +0,0 @@ -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/b45a3d00/docs/declaring-references.adoc ---------------------------------------------------------------------- diff --git a/docs/declaring-references.adoc b/docs/declaring-references.adoc new file mode 100644 index 0000000..c6c3107 --- /dev/null +++ b/docs/declaring-references.adoc @@ -0,0 +1,6 @@ +# Declaring References +:index-group: Unrevised +:jbake-date: 2018-12-05 +:jbake-type: page +:jbake-status: published + http://git-wip-us.apache.org/repos/asf/tomee/blob/b45a3d00/docs/declaring-references.md ---------------------------------------------------------------------- diff --git a/docs/declaring-references.md b/docs/declaring-references.md deleted file mode 100644 index 5cfabca..0000000 --- a/docs/declaring-references.md +++ /dev/null @@ -1,6 +0,0 @@ -index-group=Unrevised -type=page -status=published -title=Declaring References -~~~~~~ - http://git-wip-us.apache.org/repos/asf/tomee/blob/b45a3d00/docs/deploy-tool.adoc ---------------------------------------------------------------------- diff --git a/docs/deploy-tool.adoc b/docs/deploy-tool.adoc new file mode 100644 index 0000000..f269dfe --- /dev/null +++ b/docs/deploy-tool.adoc @@ -0,0 +1,167 @@ +:index-group: OpenEJB +Standalone Server +:jbake-date: 2018-12-05 +:jbake-type: page +:jbake-status: published +:jbake-title: Deploy Tool + + +# NAME + +openejb deploy - OpenEJB Deploy Tool + +# SYNOPSIS + +____________________________________________________________________ +openejb deploy link:#DeployTool-OPTIONS[options] <file> [<file> ...] +____________________________________________________________________ + +# 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:-3.0> bindeploy --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 +_____________________ + +# 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. + +# OPTIONS + +-d, --debug + +Increases the level of detail on validation errors and deployment +summary. + +--dir + +Sets the destination directory where the app will be deployed. The +default is /apps/ directory. Note when changing this setting make sure +the directory is listed in the openejb.xml via a tag or the app will not +be picked up again on restart. + +-conf file + +Sets the OpenEJB configuration to the specified file. + +-h, --help + +Lists these options and exit. + +-o, --offline + +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. + +-q, --quiet + +Decreases the level of detail on validation and skips the deployment +summary. + +-s, --server-url <url> + +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'. + +-v, --version + +Prints the OpenEJB version and exits. + +# EXAMPLES + +== Deploying multiple jar files + +__________________________________ +openejb deploy myapp.jar myapp.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 +_________________________ + +# 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/b45a3d00/docs/deploy-tool.md ---------------------------------------------------------------------- diff --git a/docs/deploy-tool.md b/docs/deploy-tool.md deleted file mode 100644 index df0137d..0000000 --- a/docs/deploy-tool.md +++ /dev/null @@ -1,165 +0,0 @@ -index-group=OpenEJB Standalone Server -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/b45a3d00/docs/deploying-in-tomee.adoc ---------------------------------------------------------------------- diff --git a/docs/deploying-in-tomee.adoc b/docs/deploying-in-tomee.adoc new file mode 100644 index 0000000..7d1c322 --- /dev/null +++ b/docs/deploying-in-tomee.adoc @@ -0,0 +1,73 @@ +:index-group: General Information +:jbake-date: 2018-12-05 +:jbake-type: page +:jbake-status: published + + +NOTE: 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, +link:tomee-and-eclipse.html[tomee-and-eclipse] 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 + +==== 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 + +==== 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/b45a3d00/docs/deploying-in-tomee.md ---------------------------------------------------------------------- diff --git a/docs/deploying-in-tomee.md b/docs/deploying-in-tomee.md deleted file mode 100644 index 63f1d42..0000000 --- a/docs/deploying-in-tomee.md +++ /dev/null @@ -1,73 +0,0 @@ -index-group=General Information -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/b45a3d00/docs/deployment-id.adoc ---------------------------------------------------------------------- diff --git a/docs/deployment-id.adoc b/docs/deployment-id.adoc new file mode 100644 index 0000000..0855413 --- /dev/null +++ b/docs/deployment-id.adoc @@ -0,0 +1,231 @@ +# Deployment ID +:index-group: Unrevised +:jbake-date: 2018-12-05 +:jbake-type: page +:jbake-status: published + + +# 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. + +== Like ejb-name + +This deployment id is much like the element of the ejb-jar.xml , with +one very important difference. The 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. + +== 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 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. + +== 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. + +== 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! + +# How is it used? + +== 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. + +== 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 , , and +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 + +== 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"); +... +.... + +== 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 ); +... +.... + +# 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". +....
