You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@tomee.apache.org by db...@apache.org on 2018/11/30 23:04:30 UTC
[15/20] tomee git commit: Docs old and new
http://git-wip-us.apache.org/repos/asf/tomee/blob/f779264f/docs/datasource-config.mdtext
----------------------------------------------------------------------
diff --git a/docs/datasource-config.mdtext b/docs/datasource-config.mdtext
new file mode 100644
index 0000000..9f0cebd
--- /dev/null
+++ b/docs/datasource-config.mdtext
@@ -0,0 +1,537 @@
+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>
+<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/f779264f/docs/datasource-configuration-by-creator.md
----------------------------------------------------------------------
diff --git a/docs/datasource-configuration-by-creator.md b/docs/datasource-configuration-by-creator.md
new file mode 100644
index 0000000..1a02b70
--- /dev/null
+++ b/docs/datasource-configuration-by-creator.md
@@ -0,0 +1,151 @@
+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)
+
+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
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/tomee/blob/f779264f/docs/datasource-password-encryption.mdtext
----------------------------------------------------------------------
diff --git a/docs/datasource-password-encryption.mdtext b/docs/datasource-password-encryption.mdtext
new file mode 100644
index 0000000..2ddc25f
--- /dev/null
+++ b/docs/datasource-password-encryption.mdtext
@@ -0,0 +1,124 @@
+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>
+<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/f779264f/docs/deamon/lin-service.mdtext
----------------------------------------------------------------------
diff --git a/docs/deamon/lin-service.mdtext b/docs/deamon/lin-service.mdtext
new file mode 100644
index 0000000..f3a59f6
--- /dev/null
+++ b/docs/deamon/lin-service.mdtext
@@ -0,0 +1,13 @@
+###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/f779264f/docs/deamon/win-service.mdtext
----------------------------------------------------------------------
diff --git a/docs/deamon/win-service.mdtext b/docs/deamon/win-service.mdtext
new file mode 100644
index 0000000..f3a59f6
--- /dev/null
+++ b/docs/deamon/win-service.mdtext
@@ -0,0 +1,13 @@
+###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/f779264f/docs/declaring-references.mdtext
----------------------------------------------------------------------
diff --git a/docs/declaring-references.mdtext b/docs/declaring-references.mdtext
new file mode 100644
index 0000000..088e285
--- /dev/null
+++ b/docs/declaring-references.mdtext
@@ -0,0 +1,2 @@
+Title: Declaring References
+
http://git-wip-us.apache.org/repos/asf/tomee/blob/f779264f/docs/deploy-tool.mdtext
----------------------------------------------------------------------
diff --git a/docs/deploy-tool.mdtext b/docs/deploy-tool.mdtext
new file mode 100644
index 0000000..b3c724a
--- /dev/null
+++ b/docs/deploy-tool.mdtext
@@ -0,0 +1,161 @@
+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>
+<tr>
+<td>-d, --debug </td>
+<td>Increases the level of detail on validation errors and
+deployment summary.</td>
+</tr>
+
+<tr><td>--dir </td>
+<td>Sets the destination directory where the app will be deployed.
+The default is <OPENEJB_HOME>/apps/ directory. Note when changing this
+setting make sure the directory is listed in the openejb.xml via a
+<Deployments dir=""/> tag or the app will not be picked up again on
+restart.
+</tr>
+
+<tr><td>-conf file </td>
+<td>Sets the OpenEJB configuration to the specified file.</td></tr>
+
+<tr><td>-h, --help </td>
+<td>Lists these options and exit.</td></tr>
+
+<tr><td>-o, --offline</td>
+<td>Deploys the app to an offline server by copying the
+archive into the server's apps/ directory. The app will be deployed when
+the server is started. The default is online.</td></tr>
+
+<tr><td>-q, --quiet </td>
+<td> Decreases the level of detail on validation and skips the
+deployment summary.</td></tr>
+
+<tr><td>-s, --server-url <url> </td>
+<td> Sets the url of the OpenEJB server to which
+the app will be deployed. The value should be the same as the JNDI
+Provider URL used to lookup EJBs. The default is 'ejbd://localhost:4201'.
+</td></tr>
+
+<tr><td>-v, --version</td>
+<td> Prints the OpenEJB version and exits. </td></tr>
+</table>
+
+
+<a name="DeployTool-EXAMPLES"></a>
+# EXAMPLES
+
+
+<a name="DeployTool-Deployingmultiplejarfiles"></a>
+## Deploying multiple jar files
+
+
+> openejb deploy myapp\fooEjbs.jar myapp\barEjbs.jar
+
+
+Deploys the beans in the fooEjbs.jar first, then deploys the beans in the
+barEjbs.jar. Wildcards can be used as well.
+
+> openejb deploy myapp\*.jar
+
+
+<a name="DeployTool-OUTPUT"></a>
+# OUTPUT
+
+On running the deploy tool with a valid EJB jar the following output is
+printed on the console
+
+
+ Application deployed successfully at {0}
+ App(id=C:\samples\Calculator-new\hello-addservice.jar)
+ EjbJar(id=hello-addservice.jar, path=C:\samples\Calculator-new\hello-addservice.jar)
+ Ejb(ejb-name=HelloBean, id=HelloBean)
+ Jndi(name=HelloBean)
+ Jndi(name=HelloBeanLocal)
+
+ Ejb(ejb-name=AddServiceBean, id=AddServiceBean)
+ Jndi(name=AddServiceBean)
+ Jndi(name=AddServiceBeanLocal)
+
+
+Note: In the above case the command used is:
+> openejb deploy hello-addservice.jar
+
+The JAR file contains two EJBs: AddServiceBean and HelloBean.
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/tomee/blob/f779264f/docs/deploying-in-tomee.mdtext
----------------------------------------------------------------------
diff --git a/docs/deploying-in-tomee.mdtext b/docs/deploying-in-tomee.mdtext
new file mode 100644
index 0000000..ebad058
--- /dev/null
+++ b/docs/deploying-in-tomee.mdtext
@@ -0,0 +1,69 @@
+Title:
+Notice: Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+ .
+ http://www.apache.org/licenses/LICENSE-2.0
+ .
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License.
+
+#Deploying in TomEE
+
+Deploying applications in TomEE is as simple as deploying them in Tomcat.
+
+You could deploy your application in Eclipse just like how you would deploy with Tomcat. For an example, [tomee-and-eclipse](tomee-and-eclipse.html) shows how to use TomEE with Eclipse.
+
+Or you can simply package your application as a standard **WAR** file and copy it to the **[TomEE]/webapps** folder, or as an **EAR** file and copy it to the **[TomEE]/apps** folder.
+
+Read on to learn more about packaging EJBs in a WAR file.
+
+
+### Packaging
+
+<a name="CollapsedEAR-Onearchive"></a>
+#### One archive
+
+The basic idea of this approach is that your Servlets and EJBs are together in your WAR file as one application.
+
+ - No classloader boundaries between Servlets and EJBs
+
+ - EJBs and Servlets can share all third-party libraries (like Spring\!)
+
+ - No EAR required.
+
+ - Can put the web.xml and ejb-jar.xml in the same archive (the WAR file)
+
+ - EJBs can see Servlet classes and vice versa
+
+<a name="CollapsedEAR-NotquiteJ2EE(itistrulyJava EE6)"></a>
+#### Not quite J2EE (But it is Java EE 6)
+
+This is very different than J2EE or Java EE 5 as there are not several levels of separation and classloader hierarchy any more.
+This may take some getting used to and it is important to understand that this style of packaging is **not** J2EE compliant.
+You should not worry though, as it is an accepted feature of Java EE 6.
+
+#### J2EE classloading rules:
+ - You cannot ever have EJBs and Servlets in the same classloader.
+
+ - Three classloader minimum; a classloader for the ear, one for each
+ejb-jar, and one for each WAR file.
+
+ - Servlets can see EJBs, but EJBs cannot see Servlets.
+
+ To pull that off, J2EE has to kill you on packaging:
+ - You cannot have EJB classes and Servlet classes in the same archive.
+
+ - You need at least three archives to combine Servlets and EJBs; 1 EAR containing 1 EJB jar and 1 Servlet WAR.
+
+ - Shared libraries must go in the EAR and be included in a specially formatted 'Class-Path' entry in the EAR's MANIFEST file.
+
+ Critically speaking, forcing more than one classloader on an application is where J2EE "jumps the shark" for a large majority of people's needs.
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/tomee/blob/f779264f/docs/deployment-id.mdtext
----------------------------------------------------------------------
diff --git a/docs/deployment-id.mdtext b/docs/deployment-id.mdtext
new file mode 100644
index 0000000..58c7d3d
--- /dev/null
+++ b/docs/deployment-id.mdtext
@@ -0,0 +1,227 @@
+Title: Deployment ID
+
+<a name="DeploymentID-WhatisaDeploymentID?"></a>
+# What is a Deployment ID?
+
+Every bean deployed in OpenEJB has a unique deployment-id that identifies
+it within the scope of the entire container system. The server and
+container system refer beans at run-time using the bean's deployment id.
+
+<a name="DeploymentID-Likeejb-name"></a>
+## Like ejb-name
+
+This deployment id is much like the <ejb-name> element of the ejb-jar.xml ,
+with one very important difference. The <ejb-name> is only required to be
+unique within the scope of the ejb-jar.xml in the bean's jar. The
+deployment id is required to be unique across all beans and jars in
+OpenEJB. This is a subtle, but important, distinction.
+
+Remember that the EJB specification was designed so that enterprise beans
+could be create, packaged, and sold by vendors (EJB Providers).
+Furthermore, users should be able to buy a packaged set of beans (a jar
+with an ejb-jar.xml in it) and deploy it into an EJB Container without
+modification.
+
+<a name="DeploymentID-Theejb-nameisnotunique"></a>
+## The ejb-name is not unique
+
+Let's consider this, what happens if two vendors each sell a package (jar)
+that contains a bean with the <ejb-name> PurchaseOrder? Both are completely
+different in terms functionality and are different beans in every other
+respect. The EJB spec says, this is fine, ejb-names only have to unique
+within the jar and that jar's ejb-jar.xml file. It's ridiculous to expect
+EJB Providers to call each other up and ask, "Are you already using the
+name 'PurchaseOrder' in your jar?" Remember that the EJB specification was
+designed so that enterprise beans could be create, packaged, and sold by
+vendors (EJB Providers). Furthermore, users should be able to buy a
+packaged set of beans (a jar with an ejb-jar.xml in it) and deploy it into
+an EJB Container without modification. This is all fine and dandy, but it
+still leaves it up to the EJB Container/Server providers to settle the
+difference.
+
+<a name="DeploymentID-Thedeployment-idisunique"></a>
+## The deployment-id is unique
+
+OpenEJB solves this with the OpenEJB-specific deployment id. By requiring
+that each bean deployed into OpenEJB has a unique name, we can guarantee
+that we are always referring to the right bean at all times. Furthermore, it
+allows you to deploy different versions of the same package several times
+in the same container system, each time giving the beans new deployment
+ids.
+
+<a name="DeploymentID-Usingejb-nameasdeployment-idanyway"></a>
+## Using ejb-name as deployment-id anyway
+
+If you're lazy -- as any truly great programmer should be -- and don't want
+to type a deployment id for each bean every time you deploy a jar, you can
+use the -D option of the Deploy Tool. This will throw caution to the wind,
+and automatically assign the bean's ejb-name as the value of the bean's
+OpenEJB deployment id. This leaves up to you to guarantee that bean's
+ejb-name will be unique across all beans and jars in the container system.
+In other words, be very careful with the -D option!
+
+<a name="DeploymentID-Howisitused?"></a>
+# How is it used?
+
+<a name="DeploymentID-Inthecontainersystem"></a>
+## In the container system
+
+In the container system, the deployment id is used to index the bean in a
+system-wide registry. This registry is refereed to on every call made in the
+container system. Being able to safely hash and cache bean information by
+id is a must. This stresses the importance of unique ids for every bean
+deployed in OpenEJB.
+
+<a name="DeploymentID-IntheLocalServer"></a>
+## In the Local Server
+
+The Local (IntraVM) Server is an integral part of the container system and
+the two are, in many ways, inseparable. The Local Server takes care of all
+bean to bean and client to bean invocations made inside the virtual
+machine. For this reason, it often refered to as the IntraVM Server.
+
+For bean to bean communications, the Local Server must create a JNDI
+namespace (JNDI ENC) for each bean as defined by the bean's <env-entry>,
+<ejb-ref>, and <resource-ref> elements of the bean's ejb-jar.xml file.
+Every bean literally gets its very own JNDI namespace. When a bean makes a
+JNDI call, the Local Server intercepts this call and uses the deployment id
+of the calling bean to retrieve that bean's private JNDI namespace from the
+container system's index. The Local Server then carries out the lookup on
+that bean's namespace.
+
+All non-bean clients share one big global namespace. Since non-bean clients
+are not deployed and do not have a deployment descriptor like an
+ejb-jar.xml, the Local Server is unable to taylor a namespace for each
+non-bean client as it can for bean clients. The Local server cannot
+identify non-bean clients as they have no deployment id. All JNDI calls
+made by clients that the Local Server cannot identify go to the public,
+global namespace. The public, global JNDI namespace contains all beans and
+resources in the container system. name.
+
+Each bean is added to the public, global namespace using it's deployment id
+as its JNDI lookup. For example, if a bean had a deployment-id of
+"/my/bean/foo", a non-bean client could lookup that bean as follows.
+
+ ...
+ Object bean = initialContext.lookup("/my/bean/Foo");
+ ...
+
+
+If a bean in the container system made the above JNDI call, the Local
+Server would see the bean's identity (deployment id) hidden in the Thread,
+go get the bean's private JNDI namespace and finish the lookup on that.
+Since all names in bean's JNDI namespace are required start with
+"java:comp/env", the lookup would fail and the bean would receive a
+javax.naming.NameNotFoundException.
+
+In short...
+
+For beans:
+ - Each bean has it's own private, personalized JNDI namespace
+ - The names in it are the same names it uses in its ejb-jar.xml
+ - Beans can only access their private namespace, period
+
+For non-beans (everyone else):
+ - Non-bean clients share the public, global JNDI namespace
+ - The names in it are the deployment ids of all the beans
+ - Non-bean clients can only access the one global namespace
+
+<a name="DeploymentID-IntheRemoteServer"></a>
+## In the Remote Server
+
+The Remote Server has a public, global namespace just as the Local Server
+does. The difference being that the Remote Server only serves clients
+outside the container system and outside the virtual machine. So, all
+clients from the perspective of the Remote Server are non-bean clients. As
+a result, the Remote Server only has the one public, global JNDI namespace.
+Just as in the Local Server, the names in this namespace consist of the
+deployment ids of the beans in the container system.
+
+Just as before, clients can lookup beans from the Remote Server using the
+bean's deployment id. For example, if a bean had a deployment-id of
+"/my/bean/foo", a client could lookup that bean as follows.
+
+ ...
+ Object bean = initialContext.lookup("/my/bean/Foo");
+ ...
+
+
+<a name="DeploymentID-IntheCORBAAdapter"></a>
+## In the CORBA Adapter
+
+The CORBA Adapter is separate than the Remote Server. It adapts the OpenEJB
+Container System and the Local Server into OpenORB as an embedded library.
+It provides users of OpenORB the ability to lookup and execute beans (EJBs)
+via the RMI-IIOP protocol. All the EJBHome and EJBObject interfaces of
+beans in OpenEJB are implemented by OpenORB as CORBA stubs and ties.
+
+The beans are exported into OpenORB's naming service by deployment id. So,
+just as with the Local Server and Remote Server, clients can lookup beans
+using the bean's deployment id. OpenORB has a JNDI implementation of their
+naming service, so lookups can be done just as before.
+
+ ...
+ String[] args = ...
+
+ // The ORB and Object
+ org.omg.CORBA.ORB orb = null;
+ org.omg.CORBA.Object bean = null.
+
+ // The Naming Service and Object Name
+ org.omg.CosNaming.NamingContext context = null;
+ org.omg.CosNaming.NameComponent[] name = null;
+
+ // Get the ORB
+ orb = org.omg.CORBA.ORB.init( args, null );
+
+ // Get the Naming Service
+ org.omg.CORBA.Object ref = null;
+ ref = orb.resolve_initial_references("NameService");
+ context = org.omg.CosNaming.NamingContextHelper.narrow( ref );
+
+ // Get the Name as a component
+ // Note: the string is the bean's deployment id
+ name = new org.omg.CosNaming.NameComponent[ 1 ];
+ name[0] = new org.omg.CosNaming.NameComponent("/my/bean/foo","");
+
+ // Finally, get the bean as a CORBA object
+ // Equvalent to an InitialContext.lookup("/my/bean/foo");
+ bean = context.resolve( name );
+ ...
+
+
+<a name="DeploymentID-WhathappensifthereisaduplicatedeploymentID?"></a>
+# What happens if there is a duplicate deployment ID?
+
+The deployment ID uniquely identifies the bean in the OpenEJB container
+system. Therefore, no two beans can share the same deployment ID.
+
+If a bean attempts to use a deployment ID that is already in use by another
+bean, the second bean and all beans in it's jar will not be loaded. In
+addition, the system will log a warning like the following one asking you
+to redeploy the jar and choose an different deployment ID for the bean.
+
+ WARN : Jar C:\openejb\beans\fooEjbs.jar cannot be loaded. The Deployment ID "/my/bean/foo" is already in use. Please redeploy this jar and assign a different deployment ID to the bean with the ejb-name "FooBean".
+
+For example, the acmeEjbs.jar contains a bean with the ejb-name
+"DaffyDuckBean". The disneyEjbs.jar contains contains a bean with the
+ejb-name "DonaldDuckBean".
+
+We deploy the acmeEjbs.jar and give the "DaffyDuckBean" the deployment ID
+of "/my/favorite/duck". Sometime afterwards, we deploy the disneyEjbs.jar
+and assign the "DonaldDuckBean" the deployment ID "/my/favorite/duck",
+having forgotten that we already gave that unique ID to the "DaffyDuckBean"
+in the acmeEjbs.jar.
+
+When the container system is started, the system will begin loading all the
+beans one jar at a time. It will first load the acmeEjbs.jar and index each
+bean by deployment ID. But, when the system reaches the disneyEjbs.jar, it
+will discover that it cannot index the "DonaldDuckBean" using the
+deployment ID "/my/favorite/duck" because that index is already taken.
+
+The system cannot load the "DonaldDuckBean" and must also ignore the rest
+of the beans in the disneyEjbs.jar as they may need the "DonaldDuckBean"
+bean to function properly. The disneyEjbs.jar is skipped and the following
+warning is logged.
+
+ WARN : Jar C:\openejb\beans\disneyEjbs.jar cannot be loaded. The Deployment ID "/my/favorite/duck" is already in use. Please redeploy this jar and assign a different deployment ID to the bean with the ejb-name "DonaldDuckBean".
http://git-wip-us.apache.org/repos/asf/tomee/blob/f779264f/docs/deployments.mdtext
----------------------------------------------------------------------
diff --git a/docs/deployments.mdtext b/docs/deployments.mdtext
new file mode 100644
index 0000000..90ab0cf
--- /dev/null
+++ b/docs/deployments.mdtext
@@ -0,0 +1,131 @@
+Title: Deployments
+
+<a name="Deployments-The'Deployments'elementinopenejb.xml"></a>
+# The 'Deployments' element in openejb.xml
+
+<a name="Deployments-Asinglejar"></a>
+## A single jar
+
+To include a single jar by name, just declare a 'Deployments' element with
+a 'jar' attribute pointing to the jar file on the file system.
+
+ <openejb>
+ ...
+ <Deployments jar="c:\my\app\superEjbs.jar" />
+ <Deployments jar="c:\someplace\purchasing.jar" />
+ <Deployments jar="timeTrack.jar" />
+ </openejb>
+
+
+The last element in the example uses a relative path to point to the ejb
+jar. This path will be resolved relative to the openejb.base property.
+So, for example, of the value of openejb.base was 'c:\timeapp\' then
+OpenEJB would look for the jar 'c:\timeapp\timeTrack.jar'. See the [OPENEJB:Configuration]
+ guide for more details.
+
+## A directory of jars
+
+To point to a directory that contains several jar files that OpenEJB should
+load, simply declare a 'Deployments' element with a 'dir' attribute
+pointing to the directory containing the jar files.
+
+ <openejb>
+ ...
+
+ <Deployments dir="c:\my\app\beans\" />
+ <Deployments dir="c:\crimestopper\lib" />
+ <Deployments dir="ejbs" />
+ <Deployments dir="beans" />
+ </openejb>
+
+
+The directories listed will be searched for jars containing
+'META-INF/ejb-jar.xml' files and will be added to the list of jars to load
+if they do. Better said, it's completely safe to point to a directory
+containing a mix of ejbs and regular jar files. OpenEJB will simply skip
+over jars that do contain the required 'META-INF/ejb-jar.xml' file.
+
+The last Deployments element declares a 'beans' directory relative to
+openejb.base for holding ejb jars. This declaration is simply convention
+and not required.
+
+<a name="Deployments-Anunpackedjar"></a>
+## An unpacked jar
+
+As of 1.0 beta1, OpenEJB supports unpacked ejb jars. Simply meaning that
+you don't need to pack your ejb's into a jar file in order to use them in
+OpenEJB. You still need to follow the ejb jar layout and include an
+"META-INF/ejb-jar.xml" in the directory that contains your ejbs.
+
+For example, if you have a directory structure like this:
+
+ > C:\myapp\
+ > C:\myapp\acmeEjbs\
+ > C:\myapp\acmeEjbs\META-INF\ejb-jar.xml
+ > C:\myapp\acmeEjbs\org\acme\Foo.class
+ > C:\myapp\acmeEjbs\org\acme\FooBean.class
+ > C:\myapp\acmeEjbs\org\acme\FooHome.class
+ > C:\myapp\acmeEjbs\org\acme\Bar.class
+ > C:\myapp\acmeEjbs\org\acme\BarBean.class
+ > C:\myapp\acmeEjbs\org\acme\BarHome.class
+
+Then you would delcare a 'Deployments' element with the 'dir' attribute set
+to 'C:\myapp\acmeEjbs' as shown below.
+
+ <openejb>
+ ...
+
+ <Deployments dir="c:\myapp\acmeEjbs" />
+ </openejb>
+
+
+Note that this syntax is the same as the directory syntax above. If
+OpenEJB finds a META-INF directory with an 'ejb-jar.xml' fine inside, then
+OpenEJB will treat the directory as an unpacked ejb jar. Otherwise OpenEJB
+will look for ejb jar files to load as detailed in the above section.
+
+# Log file
+
+When trying to figure out if your ejbs were loaded, the openejb.log file is
+an incredible asset.
+
+If your ejbs were loaded successfully you should see entries like the
+following (1.x and higher only):
+
+ INFO : Loaded EJBs from
+ /usr/local/openejb-1.0-beta1/beans/openejb-itests-beans.jar
+ INFO : Loaded EJBs from
+ /usr/local/openejb-1.0-beta1/beans/openejb-webadmin-clienttools.jar
+
+If your ejbs failed to load, you will see an entry similar to the
+following.
+
+ WARN : Jar not loaded. /usr/local/openejb-1.0-beta1/beans/helloworld.jar.
+ Jar failed validation. Use the validation tool for more details
+
+Additionally, all the successfully loaded ejbs are individually listed in
+the log file at startup. The Deployment ID listed is the JNDI name used to
+lookup the ejb from a client of the Local or Remote Servers. The beans
+listed below are from our test suite.
+
+ DEBUG: Deployments : 19
+ DEBUG: Type Deployment ID
+ DEBUG: CMP_ENTITY client/tests/entity/cmp/RMI-over-IIOP/EJBHome
+ DEBUG: STATEFUL client/tests/stateful/EncBean
+ DEBUG: STATELESS client/tests/stateless/BeanManagedBasicStatelessHome
+ DEBUG: STATEFUL client/tests/stateful/BasicStatefulHome
+ DEBUG: STATELESS client/tests/stateless/EncBean
+ DEBUG: STATEFUL client/tests/stateful/BeanManagedTransactionTests/EJBHome
+ DEBUG: BMP_ENTITY client/tests/entity/bmp/RMI-over-IIOP/EJBHome
+ DEBUG: STATEFUL client/tests/stateful/RMI-over-IIOP/EJBHome
+ DEBUG: STATELESS client/tests/stateless/BeanManagedTransactionTests/EJBHome
+ DEBUG: BMP_ENTITY client/tests/entity/bmp/allowed_operations/EntityHome
+ DEBUG: CMP_ENTITY client/tests/entity/cmp/EncBean
+ DEBUG: STATEFUL client/tests/stateful/BeanManagedBasicStatefulHome
+ DEBUG: BMP_ENTITY client/tests/entity/bmp/BasicBmpHome
+ DEBUG: STATELESS client/tests/stateless/BasicStatelessHome
+ DEBUG: CMP_ENTITY client/tests/entity/cmp/BasicCmpHome
+ DEBUG: STATELESS client/tools/DatabaseHome
+ DEBUG: CMP_ENTITY client/tests/entity/cmp/allowed_operations/EntityHome
+ DEBUG: BMP_ENTITY client/tests/entity/bmp/EncBean
+ DEBUG: STATELESS client/tests/stateless/RMI-over-IIOP/EJBHome
http://git-wip-us.apache.org/repos/asf/tomee/blob/f779264f/docs/details-on-openejb-jar.mdtext
----------------------------------------------------------------------
diff --git a/docs/details-on-openejb-jar.mdtext b/docs/details-on-openejb-jar.mdtext
new file mode 100644
index 0000000..2119bf0
--- /dev/null
+++ b/docs/details-on-openejb-jar.mdtext
@@ -0,0 +1,152 @@
+Title: Details on openejb-jar
+
+<a name="Detailsonopenejb-jar-Whatisanopenejb-jar.xml?"></a>
+# What is an openejb-jar.xml?
+
+This is the file created by the Deploy Tool that maps your bean's
+deployment descriptor (ejb-jar.xml) to actual containers and resources
+declared in your OpenEJB configuration (openejb.conf). In fact, the Deploy
+tool really does nothing more than create this file and put it in your jar,
+that's it.
+
+<a name="Detailsonopenejb-jar-Whenistheopenejb-jar.xmlused?"></a>
+# When is the openejb-jar.xml used?
+
+At startup, any jar containing a openejb-jar.xml is loaded by the container
+system. The configuration tools will go looking in all the directories and
+jars you have declared in your openejb.conf with the <Deployment> element.
+For every jar file it finds, it will look inside for an openejb-jar.xml. If
+it finds one, it will attempt to load and deploy it into the container
+system.
+
+<a name="Detailsonopenejb-jar-DoIevenneedthedeploytoolthen?"></a>
+# Do I even need the deploy tool then?
+
+Nope. Typically you would only use the deploy tool to create your
+openejb-jar.xml, then just keep your openejb-jar.xml in your CVS (or other
+repository). If you learn how to maintain this openejb-jar.xml file, you'll
+never need the deploy tool again! You can do all your builds and deploys
+automatically.
+
+<a name="Detailsonopenejb-jar-WheredoIputtheopenejb-jar.xmlinmyjar?"></a>
+# Where do I put the openejb-jar.xml in my jar?
+
+The openejb-jar.xml file just goes in the META-INF directory of your jar
+next to the ejb-jar.xml file.
+
+<a name="Detailsonopenejb-jar-Isthefileformateasy?"></a>
+# Is the file format easy?
+
+If you can understand the ejb-jar.xml, the openejb-jar.xml should be a
+breeze.
+
+This is the openejb-jar.xml that is created by the Deploy tool in the Hello
+World example. As you can see, the file format is extremely simple.
+
+ <?xml version="1.0"?>
+ <openejb-jar xmlns="http://www.openejb.org/openejb-jar/1.1">
+ <ejb-deployment ejb-name="Hello"
+ deployment-id="Hello"
+ container-id="Default Stateless Container"/>
+ </openejb-jar>
+
+
+
+The *ejb-name* attribute is the name you gave the bean in your ejb-jar.xml.
+The *deployment-id* is the name you want to use to lookup the bean in your
+client's JNDI namespace. The *container-id* is the name of the container in
+your openejb.conf file that you would like the bean to run in. There MUST
+be one *ejb-deployment* element for each EJB in your jar.
+
+# What if my bean uses a JDBC datasource?
+
+Then you simply add a <resource-link> element to your <ejb-deployment>
+element like this
+
+ <?xml version="1.0"?>
+ <openejb-jar xmlns="http://www.openejb.org/openejb-jar/1.1">
+
+ <ejb-deployment ejb-name="Hello"
+ deployment-id="Hello"
+ container-id="Default Stateless Container" >
+
+ <resource-link res-ref-name="jdbc/basic/entityDatabase"
+ res-id="Default JDBC Database"/>
+
+ </ejb-deployment>
+
+ </openejb-jar>
+
+
+
+The *res-ref-name* attribute refers to the <res-ref-name> element of the
+bean's <resource-ref> declaration in the ejb-jar.xml. The *res-id*
+attribute refers to the id of the <Connector> declared in your openejb.conf
+that will handle the connections and provide access to the desired
+resource.
+
+<a name="Detailsonopenejb-jar-Howmanyresource-linkelementswillIneed?"></a>
+# How many resource-link elements will I need?
+
+You will need one <resource-link> element for every <resource-ref> element
+in your ejb-jar.xml. So if you had an ejb-jar.xml like the following
+
+ <?xml version="1.0"?>
+ <ejb-jar>
+ <enterprise-beans>
+ <session>
+ <ejb-name>MyExampleBean</ejb-name>
+ <home>com.widget.ExampleHome</home>
+ <remote>com.widget.ExampleObject</remote>
+ <ejb-class>com.widget.ExampleBean</ejb-class>
+ <session-type>Stateless</session-type>
+ <transaction-type>Container</transaction-type>
+
+ <resource-ref>
+ <description>
+ This is a reference to a JDBC database.
+ </description>
+ <res-ref-name>jdbc/myFirstDatabase</res-ref-name>
+ <res-type>javax.sql.DataSource</res-type>
+ <res-auth>Container</res-auth>
+ </resource-ref>
+
+ <resource-ref>
+ <description>
+ This is another reference to a JDBC database.
+ </description>
+ <res-ref-name>jdbc/anotherDatabase</res-ref-name>
+ <res-type>javax.sql.DataSource</res-type>
+ <res-auth>Container</res-auth>
+ </resource-ref>
+
+ </session>
+ </enterprise-beans>
+ </ejb-jar>
+
+
+Then you would need two <resource-link> elements for that bean in your
+openejb-jar.xml file as such.
+
+ <?xml version="1.0"?>
+ <openejb-jar xmlns="http://www.openejb.org/openejb-jar/1.1">
+
+ <ejb-deployment ejb-name="MyExampleBean"
+ deployment-id="MyExampleBean"
+ container-id="Default Stateless Container" >
+
+ <resource-link res-ref-name="jdbc/myFirstDatabase"
+ res-id="My Oracle JDBC Database"/>
+
+ <resource-link res-ref-name="jdbc/anotherDatabase"
+ res-id="My PostgreSQL JDBC Database"/>
+
+ </ejb-deployment>
+
+ </openejb-jar>
+
+
+
+This would require two <Connector> declarations in your openejb.conf, one
+with the *id* attribute set to _"My Oracle JDBC Database"_ , and another
+with it's *id* attribute set to _"My PostgreSQL JDBC Database"_
http://git-wip-us.apache.org/repos/asf/tomee/blob/f779264f/docs/developer/.DS_Store
----------------------------------------------------------------------
diff --git a/docs/developer/.DS_Store b/docs/developer/.DS_Store
new file mode 100644
index 0000000..23b46d8
Binary files /dev/null and b/docs/developer/.DS_Store differ
http://git-wip-us.apache.org/repos/asf/tomee/blob/f779264f/docs/developer/classloading/index.adoc
----------------------------------------------------------------------
diff --git a/docs/developer/classloading/index.adoc b/docs/developer/classloading/index.adoc
new file mode 100755
index 0000000..fb47ef3
--- /dev/null
+++ b/docs/developer/classloading/index.adoc
@@ -0,0 +1,59 @@
+= The TomEE ClassLoader
+:jbake-date: 2016-03-16
+:jbake-type: page
+:jbake-status: published
+:jbake-tomeepdf:
+
+TomEE ClassLoading is directly mapped to Tomcat one.
+
+ifndef::backend-pdf[]
+
+[#filetree.col-md-3]
+[
+ {
+ label: 'JVM',
+ description: 'The JVM classloader launching tomcat main(String[])',
+ children: [
+ {
+ label:'common.loader',
+ description:'Customizable in conf/catalina.properties, the common loader is the Tomcat classloader',
+ children: [
+ {
+ label:'shared.loader',
+ description:'Optional layer where you can add libraries for the web applications not seen by Tomcat. It is generally not used and not encouraged since Tomcat 6',
+ children: [
+ {
+ label:'webapp1',
+ description:'loader of one of your wars, it container WEB-INF/classes, WEB-INF/lib/*.jar'
+ },
+ {
+ label:'webapp2',
+ description:'loader of another one of your wars, it container WEB-INF/classes, WEB-INF/lib/*.jar'
+ },
+ {
+ label:'application1',
+ description:'loader of another application, it can be an ear, it contains lib and ejbmodules of the ear',
+ children: [
+ {
+ label:'earwebapp1',
+ description:'loader of one of the wars of the ear'
+ },
+ {
+ label:'earwebapp2',
+ description:'loader of the other webapp of the ear'
+ }
+ ]
+ }
+ ]
+ }
+ ]
+ }
+ ]
+ }
+]
+
+[#filetreedetail.col-md-8.bs-callout.bs-callout-primary]
+Click on the tree (JVM) on the left to see the detail there.
+
+endif::[]
+
http://git-wip-us.apache.org/repos/asf/tomee/blob/f779264f/docs/developer/configuration/cxf.adoc
----------------------------------------------------------------------
diff --git a/docs/developer/configuration/cxf.adoc b/docs/developer/configuration/cxf.adoc
new file mode 100755
index 0000000..997fc82
--- /dev/null
+++ b/docs/developer/configuration/cxf.adoc
@@ -0,0 +1,93 @@
+= CXF Configuration - JAX-RS (RESTful Services) and JAX-WS (Web Services)
+:jbake-date: 2016-03-16
+:jbake-type: page
+:jbake-status: published
+:jbake-tomeepdf:
+
+TomEE relies on Apache CXF for JAX-RS (RESTful Services) and JAX-WS (Web Services). It does not provide all CXF modules, but the most common ones for both specifications (JAX-RS is part of all distributions but JAX-WS is only part of plus one).
+
+== Configuration
+
+CXF API is reusable but you can also configure the interceptors through `openejb-jar.xml` (located in WEB-INF).
+
+If you want to configure JAX-RS you will use the prefix `cxf.jaxrs` and if you configure JAX-WS you use `cxf.jaxws` prefix.
+
+TIP: to configure directly the bus use `org.apache.openejb.cxf.bus.` prefix and configure it in `conf/system.properties`.
+
+To configure JAX-RS you need to add in `openejb-jar.xml` a `pojo-deployment`:
+
+[source,xml]
+----
+<?xml version="1.0" encoding="UTF-8"?>
+<openejb-jar>
+ <pojo-deployment class-name="jaxrs-application">
+ <properties>
+ # here will go the config
+ </properties>
+ </pojo-deployment>
+</openejb-jar>
+----
+
+For JAX-WS you will use a `pojo-deployment` matching the webservice class name for POJO webservices
+or an `ejb-deployment` instead of a `pojo-deployment` for EJB webservices:
+
+
+[source,xml]
+----
+<?xml version="1.0" encoding="UTF-8"?>
+<openejb-jar>
+ <ejb-deployment ejb-name="MyEJBWebService">
+ <properties>
+ # here will go the config
+ </properties>
+ </ejb-deployment>
+</openejb-jar>
+----
+
+Then once you selected your prefix and know where to write the config just use the following entries:
+
+- properties: server factory properties
+- features: CXF features
+- in-interceptors: CXF in interceptors
+- out-interceptors: CXF out interceptors
+- in-fault-interceptors: CXF in interceptors for fault handling
+- out-fault-interceptors: CXF out interceptors for fault handling
+- databinding: server databinding
+- providers (only for JAX-RS endpoint): list of JAX-RS providers
+- skip-provider-scanning (only for JAX-RS): is provider scanning on or not (default true)
+
+For features and interceptors the rule is the same: value is a list comma separated. Each value of the list is either a qualified class name or an id of a service in resources.xml.
+
+Databinding is simply either a qualified name or a service id in resources.xml (located in WEB-INF).
+
+== Sample for JAX-WS
+
+To configure WSS4J on the EJB `CalculatorBean` for instance add in openejb-jar.xml:
+
+[source,xml]
+----
+<openejb-jar xmlns="http://www.openejb.org/openejb-jar/1.1">
+ <ejb-deployment ejb-name="CalculatorBean">
+ <properties>
+ cxf.jaxws.in-interceptors = wss4j
+ </properties>
+ </ejb-deployment>
+</openejb-jar>
+----
+
+With associated resources.xml which will define precisely the `wss4j` configuration:
+
+[source,xml]
+----
+<resources>
+ <Service id="wss4j" class-name="org.apache.openejb.server.cxf.config.WSS4JInInterceptorFactory" factory-name="create">
+ action = UsernameToken
+ passwordType = PasswordText
+ passwordCallbackClass = org.superbiz.ws.security.PasswordCallbackHandler
+ </Service>
+</resources>
+----
+
+== Sample for JAX-RS
+
+link:../json/index.html[JAX-RS JSON] page shows a sample dedicated to JAX-RS.
http://git-wip-us.apache.org/repos/asf/tomee/blob/f779264f/docs/developer/ide/index.adoc
----------------------------------------------------------------------
diff --git a/docs/developer/ide/index.adoc b/docs/developer/ide/index.adoc
new file mode 100755
index 0000000..9bc3370
--- /dev/null
+++ b/docs/developer/ide/index.adoc
@@ -0,0 +1,25 @@
+= Integrated Development Environments (IDEs)
+:jbake-date: 2016-03-16
+:jbake-type: page
+:jbake-status: published
+:jbake-tomeepdf:
+
+TomEE is supported by the main IDEs in the market:
+
+- https://eclipse.org/downloads/[Eclipse]
+- https://www.jetbrains.com/idea/download/[Intellij Idea]
+- https://netbeans.org/downloads/[Netbeans]
+
+=== Eclipse
+
+Be the first to write this part!
+
+=== Idea
+
+Be the first to write this part!
+
+=== Netbeans
+
+Be the first to write this part!
+
+
http://git-wip-us.apache.org/repos/asf/tomee/blob/f779264f/docs/developer/index.adoc
----------------------------------------------------------------------
diff --git a/docs/developer/index.adoc b/docs/developer/index.adoc
new file mode 100755
index 0000000..5d49d24
--- /dev/null
+++ b/docs/developer/index.adoc
@@ -0,0 +1,7 @@
+= Developer
+:jbake-date: 2016-03-16
+:jbake-type: page
+:jbake-status: published
+:jbake-tomeepdf:
+
+Click link:../docs.html[here] to find documentation for developers.
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/tomee/blob/f779264f/docs/developer/json/index.adoc
----------------------------------------------------------------------
diff --git a/docs/developer/json/index.adoc b/docs/developer/json/index.adoc
new file mode 100755
index 0000000..9141d88
--- /dev/null
+++ b/docs/developer/json/index.adoc
@@ -0,0 +1,206 @@
+= TomEE and Apache Johnzon - JAX-RS JSON Provider
+:jbake-date: 2016-03-16
+:jbake-type: page
+:jbake-status: published
+:jbake-tomeepdf:
+
+Since TomEE 7.0, TomEE comes with Apache Johnzon.
+It means you can use JSON-P out of the box but also Johnzon Mapper
+which is the default JAX-RS provider for JSON.
+
+*IMPORTANT* - this is a breaking change with 1.x which was using jettison.
+This last one was relying on JAXB model to generate JSON which often led
+to unexpected JSON tree and some unexpected escaping too.
+
+== Getting started with Johnzon Mapper
+
+http://johnzon.apache.org/ will get more informations than this quick
+getting started but here are the basics of the mapping with Johnzon.
+
+The mapper uses a direct java to json representation.
+
+For instance this java bean:
+
+[source,java]
+----
+public class MyModel {
+ private int id;
+ private String name;
+
+ // getters/setters
+}
+----
+
+will be mapped to:
+
+[source,java]
+----
+{
+ "id": 1234,
+ "name": "Johnzon doc"
+}
+----
+
+Note that Johnzon supports several customization either directly on the MapperBuilder of through annotations.
+
+=== @JohnzonIgnore
+
+@JohnzonIgnore is used to ignore a field. You can optionally say you ignore the field until some version
+if the mapper has a version:
+
+[source,java]
+----
+public class MyModel {
+ @JohnzonIgnore
+ private String name;
+
+ // getters/setters
+}
+----
+
+Or to support name for version 3, 4, ... but ignore it for 1 and 2:
+
+
+[source,java]
+----
+public class MyModel {
+ @JohnzonIgnore(minVersion = 3)
+ private String name;
+
+ // getters/setters
+}
+----
+
+=== @JohnzonConverter
+
+Converters are used for advanced mapping between java and json.
+
+There are several converter types:
+
+1. Converter: map java to json and the opposite based on the string representation
+2. Adapter: a converter not limited to String
+3. ObjectConverter.Reader: to converter from json to java at low level
+4. ObjectConverter.Writer: to converter from java to json at low level
+4. ObjectConverter.Codec: a Reader and Writer
+
+The most common is to customize date format but they all take. For that simple case we often use a Converter:
+
+[source,java]
+----
+public class LocalDateConverter implements Converter<LocalDate> {
+ @Override
+ public String toString(final LocalDate instance) {
+ return instance.toString();
+ }
+
+ @Override
+ public LocalDate fromString(final String text) {
+ return LocalDate.parse(text);
+ }
+}
+----
+
+If you need a more advanced use case and modify the structure of the json (wrapping the value for instance)
+you will likely need Reader/Writer or a Codec.
+
+Then once your converter developed you can either register globally on the MapperBuilder or simply decorate
+the field you want to convert with @JohnzonConverter:
+
+[source,java]
+----
+public class MyModel {
+ @JohnzonConverter(LocalDateConverter.class)
+ private LocalDate date;
+
+ // getters/setters
+}
+----
+
+=== @JohnzonProperty
+
+Sometimes the json name is not java friendly (_foo or foo-bar or even 200 for instance). For that cases
+@JohnzonProperty allows to customize the name used:
+
+[source,java]
+----
+public class MyModel {
+ @JohnzonProperty("__date")
+ private LocalDate date;
+
+ // getters/setters
+}
+----
+
+=== AccessMode
+
+On MapperBuilder you have several AccessMode available by default but you can also create your own one.
+
+The default available names are:
+
+* field: to use fields model and ignore getters/setters
+* method: use getters/setters (means if you have a getter but no setter you will serialize the property but not read it)
+* strict-method (default based on Pojo convention): same as method but getters for collections are not used to write
+
+You can use these names with setAccessModeName().
+
+=== Your own mapper
+
+Since johnzon is in tomee libraries you can use it yourself (if you use maven/gradle set johnzon-mapper as provided):
+
+[source,java]
+----
+final MySuperObject object = createObject();
+
+final Mapper mapper = new MapperBuilder().build();
+mapper.writeObject(object, outputStream);
+
+final MySuperObject otherObject = mapper.readObject(inputStream, MySuperObject.class);
+----
+
+== Johnzon and JAX-RS
+
+TomEE uses by default Johnzon as JAX-RS provider for versions 7.x. If you want however to customize it you need to follow this procedure:
+
+1. Create a WEB-INF/openejb-jar.xml:
+
+[source,xml]
+----
+<?xml version="1.0" encoding="UTF-8"?>
+<openejb-jar>
+ <pojo-deployment class-name="jaxrs-application">
+ <properties>
+ # optional but requires to skip scanned providers if set to true
+ cxf.jaxrs.skip-provider-scanning = true
+ # list of providers we want
+ cxf.jaxrs.providers = johnzon,org.apache.openejb.server.cxf.rs.EJBAccessExceptionMapper
+ </properties>
+ </pojo-deployment>
+</openejb-jar>
+----
+
+2. Create a WEB-INF/resources.xml to define johnzon service which will be use to instantiate the provider
+
+[source,xml]
+----
+<?xml version="1.0" encoding="UTF-8"?>
+<resources>
+ <Service id="johnzon" class-name="org.apache.johnzon.jaxrs.ConfigurableJohnzonProvider">
+ # 1M
+ maxSize = 1048576
+ bufferSize = 1048576
+
+ # ordered attributes
+ attributeOrder = $order
+
+ # Additional types to ignore
+ ignores = org.apache.cxf.jaxrs.ext.multipart.MultipartBody
+ </Service>
+
+ <Service id="order" class-name="com.company.MyAttributeSorter" />
+
+</resources>
+----
+
+Note: as you can see you mainly just need to define a service with the id johnzon (same as in openejb-jar.xml)
+and you can reference other instances using $id for services and @id for resources.
+
http://git-wip-us.apache.org/repos/asf/tomee/blob/f779264f/docs/developer/migration/tomee-1-to-7.adoc
----------------------------------------------------------------------
diff --git a/docs/developer/migration/tomee-1-to-7.adoc b/docs/developer/migration/tomee-1-to-7.adoc
new file mode 100644
index 0000000..5bf7153
--- /dev/null
+++ b/docs/developer/migration/tomee-1-to-7.adoc
@@ -0,0 +1,33 @@
+= Migrate from TomEE 1 to TomEE 7
+:jbake-date: 2017-06-17
+:jbake-type: page
+:jbake-status: published
+:jbake-tomeepdf:
+
+== Breaking changes
+
+- Artifact coordinates changes
+
+GroupId changed from `org.apache.openejb` to `org.apache.tomee`.
+It includes maven plugins which use now `org.apache.tomee.maven` and the `javaee-api`.
+
+Versions of openejb and tomee are now aligned on 7.x and you don't need to use
+4.x and 1.x (or any variant) for openejb and tomee.
+
+- JAX-RS 2 specification refined the sorting of providers. It can have side effects for message body
+readers/writers which don't define their target mediatype properly like Jackson which uses wildcard instead of
+a json related mediatype. To solve it register a custom provider redefining the media type.
+
+Can be as easy as:
+
+[source,java]
+----
+@Provider
+@Consumes("application/json")
+@Produces("application/json")
+public class MyAppJsonProvider extends JacksonJsonProvider {
+}
+----
+
+- JPA and CDI are linked now, enabling JPA to use CDI for its components but CDI can use JPA too...
+to solve issues with hibernate you need to add either as system property or persistence unit `tomee.jpa.factory.lazy = true`.
http://git-wip-us.apache.org/repos/asf/tomee/blob/f779264f/docs/developer/testing/applicationcomposer/index.adoc
----------------------------------------------------------------------
diff --git a/docs/developer/testing/applicationcomposer/index.adoc b/docs/developer/testing/applicationcomposer/index.adoc
new file mode 100755
index 0000000..64b5e48
--- /dev/null
+++ b/docs/developer/testing/applicationcomposer/index.adoc
@@ -0,0 +1,335 @@
+= ApplicationComposer: The TomEE Swiss Knife
+:jbake-date: 2016-03-16
+:jbake-type: page
+:jbake-status: published
+:jbake-tomeepdf:
+
+ApplicationComposer API is mainly contained in org.apache.openejb.testing package (historically, today we would have called the package org.apache.tomee.applicationcomposer).
+
+=== Dependencies
+
+To start using ApplicationComposer you need to add some dependencies.
+
+The minimum required one is openejb-core:
+
+[source,xml]
+----
+<dependency>
+ <groupId>org.apache.tomee</groupId>
+ <artifactId>openejb-core</artifactId>
+ <version>${openejb.version></version>
+</dependency>
+----
+
+If you need JAXRS services you'll add (or replace thanks to transitivity of maven) openejb-cxf-rs:
+
+[source,xml]
+----
+<dependency>
+ <groupId>org.apache.tomee</groupId>
+ <artifactId>openejb-cxf-rs</artifactId>
+ <version>${openejb.version></version>
+</dependency>
+----
+
+If you need JAXWS services you'll add (or replace thanks to transitivity of maven) openejb-cxf:
+
+[source,xml]
+----
+<dependency>
+ <groupId>org.apache.tomee</groupId>
+ <artifactId>openejb-cxf</artifactId>
+ <version>${openejb.version></version>
+</dependency>
+----
+
+=== ApplicationComposer Components
+
+==== @Module
+An ApplicationComposer needs at minimum a module (the application you need to deploy).
+
+To do so you have two cases:
+
+before TomEE 7.x: you can only write method(s) decorated with @Module
+since TomEE 7.x: you can skip it and use @Classes directly on the ApplicationComposer class as a shortcut for:
+
+[source,java]
+----
+@Module public WebApp app() { return new WebApp(); }
+----
+
+The expected returned type of these methods are in org.apache.openejb.jee package:
+
+- Application: entry point to create an ear
+- WebApp: a web application
+- EjbJar: an ejb module
+- EnterpriseBean children: a simple EJB
+- Persistence: a persistence module with multiple units
+- PersistenceUnit: a simple unit (automatically wrapped in a Persistence)
+- Connector: a JCA connector module
+- Beans: a CDI module,
+- Class[] or Class: a set of classes scanned to discover annotations
+
+Note that for easiness @Classes was added to be able to describe a module and some scanned classes. For instance the following snippet will create a web application with classes C1, C2 as CDI beans and E1 as an EJB automatically:
+
+[source,java]
+----
+@Module
+@Classes(cdi = true, value = { C1.class, C2.class, E1.class })
+public WebApp app() {
+ return new WebApp();
+}
+----
+
+==== @Configuration
+Often you need to customize a bit the container or at least create some resources like test databases. To do so you can create a method returning Properties which will be the container properties.
+
+Note: to simplify writing properties you can use PropertiesBuilder util class which is just a fluent API to write properties.
+
+In these properties you can reuse OpenEJB/TomEE property syntax for resources.
+
+Here is a sample:
+
+[source,java]
+----
+@Configuration
+public Properties configuration() {
+ return new PropertiesBuilder()
+ .p("db", "new://Resource?type=DataSource")
+ .p("db.JdbcUrld", "jdbc:hsqldb:mem:test")
+ .build();
+}
+----
+
+Since TomEE 7.x you can also put properties on ApplicationComposer class using @ContainerProperties API:
+
+[source,java]
+----
+@ContainerProperties({
+ @ContainerProperties.Property(name = "db", value = "new://Resource?type=DataSource"),
+ @ContainerProperties.Property(name = "db.JdbcUrl", value = "jdbc:hsqldb:mem:test")
+})
+public class MyAppComposer() {
+ // ...
+}
+----
+
+==== @Component
+Sometimes you need to customize a container component. The most common use case is the security service to mock a little bit authorization if you don't care in your test.
+
+To do so just write a method decorated with @Component returning the instance you desire.
+
+Components in TomEE are stored in a container Map and the key needs to be a Class. This one is deduced from the returned type of the @Component method:
+
+[source,java]
+----
+@Component
+public SecurityService mockSecurity() {
+ return new MySecurityService();
+}
+----
+
+==== @Descriptors
+You can reuse existing file descriptors using @Descriptors. The name is the file name and the path either a classpath path or a file path:
+
+[source,java]
+----
+// runner if needed etc...
+@Descriptors(@Descriptor(name = "persistence.xml", path = "META-INF/persistence.xml"))
+public class MyTest {
+ //...
+}
+----
+
+Note: this can be put in a @Module method as well.
+
+==== Services
+If you want to test a JAXRS or JAXWS service you need to activate these services.
+
+To do so just add the needed dependency and use @EnableServices:
+
+[source,java]
+----
+// runner if needed etc...
+@EnableService("jaxrs") // jaxws supported as well
+public class MyTest {
+ //...
+}
+----
+
+==== Random port
+Services like JAXRS and JAXWS relies on HTTP. Often it is nice to have a random port to be able to deploy multiple tests/projects on the same CI platform at the same time.
+
+To shortcut all the needed logic you can use @RandomPort. It is simply an injection giving you either the port (int) or the root context (URL):
+
+[source,java]
+----
+// runner, services if needed etc...
+public class MyTest {
+ @RandomPort("http")
+ private int port;
+}
+----
+
+Note: you can generate this way multiple ports. The value is the name of the service it will apply on (being said http is an alias for httpejbd which is our embedded http layer).
+
+==== Nice logs
+@SimpleLog annotation allows you to have one liner logs
+
+==== @JaxrsProvider
+@JaxrsProvider allows you to specify on a @Module method the list of JAXRS provider you want to use.
+
+==== Dependencies without hacky code
+@Jars allows you to add dependencies (scanned) to your application automatically (like CDI libraries):
+
+[source,java]
+----
+@Module
+@Classes(cdi = true, value = { C1.class, C2.class, E1.class })
+@Jars("deltaspike-")
+public WebApp app() {
+ return new WebApp();
+}
+----
+
+==== @Default
+@Default (openejb one not CDI one) automatically adds in the application target/classes as binaries and src/main/webapp as resources for maven projects.
+
+==== @CdiExtensions
+This annotation allows you to control which extensions are activated during the test.
+
+==== @AppResource
+This annotation allows injection of few particular test resources like:
+
+the test AppModule (application meta)
+the test Context (JNDI)
+the test ApplicationComposers (underlying runner)
+ContextProvider: allow to mock JAXRS contexts
+
+==== @MockInjector
+Allows to mock EJB injections. It decorates a dedicated method returning an instance (or Class) implementing FallbackPropertyInjector.
+
+==== @WebResource
+Allow for web application to add folders containing web resources.
+
+
+=== How to run it?
+==== JUnit
+If you use JUnit you have mainly 2 solutions to run you "model" using the ApplicationComposer:
+
+using ApplicationComposer runner:
+
+[source,java]
+----
+@RunWith(ApplicationComposer.class) public class MyTest { // ... }
+----
+
+using ApplicationComposerRule rule:
+public class MyTest { @Rule // or @ClassRule if you want the container/application lifecycle be bound to the class and not test methods public final ApplicationComposerRule rule = new ApplicationComposerRule(this); }
+
+Tip: since TomEE 7.x ApplicationComposerRule is decomposed in 2 rules if you need: ContainerRule and DeployApplication. Using JUnit RuleChain you can chain them to get the samebehavior as ApplicationComposerRule or better deploy multiple ApplicationComposer models and controlling their deployment ordering (to mock a remote service for instance).
+
+Finally just write `@Test` method using test class injections as if the test class was a managed bean!
+
+==== TestNG
+TestNG integration is quite simple today and mainly ApplicationComposerListener class you can configure as a listener to get ApplicationComposer features.
+
+Finally just write TestNG @Test method using test class injections as if the test class was a managed bean!
+
+==== Standalone
+Since TomEE 7.x you can also use ApplicationComposers to directly run you ApplicationComposer model as a standalone application:
+
+[source,java]
+----
+public class MyApp {
+ public static void main(String[] args) {
+ ApplicationComposers.run(MyApp.class, args);
+ }
+
+ // @Module, @Configuration etc...
+}
+----
+
+Tip: if MyApp has `@PostConstruct` methods they will be respected and if MyApp has a constructor taking an array of String it will be instantiated getting the second parameter as argument (ie you can propagate your main parameter to your model to modify your application depending it!)
+
+=== JUnit Sample
+
+[source,java]
+----
+@Classes(cdi = true, value = { MyService.class, MyOtherService.class })
+@ContainerProperties(@ContainerProperties.Property(name = "myDb", value = "new://Resource?type=DataSource"))
+@RunWith(ApplicationComposer.class)
+public class MyTest {
+ @Resource(name = "myDb")
+ private DataSource ds;
+
+ @Inject
+ private MyService service;
+
+ @Test
+ public void myTest() {
+ // do test using injections
+ }
+}
+----
+
+=== Start and Deploy once
+
+When having a huge suite of test it can be long to start/deploy/undeploy/shutdown he container/application for each method.
+
+That's why `SingleApplicationComposerRunner` allows to just reuse the same instance accross several test.
+
+The first test will start and deploy the application and then other tests will reuse this instance until the JVM is destroyed
+where the server/application will be undeployed/shutdown.
+
+
+Here a simple usage:
+
+[source,java]
+----
+import org.apache.openejb.testing.SingleApplicationComposerRunner;
+// other imports
+
+@RunWith(SingleApplicationComposerRunner.class)
+public class MyTest {
+ @Inject
+ private ACdiBean bean;
+
+ @Application
+ private TheModel model;
+
+ @Test
+ public void aTest() {
+ // ...
+ }
+}
+----
+
+TIP: if you need a real TomEE container then you can have a look to `TomEEEmbeddedSingleRunner` which does deploys the classpath
+using tomee-embedded.
+
+==== Configure what to deploy
+
+As all tests will reuse the same application the model (the class declaring the application with `@Classes`, `@Module` etc...) needs to be extracted from the test class itself.
+
+The application lookup uses this strategy (ordered):
+
+- the fully qualified name is read from the system property `tomee.application-composer.application`
+- a *single* class decorated with `@Application` is looked in the jar/folder containing the test class
+
+If you have several "groups" you can use JUnit `@Category` to differentiate them and write one application class by category. Then
+in `surefire` plugin you declare two `executions` enforcing the system property `tomee.application-composer.application` for each of them
+and the associated `@Category`.
+
+==== Available injections
+
+- If the application model class uses `@RandomPort` then the test classes can get it as well
+- CDI injections are supported
+- `@Application` on a field allows to get the application model to get injected
+
+Compared to a standalone usage it misses all other EE injections (`@PersistenceContext`, `@Resource` etc... but you can inject them in the application model
+and just expose them or wrap them in your tests thanks to the `@Application` field.
+
+
+=== Going further
+If you want to learn more about ApplicationComposer see link:../../../advanced/applicationcomposer/index.html[ApplicationComposer Advanced] page.