tomee-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From jlmonte...@apache.org
Subject [06/44] tomee git commit: TOMEE-2316 Convert Markdown files to Asciidoc in the docs folder - 4
Date Thu, 06 Dec 2018 08:52:51 GMT
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 <cchacin@gmail.com>
Authored: Wed Dec 5 22:07:20 2018 -0800
Committer: Carlos Chacin <cchacin@gmail.com>
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&nbsp;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&nbsp;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&nbsp;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&reg; 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&reg; 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) &lt;file&gt; \[&lt;file&gt; ...\]
-
-<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 &lt;url&gt; </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".
+....


Mime
View raw message