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:32 UTC
[17/20] tomee git commit: Docs old and new
http://git-wip-us.apache.org/repos/asf/tomee/blob/f779264f/docs/application-resources.mdtext
----------------------------------------------------------------------
diff --git a/docs/application-resources.mdtext b/docs/application-resources.mdtext
new file mode 100644
index 0000000..2c66a34
--- /dev/null
+++ b/docs/application-resources.mdtext
@@ -0,0 +1,247 @@
+Title: Application Resources
+<a name="ApplicationResources"></a>
+
+# Resources
+
+TomEE provides a simple but powerful way to define resources that can be injected into managed components inside your application, or looked up via JNDI. To use a resource, it needs to be defined in the `tomee.xml` configuration file, a `resources.xml` file within an application, or as a system property. Defining a resource in `tomee.xml` will make it available server-wide, whereas defining the resource within a `resources.xml` file makes it available to a specific application.
+
+As a simple example, a JMS queue can be defined within `tomee.xml` with the following configuration.
+
+ <tomee>
+ <Resource id="MyQueue" type="javax.jms.Queue"/>
+ </tomee>
+
+Once the resource has been defined, the server will create an instance of the resource during startup, and it will be available to be injected into managed components using the `@Resource` annotation, as shown below. The `name` attribute on the `@Resource` annotation should match the `id` attribute on the `Resource` tag.
+
+ public class JmsClient {
+
+ @Resource(name="MyQueue")
+ private Queue queue;
+
+ public void sendMessage() {
+ // implementation here...
+ }
+
+ }
+
+As an alternative to defining a resource in XML, resources can also be defined using system properties:
+
+ MyQueue = new://Resource?type=javax.jms.Queue
+
+Resources, or attributes for resources specified using system properties will override definitions specified in `tomee.xml`.
+Server-wide resources can be looked up in JNDI under the following name: openejb:Resources/resource id.
+
+# Defining Resources
+<a name="DefiningResources"></a>
+
+The `<Resource>` tag has a number of attributes, and a resource may also have a number of fields that can be configured by adding properties to the body of the `Resource` tag.
+
+For example, a DataSource resource needs a JDBC driver, URL, username and password to be able to connect to a database. That would be configured with the following syntax. Notice the key/value pair syntax for the properties within the `<Resource>` tag.
+
+ <Resource id="DB" type="DataSource">
+ JdbcDriver com.mysql.jdbc.Driver
+ JdbcUrl jdbc:mysql://localhost/test
+ UserName test
+ Password password
+ </Resource>
+
+Specifying the key/value pairs specific to a Resource can also be done when defining the resource via system properties. This is done be specifying an additional property for each key/value pair, using the resource ID as a prefix: `<resourceId>.<propertyName>=<value>`. The system properties equivalent of the resource above is:
+
+ p.setProperty("DB", "new://Resource?type=DataSource");
+ p.setProperty("DB.JdbcDriver", "com.mysql.jdbc.Driver");
+ p.setProperty("DB,JdbcUrl", "jdbc:mysql://localhost/test");
+ p.setProperty("DB.UserName", "test");
+ p.setProperty("DB.Password", "password");
+
+The `<Resource>` tag has a number of attributes which control the way that the resource get created.
+
+* type
+
+A type that TomEE knows. The type is associated with a provider that knows how to create that type, and also any default properties that the resource should have if they are not specified in the resource definition. See <a href="https://github.com/apache/tomee/blob/tomee-1.7.x/tomee/tomee-webapp/src/main/resources/META-INF/org.apache.tomee/service-jar.xml">service-jar.xml</a> for an example set of service providers that come with TomEE.
+
+* provider
+
+Explicitly specifies a provider to create the resource, using defaults for any properties not specified.
+
+* class-name
+
+The fully qualified class that creates the resource. This might the resource class itself, which is created by calling the constructor, or a factory class that provides a specific factory method to create the resource.
+
+* factory-name
+
+The name of the method to call to create the resource. If this is not specified, the constructor for the class specified by class-name will be used.
+
+* constructor
+
+Specifies a comma separated list of constructor arguments. These can be other services, or attributes on the resource itself.
+
+# Custom resources
+
+TomEE allows you to define resources using your own Java classes, and these can also be injected into managed components in the same way as known resource types are.
+
+So the following simple resource
+
+ public class Configuration {
+
+ private String url;
+ private String username;
+ private int poolSize;
+
+ // getters and setters
+ }
+
+Can be defined in `tomee.xml` using the following configuration (note the `class-name` attribute):
+
+ <Resource id="config" class-name="org.superbiz.Configuration">
+ url http://localhost
+ username tomee
+ poolSize 20
+ </Resource>
+
+This resource must be available in TomEE's system classpath - i.e. it must be defined in a .jar within the `lib/` directory.
+
+# Field and properties
+
+As shown above, a resource class can define a number of fields, and TomEE will attempt to apply the values from the resource definition onto those fields.
+
+As an alternative to this, you can also add a properties field as shown below, and this will have any used properties from the resource configuration set added to it. So as an alternative to the above code, you could do:
+
+ public class Configuration {
+
+ private Properties properties;
+
+ public Properties getProperties() {
+ return properties;
+ }
+
+ public void setProperties(final Properties properties) {
+ this.properties = properties;
+ }
+
+ }
+
+Using the same resource definition:
+
+ <Resource id="config" class-name="org.superbiz.Configuration">
+ url http://localhost
+ username tomee
+ poolSize 20
+ </Resource>
+
+the url, username and poolSize values will now be available in the properties field, so for example, the username property could be accessed via properties.getProperty("username");
+
+# Application resources
+
+Resources can also be defined within an application, and optionally use classes from the application's classpath. To define resources in a .war file, include a `WEB-INF/resources.xml`. For an ejb-jar module, use `META-INF/resources.xml`.
+
+The format of `resources.xml` uses the same `<Resource>` tag as `tomee.xml`. One key difference is the root element of the XML is `<resources>` and not `<tomee>`.
+
+ <resources>
+ <Resource id="config" class-name="org.superbiz.Configuration">
+ url http://localhost
+ username tomee
+ poolSize 20
+ </Resource>
+ </resources>
+
+This mechanism allows you to package your custom resources within your application, alongside your application code, rather than requiring a .jar file in the `lib/` directory.
+
+Application resources are bound in JNDI under openejb:Resource/appname/resource id.
+
+# Additional resource properties
+
+Resources are typically discovered, created, and bound to JNDI very early on in the deployment process, as other components depend on them. This may lead to problems where the final classpath for the application has not yet been determined, and therefore TomEE is unable to load your custom resource.
+
+The following properties can be used to change this behavior.
+
+* Lazy
+
+This is a boolean value, which when true, creates a proxy that defers the actual instantiation of the resource until the first time it is looked up from JNDI. This can be useful if the resource's classpath until the application is started (see below), or to improve startup time by not fully initializing resources that might not be used.
+
+* UseAppClassLoader
+
+This boolean value forces a lazily instantiated resource to use the application classloader, instead of the classloader available when the resources were first processed.
+
+* InitializeAfterDeployment
+
+This boolean setting forces a resource created with the Lazy property to be instantiated once the application has started, as opposed to waiting for it to be looked up. Use this flag if you require the resource to be loaded, irrespective of whether it is injected into a managed component or manually looked up.
+
+By default, all of these settings are `false`, unless TomEE encounters a custom application resource that cannot be instantiated until the application has started. In this case, it will set these three flags to `true`, unless the `Lazy` flag has been explicitly set.
+
+# Initializing resources
+
+## constructor
+
+By default, if no factory-name attribute and no constructor attribute is specified on the `Resource`, TomEE will instantiate the resource using its no-arg constructor. If you wish to pass constructor arguments, specify the arguments as a comma separated list:
+
+ <Resource id="config" class-name="org.superbiz.Configuration" constructor="id, poolSize">
+ url http://localhost
+ username tomee
+ poolSize 20
+ </Resource>
+
+## factory-name method
+
+In some circumstances, it may be desirable to add some additional logic to the creation process, or to use a factory pattern to create resources. TomEE also provides this facility via the `factory-name` method. The `factory-name` attribute on the resource can reference any no argument method that returns an object on the class specified in the `class-name` attribute.
+
+For example:
+
+ public class Factory {
+
+ private Properties properties;
+
+ public Object create() {
+
+ MyResource resource = new MyResource();
+ // some custom logic here, maybe using this.properties
+
+ return resource;
+ }
+
+ public Properties getProperties() {
+ return properties;
+ }
+
+ public void setProperties(final Properties properties) {
+ this.properties = properties;
+ }
+
+ }
+
+ <resources>
+ <Resource id="MyResource" class-name="org.superbiz.Factory" factory-name="create">
+ UserName tomee
+ </Resource>
+ </resources>
+
+## @PostConstruct / @PreDestroy
+
+As an alternative to using a factory method or a constructor, you can use @PostConstruct and @PreDestroy methods within your resource class (note that you cannot use this within a different factory class) to manage any additional creation or cleanup activities. TomEE will automatically call these methods when the application is started and destroyed. Using @PostConstruct will effectively force a lazily loaded resource to be instantiated when the application is starting - in the same way that the `InitializeAfterDeployment` property does.
+
+ public class MyClass {
+
+ private Properties properties;
+
+ public Properties getProperties() {
+ return properties;
+ }
+
+ public void setProperties(final Properties properties) {
+ this.properties = properties;
+ }
+
+ @PostConstruct
+ public void postConstruct() throws MBeanRegistrationException {
+ // some custom initialization
+ }
+ }
+
+ }
+
+# Examples
+
+The following examples demonstrate including custom resources within your application:
+
+* resources-jmx-example
+* resources-declared-in-webapp
+
http://git-wip-us.apache.org/repos/asf/tomee/blob/f779264f/docs/arquillian-available-adapters.mdtext
----------------------------------------------------------------------
diff --git a/docs/arquillian-available-adapters.mdtext b/docs/arquillian-available-adapters.mdtext
new file mode 100644
index 0000000..c50e3b1
--- /dev/null
+++ b/docs/arquillian-available-adapters.mdtext
@@ -0,0 +1,262 @@
+Title: TomEE and Arquillian
+
+Check out the [Getting started](arquillian-getting-started.html) page if you are not at all familiar with Arquillian.
+
+All the Arquillian Adapters for TomEE support the following configuration options in the **src/test/resources/arquillian.xml**:
+
+ <container qualifier="tomee" default="true">
+ <configuration>
+ <property name="httpPort">-1</property>
+ <property name="stopPort">-1</property>
+ <!--Optional Container Properties-->
+ <property name="properties">
+ aproperty=something
+ </property>
+ <!--Optional Remote Adapter Deployer Properties
+ <property name="deployerProperties">
+ aproperty=something
+ </property>
+ -->
+ </configuration>
+ </container>
+
+The above can also be set as system properties rather than via the **src/test/resources/arquillian.xml** file.
+
+ <build>
+ <plugins>
+ <plugin>
+ <groupId>org.apache.maven.plugins</groupId>
+ <artifactId>maven-surefire-plugin</artifactId>
+ <configuration>
+ <systemPropertyVariables>
+ <tomee.httpPort>-1</tomee.httpPort>
+ <tomee.stopPort>-1</tomee.stopPort>
+ </systemPropertyVariables>
+ </configuration>
+ </plugin>
+ </plugins>
+ </build>
+
+When a port is set to -1, a random port will be chosen. This is key to avoiding port conflicts on CI systems or for just plain clean testing.
+
+The TomEE Arquillian adapters will export the actual port chosen back as a system property using the same name. The test case can use the property to retrieve the port and contact the server.
+
+ URL url = new URL("http://localhost:" + System.getProperty("tomee.httpPort");
+ // use the URL to connect to the server
+
+If that property returns null
+
+When you are actually using a test on the client side, you can use instead
+
+ import org.jboss.arquillian.test.api.ArquillianResource;
+ ...
+ @ArquillianResource private URL url;
+
+The URL will get injected by Arquillian. Be careful, that injection only works if your are on the client side (it does not make sense in the server side). So, if for a specific need to need it, just use the system property.
+
+# TomEE Embedded Adapter
+
+The TomEE Embedded Adapter will boot TomEE right inside the test case itself resulting in one JVM running both the application and the test case. This is generally much faster than the TomEE Remote Adapter and great for development. That said, it is strongly recommended to also run all tests in a Continuous Integration system using the TomEE Remote Adapter.
+
+To use the TomEE Embedded Arquillian Adapter, simply add these Maven dependencies to your Maven pom.xml:
+
+ <dependency>
+ <groupId>org.apache.openejb</groupId>
+ <artifactId>arquillian-tomee-embedded</artifactId>
+ <version>1.7.1</version> <!--Current version-->
+ </dependency>
+ <dependency>
+ <groupId>org.apache.openejb</groupId>
+ <artifactId>tomee-embedded</artifactId>
+ <version>1.7.1</version>
+ </dependency>
+ <!--Required for WebServices and RESTful WebServices-->
+ <dependency>
+ <groupId>org.apache.openejb</groupId>
+ <artifactId>tomee-webservices</artifactId>
+ <version>1.7.1</version>
+ </dependency>
+ <dependency>
+ <groupId>org.apache.openejb</groupId>
+ <artifactId>tomee-jaxrs</artifactId>
+ <version>1.7.1</version>
+ </dependency>
+
+As mentioned above the Embedded Adapter has the following properties which can be specified in the **src/test/resources/arquillian.xml** file:
+
+ - `httpPort`
+ - `stopPort`
+ - `properties` (System properties for container)
+
+Or alternatively as System properties, possibly shared with other TomEE Arquillian Adapters:
+
+ - `tomee.httpPort`
+ - `tomee.stopPort`
+
+Or more specifically as a System properties only applicable to the Embedded Adapter:
+
+ - `tomee.embedded.httpPort`
+ - `tomee.embedded.stopPort`
+
+
+# TomEE Remote Adapter
+
+The TomEE Remote Adapter will unzip and setup a TomEE or TomEE Plus distribution. Once setup, the server will execute in a separate process. This will be slower, but with the added benefit it is 100% match with the production system environment.
+
+On a local machine clients can get the remote server port using the following System property:
+
+ final String port = System.getProperty("server.http.port");
+
+The following shows a typical configuration for testing against TomEE (webprofile version). The same can be done against TomEE+ by changing `<tomee.classifier>webprofile</tomee.classifier>` to `<tomee.classifier>plus</tomee.classifier>`
+
+ <properties>
+ <tomee.version>1.7.1</tomee.version>
+ <tomee.classifier>webprofile</tomee.classifier>
+ </properties>
+ <build>
+ <plugins>
+ <plugin>
+ <groupId>org.apache.maven.plugins</groupId>
+ <artifactId>maven-surefire-plugin</artifactId>
+ <configuration>
+ <systemPropertyVariables>
+ <tomee.classifier>${tomee.classifier}</tomee.classifier>
+ <tomee.version>${tomee.version}</tomee.version>
+ </systemPropertyVariables>
+ </configuration>
+ </plugin>
+ </plugins>
+ </build>
+ <dependencies>
+ <dependency>
+ <groupId>org.apache.openejb</groupId>
+ <artifactId>arquillian-tomee-remote</artifactId>
+ <version>${tomee.version}</version>
+ </dependency>
+ <dependency>
+ <groupId>org.apache.openejb</groupId>
+ <artifactId>apache-tomee</artifactId>
+ <version>${tomee.version}</version>
+ <classifier>${tomee.classifier}</classifier>
+ <type>zip</type>
+ </dependency>
+ </dependencies>
+
+The Remote Adapter has the following properties which can be specified in the **src/test/resources/arquillian.xml** file:
+
+ - `httpPort`
+ - `stopPort`
+ - `version`
+ - `classifier` (Must be either `webprofile` or `plus`)
+ - `properties` (System properties for container)
+ - `deployerProperties` (Sent to Deployer)
+
+Or alternatively as System properties, possibly shared with other TomEE Arquillian Adapters:
+
+ - `tomee.httpPort`
+ - `tomee.stopPort`
+ - `tomee.version`
+ - `tomee.classifier`
+
+Or more specifically as a System properties only applicable to the Remote Adapter:
+
+ - `tomee.remote.httpPort`
+ - `tomee.remote.stopPort`
+ - `tomee.remote.version`
+ - `tomee.remote.classifier`
+
+# Maven Profiles
+
+Setting up both adapters is quite easy via Maven profiles. Here the default adapter is the Embedded Adapter, the Remote Adapter will run with `-Ptomee-webprofile-remote` specified as a `mvn` command argument.
+
+ <profiles>
+
+ <profile>
+ <id>tomee-embedded</id>
+ <activation>
+ <activeByDefault>true</activeByDefault>
+ </activation>
+ <dependencies>
+ <dependency>
+ <groupId>org.apache.openejb</groupId>
+ <artifactId>arquillian-tomee-embedded</artifactId>
+ <version>1.0.0</version>
+ </dependency>
+ </dependencies>
+ </profile>
+
+ <profile>
+ <id>tomee-webprofile-remote</id>
+ <properties>
+ <tomee.version>1.0.0</tomee.version>
+ <tomee.classifier>webprofile</tomee.classifier>
+ </properties>
+ <build>
+ <plugins>
+ <plugin>
+ <groupId>org.apache.maven.plugins</groupId>
+ <artifactId>maven-surefire-plugin</artifactId>
+ <configuration>
+ <systemPropertyVariables>
+ <tomee.classifier>${tomee.classifier}</tomee.classifier>
+ <tomee.version>${tomee.version}</tomee.version>
+ </systemPropertyVariables>
+ </configuration>
+ </plugin>
+ </plugins>
+ </build>
+ <dependencies>
+ <dependency>
+ <groupId>org.apache.openejb</groupId>
+ <artifactId>arquillian-tomee-remote</artifactId>
+ <version>${tomee.version}</version>
+ </dependency>
+ <dependency>
+ <groupId>org.apache.openejb</groupId>
+ <artifactId>apache-tomee</artifactId>
+ <version>${tomee.version}</version>
+ <classifier>${tomee.classifier}</classifier>
+ <type>zip</type>
+ </dependency>
+ </dependencies>
+ </profile>
+
+ <profile>
+ <id>tomee-plus-remote</id>
+ <properties>
+ <tomee.version>1.0.0</tomee.version>
+ <tomee.classifier>plus</tomee.classifier>
+ </properties>
+ <build>
+ <plugins>
+ <plugin>
+ <groupId>org.apache.maven.plugins</groupId>
+ <artifactId>maven-surefire-plugin</artifactId>
+ <configuration>
+ <systemPropertyVariables>
+ <tomee.classifier>${tomee.classifier}</tomee.classifier>
+ <tomee.version>${tomee.version}</tomee.version>
+ </systemPropertyVariables>
+ </configuration>
+ </plugin>
+ </plugins>
+ </build>
+ <dependencies>
+ <dependency>
+ <groupId>org.apache.openejb</groupId>
+ <artifactId>arquillian-tomee-remote</artifactId>
+ <version>${tomee.version}</version>
+ </dependency>
+ <dependency>
+ <groupId>org.apache.openejb</groupId>
+ <artifactId>apache-tomee</artifactId>
+ <version>${tomee.version}</version>
+ <classifier>${tomee.classifier}</classifier>
+ <type>zip</type>
+ </dependency>
+ </dependencies>
+ </profile>
+
+ </profiles>
+
+
http://git-wip-us.apache.org/repos/asf/tomee/blob/f779264f/docs/arquillian-getting-started.mdtext
----------------------------------------------------------------------
diff --git a/docs/arquillian-getting-started.mdtext b/docs/arquillian-getting-started.mdtext
new file mode 100644
index 0000000..744c82f
--- /dev/null
+++ b/docs/arquillian-getting-started.mdtext
@@ -0,0 +1,20 @@
+Title: Getting started with Arquillian and TomEE
+
+Arquillian is a testing framework on top of JUnit (or TestNG if you prefer). It makes it easier to do integration tests in a managed environment (JEE environment here after).
+
+We provide an embedded and remote adapter, see [the available adapters](arquillian-available-adapters.html) for more details.
+
+In a managed environment it is usually quite difficult to perform unit tests, due to the fact that most of the time you have to mock almost the entire environment. It is very time consuming and requires complicated integration tests that must reflect the production environment as best as possible. Unit tests lose their true value.
+
+JEE always got seen as an heavy technology, impossible to test and to use in development. OpenEJB always fight against that idea and proved that it's really possible.
+
+As David Blevins said:
+> "Do not blame EJBs (ie. Java EE) because your server is not testable."
+
+With latest Java EE specifications (5 and especially 6), it becomes a reality. Arquillian typically addresses that area. It is basically a framework that aims at helping/managing the server/container in an agnostic way. Arquillian is responsible for the lifecycle of the container (start, deploy, undeploy, stop, etc).
+
+TomEE community heavily invested on that framework to prove it's really useful and can really help testing Java EE application. That's also an opportunity to get the most out of TomEE (lightweight, fast, feature-rich, etc).
+
+{info
+See [Arquillian.org](http://arquillian.org) for a great quick-start tutorial on Arquillian itself.
+}
http://git-wip-us.apache.org/repos/asf/tomee/blob/f779264f/docs/basics---getting-things.mdtext
----------------------------------------------------------------------
diff --git a/docs/basics---getting-things.mdtext b/docs/basics---getting-things.mdtext
new file mode 100644
index 0000000..d252be1
--- /dev/null
+++ b/docs/basics---getting-things.mdtext
@@ -0,0 +1,103 @@
+Title: Basics - Getting Things
+<a name="Basics-GettingThings-GettingStufffromtheContainer"></a>
+# Getting Stuff from the Container
+
+Generally speaking the only way to get a [Container-Managed Resource](container-managed-resource.html)
+ is via *dependency injection* or *lookup* from within a [Container-Managed Component]
+.
+
+The *unbreakable rules*. Read these over and over again when things don't
+work.
+
+1. java:comp/env is the spec defined namespace for lookup of any [Container-Managed Resource](container-managed-resource.html)
+1. java:comp/env is *empty* by default
+1. java:comp/env is *read-only* at runtime
+1. java:comp/env is populated by [Declaring References](declaring-references.html)
+ to [Container-Managed Resource]
+ via xml or annotation
+1. only [Container-Managed Component](container-managed-component.html)
+s, *not* their libraries, can [Declare References|Declaring References]
+ via xml or annotation
+1. only [Container-Managed Component](container-managed-component.html)
+s, *not* their libraries, can get dependency injection of [Container-Managed Resource]
+s
+1. only [Container-Managed Component](container-managed-component.html)
+s, *and* their libraries, may lookup from java:comp/env
+1. you *must* use the *no-arg* 'new InitialContext()' constructor to
+lookup something from java:comp/env
+1. the annotations and xml for [Declaring References](declaring-references.html)
+ are *identical* in functionality, both *always* configure lookup with
+*optional* dependency injection
+
+<a name="Basics-GettingThings-Commonmistakes,misunderstandings,andmyths"></a>
+## Common mistakes, misunderstandings, and myths
+
+- *_"I tried it via annotation and it didn't work, so I used xml and then
+it did work"_*
+
+See rule 9. If one form worked and the other didn't, it means you simply
+made a mistake in using one versus the other. Use what works for you, but
+understand both annotations or xml will work for either lookup or injection
+if used correctly.
+
+- *_"I need to use lookups, so I can't use the annotation"_*
+
+See rule 9. Annotations are not just for injection, that is just how they
+are typically used. Know that when you use an annotation for injection, it
+will *always* create an entry in java:comp/env. As well you can use the
+annotation at the *class level* and it will cause no dependency injection
+and only the entry creation in java:comp/env.
+
+- *_"I don't want injection, so I can't use the annotation"_*
+
+See rule 9 and the above. You can use the annotation at the *class level*
+and it will cause no dependency injection and only the entry creation in
+java:comp/env.
+
+- *_"I tried to list java:comp/env but it's empty?!"_*
+
+See rule 2 and rule 4. There will be nothing in java:comp/env unless you [Declare a Reference](declaring-references.html)
+ to it. It does not matter if is a DataSource configured at the server
+level, etc. Nothing is bound into java:comp/env unless you explicitly
+declare a reference to it. The Java EE 5 TCK (Technology Compatibility
+Kit) tests for this extensively and is a rule we cannot break. Java EE 6
+does finally offer some new namesaces (java:global, java:app, and
+java:module) which will offer some great new options for more global-style
+lookups.
+
+- *_"I deployed the EJB but can't look it up, it's name is Foo"_*
+
+See rule 2 and the above. Just creating an EJB doesn't cause it to be
+added to java:comp/env. If a [Container-Managed Component](container-managed-component.html)
+ wants to lookup the EJB they must [Declare a Reference|Declaring References]
+ to it via the @EJB annotionation or <ejb-local-ref> or <ejb-ref> in xml.
+In Java EE 6, however, EJBs will be automatically bound to
+"java:global[/<app-name>]/<module-name>/<bean-name>[!<fully-qualified-interface-name>]"
+and can be looked up without declaring a reference first.
+
+- *_"Which InitialContextFactory do I use for java:comp/env?"_*
+
+See rule 8. You are not allowed to use an InitialContextFactory for
+java:comp/env lookups. Setting an InitialContextFactory via
+'java.naming.factory.initial' in either System properties, InitialContext
+properties, or a jndi.properties file is illegal and will cause
+java:comp/env lookups to fail.
+
+- *_"My Client can't lookup the EJB from java:comp/env"_*
+
+See rule 7. A plain, standalone, Java application cannot use
+java:comp/env. There is the official concept of a Java EE Application
+Client which can be packaged in an ear and deployed into the Container. In
+practice, most people find them restrictive, cumbersome, and hard to use
+and are therefore rarely employed in "real world" projects. Most people
+opt to use the non-standard, vendor-specific, approach to looking up EJBs
+from their plain java clients. In OpenEJB this can be done via either the
+RemoteInitialContextFactory (for remote clients) or the
+LocalInitialContextFactory (for local clients of an embedded container).
+The JNDI names can be configured as [shown here](jndi-names.html)
+.
+
+- *_"I declared the reference, but still can't look it up"_*
+
+See all of the above and reread the rules a few times. Always check the
+log output as well.
http://git-wip-us.apache.org/repos/asf/tomee/blob/f779264f/docs/basics---security.mdtext
----------------------------------------------------------------------
diff --git a/docs/basics---security.mdtext b/docs/basics---security.mdtext
new file mode 100644
index 0000000..13c932d
--- /dev/null
+++ b/docs/basics---security.mdtext
@@ -0,0 +1,52 @@
+Title: Basics - Security
+This section is under construction, please check back later.
+
+<a name="Basics-Security-RelatedDocuments"></a>
+## Related Documents
+
+[Security](security.html)
+ \- login module configuration
+[Security Annotations](security-annotations.html)
+ \- EJB3 related annotation based security.
+
+<a name="Basics-Security-ServerSideSecurity"></a>
+## Server Side Security
+
+There's a few things that should be noted about security from the server
+side perspective.
+
+<a name="Basics-Security-SecurityPropagation"></a>
+### Security Propagation
+Note, this is partially documented in the EJB 3 spec section 14.8.1.1.
+
+1. Once a remote bean has been instantiated, from within the container, it
+inherits the entire security context, and all roles will be inherited the
+same as the method where the bean is being looked up.
+1. Looking up a bean via an `InitialContext`, or via injection, will inherit
+the security context (user, roles, etc), thereby propagating the security
+through to any container bean in the chain of method calls.
+1. No properties are allowed for the `InitialContext`, and you *MUST* be
+calling the no args constructor only. There are documents elsewhere that
+describe using the OpenEJB initial context factories and such, with
+usernames and passwords, etc; it should be noted that this method of using
+the factories is OpenEJB specific, to facilitate non-standard clients not
+running in an EJB container, etc.
+
+For example, here is an EJB that returns another bean, through a remote
+method call. In this case, the *OtherBean* instance, will have the same
+security as *MyBean*, including the principal (username), roles, etc.
+
+
+ import javax.ejb.EJB;
+ import javax.naming.InitialContext;
+
+ @EJB(name = "otherBean", beanInterface = IOtherBean.class)
+ public class MyBean
+ {
+ public IOtherBean getOtherBean()
+ {
+ InitialContext context = new InitialContext();
+ return (IOtherBean) context.lookup("java:comp/env/otherBean");
+ }
+ }
+
http://git-wip-us.apache.org/repos/asf/tomee/blob/f779264f/docs/basics---transactions.mdtext
----------------------------------------------------------------------
diff --git a/docs/basics---transactions.mdtext b/docs/basics---transactions.mdtext
new file mode 100644
index 0000000..7e1e1eb
--- /dev/null
+++ b/docs/basics---transactions.mdtext
@@ -0,0 +1,56 @@
+Title: Basics - Transactions
+One of the many benefits of EJB, is that transactions within the EJB
+container are generally managed entirely automatically. Any EJB component
+will, by default, partake in that transaction.
+
+Here are some basic rules to understand about transactions. Keep note that
+this is the default behaviour, and the system can be configured to behave
+differently, depending on the needs of your system, bean, or individual
+methods of your beans.
+
+<a name="Basics-Transactions-Participants"></a>
+## Participants
+
+Various components and parts of the EJB system can be part of a
+transaction. Examples are
+
+1. Session bean
+1. Message Driven Bean
+1. EntityManager (a.k.a. Persistence context)
+
+<a name="Basics-Transactions-Behaviour"></a>
+## Behaviour
+
+The basic default behaviours are
+1. A transaction starts at the beginning of the first EJB method call, in a
+chain of calls that are participating in the given transaction
+1. A transaction ends at the end of the first EJB method, in the same chain
+1. If a bean that has started a transaction, uses another bean, that bean
+will automatically use the same transaction as the calling bean.
+
+<a name="Basics-Transactions-Configuration"></a>
+## Configuration
+
+You can configure your beans in a variety of ways. Generally speaking, a
+transaction is started when a method is called, but can be configured using
+@TransactionAttribute(value = TransactionAttributeType.X), where X is one
+of...
+
+1. REQUIRED - the default, which is to start a transaction if one does not exist, but to use the existing one if it has already been started.
+1. REQUIRES_NEW - the transaction is created on every call, and ends when the call is completed. Beans don't partake in transactions created by other parts of the system.
+1. MANDATORY - a transaction must always exist prior to the call, and it will be used. It is an error otherwise
+1. NOT_SUPPORTED - component not included in the transaction
+1. SUPPORTS - transaction will be used if it exists, but will not be created if it does not exist
+1. NEVER - if a transaction exists, it is an error to call the method
+
+@TransactionAttribute applies to both methods and entire beans. You may
+set one type of transaction behaviour (as seen above) on the bean, and a
+different one on a specific method of that same bean, which overrides the
+one configured for the overall bean. For instance, maybe you want to make
+an audit entry in the database that you are about to attempt a credit card
+payment. It really needs to be in it's own transaction so that it is
+IMMEDIATELY committed for audit purposes, if something goes wrong with the
+credit card payment. So, perhaps you use MANDATORY on the bean, and
+REQUIRES_NEW on the method for audit logging. As soon as the method that
+does the audit logging is complete, the transaction is committed, and the
+credit card payment transaction continues on it's way.
http://git-wip-us.apache.org/repos/asf/tomee/blob/f779264f/docs/bmpentitycontainer-config.mdtext
----------------------------------------------------------------------
diff --git a/docs/bmpentitycontainer-config.mdtext b/docs/bmpentitycontainer-config.mdtext
new file mode 100644
index 0000000..64d6729
--- /dev/null
+++ b/docs/bmpentitycontainer-config.mdtext
@@ -0,0 +1,35 @@
+Title: BmpEntityContainer Configuration
+
+
+A BmpEntityContainer 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.
+
+ <Container id="myBmpEntityContainer" type="BMP_ENTITY">
+ poolSize = 10
+ </Container>
+
+Alternatively, a BmpEntityContainer 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`
+
+ myBmpEntityContainer = new://Container?type=BMP_ENTITY
+ myBmpEntityContainer.poolSize = 10
+
+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 BmpEntityContainer a warning will be logged. If a BmpEntityContainer is needed by the application and one is not declared, TomEE will create one dynamically using default settings. Multiple BmpEntityContainer declarations are allowed.
+# Supported Properties
+<table>
+<tr>
+<th>Property</th>
+<th>Type</th>
+<th>Default</th>
+<th>Description</th>
+</tr>
+<tr>
+ <td>poolSize</td>
+ <td>int</td>
+ <td>10</td>
+ <td>
+Specifies the size of the bean pools for this
+bmp entity container.
+</td>
+</tr>
+</table>
+
+
http://git-wip-us.apache.org/repos/asf/tomee/blob/f779264f/docs/bouncy-castle.mdtext
----------------------------------------------------------------------
diff --git a/docs/bouncy-castle.mdtext b/docs/bouncy-castle.mdtext
new file mode 100644
index 0000000..12ceb33
--- /dev/null
+++ b/docs/bouncy-castle.mdtext
@@ -0,0 +1,31 @@
+Title: Installing Bouncy Castle
+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.
+
+Installation of Bouncy Castle for use in TomEE itself is done in two steps:
+
+ 1. Add the Bouncy Castle provider jar to the `$JAVA_HOME/jre/lib/ext` directory
+ 1. Create a Bouncy Castle provider entry in the `$JAVA_HOME/jre/lib/security/java.security` file
+
+The entry to `java.security` will look something like the following:
+
+ security.provider.N=org.bouncycastle.jce.provider.BouncyCastleProvider
+
+Replace `N` with the order of precedence you would like to give Bouncy Castle in comparison to the
+other providers in the file. **Recommended** would be the last entry in the list -- `N` being the higest number in the list.
+**Warning** that configuring Bouncy Castle as the first provider, `security.provider.1`, may cause JVM errors.
+
http://git-wip-us.apache.org/repos/asf/tomee/blob/f779264f/docs/built-in-type-converters.mdtext
----------------------------------------------------------------------
diff --git a/docs/built-in-type-converters.mdtext b/docs/built-in-type-converters.mdtext
new file mode 100644
index 0000000..74958f1
--- /dev/null
+++ b/docs/built-in-type-converters.mdtext
@@ -0,0 +1,91 @@
+Title: Built-in Type Converters
+The following built-in types are supported for @Resource injection in EJBs
+via <env-entry> elements in a META-INF/ejb-jar.xml or via plain properties
+in a META-INF/env-entries.properties file.
+
+EJB 3.0 required types:
+
+ - java.lang.Boolean
+ - java.lang.Byte
+ - java.lang.Character
+ - java.lang.Double
+ - java.lang.Float
+ - java.lang.Integer
+ - java.lang.Long
+ - java.lang.Short
+ - java.lang.String
+
+OpenEJB 3.0 additional types:
+
+ - java.lang.Class
+ - java.lang.Enum (any subclass of)
+ - java.io.File
+ - java.math.BigDecimal
+ - java.math.BigInteger
+ - java.net.Inet4Address
+ - java.net.Inet6Address
+ - java.net.InetAddress
+ - java.net.URI
+ - java.net.URL
+ - java.util.ArrayList
+ - java.util.Date
+ - java.util.HashMap
+ - java.util.Hashtable
+ - java.util.IdentityHashMap
+ - java.util.LinkedHashMap
+ - java.util.LinkedHashSet
+ - java.util.LinkedList
+ - java.util.List
+ - java.util.Map
+ - java.util.Properties
+ - java.util.Set
+ - java.util.SortedMap
+ - java.util.TreeMap
+ - java.util.TreeSet
+ - java.util.Vector
+ - java.util.WeakHashMap
+ - java.util.logging.Logger
+ - java.util.regex.Pattern
+ - javax.management.ObjectName
+ - javax.naming.Context
+ - org.apache.commons.logging.Log
+ - org.apache.log4j.Logger
+
+To use an OpenEJB additional type in xml, simply declare it as
+<env-entry-type>java.lang.String</env-entry-type> and it will be converted
+on the fly to the field/setter type used by the bean class. For example:
+
+
+ package org.superbiz.foo;
+
+ import java.util.Date;
+
+ @Stateless
+ public class MyBean {
+
+ @Resource
+ private Date myDate;
+ }
+
+
+Works with an ejb-jar.xml as follows:
+
+ <ejb-jar xmlns="http://java.sun.com/xml/ns/javaee" version="3.0"
+ metadata-complete="false">
+ <enterprise-beans>
+ <session>
+ <ejb-name>MyBean</ejb-name>
+ <env-entry>
+ <env-entry-name>org.superbiz.foo.MyBean/myDate</env-entry-name>
+ <env-entry-value>2008-04-19</env-entry-value>
+ <env-entry-type>java.lang.String</env-entry-type>
+ </env-entry>
+ </session>
+ </enterprise-beans>
+ </ejb-jar>
+
+
+Or with an env-entries.properties file as follows:
+
+ org.superbiz.foo.MyBean/myDate = 2008-04-19
+
http://git-wip-us.apache.org/repos/asf/tomee/blob/f779264f/docs/callbacks.mdtext
----------------------------------------------------------------------
diff --git a/docs/callbacks.mdtext b/docs/callbacks.mdtext
new file mode 100644
index 0000000..143da30
--- /dev/null
+++ b/docs/callbacks.mdtext
@@ -0,0 +1,164 @@
+Title: Callbacks
+Correct usage of PostConstruct, PreDestroy, PrePassivate, PostActivate, and
+AroundInvoke for EJBs and Interceptors.
+
+For Stateful, Stateless, and MessageDriven, the syntax is as follows:
+
+ - @PostConstruct <any-scope> void <method-name>()
+ - @PreDestroy <any-scope> void <method-name>()
+ - @PrePassivate <any-scope> void <method-name>()
+ - @PostActivate <any-scope> void <method-name>()
+
+For an Interceptor, the syntax includes InvocationContext as follows:
+
+ - @PostConstruct <any-scope> void <method-name>(InvocationContext)
+ - @PreDestroy <any-scope> void <method-name>(InvocationContext)
+ - @PrePassivate <any-scope> void <method-name>(InvocationContext)
+ - @PostActivate <any-scope> void <method-name>(InvocationContext)
+
+The AroundInvoke syntax for an EJB or Interceptor is the same:
+
+ - @AroundInvoke <any-scope> Object <method-name>(InvocationContext) throws Exception
+
+
+<a name="Callbacks-Stateless"></a>
+## Stateless
+
+
+ import javax.ejb.Stateless;
+ import javax.annotation.PostConstruct;
+ import javax.annotation.PreDestroy;
+ import javax.interceptor.AroundInvoke;
+ import javax.interceptor.InvocationContext;
+
+ @Stateless
+ public class MyStatelessBean implements MyBusinessInterface {
+
+ @PostConstruct
+ public void constructed(){
+
+ }
+
+ @PreDestroy
+ public void destroy(){
+
+ }
+
+ @AroundInvoke
+ public Object invoke(InvocationContext invocationContext) throws Exception {
+ return invocationContext.proceed();
+ }
+ }
+
+
+<a name="Callbacks-Stateful"></a>
+## Stateful
+
+
+ import javax.ejb.Stateful;
+ import javax.ejb.PostActivate;
+ import javax.ejb.PrePassivate;
+ import javax.annotation.PostConstruct;
+ import javax.annotation.PreDestroy;
+ import javax.interceptor.AroundInvoke;
+ import javax.interceptor.InvocationContext;
+
+ @Stateful
+ public class MyStatefulBean implements MyBusinessInterface {
+
+ @PostConstruct
+ public void constructed(){
+
+ }
+
+ @PreDestroy
+ public void destroy(){
+
+ }
+
+ @AroundInvoke
+ public Object invoke(InvocationContext invocationContext) throws Exception {
+ return invocationContext.proceed();
+ }
+
+ @PostActivate
+ public void activated(){
+
+ }
+
+ @PrePassivate
+ public void passivate(){
+
+ }
+ }
+
+
+<a name="Callbacks-MessageDriven"></a>
+## MessageDriven
+
+
+ import javax.ejb.MessageDriven;
+ import javax.annotation.PostConstruct;
+ import javax.annotation.PreDestroy;
+ import javax.interceptor.AroundInvoke;
+ import javax.interceptor.InvocationContext;
+
+ @MessageDriven
+ public class MyMessageDrivenBean implements MyListenerInterface {
+
+ @PostConstruct
+ public void constructed(){
+
+ }
+
+ @PreDestroy
+ public void destroy(){
+
+ }
+
+ @AroundInvoke
+ public Object invoke(InvocationContext invocationContext) throws Exception {
+ return invocationContext.proceed();
+ }
+ }
+
+
+<a name="Callbacks-Interceptor"></a>
+## Interceptor
+
+
+ import javax.annotation.PostConstruct;
+ import javax.annotation.PreDestroy;
+ import javax.interceptor.InvocationContext;
+ import javax.interceptor.AroundInvoke;
+ import javax.ejb.PostActivate;
+ import javax.ejb.PrePassivate;
+
+ public class MyInterceptor {
+
+ @PostConstruct
+ public void constructed(InvocationContext invocationContext){
+
+ }
+
+ @PreDestroy
+ public void destroy(InvocationContext invocationContext){
+
+ }
+
+ @AroundInvoke
+ public Object invoke(InvocationContext invocationContext) throws Exception {
+ return invocationContext.proceed();
+ }
+
+ @PostActivate
+ public void activated(InvocationContext invocationContext){
+
+ }
+
+ @PrePassivate
+ public void passivate(InvocationContext invocationContext){
+
+ }
+ }
+
http://git-wip-us.apache.org/repos/asf/tomee/blob/f779264f/docs/changing-jms-implementations.mdtext
----------------------------------------------------------------------
diff --git a/docs/changing-jms-implementations.mdtext b/docs/changing-jms-implementations.mdtext
new file mode 100644
index 0000000..1975441
--- /dev/null
+++ b/docs/changing-jms-implementations.mdtext
@@ -0,0 +1,133 @@
+Title: Changing JMS Implementations
+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.
+
+ActiveMQ is the default JMS provider in Apache TomEE and OpenEJB.
+
+Changing JMS implementation is as simple as using that implementation's Java EE Connector. The connector which will be a `.rar` file should be bundled with the application in a `.ear`
+file. All JMS usage in that `.ear` will favor the JMS ConnectionFactory and Topic and Queue implementations
+that are configured in the `.rar` file rather than ActiveMQ.
+
+If the JMS implementation does not have a `.rar` file, there are still some options for wiring in an alternate implementation.
+
+# Generic JMS Resource Adapter
+
+If the JMS implementation does not have a Resource Archive (`.rar` file) that defines a compliant Resource Adapter, the [Generic Resource Adapter for JMS](http://genericjmsra.java.net/) should work fine.
+
+To use this Adapter in TomEE or OpenEJB you'll need to create a `service-jar.xml` file and include that in a jar file and add it to the `<tomee.home>/lib/` directory.
+Then you can declare `ConnectionFactory`, `Topic`, and `Queue` and more via the `tomee.xml` file.
+
+The one below should be considered boiler plate. Updating it to contain some useful default values for your JMS implementation would be good. These values can be overridden in the `tomee.xml` or `openejb.xml`
+
+Let's say that the following file lives in the jar at `META-INF/org.superbiz/service-jar.xml`
+
+ <?xml version="1.0" encoding="UTF-8"?>
+ <ServiceJar>
+ <ServiceProvider
+ id="genericra"
+ service="Resource"
+ types="GenericJMSRA"
+ class-name="com.sun.genericra.GenericJMSRA">
+ UserName
+ Password
+ ProviderIntegrationMode
+ ConnectionFactoryClassName
+ QueueConnectionFactoryClassName
+ TopicConnectionFactoryClassName
+ XAConnectionFactoryClassName
+ XAQueueConnectionFactoryClassName
+ XATopicConnectionFactoryClassName
+ UnifiedDestinationClassName
+ TopicClassName
+ QueueClassName
+ SupportsXA
+ ConnectionFactoryProperties
+ JndiProperties
+ CommonSetterMethodName
+ RMPolicy
+ LogLevel
+ DeliveryType
+ UseFirstXAForRedelivery
+ </ServiceProvider>
+
+ <ServiceProvider
+ id="ConnectionFactory"
+ service="Resource"
+ types="javax.jms.ConnectionFactory, javax.jms.QueueConnectionFactory, javax.jms.TopicConnectionFactory, QueueConnectionFactory, TopicConnectionFactory"
+ class-name="com.sun.genericra.outbound.ManagedJMSConnectionFactory">
+ ConnectionFactoryJndiName
+ ClientId
+ ConnectionValidationEnabled
+ ResourceAdapter
+ </ServiceProvider>
+
+ <ServiceProvider
+ id="Queue"
+ service="Resource"
+ types="javax.jms.Queue, Queue"
+ class-name="com.sun.genericra.outbound.QueueProxy">
+ DestinationJndiName
+ ResourceAdapter
+ UserName
+ Password
+ JndiProperties
+ QueueClassName
+ </ServiceProvider>
+
+ <ServiceProvider
+ id="Topic"
+ service="Resource"
+ types="javax.jms.Topic, Topic"
+ class-name="com.sun.genericra.outbound.TopicProxy">
+ DestinationJndiName
+ ResourceAdapter
+ UserName
+ Password
+ JndiProperties
+ TopicClassName
+ </ServiceProvider>
+ </ServiceJar>
+
+It is strongly recommended to not leave the values in the service-jar.xml file blank as shown above. It is
+possible to setup several sets of defaults in a `service-jar.xml` or via several `service-jar.xml` files.
+
+Once this file is packed in a jar and added to the `<tomee.home>/lib` or `<openejb.home>/lib` directory, you can
+then declare and configure "instances" of these things in your `tomee.xml` or `openejb.xml` config file as follows:
+
+ <Resource id="My Generic Adapter" type="GenericJMSRA" provider="org.superbiz:genericra">
+ AdapterProperty1 PropertyValue1
+ AdapterProperty2 PropertyValue2
+ ...
+ </Resource>
+
+Or in properties like so:
+
+ myGenericAdapter = new://Resource?type=GenericJMSRA&provider=org.superbiz:genericra
+ myGenericAdapter.AdapterProperty1 = PropertyValue1
+ myGenericAdapter.AdapterProperty2 = PropertyValue2
+
+This is basically the same as all configuration in TomEE/OpenEJB, but with the addition that you must
+specify the `provider` attribute so the server knows where to look for the `service-jar.xml` file that
+defines the resource and all its defaults.
+
+In this example:
+
+ - the file is `META-INF/org.superbiz/service-jar.xml`
+ - so the `provider` attribute is `org.superbiz`
+
+You can use whatever prefix you like for the `provider` id, though for obvious reasons we'd advise not using `org.apache.openejb` or `org.apache.tomee` in the prefix.
+
http://git-wip-us.apache.org/repos/asf/tomee/blob/f779264f/docs/client-server-transports.mdtext
----------------------------------------------------------------------
diff --git a/docs/client-server-transports.mdtext b/docs/client-server-transports.mdtext
new file mode 100644
index 0000000..5dd8721
--- /dev/null
+++ b/docs/client-server-transports.mdtext
@@ -0,0 +1,19 @@
+Title: Client-Server Transports
+<a name="Client-ServerTransports-Client/Servertransports"></a>
+# Client/Server transports
+
+<table>
+<tr><th> jar </th><th> transport description </th></tr>
+<tr><td> openejb-ejbd-3.0.jar </td><td> provides the 'ejbd' protocol. A binary protocol
+traveling over a socket </td></tr>
+<tr><td> openejb-http-3.0.jar </td><td> supports the ejbd protocol over http </td></tr>
+<tr><td> openejb-derbynet-3.0.jar </td><td> allows for derby to accessed via it's network
+driver </td></tr>
+<tr><td> openejb-hsql-3.0.jar </td><td> allows for hsqldb to be accessed via it's network
+driver </td></tr>
+<tr><td> openejb-cxf-3.0.jar </td><td> turns on webservice ability, soap/http, via cxf </td></tr>
+<tr><td> openejb-activemq-3.0.jar </td><td> supports remote jms clients via activemq </td></tr>
+<tr><td> openejb-telnet-3.0.jar </td><td> allows for connecting to the server via telnet
+for monitoring </td></tr>
+</table>
+
http://git-wip-us.apache.org/repos/asf/tomee/blob/f779264f/docs/clients.mdtext
----------------------------------------------------------------------
diff --git a/docs/clients.mdtext b/docs/clients.mdtext
new file mode 100644
index 0000000..368a703
--- /dev/null
+++ b/docs/clients.mdtext
@@ -0,0 +1,101 @@
+Title: Clients
+
+<a name="Clients-LocalClient(embeddedcontainer)"></a>
+### Local Client (embedded container)
+
+
+ Properties p = new Properties();
+ p.put("java.naming.factory.initial", "org.apache.openejb.client.LocalInitialContextFactory");
+
+ InitialContext ctx = new InitialContext(p);
+
+ MyBean myBean = (MyBean) ctx.lookup("MyBeanRemote");
+
+
+<a name="Clients-LocalClient(non-defaultrealmname)"></a>
+### Local Client (non-default realm name)
+
+<a name="Clients-Loginconfigurationfile(conf/login.config)"></a>
+### Login configuration file (conf/login.config)
+
+
+ PropertiesLogin {
+ org.apache.openejb.core.security.jaas.PropertiesLoginModule required
+ Debug=true
+ UsersFile="users.properties"
+ GroupsFile="groups.properties";
+ };
+ MyApp {
+ org.apache.openejb.core.security.jaas.SQLLoginModule required
+ dataSourceName="MyDataSource"
+ userSelect="SELECT username, password FROM users WHERE username=?"
+ groupSelect="SELECT username, grp FROM users WHERE username=?";
+ };
+
+
+<a name="Clients-Programcode"></a>
+### Code
+
+
+ Properties p = new Properties();
+ p.put("java.naming.factory.initial", "org.apache.openejb.client.LocalInitialContextFactory");
+ p.put("openejb.authentication.realmName", "MyApp");
+
+ InitialContext ctx = new InitialContext(p);
+
+ MyBean myBean = (MyBean) ctx.lookup("MyBeanRemote");
+
+
+<a name="Clients-RemoteClient(openejbstandalone)"></a>
+### Remote Client (openejb standalone)
+
+
+ Properties p = new Properties();
+ p.put("java.naming.factory.initial", "org.apache.openejb.client.RemoteInitialContextFactory");
+ p.put("java.naming.provider.url", "ejbd://localhost:4201");
+ // user and pass optional
+ p.put("java.naming.security.principal", "myuser");
+ p.put("java.naming.security.credentials", "mypass");
+
+ InitialContext ctx = new InitialContext(p);
+
+ MyBean myBean = (MyBean) ctx.lookup("MyBeanRemote");
+
+
+<a name="Clients-RemoteClientwithHTTP(openejbstandalone)"></a>
+### Remote Client with HTTP (openejb standalone)
+
+
+ Properties p = new Properties();
+ p.put("java.naming.factory.initial", "org.apache.openejb.client.RemoteInitialContextFactory");
+ p.put("java.naming.provider.url", "http://localhost:4204/ejb");
+ // user and pass optional
+ p.put("java.naming.security.principal", "myuser");
+ p.put("java.naming.security.credentials", "mypass");
+
+ InitialContext ctx = new InitialContext(p);
+
+ MyBean myBean = (MyBean) ctx.lookup("MyBeanRemote");
+
+
+
+<a name="Clients-RemoteClientwithHTTP(intomcat)"></a>
+### Remote Client with HTTP (in TomEE)
+
+
+ Properties p = new Properties();
+ p.put("java.naming.factory.initial", "org.apache.openejb.client.RemoteInitialContextFactory");
+ p.put("java.naming.provider.url", "http://127.0.0.1:8080/tomee/ejb");
+ // user and pass optional
+ p.put("java.naming.security.principal", "myuser");
+ p.put("java.naming.security.credentials", "mypass");
+
+ InitialContext ctx = new InitialContext(p);
+
+ MyBean myBean = (MyBean) ctx.lookup("MyBeanRemote");
+
+<a name="RemoteClientUsingEjbInjection)"></a>
+### Remote Client using @EJB Injection
+see here:
+<a href="http://tomee.apache.org/ejb-refs.html">ejb-refs</a>
+
http://git-wip-us.apache.org/repos/asf/tomee/blob/f779264f/docs/cmpentitycontainer-config.mdtext
----------------------------------------------------------------------
diff --git a/docs/cmpentitycontainer-config.mdtext b/docs/cmpentitycontainer-config.mdtext
new file mode 100644
index 0000000..0947167
--- /dev/null
+++ b/docs/cmpentitycontainer-config.mdtext
@@ -0,0 +1,34 @@
+Title: CmpEntityContainer Configuration
+
+
+A CmpEntityContainer 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.
+
+ <Container id="myCmpEntityContainer" type="CMP_ENTITY">
+ cmpEngineFactory = org.apache.openejb.core.cmp.jpa.JpaCmpEngineFactory
+ </Container>
+
+Alternatively, a CmpEntityContainer 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`
+
+ myCmpEntityContainer = new://Container?type=CMP_ENTITY
+ myCmpEntityContainer.cmpEngineFactory = org.apache.openejb.core.cmp.jpa.JpaCmpEngineFactory
+
+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 CmpEntityContainer a warning will be logged. If a CmpEntityContainer is needed by the application and one is not declared, TomEE will create one dynamically using default settings. Multiple CmpEntityContainer declarations are allowed.
+# Supported Properties
+<table>
+<tr>
+<th>Property</th>
+<th>Type</th>
+<th>Default</th>
+<th>Description</th>
+</tr>
+<tr>
+ <td>cmpEngineFactory</td>
+ <td>String</td>
+ <td>org.apache.openejb.core.cmp.jpa.JpaCmpEngineFactory</td>
+ <td>
+
+</td>
+</tr>
+</table>
+
+
http://git-wip-us.apache.org/repos/asf/tomee/blob/f779264f/docs/collapsed-ear.mdtext
----------------------------------------------------------------------
diff --git a/docs/collapsed-ear.mdtext b/docs/collapsed-ear.mdtext
new file mode 100644
index 0000000..7ce0541
--- /dev/null
+++ b/docs/collapsed-ear.mdtext
@@ -0,0 +1,42 @@
+Title: Collapsed EAR
+<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 app.
+
+* No classloader boundries 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 (it is truly Java EE6)
+
+This is very different than J2EE or Java EE 5 as there aren't several
+levels of separation and classloader hierarchy. This is going to take some
+getting used to and it should be understood that this style of packaging
+isn't J2EE compliant. Who would care tough as it is a feature of Java EE 6
+we would've been waiting for so long.
+
+ 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.
+
+<a name="CollapsedEAR-ExamplewithTomcat"></a>
+# Example with Tomcat
+
+If you want to try to work with Servlets/JSP and OpenEJB using Tomcat, see
+the [setup page](openejbx30:tomcat.html)
+ and the "/webapps/ejb-examples" section of the [openejb-examples.zip](downloads.html)
+ available on the [download page](http://tomee.apache.org/downloads.html).
http://git-wip-us.apache.org/repos/asf/tomee/blob/f779264f/docs/common-datasource-configurations.mdtext
----------------------------------------------------------------------
diff --git a/docs/common-datasource-configurations.mdtext b/docs/common-datasource-configurations.mdtext
new file mode 100644
index 0000000..fb9a992
--- /dev/null
+++ b/docs/common-datasource-configurations.mdtext
@@ -0,0 +1,111 @@
+Title: Common DataSource Configurations
+
+See the [DataSource Configuration](datasource-config.html) for details on all configuration options for DataSources.
+
+<a name="CommonDataSourceConfigurations-HSQLDB"></a>
+## HSQLDB
+
+The drivers are included with OpenEJB 3.0 and HSQLDB is the default
+database.
+
+ <Resource id="HSQLDB Database" type="DataSource">
+ JdbcDriver org.hsqldb.jdbcDriver
+ JdbcUrl jdbc:hsqldb:file:hsqldb
+ UserName sa
+ Password
+ </Resource>
+
+
+<a name="CommonDataSourceConfigurations-Derby(Embedded)"></a>
+## Derby (Embedded)
+
+
+ <Resource id="Derby Database" type="DataSource">
+ #Embedded Derby example
+
+ JdbcDriver org.apache.derby.jdbc.EmbeddedDriver
+ JdbcUrl jdbc:derby:derbyDB;create=true
+ UserName admin
+ Password pass
+ </Resource>
+
+
+<a name="CommonDataSourceConfigurations-MySQL"></a>
+## MySQL
+
+
+ <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
+ </Resource>
+
+
+<a name="CommonDataSourceConfigurations-Oracle"></a>
+## Oracle
+
+
+ <Resource id="Oracle Database" type="DataSource">
+ # Oracle example
+ #
+ # This connector will not work until you download the driver at:
+ # http://otn.oracle.com/software/tech/java/sqlj_jdbc/content.html
+ JdbcDriver oracle.jdbc.OracleDriver
+ JdbcUrl jdbc:oracle:thin:@localhost:1521:orcl
+ UserName scott
+ Password tiger
+ </Resource>
+
+<a name="CommonDataSourceConfigurations-OracleXA"></a>
+## OracleXA
+
+
+ <Resource id="OracleXA Database" type="DataSource">
+ # OracleXA example
+ #
+ # This connector will not work until you download the driver at:
+ # http://otn.oracle.com/software/tech/java/sqlj_jdbc/content.html
+ JdbcDriver oracle.jdbc.xa.client.OracleXADataSource
+ JdbcUrl jdbc:oracle:thin:@localhost:1521:orcl
+ UserName scott
+ Password tiger
+ </Resource>
+
+<a name="CommonDataSourceConfigurations-PosgreSQL"></a>
+## PosgreSQL
+
+
+ <Resource id="PostgreSQL Database" type="DataSource">
+ # PostgreSQL example
+ #
+ # This connector will not work until you download the driver at:
+ # http://jdbc.postgresql.org/download.html
+ JdbcDriver org.postgresql.Driver
+ JdbcUrl jdbc:postgresql://localhost/test
+ UserName postgres
+ Password pass
+ </Resource>
+
+
+<a name="CommonDataSourceConfigurations-InstantDB"></a>
+## InstantDB
+
+
+ <Resource id="InstantDB Database" type="DataSource">
+ # InstantDB example
+ #
+ JdbcDriver org.enhydra.instantdb.jdbc.idbDriver
+ JdbcUrl jdbc:idb:conf/instantdb.properties
+ UserName Admin
+ Password pass
+ </Resource>
+
+
+
+Internally, from TomEE 1.5.0, JDBC pools are managed via Tomcat-pool. You can still switch back to Apache Commons DBCP by adding the following property: DataSourceCreator dbcp. To
+get the full list of available configuration properties, have a look to [Apache Commons DBCP configuration](http://commons.apache.org/dbcp/configuration.html).
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/tomee/blob/f779264f/docs/common-errors.mdtext
----------------------------------------------------------------------
diff --git a/docs/common-errors.mdtext b/docs/common-errors.mdtext
new file mode 100644
index 0000000..7b3e44c
--- /dev/null
+++ b/docs/common-errors.mdtext
@@ -0,0 +1,27 @@
+Title: Common Errors
+
+<a name="CommonErrors-Cannotfindcontainer"FOO"forbean"BAR""></a>
+# Cannot find container "FOO" for bean "BAR"
+
+When a bean gets deployed in OpenEJB, it gets associated with a particular
+container. Subsequently, that container may not be configured in that
+instance of the server. When the server loads the Jar with the deployed
+beans, it places beans in the containers that the beans were configured
+with. Here, the bean BAR wants to go into the container FOO, which is not
+currently configured.
+
+This message is displayed when the server is starting up.
+<a name="CommonErrors-Cannotfindbean"FOO"referencedbybean"BAR"."></a>
+# Cannot find bean "FOO" referenced by bean "BAR".
+
+When a bean gets deployed in OpenEJB, it may contain references to other
+beans. Subsequently, those beans may not be configured in that instance of
+the server. When the server loads the Jar with the deployed beans, it
+stores those references to those beans. Here, the bean BAR references FOO,
+which is not currently configured in the JNDI namespace.
+
+This message is displayed when the server is starting up.
+
+This message is usally the result of a deployment descriptor that has been
+created by hand.
+
http://git-wip-us.apache.org/repos/asf/tomee/blob/f779264f/docs/common-persistenceprovider-properties.mdtext
----------------------------------------------------------------------
diff --git a/docs/common-persistenceprovider-properties.mdtext b/docs/common-persistenceprovider-properties.mdtext
new file mode 100644
index 0000000..e1fe351
--- /dev/null
+++ b/docs/common-persistenceprovider-properties.mdtext
@@ -0,0 +1,44 @@
+Title: Common PersistenceProvider properties
+While not a definitive list, it does help to show a side-by-side view of
+common properties used by the various persistence providers out there.
+
+<a name="CommonPersistenceProviderproperties-TopLink"></a>
+# TopLink
+
+
+ <properties>
+
+ <!--http://www.oracle.com/technology/products/ias/toplink/JPA/essentials/toplink-jpa-extensions.html-->
+ <property name="toplink.ddl-generation" value="drop-and-create-tables"/>
+ <property name="toplink.logging.level" value="FINEST"/>
+ <property name="toplink.ddl-generation.output-mode" value="both"/>
+ <property name="toplink.target-server" value="pl.zsk.samples.ejbservice.OpenEJBServerPlatform"/>
+ </properties>
+
+
+<a name="CommonPersistenceProviderproperties-OpenJPA"></a>
+# OpenJPA
+
+
+ <properties>
+ <!--http://openjpa.apache.org/faq.html-->
+ <!-- does not create foreign keys, creates schema and deletes content of a database
+ (deleteTableContents - foreign keys are created twice???), use dropDB instead -->
+ <property name="openjpa.jdbc.SynchronizeMappings" value="buildSchema(foreignKeys=true,schemaAction='dropDB,add')"/>
+ <!--Resolves the problem with foreign key integrity - joined entities are persisted sometimes in wrong order??? (verify it)-->
+ <property name="openjpa.jdbc.SchemaFactory" value="native(foreignKeys=true)" />
+ <!--Create foreign keys-->
+ <property name="openjpa.jdbc.MappingDefaults" value="ForeignKeyDeleteAction=restrict, JoinForeignKeyDeleteAction=restrict"/>
+ <property name="openjpa.Log" value="DefaultLevel=TRACE,SQL=TRACE" />
+ </properties>
+
+
+<a name="CommonPersistenceProviderproperties-Hibernate"></a>
+# Hibernate
+
+
+ <properties>
+ <property name="hibernate.hbm2ddl.auto" value="create-drop"/>
+ <property name="hibernate.transaction.manager_lookup_class" value="org.apache.openejb.hibernate.TransactionManagerLookup"/>
+ </properties>
+
http://git-wip-us.apache.org/repos/asf/tomee/blob/f779264f/docs/comparison.mdtext
----------------------------------------------------------------------
diff --git a/docs/comparison.mdtext b/docs/comparison.mdtext
new file mode 100644
index 0000000..4f417b3
--- /dev/null
+++ b/docs/comparison.mdtext
@@ -0,0 +1,219 @@
+Title: Comparison
+
+Apache OpenEJB and Apache TomEE are born from the same project and community. They differ in two major ways, only one of them technical:
+
+ - TomEE incorporates two additional projects; Tomcat and MyFaces
+ - TomEE, as a name, more easily implies the breadth of technologies included
+
+Effectively, TomEE is a superset of OpenEJB. They share the same code and TomEE grew out of OpenEJB.
+
+Note: this table is for TomEE 1.x, TomEE 7 comments are under it.
+
+<table>
+<tr>
+<th></th>
+<th>Tomcat</th>
+<th>TomEE</th>
+<th>TomEE JAX-RS (~ Microprofile)</th>
+<th>TomEE+</th>
+<th>TomEE PluME</th>
+<th>OpenEJB</th>
+</tr>
+
+<tr>
+<td>Java Servlets</td>
+<td>(/)</td>
+<td>(/)</td>
+<td>(/)</td>
+<td>(/)</td>
+<td>(/)</td>
+<td></td>
+</tr>
+
+<tr>
+<td>Java ServerPages (JSP)</td>
+<td>(/)</td>
+<td>(/)</td>
+<td>(/)</td>
+<td>(/)</td>
+<td>(/)</td>
+<td></td>
+</tr>
+
+<tr>
+<td>Java ServerFaces (JSF)</td>
+<td></td>
+<td>(/)</td>
+<td>(/)</td>
+<td>(/)</td>
+<td>(/)</td>
+<td></td>
+</tr>
+
+<tr>
+<td>Java Transaction API (JTA)</td>
+<td></td>
+<td>(/)</td>
+<td>(/)</td>
+<td>(/)</td>
+<td>(/)</td>
+<td>(/)</td>
+</tr>
+
+<tr>
+<td>Java Persistence API (JPA)</td>
+<td></td>
+<td>(/)</td>
+<td>(/)</td>
+<td>(/)</td>
+<td>(/)</td>
+<td>(/)</td>
+</tr>
+
+<tr>
+<td>Java Contexts and Dependency Injection (CDI)</td>
+<td></td>
+<td>(/)</td>
+<td>(/)</td>
+<td>(/)</td>
+<td>(/)</td>
+<td>(/)</td>
+</tr>
+
+<tr>
+<td>Java Authentication and Authorization Service (JAAS)</td>
+<td></td>
+<td>(/)</td>
+<td>(/)</td>
+<td>(/)</td>
+<td>(/)</td>
+<td>(/)</td>
+</tr>
+
+<tr>
+<td>Java Authorization Contract for Containers (JACC)</td>
+<td></td>
+<td>(/)</td>
+<td>(/)</td>
+<td>(/)</td>
+<td>(/)</td>
+<td>(/)</td>
+</tr>
+
+<tr>
+<td>JavaMail API</td>
+<td></td>
+<td>(/)</td>
+<td>(/)</td>
+<td>(/)</td>
+<td>(/)</td>
+<td>(/)</td>
+</tr>
+
+<tr>
+<td>Bean Validation</td>
+<td></td>
+<td>(/)</td>
+<td>(/)</td>
+<td>(/)</td>
+<td>(/)</td>
+<td>(/)</td>
+</tr>
+
+<tr>
+<td>Enterprise JavaBeans</td>
+<td></td>
+<td>(/)</td>
+<td>(/)</td>
+<td>(/)</td>
+<td>(/)</td>
+<td>(/)</td>
+</tr>
+
+<tr>
+<td>Java API for RESTful Web Services (JAX-RS)</td>
+<td></td>
+<td></td>
+<td>(/)</td>
+<td>(/)</td>
+<td>(/)</td>
+<td>(/)</td>
+</tr>
+
+<tr>
+<td>Java API for XML Web Services (JAX-WS)</td>
+<td></td>
+<td></td>
+<td></td>
+<td>(/)</td>
+<td>(/)</td>
+<td>(/)</td>
+</tr>
+
+<tr>
+<td>Java EE Connector Architecture</td>
+<td></td>
+<td></td>
+<td></td>
+<td>(/)</td>
+<td>(/)</td>
+<td>(/)</td>
+</tr>
+
+<tr>
+<td>Java Messaging Service (JMS)</td>
+<td></td>
+<td></td>
+<td></td>
+<td>(/)</td>
+<td>(/)</td>
+<td>(/)</td>
+</tr>
+
+<tr>
+<td>EclipseLink</td>
+<td></td>
+<td></td>
+<td></td>
+<td></td>
+<td>(/)</td>
+<td></td>
+</tr>
+
+<tr>
+<td>Mojarra</td>
+<td></td>
+<td></td>
+<td></td>
+<td></td>
+<td>(/)</td>
+<td></td>
+</tr>
+
+</table>
+
+
+TomEE 7 targets JavaEE 7 and implements these specifications (in parenthesis the distibution(s) containing it if not part of the basic packages):
+
+* WebSocket JSR 356
+* JSON-P JSR 353
+* Servlet 3.1 JSR 340
+* JSF 2.2 JSR 344
+* EL 3.0 JSR 341
+* JSP 2.3 JSR 245
+* JSTL 1.2 JSR 52
+* JBatch (plus) JSR 352
+* Concurrency utilities for EE JSR 236
+* CDI 1.2, DI, Interceptors 1.2, Common Annotations JSR 346 + JSR 330 + JSR 318 + JSR 250
+* Bean Validation 1.1 JSR 349
+* EJB 3.2 JSR 345
+* JavaEE Connector JSR 322
+* JPA 2.1 JSR 338 (WARNING: openjpa based distributions provide a JPA 2.0 runtime)
+* JMS 2.0 JSR 343 (layer based on ActiveMQ 5 / JMS 1.1 for default distributions)
+* JTA 1.2 JSR 907
+* Javamail 1.4 (NOTE: EE 7 requires 1.5)
+* JAX-RS 2.0 JSR 339
+* JAX-WS 2.2 JSR 224
+* JAXB 2.2 JSR 222
+* and more inherited from TomEE 1/JavaEE 6
+
http://git-wip-us.apache.org/repos/asf/tomee/blob/f779264f/docs/concepts.mdtext
----------------------------------------------------------------------
diff --git a/docs/concepts.mdtext b/docs/concepts.mdtext
new file mode 100644
index 0000000..dba6d33
--- /dev/null
+++ b/docs/concepts.mdtext
@@ -0,0 +1,75 @@
+Title: Concepts
+OpenEJB was founded on the idea that it would be embedded into third-party
+environments whom would likely already have three things:
+
+ - their one "server" platform with existing clients and protocols
+ - their own way to configure their platform
+ - existing services like TransactionManager, Security, and Connector
+
+Thus the focus of OpenEJB was to create an EJB implementation that would be
+easily embeddible, configurable, and customizable.
+
+Part of achieving that is a drive to be as simple as possible as to not
+over-define and therefore restrict the ability to be embeddible,
+configurable and customizable. Smaller third-party environments could
+easily 'downscale' OpenEJB in their integrations by replacing standard
+components with lighter implementations or removing them all together and
+larger environments could 'upscale' OpenEJB by replacing and adding heavier
+implementations of those standard components likely tailored to their
+systems and infrastructure.
+
+Container and Server are mentioned in the EJB spec as being separate things
+but are never defined formally. In our world Containers, which implement
+the basic component contract and lifecycle of a bean are not coupled to any
+particular Server, which has the job of providing a naming service and
+providing a way for it's clients to reference and invoke components (beans)
+hosted in Containers. Because Containers have no dependence at all only
+Server, you can run OpenEJB without any Server at all in an embedded
+environment for example without any work or any extra overhead. Similarly
+you can add as many new Server components as you want without ever having
+to modify any Containers.
+
+There is a very strong pluggability focus in OpenEJB as it was always
+intended to be embedded and customized in other environments. As a result
+all Containers are pluggable, isolated from each other, and no one
+Container is bound to another Container and therefore removing or adding a
+Container has no repercussions on the other Containers in the system.
+TransactionManager, SecurityService and Connector also pluggable and are
+services exposed to Containers. A Container may not be dependent on
+specific implementations of those services. Service Providers define what
+services they are offering (Container, Connector, Security, Transaction,
+etc.) in a file they place in their jar called service-jar.xml.
+
+The service-jar.xml should be placed not in the META-INF but somewhere in
+your package hierarchy (ours is in /org/apache/openejb/service-jar.xml)
+which allows the services in your service-jar.xml to be referenced by name
+(such as DefaultStatefulContainer) or more specifically by package and id
+(such as org.apache.openejb#DefaultStatefulContainer).
+
+The same implementation of a service can be declared several times in a
+service-jar.xml with different ids. This allows for you to setup several
+several different profiles or pre-configured versions of the services you
+provide each with a different name and different set of default values for
+its properties.
+
+In your openejb.conf file when you declare Containers and Connectors, we
+are actually hooking you up with Service Providers automatically. You get
+what is in the org/apache/openejb/service-jar.xml by default, but you are
+able to point specifically to a specific Service Provider by the 'provider'
+attribute on the Container, Connector, TransactionManager, SecurityService,
+etc. elements of the openejb.conf file. When you declare a service
+(Container, Connector, etc.) in your openejb.conf file the properties you
+supply override the properties supplied by the Service Provider, thus you
+only need to specify the properties you'd like to change and can have your
+openejb.conf file as large or as small as you would like it. The act of
+doing this can be thought of as essentially instantiating the Service
+Provider and configuring that instance for inclusion in the runtime system.
+
+For example Container(id=NoTimeoutStatefulContainer,
+provider=DefaultStatefulContainer) could be declared with it's Timeout
+property set to 0 for never, and a
+Container(id=ShortTimeoutStatefulContainer,
+provider=DefaultStatefulContainer) could be declared with it's Timeout
+property set to 15 minutes. Both would be instances of the
+DefaultStatefulContainer Service Provider which is a service of type
+Container.
http://git-wip-us.apache.org/repos/asf/tomee/blob/f779264f/docs/configuration.mdtext
----------------------------------------------------------------------
diff --git a/docs/configuration.mdtext b/docs/configuration.mdtext
new file mode 100644
index 0000000..f3786a5
--- /dev/null
+++ b/docs/configuration.mdtext
@@ -0,0 +1,140 @@
+Title: Configuration
+<a name="Configuration-ShortOverview"></a>
+# Short Overview
+
+<a name="Configuration-ConfigurationProperties"></a>
+## Configuration Properties
+
+* _openejb.home_ - OpenEJB home (installation) directory path. All relative paths are resolved against the property unless openejb.base is set. Unless set, the value is assigned to the _user.dir_ Java property.
+* _openejb.base_ - OpenEJB base directory path. If set, the directory pointed by the property is searched for resources before openejb.home.
+* _openejb.configuration_ - OpenEJB configuration file path.
+* _openejb.loader_ - OpenEJB loader that's responsible for loading EJBs. There are 3 different loader types:
+** _tomcat-webapp_ - set it when inside of Tomcat scoped at just the webapp, aka. [Collapsed EAR](collapsed-ear.html)
+** _tomcat_ - set it when inside of Tomcat scoped for all webapps to share
+** _system_ (also: bootstrap)
+** _embedded_ (also: noload)
+* _openejb.configurator_ (default: _org.openejb.alt.config.ConfigurationFactory_ ) - a class that builds org.openejb.alt.assembler.classic.OpenEjbConfiguration object; implements the org.openejb.alt.assembler.classic.OpenEjbConfigurationFactory interface
+* _openejb.descriptors.output_ - possible values: true|false - When set OpenEJB saves deployment descriptors - ejb-jar.xml and openejb-jar.xml
+
+<a name="Configuration-ConfigurationFile"></a>
+## Configuration File
+
+Show a config file with the elements hyperlinked.
+
+ <?xml version="1.0"?>
+ <openejb>
+ <Container id="Default CMP Container" ctype="CMP_ENTITY">
+ Global_TX_Database c:/my/app/conf/postgresql.cmp_global_database.xml
+ Local_TX_Database c:/my/app/conf/postgresql.cmp_local_database.xml
+ </Container>
+ <Connector id="Default JDBC Database">
+ JdbcDriver org.postgresql.Driver
+ JdbcUrl jdbc:postgresql://localhost/mydb
+ UserName username
+ Password password
+ </Connector>
+ <SecurityService id="Default Security Service"/>
+ <TransactionService id="Default Transaction Manager"/>
+ <Deployments jar="c:/my/app/employee.jar"/>
+ <Deployments dir="beans/" />
+ </openejb>
+
+
+# Basic Layout
+
+Basically, openejb.base is the source for 100% of all configuration
+information and third party config files (log4j, castor, instantdb,
+whatever). This includes finding where the, possibly many, <Deployment>
+entries in the openejb.conf point. The openejb.home is where the code
+loading OpenEJB will look for all the OpenEJB libraries. Usually
+openejb.base is not explicitly set and defaults to the value of
+openejb.home, so many people are used to only dealing with openejb.home.
+
+The point of having and openejb.base and openejb.home was basically to
+allow several independently configured instances of OpenEJB running on a
+system (perhaps embedded in Swing apps, in Tomcat, running as a standalone
+Server, or even in Groovy as Mr. Strachan did!) but without the need to
+copy all the OpenEJB system libraries everywhere.
+
+ *openejb.home*
+ * can be set explicitly via a system property.
+ * if not set it default's to user.dir, which is the current working
+ directory.
+
+ *openejb.base*
+ * can be set explicitly via a system property.
+ * If not set it default's to openejb.home.
+
+ *openejb.configuration*
+ * can be set to explicitly point to the file containing your
+ configuration.
+ * If set to a relative path, we first look in user.dir/your-conf-file,
+ then in openejb.base/your-conf-file
+ * If not set we check in openejb.base/conf/openejb.conf
+ * If no conf file is found, we create one in
+ openejb.base/conf/openejb.conf
+
+
+ *relative paths in openejb.conf*
+ * Deployment entries are resolved relative to openejb.base.
+ * Containers use openejb.base to resolve their own config files. For
+ example, Castor JDO to loads the database.xml and all other files from the
+ openejb.base directory.
+ * Resource adapters that are embedded usually have config files of their
+ own and are also loaded from the openeb.base.
+
+ *log files*
+ * The log4.configuration file is resolved relative to openejb.base.
+ * The properties in the config file that point to files are also resolved
+ relative to openejb.base.
+
+ *OpenEJB libraries*
+ * The jars in the lib and dist directories under openejb.home are added
+to the classpath.
+
+## Summary
+
+A summary of the above in a different notation:
+
+ openejb.home = user.dir (can be set explicitly)
+ openejb.base = openejb.home (can be set explicitly)
+ openejb.conf = openejb.base/conf/openejb.conf (can be set explicitly)
+ logging.conf = openejb.base/conf/logging.conf (can be set explicitly)
+ deployments = paths listed in openejb.conf (relative paths resolved from openejb.base)
+ Classpath includes openejb.home/lib and openejb.home/dist
+
+## Example layout
+
+In this one the openejb.home and openejb.base are set, everything else is
+defaulted. The openejb.conf file as been updated to point to the ejb jars
+by name (abc-ejbs.jar and xyz-ejbs.jar).
+
+An example layout:
+
+ /usr/local/openejb (openejb.home)
+ /usr/local/openejb/lib (in classpath)
+ /usr/local/openejb/dist (in classpath)
+ /home/jsmith/foo_app (openejb.base)
+ /home/jsmith/foo_app/conf/openejb.conf
+ /home/jsmith/foo_app/conf/logging.conf
+ /home/jsmith/foo_app/abc-ejbs.jar (Deployment entry in openejb.conf)
+ /home/jsmith/foo_app/xyz-ejbs.jar (Deployment entry in openejb.conf)
+ /home/jsmith/foo_app/logs/
+
+
+## Another Example layout
+
+In this example openejb.home and openejb.base are setup as well as the
+explicit paths for the openejb and log4j configuration files.
+
+An example layout:
+
+ /usr/local/openejb (openejb.home)
+ /usr/local/openejb/lib (in classpath)
+ /usr/local/openejb/dist (in classpath)
+ /home/jsmith/foo_app (openejb.base)
+ /home/jsmith/foo_app/openejb.xml (openejb.configuration)
+ /home/jsmith/foo_app/abc-ejbs.jar (Deployment entry in openejb.xml)
+ /home/jsmith/foo_app/xyz-ejbs.jar (Deployment entry in openejb.xml)
+ /home/jsmith/foo_app/log4j.conf (log4j.configuration)
+ /home/jsmith/foo_app/mylogs/ (logging dir as defined in log4j.conf)
http://git-wip-us.apache.org/repos/asf/tomee/blob/f779264f/docs/configuring-containers-in-tests.mdtext
----------------------------------------------------------------------
diff --git a/docs/configuring-containers-in-tests.mdtext b/docs/configuring-containers-in-tests.mdtext
new file mode 100644
index 0000000..c38aecb
--- /dev/null
+++ b/docs/configuring-containers-in-tests.mdtext
@@ -0,0 +1,24 @@
+Title: Configuring Containers in Tests
+Like Resources, Containers can also be declared via InitialContext
+properties as well. The most useful is to declare a Stateful SessionBean
+container so that it's guaranteed to passivate and activate on each call to
+the bean, allowing you to test your callbacks behave as you need them to.
+
+
+ Properties p = new Properties();
+ p.put(Context.INITIAL_CONTEXT_FACTORY, "org.apache.openejb.core.LocalInitialContextFactory");
+
+ p.put("myStatefulContainer", "new://Container?type=STATEFUL");
+ p.put("myStatefulContainer.PoolSize", "0");
+ p.put("myStatefulContainer.BulkPassivate", "1");
+
+ Context context = new InitialContext(p);
+
+
+Note, this only works when using the LocalInitialContextFactory to embed
+OpenEJB into the vm. Once embedded, further configuration properties are
+ignored.
+
+See [Containers and Resources](containers-and-resources.html)
+ for a full list of supported Resource types and their properties.
+