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:18 UTC
[03/20] tomee git commit: Docs old and new
http://git-wip-us.apache.org/repos/asf/tomee/blob/f779264f/docs/security-annotations.mdtext
----------------------------------------------------------------------
diff --git a/docs/security-annotations.mdtext b/docs/security-annotations.mdtext
new file mode 100644
index 0000000..bdd8d6d
--- /dev/null
+++ b/docs/security-annotations.mdtext
@@ -0,0 +1,294 @@
+Title: Security Annotations
+This page shows the correct usage of the security related annotations:
+
+ - javax.annotation.security.RolesAllowed
+ - javax.annotation.security.PermitAll
+ - javax.annotation.security.DenyAll
+ - javax.annotation.security.RunAs
+ - javax.annotation.security.DeclareRoles
+
+<a name="SecurityAnnotations-Basicidea"></a>
+## Basic idea
+
+- By default all methods of a business interface are accessible, logged in
+or not
+- The annotations go on the bean class, not the business interface
+- Security annotations can be applied to entire class and/or individual
+methods
+- The names of any security roles used must be declared via @DeclareRoles
+
+<a name="SecurityAnnotations-Norestrictions"></a>
+## No restrictions
+
+Allow anyone logged in or not to invoke 'svnCheckout'.
+
+These three examples are all equivalent.
+
+
+ @Stateless
+ public class OpenSourceProjectBean implements Project {
+
+ public String svnCheckout(String s) {
+ return s;
+ }
+ }
+
+
+ @Stateless
+ @PermitAll
+ public class OpenSourceProjectBean implements Project {
+
+ public String svnCheckout(String s) {
+ return s;
+ }
+ }
+
+
+ @Stateless
+ public class OpenSourceProjectBean implements Project {
+
+ @PermitAll
+ public String svnCheckout(String s) {
+ return s;
+ }
+ }
+
+
+ - Allow anyone logged in or not to invoke 'svnCheckout'.
+
+<a name="SecurityAnnotations-RestrictingaMethod"></a>
+## Restricting a Method
+
+Restrict the 'svnCommit' method to only individuals logged in and part of
+the "committer" role. Note that more than one role can be listed.
+
+
+ @Stateless
+ @DeclareRoles({"committer"})
+ public class OpenSourceProjectBean implements Project {
+
+ @RolesAllowed({"committer"})
+ public String svnCommit(String s) {
+ return s;
+ }
+
+ public String svnCheckout(String s) {
+ return s;
+ }
+ }
+
+
+ - Allow only logged in users in the "committer" role to invoke
+'svnCommit'.
+ - Allow anyone logged in or not to invoke 'svnCheckout'.
+
+
+<a name="SecurityAnnotations-DeclareRoles"></a>
+## DeclareRoles
+
+You need to update the @DeclareRoles when referencing roles via
+isCallerInRole(roleName).
+
+
+ @Stateless
+ @DeclareRoles({"committer", "contributor"})
+ public class OpenSourceProjectBean implements Project {
+
+ @Resource SessionContext ctx;
+
+ @RolesAllowed({"committer"})
+ public String svnCommit(String s) {
+ ctx.isCallerInRole("committer"); // Referencing a Role
+ return s;
+ }
+
+ @RolesAllowed({"contributor"})
+ public String submitPatch(String s) {
+ return s;
+ }
+ }
+
+
+<a name="SecurityAnnotations-Restrictingallmethodsinaclass"></a>
+## Restricting all methods in a class
+
+Placing the annotation at the class level changes the default of PermitAll
+
+
+ @Stateless
+ @DeclareRoles({"committer"})
+ @RolesAllowed({"committer"})
+ public class OpenSourceProjectBean implements Project {
+
+ public String svnCommit(String s) {
+ return s;
+ }
+
+ public String svnCheckout(String s) {
+ return s;
+ }
+
+ public String submitPatch(String s) {
+ return s;
+ }
+ }
+
+
+- Allow only logged in users in the "committer" role to invoke 'svnCommit',
+'svnCheckout' or 'submitPatch'.
+
+<a name="SecurityAnnotations-Mixingclassandmethodlevelrestrictions"></a>
+## Mixing class and method level restrictions
+
+Security annotations can be used at the class level and method level at the
+same time. These rules do not stack, so marking 'submitPatch' overrides
+the default of "committers".
+
+
+ @Stateless
+ @DeclareRoles({"committer", "contributor"})
+ @RolesAllowed({"committer"})
+ public class OpenSourceProjectBean implements Project {
+
+ public String svnCommit(String s) {
+ return s;
+ }
+
+ public String svnCheckout(String s) {
+ return s;
+ }
+
+ @RolesAllowed({"contributor"})
+ public String submitPatch(String s) {
+ return s;
+ }
+ }
+
+
+ - Allow only logged in users in the "committer" role to invoke 'svnCommit'
+or 'svnCheckout'
+ - Allow only logged in users in the "contributor" role to invoke
+'submitPatch'.
+
+<a name="SecurityAnnotations-PermitAll"></a>
+## PermitAll
+
+When annotating a bean class with @RolesAllowed, the @PermitAll annotation
+becomes very useful on individual methods to open them back up again.
+
+
+ @Stateless
+ @DeclareRoles({"committer", "contributor"})
+ @RolesAllowed({"committer"})
+ public class OpenSourceProjectBean implements Project {
+
+ public String svnCommit(String s) {
+ return s;
+ }
+
+ @PermitAll
+ public String svnCheckout(String s) {
+ return s;
+ }
+
+ @RolesAllowed({"contributor"})
+ public String submitPatch(String s) {
+ return s;
+ }
+ }
+
+
+ - Allow only logged in users in the "committer" role to invoke
+'svnCommit'.
+ - Allow only logged in users in the "contributor" role to invoke
+'submitPatch'.
+ - Allow anyone logged in or not to invoke 'svnCheckout'.
+
+
+<a name="SecurityAnnotations-DenyAll"></a>
+## DenyAll
+
+The @DenyAll annotation can be used to restrict business interface access
+from anyone, logged in or not. The method is still invokable from within
+the bean class itself.
+
+
+ @Stateless
+ @DeclareRoles({"committer", "contributor"})
+ @RolesAllowed({"committer"})
+ public class OpenSourceProjectBean implements Project {
+
+ public String svnCommit(String s) {
+ return s;
+ }
+
+ @PermitAll
+ public String svnCheckout(String s) {
+ return s;
+ }
+
+ @RolesAllowed({"contributor"})
+ public String submitPatch(String s) {
+ return s;
+ }
+
+ @DenyAll
+ public String deleteProject(String s) {
+ return s;
+ }
+ }
+
+
+ - Allow only logged in users in the "committer" role to invoke
+'svnCommit'.
+ - Allow only logged in users in the "contributor" role to invoke
+'submitPatch'.
+ - Allow anyone logged in or not to invoke 'svnCheckout'.
+ - Allow *no one* logged in or not to invoke 'deleteProject'.
+
+<a name="SecurityAnnotations-IllegalUsage"></a>
+# Illegal Usage
+
+Generally, security restrictions cannot be made on AroundInvoke methods and
+most callbacks.
+
+The following usages of @RolesAllowed have no effect.
+
+
+ @Stateful
+ @DecalredRoles({"committer"})
+ public class MyStatefulBean implements MyBusinessInterface {
+
+ @PostConstruct
+ @RolesAllowed({"committer"})
+ public void constructed(){
+
+ }
+
+ @PreDestroy
+ @RolesAllowed({"committer"})
+ public void destroy(){
+
+ }
+
+ @AroundInvoke
+ @RolesAllowed({"committer"})
+ public Object invoke(InvocationContext invocationContext) throws
+Exception {
+ return invocationContext.proceed();
+ }
+
+ @PostActivate
+ @RolesAllowed({"committer"})
+ public void activated(){
+
+ }
+
+ @PrePassivate
+ @RolesAllowed({"committer"})
+ public void passivate(){
+
+ }
+ }
+
+
http://git-wip-us.apache.org/repos/asf/tomee/blob/f779264f/docs/security.mdtext
----------------------------------------------------------------------
diff --git a/docs/security.mdtext b/docs/security.mdtext
new file mode 100644
index 0000000..95fee1c
--- /dev/null
+++ b/docs/security.mdtext
@@ -0,0 +1,144 @@
+Title: Security
+<a name="Security-Security-HowTo."></a>
+# Security - How To.
+
+We currently have two authentication mechanisms to choose from:
+* *PropertiesLoginModule* (a basic text file based login that looks up
+users and groups from the specified properties files)
+* *SQLLoginModule* (database based login that looks up users and groups
+in a database through SQL queries)
+
+To make your program authenticate itself to the server, simply construct
+your InitialContext with the standard javax.naming.Context properties for
+user/pass info, which is:
+
+ Properties props = new Properties();
+ props.setProperty(Context.INITIAL_CONTEXT_FACTORY, "org.apache.openejb.client.RemoteInitialContextFactory");
+ props.setProperty(Context.PROVIDER_URL, "ejbd://localhost:4201");
+ props.setProperty(Context.SECURITY_PRINCIPAL, "someuser");
+ props.setProperty(Context.SECURITY_CREDENTIALS, "thepass");
+ props.setProperty("openejb.authentication.realmName", "PropertiesLogin");
+ // optional
+ InitialContext ctx = new InitialContext(props);
+ ctx.lookup(...);
+
+That will get you logged in and all your calls from that context should
+execute as you.
+
+*$\{openejb.base\}/conf/login.config* is a standard JAAS config file.
+Here, you can configure any number of security realms to authenticate
+against.
+To specify which of the realms you want to authenticate against, you can
+set the *openejb.authentication.realmName* property to any of the
+configured realm names in *login.config*.
+If you don't speficy a realm name, the default (currently
+*PropertiesLogin*) is used.
+For examples and more information on JAAS configuration, see the [JAAS Reference Guide](http://java.sun.com/javase/6/docs/technotes/guides/security/jaas/JAASRefGuide.html)
+.
+
+<a name="Security-PropertiesLoginModule"></a>
+## PropertiesLoginModule
+
+Supported options:
+<table>
+<tr><th>Option</th><th>Description</th><th>Required</th></tr>
+<tr><td>UsersFile</td><td>name of the properties file that contains the users and their
+passwords</td><td>*yes*</td></tr>
+<tr><td>GroupsFile</td><td>name of the properties file that contains the groups and their
+member lists</td><td>*yes*</td></tr>
+</table>
+
+*UsersFile* and *GroupsFile* are read in on every login, so +you can
+update them+ on a running system and those users will "show up" immediately
++without the need for a restart+ of any kind.
+
+<a name="Security-SQLLoginModule"></a>
+## SQLLoginModule
+
+You can either use a data source or configure the JDBC URL through which
+the user/group lookups will be made.
+
+If you use a *DataSource*, you must specify its JNDI name with the
+*dataSourceName* option.
+
+If you use JDBC directly, you have to specify at least the JDBC URL of the
+database.
+The driver should be autodetected (provided the appropriate jar is on your
+classpath), but if that fails for some reason, you can force a specific
+driver using the *jdbcDriver* option.
+For more information on JDBC URLs, see the [JDBC Guide](http://java.sun.com/javase/6/docs/technotes/guides/jdbc/)
+
+The *userSelect* query must return a two-column list of user names
+(column 1) and passwords (column 2). This query should normally return a
+single row, which can be achieved by the use of a query parameter
+placeholder "?".
+Any such placeholders in both queries will be filled in with the username
+that the client is trying to log in with.
+The *groupSelect* query must return a two-column list of user names and
+their groups (or "roles" in the EJB world).
+
+Supported options:
+<table>
+<tr><th>Option</th><th>Description</th><th>Required</th></tr>
+<tr><td>dataSourceName</td><td>the name of a data source</td><td>*yes* (alternative 1)</td></tr>
+<tr><td>jdbcURL</td><td>a standard JDBC URL</td><td>*yes* (alternative 2)</td></tr>
+<tr><td>jdbcDriver</td><td>the fully qualified class name of the database driver</td><td>no</td></tr>
+<tr><td>jdbcUser</td><td>the user name for accessing the database</td><td>no</td></tr>
+<tr><td>jdbcPassword</td><td>the password for accessing the database</td><td>no</td></tr>
+<tr><td>userSelect</td><td>the SQL query that returns a list of users and their
+passwords</td><td>*yes*
+</tr>
+<tr><td>groupSelect</td><td>the SQL query that returns a list of users and groups
+(roles)</td><td>*yes*
+</tr>
+<tr><td>digest</td><td>the name of the digest algorithm (e.g. "MD5" or "SHA") for digest
+authentication</td><td>no</td></tr>
+<tr><td>encoding</td><td>the digest encoding, can be "hex" or "base64"</td><td>no</td></tr>
+</table>
+
+<a name="Security-PLUGPOINTS"></a>
+# PLUG POINTS
+
+There are four-five different plug points where you could customize the
+functionality. From largest to smallest:
+- *The SecurityService interface*: As before all security work
+(authentication and authorization) is behind this interface, only the
+methods on it have been updated. If you want to do something really "out
+there" or need total control, this is where you go. Plugging in your own
+SecurityService should really be a last resort. We still have our "do
+nothing" SecurityService implementation just as before, but it is no longer
+the default. +You can add a new SecurityService impl by creating a
+service-jar.xml and packing it in your jar+. You can configure OpenEJB to
+use a different SecurityService via the openejb.xml.
+
+- *JaccProvider super class*: If you want to plug in your own JACC
+implementation to perform custom authorization (maybe do some fancy
+auditing), this is one way to do it without really having to understand
+JACC too much. We will plug your provider in to all the places required by
+JACC if you simply +set the system property+
+"*org.apache.openejb.core.security.JaccProvider*" with the name of your
+JaccProvider impl.
+
+- *Regular JACC*. The JaccProvider is simply a wrapper around the many
+things you have to do to create and plugin a JACC provider, but you can
+still plugin a JACC provider in the standard ways. Read the JACC spec for
+that info.
+
+- *JAAS LoginModule*. You can setup a different JAAS LoginModule to do all
+your authentication by simply editing the conf/login.config file which is a
+plain JAAS config file. At the moment we only support username/password
+based login modules. At some point it would be nice to support any kind of
+input for a JAAS LoginModule, but username/password at least covers the
+majority. It actually *is* possible to support any LoginModule, but you
+would have to supply your clients with your own way to authenticate to it
+and write a strategy for telling the OpenEJB client what data to send to
+the server with each invocation request. See the [JAAS LoginModule Developer's Guide](http://java.sun.com/javase/6/docs/technotes/guides/security/jaas/JAASLMDevGuide.html)
+ for more information.
+
+- *Client IdentityResolver*. This is the just mentioned interface you
+would have to implement to supply the OpenEJB client with alternate data to
+send to the server with each invocation request. If you're plugging in a
+new version of this it is likely that you may also want to plugin in your
+own SecurityService implementation. Reason being, the object returned from
+IdentiyResolve.getIdentity() is sent across the wire and straight in to the
+SecurityService.associate(Object) method.
http://git-wip-us.apache.org/repos/asf/tomee/blob/f779264f/docs/securityservice-config.mdtext
----------------------------------------------------------------------
diff --git a/docs/securityservice-config.mdtext b/docs/securityservice-config.mdtext
new file mode 100644
index 0000000..84c354c
--- /dev/null
+++ b/docs/securityservice-config.mdtext
@@ -0,0 +1,34 @@
+Title: SecurityService Configuration
+
+
+A SecurityService 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.
+
+ <SecurityService id="mySecurityService" type="SecurityService">
+ defaultUser = guest
+ </SecurityService>
+
+Alternatively, a SecurityService 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`
+
+ mySecurityService = new://SecurityService?type=SecurityService
+ mySecurityService.defaultUser = guest
+
+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 SecurityService a warning will be logged. If a SecurityService is needed by the application and one is not declared, TomEE will create one dynamically using default settings. Multiple SecurityService declarations are allowed.
+# Supported Properties
+<table>
+<tr>
+<th>Property</th>
+<th>Type</th>
+<th>Default</th>
+<th>Description</th>
+</tr>
+<tr>
+ <td>defaultUser</td>
+ <td>String</td>
+ <td>guest </td>
+ <td>
+
+</td>
+</tr>
+</table>
+
+
http://git-wip-us.apache.org/repos/asf/tomee/blob/f779264f/docs/service-locator.mdtext
----------------------------------------------------------------------
diff --git a/docs/service-locator.mdtext b/docs/service-locator.mdtext
new file mode 100644
index 0000000..b96344c
--- /dev/null
+++ b/docs/service-locator.mdtext
@@ -0,0 +1,169 @@
+Title: Service Locator
+The functionality of the [openejb.jndiname.format](jndi-names.html)
+ allows for writing some really fun service locator code. Creating the
+exact layout you want using the exact data you want means you can create
+robust libraries for pulling things out of JNDI.
+
+<a name="ServiceLocator-Lookupexamples"></a>
+# Lookup examples
+
+To get the creative juices flowing here are a few examples of lookup
+methods you could create for your service locator, the jndi name formats
+that would work with those lookups, and examples of client code using the
+service locator. For simplicity, we'll assume all the lookup examples
+start with this basic class that has a built-in lookup allowing for a
+common prefix to be optionally applied to the beginning of all lookup
+strings.
+
+ public class MyLocator {
+ private final Context context;
+
+ public MyLocator() throws NamingException {
+ this(null);
+ }
+
+ public MyLocator(String commonPrefix) throws NamingException {
+ Properties properties = new Properties();
+ properties.put(Context.INITIAL_CONTEXT_FACTORY, "org.apache.openejb.client.RemoteInitialContextFactory");
+ properties.put(Context.PROVIDER_URL, "ejbd://localhost:4201/");
+ this.context = new InitialContext(properties);
+ }
+
+ public Object lookup(String name) {
+ try {
+ if (commonPrefix != null) name = commonPrefix + "/" +name;
+ return context.lookup(name);
+ } catch (NamingException e) {
+ throw new IllegalArgumentException(e);
+ }
+ }
+ }
+
+
+<a name="ServiceLocator-Justtheinterface"></a>
+## Just the interface
+Usable with JNDI name formats ending in the full class name of the
+interface such as:
+ - \{interfaceClass}
+
+
+ public <T> T lookup(Class<T> type) {
+ return (T) lookup(type.getName());
+ }
+
+
+
+ MyLocator locator = new MyLocator();
+ Widget widget = locator.lookup(Widget.class);
+
+
+Or with a common prefix or with a common prefix supplied in constructor
+such as:
+ - \{moduleId}/\{interfaceClass}
+ - ejb/\{moduleId}/\{interfaceClass}
+
+
+ MyLocator locator = new MyLocator("ejb/superbiz");
+ Widget widget = locator.lookup(Widget.class);
+ Store store = locator.lookup(Store.class);
+
+
+
+<a name="ServiceLocator-Interfaceclassandaprefix"></a>
+## Interface class and a prefix
+
+Usable with JNDI name formats including a varying prefix such as ejbName or
+deploymentID
+and ending in the full class name of the interface
+
+ - \{ejbName}/\{interfaceClass}
+ - \{deploymentId}/\{interfaceClass}
+
+
+ public <T> T lookup(String prefix, Class<T> type) {
+ return (T) lookup(prefix + "/" + type.getName());
+ }
+
+
+
+ MyLocator locator = new MyLocator();
+ Widget redWidget = locator.lookup("RedWidgetBean", Widget.class);
+ Widget blueWidget = locator.lookup("BlueWidgetBean", Widget.class);
+
+
+Or with a common prefix or with a common prefix supplied in constructor
+such as:
+ - \{moduleId}/\{ejbName}/\{interfaceClass}
+ - ejb/\{moduleId}/\{deploymentId}/\{interfaceClass}
+
+
+ MyLocator locator = new MyLocator("accountingApp");
+ Widget widget = locator.lookup("RedWidgetBean", Widget.class);
+ Store store = locator.lookup("StoreBean", Store.class);
+
+
+<a name="ServiceLocator-Interfaceclassandejbclass"></a>
+## Interface class and ejb class
+
+Usable with JNDI name formats comprised of the interfaceClass and ejbClass
+
+For variation, the interface class is the prefix and the ejb class is the
+suffix. This is neat as the the prefix (the interface class name) becomes
+a jndi context with one binding in it for each implementing ejb class.
+
+Works with:
+ - \{interfaceClass}/\{ejbClass}
+
+
+ public <T> T lookup(Class<T> type, Class ejbClass) {
+ return (T) lookup(type.getName() + "/" + ejbClass.getName());
+ }
+
+
+
+ MyLocator locator = new MyLocator();
+ Widget widget = locator.lookup(Widget.class, BlueWidgetBean.class);
+
+
+Or with a common prefix or with a common prefix supplied in constructor
+such as:
+ - \{moduleId}/\{interfaceClass}/\{ejbClass}
+ - ejb/\{moduleId}/\{interfaceClass}/\{ejbClass}
+
+
+ MyLocator locator = new MyLocator("ejb/purchasingApp");
+ Widget widget = locator.lookup(Widget.class, RedWidgetBean.class);
+ Store store = locator.lookup(Store.class, StoreBean.class);
+
+
+
+<a name="ServiceLocator-Interfaceclassandejbclasswithsimplenames"></a>
+## Interface class and ejb class with simple names
+
+Similar to the above example but using the simple name of the classes
+resulting
+in a JNDI tree that's a bit more human readable.
+ - \{ejbClass.simpleName}/\{interfaceClass.simpleName}
+
+
+ public <T> T lookup(Class ejbClass, Class<T> type) {
+ return (T) lookup(ejbClass.getSimpleName() + "" + type.getSimpleName());
+ }
+
+and
+
+ MyLocator locator = new MyLocator();
+ Widget widget = locator.lookup(RedWidgetBean.class, Widget.class);
+
+
+Or with a common prefix or with a common prefix supplied in constructor
+such as:
+ - \{moduleId}/\{ejbClass.simpleName}/\{interfaceClass.simpleName}
+ - ejb/\{moduleId}/\{ejbClass.simpleName}/\{interfaceClass.simpleName}
+
+
+ MyLocator locator = new MyLocator("shippingApp");
+ Widget widget = locator.lookup(GreenWidgetBean.class, Widget.class);
+ Store store = locator.lookup(SuperStoreBean.class, Store.class);
+
+
http://git-wip-us.apache.org/repos/asf/tomee/blob/f779264f/docs/services.mdtext
----------------------------------------------------------------------
diff --git a/docs/services.mdtext b/docs/services.mdtext
new file mode 100644
index 0000000..5e3bc4b
--- /dev/null
+++ b/docs/services.mdtext
@@ -0,0 +1,16 @@
+Title: ServicePool and Services
+
+OpenEJB and TomEE services using ServicePool as wrapper - for instance ejbd service or all services not implementing SelfManaging interface - support some additional configuration due
+to the pooling. Here is the list of the additional properties (either configure them in the service configuration file in conf/conf.d/${service}.properties or in conf/system.properties prefixing them by “{service}.”).
+
+Basically using ServicePool the service is associated to a ThreadPoolExecutor and this one is configured with these properties (see ThreadPoolExecutor constructor for the detail):
+
+* threadsCore (default 10)
+* threads (default 150)
+* queue (default threadCore-1)
+* block (default true)
+* keepAliveTime (default 60000)
+
+Additionally you can force the socket to be closed after each request (this is an advanced setting, use it with caution):
+
+* forceSocketClose (default true)
http://git-wip-us.apache.org/repos/asf/tomee/blob/f779264f/docs/singleton-beans.mdtext
----------------------------------------------------------------------
diff --git a/docs/singleton-beans.mdtext b/docs/singleton-beans.mdtext
new file mode 100644
index 0000000..3cee7d2
--- /dev/null
+++ b/docs/singleton-beans.mdtext
@@ -0,0 +1,223 @@
+Title: Singleton Beans
+<a name="SingletonBeans-SingletonOverview"></a>
+# Singleton Overview
+For the first time in years EJB has a new bean type, the *@Singleton*. In
+my opinion, the javax.ejb.Singleton will replace a lot of what people are
+using @Stateless for today.
+
+The Singleton is essentially what you get if you take a Stateless bean and
+adjust the pool size to be exactly 1 resulting in there being exactly one
+instance of the Singleton bean in the application which can be invoked
+concurrently by multiple threads, like a servlet. It can do everything a
+Stateless can do such as support local and remote business interfaces, web
+services, security, transactions, and more. Additionally, the Singleton
+can have its @PostConstruct method called with the application starts up
+and its @PreDestroy method called when the application shuts down. This
+allows it to serve as an application lifecycle listener which is something
+only Servlets could do before. It has an *@Startup* annotation which is
+similar in concept to the servlet <load-on-startup>, but unlike servlets it
+doesn't take a number as an argument. Instead, you can use an *@DependsOn*
+annotation to say which other Singletons you need and the container will
+ensure they start before you.
+
+See the [Singleton Example](singleton-example.html)
+ for sample bean code and client.
+
+<a name="SingletonBeans-Concurrency"></a>
+## Concurrency
+
+Singletons support two modes of concurrent access, Container-Managed
+Concurrency (the default) and Bean-Managed Concurrency.
+
+<a name="SingletonBeans-Bean-ManagedConcurrency"></a>
+### Bean-Managed Concurrency
+
+With Bean-Managed Concurrency, annotated as *@ConcurrencyManagement(BEAN)*,
+the container sends all invocations into the bean and lets the Singleton
+bean instance decide how and when to synchronize access, if at all. Here
+the 'synchronization' keyword is allowed as well as the full
+javax.util.concurrent set of libraries.
+
+<a name="SingletonBeans-Container-ManagedConcurrency"></a>
+### Container-Managed Concurrency
+
+With Container-Managed Concurrency, annotated as
+*@ConcurrencyManagement(CONTAINER)*, the container will enforce concurrency
+for you via locking method access to the bean. Two modes, called locks
+exist and can be assigned to both the bean class and methods of the bean
+class.
+
+<a name="SingletonBeans-Locktype"></a>
+#### Lock type
+
+The first and the default is a "write" lock, annotated as *@Lock(WRITE)*.
+Essentially, with a write lock the caller holds an exclusive lock on the
+bean for the duration of the method call and all other threads for that or
+any other method must wait.
+
+The second option is a "read" lock, annotated as *@Lock(READ)*. The read
+lock allows full concurrent access to the methods (assuming no write locks
+are held). The default mode of "write" essentially makes your bean a
+single-threaded bean, which is very slow. The more conservative
+@Lock(WRITE) was chosen as the default as this is how all the other bean
+types work (only a single thread may access a bean instance at any given
+time). Those that are aware of how to handle concurrent access can easily
+put @Lock(READ) on their bean class, thus changing the default, and then
+@Lock(WRITE) on specific methods if needed.
+
+The locking modes of Container-Managed Concurrency map directly to the *[java.util.concurrent.ReadWriteLock](http://java.sun.com/j2se/1.5.0/docs/api/java/util/concurrent/locks/ReadWriteLock.html)
+* API which looks like this:
+
+ public interface ReadWriteLock {
+ /**
+ * Returns the lock used for reading.
+ *
+ * @return the lock used for reading.
+ */
+ Lock readLock();
+
+ /**
+ * Returns the lock used for writing.
+ *
+ * @return the lock used for writing.
+ */
+ Lock writeLock();
+ }
+
+
+Literally 100% of the Singleton locking we're talking about is taken from
+this interface and its javadoc is a great source of information. It's safe
+to imagine that under the covers the Singleton Container has an instance of
+ReadWriteLock which it uses to enforce the locking for all the Singleton
+bean's methods. Essentially:
+
+ - @Lock(READ) == theSingletonReadWriteLock.readLock().lock()
+ - @Lock(WRITE) == theSingletonReadWriteLock.writeLock().lock()
+
+The EJB container may use something other than ReadWriteLock but the
+semantics of a ReadWriteLock must be followed. Internally, we use an
+instance of [java.util.concurrent.ReentrantReadWriteLock](http://java.sun.com/j2se/1.5.0/docs/api/java/util/concurrent/locks/ReentrantReadWriteLock.html)
+ which supports correct memory synchronization, some reentrancy, lock
+downgrading, and [more|http://java.sun.com/j2se/1.5.0/docs/api/java/util/concurrent/locks/ReentrantReadWriteLock.html]
+.
+
+<a name="SingletonBeans-AcquiringtheLock"></a>
+#### Acquiring the Lock
+
+The *@AccessTimetout* annotation can configure how long a thread will wait
+to acquire the read or write lock. This annotation can be used on the bean
+class or individual methods. The annotation maps directly to the [java.util.concurrent.locks.Lock](http://java.sun.com/j2se/1.5.0/docs/api/java/util/concurrent/locks/Lock.html)
+ interface.
+
+ public interface Lock {
+
+ /**
+ * Blocks (potentially) forever
+ *
+ * @AccessTimout with a value of -1
+ */
+ void lock();
+
+ /**
+ * Non-blocking
+ *
+ * @AccessTimout with a value of 0
+ */
+ boolean tryLock();
+
+ /**
+ * Blocks (potentially) up to a limit
+ *
+ * @AccessTimout(30, TimeUnit.SECONDS)
+ */
+ boolean tryLock(long time, TimeUnit unit) throws InterruptedException;
+
+ }
+
+
+In the event it is not possible to acquire the lock a
+*javax.ejb.ConcurrentAccessException* or
+*javax.ejb.ConcurrentAccessTimeoutException* will be thrown.
+
+<a name="SingletonBeans-DefaultTimeout"></a>
+#### Default Timeout
+
+The default value of *@AccessTimeout* annotation is vendor specific. In
+OpenEJB it defaults to the value of the *AccessTimeout* property which can
+be configured in many different scopes. Here is the order of preference:
+
+1. bean-level in
+openejb-jar.xml/<openejb-jar>/<ejb-deployment>/<properties>
+1. jar-level in openejb-jar.xml/<openejb-jar>/<properties>
+1. container-level in openejb.xml/<openejb>/<Container>
+1. boot-level via InitialContext(Properties) or
+EJBContainer.createEjbContainer(Map<Object,Object>)
+1. system-level in System.getProperties()
+
+The value of the property can be phrased in plain english such as "1 hour
+and 23 minutes and 17 seconds" see [Configuring Durations](configuring-durations.html)
+ for details.
+
+<a name="SingletonBeans-StartupandStartupOrdering"></a>
+## Startup and Startup Ordering
+
+Singletons have an *@Startup* annotation which can be applied to the bean
+class. When used, the Container will instantiate the Singleton instance
+_eagerly_ when the application starts up, otherwise the Container will
+instantiate the Singleton instance _lazily_ when the bean is first
+accessed.
+
+If one Singleton refers to another Singleton in the @PostConstruct or
+@PreDestroy method, there must be some measure taken to ensure the other
+Singleton exists and is started. This sort of ordering is achieved with
+the *@DependsOn* annotation which can be used to list the names of
+Singleton beans that must be started before the Singleton bean using the
+annotation.
+
+
+ @DependsOn({"SingletonB", "SingletonC"})
+ @Singleton
+ public class SingletonA {
+
+ }
+
+
+Circular references are not supported. If BeanA uses @DependsOn to point
+to BeanB and BeanB also uses @DependsOn to point at BeanA, the result is a
+deployment exception. Be aware that circular references can happen in less
+trivial ways such as A referring to B which refers to C which refers to D
+which refers back to A. We will detect and print all circular dependencies
+(called circuits) at deploy time.
+
+Note that @DependsOn is only required (and should only be used) if a
+Singleton *uses* another Singleton in its @PostConstruct method or
+@PreDestroy method. Simply having a reference to another Singleton and
+using it in other business methods does not require an @DependsOn
+declaration. The @DependsOn allows the Container to calculate the correct
+startup order and shutdown order so that it can guarantee the Singletons
+you need are available in your @PostConstruct or @PreDestroy methods. All
+Singletons will automatically be available to your business methods
+regardless if @DependsOn is used. Because of the greater chance of
+creating circular dependencies, it is better not to use the @DependsOn
+annotation "just in case" and should only be used when truly needed.
+
+<a name="SingletonBeans-XMLandAnnotationOverriding"></a>
+# XML and Annotation Overriding
+
+Singletons can be declared in the ejb-jar.xml as follows:
+
+ <ejb-jar>
+ <enterprise-beans>
+ <session>
+ <ejb-name>MySingletonBean</ejb-name>
+ <ejb-class>org.superbiz.MySingletonBean</ejb-class>
+ <session-type>Singleton</session-type>
+ <load-on-startup/>
+ <depends-on>
+ <ejb-name>SingletonFoo</ejb-name>
+ <ejb-name>SingletonBar</ejb-name>
+ </depends-on>
+ </session>
+ </enterprise-beans>
+ </ejb-jar>
+
http://git-wip-us.apache.org/repos/asf/tomee/blob/f779264f/docs/singleton-ejb.mdtext
----------------------------------------------------------------------
diff --git a/docs/singleton-ejb.mdtext b/docs/singleton-ejb.mdtext
new file mode 100644
index 0000000..3297c07
--- /dev/null
+++ b/docs/singleton-ejb.mdtext
@@ -0,0 +1,2 @@
+Title: Singleton EJB
+{include:OPENEJBx30:Singleton Beans}
http://git-wip-us.apache.org/repos/asf/tomee/blob/f779264f/docs/singletoncontainer-config.mdtext
----------------------------------------------------------------------
diff --git a/docs/singletoncontainer-config.mdtext b/docs/singletoncontainer-config.mdtext
new file mode 100644
index 0000000..162ad2c
--- /dev/null
+++ b/docs/singletoncontainer-config.mdtext
@@ -0,0 +1,53 @@
+Title: SingletonContainer Configuration
+
+
+A SingletonContainer 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="mySingletonContainer" type="SINGLETON">
+ accessTimeout = 30 seconds
+ </Container>
+
+Alternatively, a SingletonContainer 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`
+
+ mySingletonContainer = new://Container?type=SINGLETON
+ mySingletonContainer.accessTimeout = 30 seconds
+
+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 SingletonContainer a warning will be logged. If a SingletonContainer is needed by the application and one is not declared, TomEE will create one dynamically using default settings. Multiple SingletonContainer declarations are allowed.
+# Supported Properties
+<table>
+<tr>
+<th>Property</th>
+<th>Type</th>
+<th>Default</th>
+<th>Description</th>
+</tr>
+<tr>
+ <td><a href="#accessTimeout">accessTimeout</a></td>
+ <td><a href="configuring-durations.html">time</a></td>
+ <td>30 seconds</td>
+ <td>
+Specifies the maximum time an invocation could wait for the
+`@Singleton` bean instance to become available before giving up.
+</td>
+</tr>
+</table>
+
+
+
+<a name="accessTimeout"></a>
+## accessTimeout
+
+Specifies the maximum time an invocation could wait for the
+`@Singleton` bean instance to become available before giving up.
+
+After the timeout is reached a `javax.ejb.ConcurrentAccessTimeoutException`
+will be thrown.
+
+Usable time units: nanoseconds, microsecons, milliseconds,
+seconds, minutes, hours, days. Or any combination such as
+`1 hour and 27 minutes and 10 seconds`
+
+Any usage of the `javax.ejb.AccessTimeout` annotation will
+override this setting for the bean or method where the
+annotation is used.
+
http://git-wip-us.apache.org/repos/asf/tomee/blob/f779264f/docs/spring-and-openejb-3.0.mdtext
----------------------------------------------------------------------
diff --git a/docs/spring-and-openejb-3.0.mdtext b/docs/spring-and-openejb-3.0.mdtext
new file mode 100644
index 0000000..6251937
--- /dev/null
+++ b/docs/spring-and-openejb-3.0.mdtext
@@ -0,0 +1,185 @@
+{note}OpenEJB 3.1 and later users should refer to the [Spring] page.{note}
+# Bootstrapping OpenEJB in Spring
+
+If you wish to use OpenEJB inside Spring you can do so pretty easily. Include OpenEJB and its dependencies in your classpath as you would in a plain embedded scenario then add a custom factory like the following:
+
+ public class OpenEjbFactoryBean implements org.springframework.beans.factory.FactoryBean {
+
+ private Properties properties = new Properties();
+
+ public OpenEjbFactoryBean() {
+ properties.put(Context.INITIAL_CONTEXT_FACTORY, "org.apache.openejb.client.LocalInitialContextFactory");
+ }
+
+ public Properties getJndiEnvironment() {
+ return properties;
+ }
+
+ public void setJndiEnvironment(Properties properties) {
+ this.properties.putAll(properties);
+ }
+
+ public Object getObject() {
+ try {
+ return new InitialContext(properties);
+ } catch (NamingException e) {
+ throw new RuntimeException(e);
+ }
+ }
+
+ public Class getObjectType(){
+ return Context.class;
+ }
+
+ boolean isSingleton() {
+ return true;
+ }
+ }
+
+And include that at the top of your spring xml file as follows:
+
+ <bean id="OpenEjbContext" class="org.acme.OpenEjbFactoryBean">
+ <property name="jndiEnvironment">
+ <props>
+ <prop key="myDs">new://Resource?type=DataSource</prop>
+ <prop key="myDs.JdbcDriver">com.mysql.jdbc.Driver</prop>
+ <prop key="myDs.JdbcUrl">jdbc:mysql://localhost/midastest?createDatabaseIfNotExist=true</prop>
+ <prop key="myDs.UserName">root</prop>
+ <prop key="myDs.Password"></prop>
+ </props>
+ </property>
+ </bean>
+
+The value of <props> is meant to be illustrative of the kinds of properties you can pass into OpenEJB. It's possible to create any number of datasources, topics, queues, containers and more this way.
+
+Just as with Unit Testing, OpenEJB will find and automatically deploy all the EJB beans it [finds in the classpath|Application discovery via the classpath]. You can then expose any of these things to other Spring components with custom factory beans.
+
+# Injecting OpenEJB-created resources into Spring components
+
+If you want to have any of the Topics, Queues, DataSources, EntityManagers or more that OpenEJB creates injected into components that Spring creates, here's one technique....
+
+Let's say you have a persistence unit called "*OrangeUnit*" declared in a persistence.xml file. One way to get the related *EntityManager* created by OpenEJB is to do as follows. Create an @Stateless bean with an @PersistenceContext ref in it, then use a factory bean to look it up, pull the EntityManager out and return it
+
+OrangeUnitBean.java
+
+ /*
+ * OpenEJB will automatically find this bean. Just put it in the same jar
+ * that your META-INF/persistence.xml file is located in and make sure that
+ * that same jar file also has a META-INF/ejb-jar.xml file. The ejb-jar.xml
+ * need only contain the text "<ejb-jar/>" at minimum.
+ */
+ @Stateless
+ public class OrangeUnitBean implements OrangeUnitLocal {
+
+ @PersistenceContext(unitName="OrangeUnit")
+ private EntityManager entityManager;
+
+ public EntityManager getEntityManager() {
+ return entityManager;
+ }
+ }
+
+OrangeUnitLocal.java
+
+ /**
+ * The local interface for the OrangeUnitBean
+ */
+ public interface OrangeUnitLocal {
+ public EntityManager getEntityManager();
+ }
+
+OrangeUnitFactoryBean.java
+
+ /**
+ * This factory bean will lookup the OrangeUnitBean using the javax.naming.Context
+ * that is created via the OpenEjbFactoryBean above. It will simply grab the EntityManager
+ * from that bean and hand it over to Spring. Anyone in Spring-land can then easily get
+ * a reference to the EntityManager by simply referencing this factory bean.
+ */
+ public class OrangeUnitFactoryBean implements org.springframework.beans.factory.FactoryBean {
+ private Context context;
+
+ public Context getContext() {
+ return context;
+ }
+
+ public void setContext(Context context) {
+ this.context = context;
+ }
+
+ public Object getObject() {
+ try {
+ ResourceLocal bean = (ResourceLocal) context.lookup("OrangeUnitBeanLocal");
+ return bean.getEntityManager();
+ } catch (NamingException e) {
+ throw new RuntimeException(e);
+ }
+ }
+
+ public Class getObjectType(){
+ return EntityManager.class;
+ }
+
+ boolean isSingleton() {
+ return true;
+ }
+ }
+
+The factory bean would then be declared in your spring xml file as follows:
+
+
+ <bean id="OrangeUnit" class="org.acme.OrangeUnitFactoryBean">
+ <property name="context" ref="OpenEjbContext">
+ </bean>
+
+The EntityManager can then easily be consumed by a spring bean.
+
+ public class SomePojo {
+
+ private EntityManager entityManager;
+
+ public void setEntityManager(EntityManager entityManager) {
+ this.entityManager = entityManager;
+ }
+
+ ...
+ }
+
+In the spring xml
+
+ <bean id="SomePojo" class="org.acme.SomePojo">
+ <property name="entityManager" ref="OrangeUnit">
+ </bean>
+
+Here's what all three declarations would look like together in your spring xml:
+
+Spring bean definitions combined
+
+ <bean id="OpenEjbContext" class="org.acme.OpenEjbFactoryBean">
+ <property name="jndiEnvironment">
+ <props>
+ <prop key="myDs">new://Resource?type=DataSource</prop>
+ <prop key="myDs.JdbcDriver">com.mysql.jdbc.Driver</prop>
+ <prop key="myDs.JdbcUrl">jdbc:mysql://localhost/midastest?createDatabaseIfNotExist=true</prop>
+ <prop key="myDs.UserName">root</prop>
+ <prop key="myDs.Password"></prop>
+ </props>
+ </property>
+ </bean>
+
+ <bean id="OrangeUnit" class="org.acme.OrangeUnitFactoryBean">
+ <property name="context" ref="OpenEjbContext">
+ </bean>
+
+ <bean id="SomePojo" class="org.acme.SomePojo">
+ <property name="entityManager" ref="OrangeUnit">
+ </bean>
+
+{info:title=Some more useful info.}
+Here is a bunch of links suggested by a user. If anybody has time to go through them and write a doc, that would be great. These links explain how to make available spring components to openejb
+http://twasink.net/blog/archives/2007/01/using_spring_wi.html
+http://static.springframework.org/spring/docs/2.5.x/api/org/springframework/ejb/interceptor/SpringBeanAutowiringInterceptor.html
+http://wiki.netbeans.org/MavenSpringEJBsOnGlassfish
+
+{info}
+
http://git-wip-us.apache.org/repos/asf/tomee/blob/f779264f/docs/spring-ejb-and-jpa.mdtext
----------------------------------------------------------------------
diff --git a/docs/spring-ejb-and-jpa.mdtext b/docs/spring-ejb-and-jpa.mdtext
new file mode 100644
index 0000000..eeb27e4
--- /dev/null
+++ b/docs/spring-ejb-and-jpa.mdtext
@@ -0,0 +1,170 @@
+Title: Spring EJB and JPA
+{note}OpenEJB 3.1 or later required{note}
+This example shows how to combine Spring, OpenEJB and Hibernate using the
+integration code provided by OpenEJB. Here, OpenEJB is used as an
+embeddable EJB container inside of Spring. See the [Spring](spring.html)
+ page for details.
+
+We use the basic Movie example and expand it to include more objects to
+demonstrate both Spring beans, EJB Session beans, and JPA persistent
+objects in one application. The premise of the example is a Cineplex that
+has a number of Theaters (viewing screens), each playing a number of
+Movies. The basic object layout is as follows:
+
+<table>
+<tr><th> Object </th><th> Type </th><th> Description </th></tr>
+<tr><td> [CineplexImpl](http://svn.apache.org/repos/asf/tomee/tomee/trunk/examples/spring-integration/src/main/java/org/superbiz/spring/CineplexImpl.java)
+ </td><td> @Stateless </td><td> Shows the use of @Resource to have Spring beans injected.
+Specifically, the _Theaters_ Spring bean </td></tr>
+<tr><td> [Theaters](http://svn.apache.org/repos/asf/tomee/tomee/trunk/examples/spring-integration/src/main/java/org/superbiz/spring/Theaters.java)
+ </td><td> Spring bean </td><td> Simple wrapper object injected into _CineplexImpl_ </td></tr>
+<tr><td> [Theater](http://svn.apache.org/repos/asf/tomee/tomee/trunk/examples/spring-integration/src/main/java/org/superbiz/spring/Theater.java)
+ </td><td> Spring bean </td><td> Shows that EJBs can be injected into Spring beans. Uses
+both the _Movies_ EJB and the _Movie_ JPA objects </td></tr>
+<tr><td> [MoviesImpl](http://svn.apache.org/repos/asf/tomee/tomee/trunk/examples/spring-integration/src/main/java/org/superbiz/spring/MoviesImpl.java)
+ </td><td> @Stateful </td><td> Wraps a JPA EntityManager and provides transactional access
+to the persistent _Movie_ objects </td></tr>
+<tr><td> [Movie](http://svn.apache.org/repos/asf/tomee/tomee/trunk/examples/spring-integration/src/main/java/org/superbiz/spring/Movie.java)
+ </td><td> @Entity </td><td> Basic JPA bean that is used both by Spring beans and EJBs.
+The same _Movie_ object as in all the other persistence related examples. </td></tr>
+<tr><td> [AvailableMovies](http://svn.apache.org/repos/asf/tomee/tomee/trunk/examples/spring-integration/src/main/java/org/superbiz/spring/AvailableMovies.java)
+ </td><td> Spring bean </td><td> Simple object used as a clever way to seed the
+EntityManager (and really, the database) with persistent _Movie_ objects </td></tr>
+</table>
+
+<a name="SpringEJBandJPA-Requiredjars"></a>
+# Required jars
+
+To setup the integration you'll need:
+
+1. The standard OpenEJB 3.1 libraries
+1. The [openejb-spring-3.1.jar](https://repository.apache.org/content/groups/public/org/apache/openejb/openejb-spring/3.1.2/openejb-spring-3.1.2.jar)
+ or later
+1. Spring 2.5 or other (any version should work)
+
+In Maven2 this can be done by adding the following dependencies to your
+pom.xml
+{snippet:id=required|url=openejb3/examples/spring-integration/pom.xml|lang=xml}
+For other environments, you can simply [download an openejb-3.1.zip](downloads.html)
+ or later and include all the jars under the lib/ directory in your
+classpath. Then download and add the [openejb-spring-3.1.jar|http://people.apache.org/repo/m2-ibiblio-rsync-repository/org/apache/openejb/openejb-spring/3.1/openejb-spring-3.1.jar]
+ along with your Spring jars.
+
+<a name="SpringEJBandJPA-TheSpringxml"></a>
+# The Spring xml
+
+Bootstrapping and Configuring OpenEJB is fairly simple.
+{snippet:id=bootstrapping|url=openejb3/examples/spring-integration/src/main/resources/movies.xml|lang=xml}
+As well, you can optionally declare any resources or containers. Anything
+declarable as a <Resource> or <Container> in the openejb.xml can instead be
+declared in the Spring xml file as shown here.
+{snippet:id=resources|url=openejb3/examples/spring-integration/src/main/resources/movies.xml|lang=xml}
+And finally our Spring beans.
+{snippet:id=pojos|url=openejb3/examples/spring-integration/src/main/resources/movies.xml|lang=xml}
+{note:title=Don't forget}
+{snippet:id=annotations|url=openejb3/examples/spring-integration/src/main/resources/movies.xml|lang=xml}
+It allows various annotations to be detected in bean classes: Spring's
+@Required and @Autowired, as well as JSR 250's @PostConstruct, @PreDestroy
+and @Resource (if available), JAX-WS's @WebServiceRef (if available),
+EJB3's @EJB (if available), and JPA's @PersistenceContext and
+@PersistenceUnit (if available). Alternatively, you may choose to activate
+the individual BeanPostProcessors for those annotations.
+{note}
+
+<a name="SpringEJBandJPA-TheCode"></a>
+# The Code
+
+In efforts to keep the example page somewhat short, we'll show just three
+beans, each demonstrating a particular relationship.
+
+The first is the CineplexImpl EJB which shows EJB \-> Spring.
+{snippet:id=code|url=openejb3/examples/spring-integration/src/main/java/org/superbiz/spring/CineplexImpl.java|lang=java}
+
+The second is the Theater Spring bean which shows Spring \-> EJB.
+{snippet:id=code|url=openejb3/examples/spring-integration/src/main/java/org/superbiz/spring/Theater.java|lang=java}
+
+The last is the AvailableMovies Spring bean which Shows Spring \-> EJB \->
+JPA
+{snippet:id=code|url=openejb3/examples/spring-integration/src/main/java/org/superbiz/spring/AvailableMovies.java|lang=java}
+
+<a name="SpringEJBandJPA-TheTestCase"></a>
+# The TestCase
+
+The JUnit TestCase uses a ClassPathXmlApplicationContext to load the Spring
+ApplicationContext. Anything that loads your Spring xml file should work
+fine. The following code would work a plain java app as well.
+
+{snippet:id=code|url=openejb3/examples/spring-integration/src/test/java/org/superbiz/spring/MoviesTest.java|lang=java}
+
+<a name="SpringEJBandJPA-Running"></a>
+# Running
+
+The source for this example can be downloaded from svn via:
+
+$ svn co [http://svn.apache.org/repos/asf/tomee/tomee/trunk/examples/spring-integration](http://svn.apache.org/repos/asf/tomee/tomee/trunk/examples/spring-integration)
+
+Then, in the "spring-integration" directory, run:
+
+$ mvn clean install
+
+Which should create output like the following.
+
+
+ -------------------------------------------------------
+ T E S T S
+ -------------------------------------------------------
+ Running org.superbiz.spring.MoviesTest
+ log4j:WARN No appenders could be found for logger
+(org.springframework.context.support.ClassPathXmlApplicationContext).
+ log4j:WARN Please initialize the log4j system properly.
+ Apache OpenEJB 3.1 build: 20081009-03:31
+ http://tomee.apache.org/
+ INFO - openejb.home =
+/Users/dblevins/work/openejb3/examples/spring-integration
+ INFO - openejb.base =
+/Users/dblevins/work/openejb3/examples/spring-integration
+ INFO - Configuring Service(id=Default JDK 1.3 ProxyFactory,
+type=ProxyFactory, provider-id=Default JDK 1.3 ProxyFactory)
+ INFO - Configuring Service(id=MovieDatabase, type=Resource,
+provider-id=Default JDBC Database)
+ INFO - Configuring Service(id=MovieDatabaseUnmanaged, type=Resource,
+provider-id=Default JDBC Database)
+ INFO - Found EjbModule in classpath:
+/Users/dblevins/work/openejb3/examples/spring-integration/target/classes
+ INFO - Beginning load:
+/Users/dblevins/work/openejb3/examples/spring-integration/target/classes
+ INFO - Configuring enterprise application: classpath.ear
+ INFO - Configuring Service(id=Default Stateless Container, type=Container,
+provider-id=Default Stateless Container)
+ INFO - Auto-creating a container for bean CineplexImpl:
+Container(type=STATELESS, id=Default Stateless Container)
+ INFO - Auto-linking resource-ref
+'org.superbiz.spring.CineplexImpl/theaters' in bean CineplexImpl to
+Resource(id=theaters)
+ INFO - Configuring Service(id=Default Stateful Container, type=Container,
+provider-id=Default Stateful Container)
+ INFO - Auto-creating a container for bean Movies: Container(type=STATEFUL,
+id=Default Stateful Container)
+ INFO - Configuring PersistenceUnit(name=movie-unit,
+provider=org.hibernate.ejb.HibernatePersistence)
+ INFO - Enterprise application "classpath.ear" loaded.
+ INFO - Assembling app: classpath.ear
+ INFO - PersistenceUnit(name=movie-unit,
+provider=org.hibernate.ejb.HibernatePersistence)
+ INFO - Jndi(name=CineplexImplLocal) --> Ejb(deployment-id=CineplexImpl)
+ INFO - Jndi(name=MoviesLocal) --> Ejb(deployment-id=Movies)
+ INFO - Created Ejb(deployment-id=Movies, ejb-name=Movies, container=Default
+Stateful Container)
+ INFO - Created Ejb(deployment-id=CineplexImpl, ejb-name=CineplexImpl,
+container=Default Stateless Container)
+ INFO - Deployed Application(path=classpath.ear)
+ INFO - Exported EJB Movies with interface org.superbiz.spring.Movies to
+Spring bean MoviesLocal
+ INFO - Exported EJB CineplexImpl with interface
+org.superbiz.spring.Cineplex to Spring bean CineplexImplLocal
+ Tests run: 1, Failures: 0, Errors: 0, Skipped: 0, Time elapsed: 3.141 sec
+
+ Results :
+
+ Tests run: 1, Failures: 0, Errors: 0, Skipped: 0
+
http://git-wip-us.apache.org/repos/asf/tomee/blob/f779264f/docs/spring.mdtext
----------------------------------------------------------------------
diff --git a/docs/spring.mdtext b/docs/spring.mdtext
new file mode 100644
index 0000000..e6bc4c7
--- /dev/null
+++ b/docs/spring.mdtext
@@ -0,0 +1,121 @@
+Title: Spring
+{note}
+This document and the related feature is considered a prototype and will
+change based on user feedback. All comments suggestions welcome.
+{note}
+
+<a name="Spring-Introduction"></a>
+# Introduction
+
+The OpenEJB Spring integration makes all Spring defined beans injectable to
+Java EE components, and all Java EE components can be injected to Spring beans.
+The injection system supports arbitrarily complex nesting (e.g., Spring
+bean injected into a Java EE component, which is then injected into another
+Spring bean), including:
+
+ * @Resouce injection of any Spring bean into EJB
+ * Injection of any Java EE resource into a Spring bean, including:
+ ** EJB 3.0 beans
+ ** EJB 3.1 Singleton Bean
+ ** JDBC Connector
+ ** JMS Connector
+ ** JMS Queue and Topic
+ ** Generic Java EE Connector (JCA)
+
+In addition, the OpenEJB Spring integration add support for discovery and
+deployment of standard Java EE packages within a Spring context, including:
+
+ * EAR
+ * EJB Jar
+ * Persistence Unit
+ * RAR
+
+*Requirements:*
+ * OpenEJB 3.1+
+ * Spring X.X
+ * Java 1.5 or 1.6
+
+<a name="Spring-SpringBeans"></a>
+# Spring Beans
+
+The following beans are usable in any spring xml file.
+
+<table>
+<tr><th> Class </th><th> Description </th></tr>
+<tr><td> org.apache.openejb.spring.ClassPathApplication </td><td> Scrapes the classpath
+for all EJB, RAR, and Persistence applications, deploys them, and imports
+them into the current ApplicationContext. All applications found are
+treated as one big EAR unless the _classpathAsEar_ property is set to
+_false_ </td></tr>
+<tr><td> org.apache.openejb.spring.Application </td><td> Scrapes an individual jar file
+for EJB, RAR, and Persistence applications, deploys them, and imports them
+into the current ApplicationContext. The 'jarFile' property is required.
+The application is treated as it's own self-contained EAR, separate from
+other uses of 'Application' </td></tr>
+<tr><td> org.apache.openejb.spring.Resource </td><td> Allows an OpenEJB <Resource> to be
+declared in the Spring ApplicationContext </td></tr>
+<tr><td> org.apache.openejb.spring.OpenEJBResource </td><td> A FactoryBean that imports a
+Resource from OpenEJB into the Spring ApplicationContext. Has the
+following properties: _type_ such as javax.sql.DataSource, and
+_resourceId_. In the future this bean will not be required and all OpenEJB
+Resources will automatically be imported into the Spring ApplicationContext
+</td></tr>
+<tr><td> org.apache.openejb.spring.BmpContainer </td><td> Allows an OpenEJB BMP
+<Container> to be declared in the Spring ApplicationContext. Has the
+following properties: _poolSize_ </td></tr>
+<tr><td> org.apache.openejb.spring.CmpContainer </td><td> Allows an OpenEJB CMP
+<Container> to be declared in the Spring ApplicationContext. </td></tr>
+<tr><td> org.apache.openejb.spring.SingletonContainer </td><td> Allows an OpenEJB
+Singleton <Container> to be declared in the Spring ApplicationContext. Has
+the following properties: _accessTimeout_ </td></tr>
+<tr><td> org.apache.openejb.spring.StatefulContainer </td><td> Allows an OpenEJB Stateful
+<Container> to be declared in the Spring ApplicationContext. Has the
+following properties: _timeOut_</td></tr>
+<tr><td> org.apache.openejb.spring.StatelessContainer </td><td> Allows an OpenEJB Stateful
+<Container> to be declared in the Spring ApplicationContext. Has the
+following properties: _timeOut_, _poolSize_, and _strictPooling_ </td></tr>
+<tr><td> org.apache.openejb.spring.MdbContainer </td><td> Allows an OpenEJB Message-Driven
+<Container> to be declared in the Spring ApplicationContext. Has the
+following properties: _resourceAdapter_, _messageListenerInterface_,
+_activationSpecClass_, and _instanceLimit_ </td></tr>
+<tr><td> org.apache.openejb.spring.EJB </td><td> A FactoryBean that imports an EJB from
+OpenEJB into the Spring ApplicationContext. One of these is automatically
+created for each interface of each EJB, but explicit use can be nice if you
+desire to import an EJB with a specific name. Has the following
+properties: _deploymentId_, _interface_ </td></tr>
+</table>
+
+<a name="Spring-Examples"></a>
+# Examples
+
+See the [Spring EJB and JPA](spring-ejb-and-jpa.html)
+ page for example code and a working Spring xml file.
+
+<a name="Spring-{anchor:problems}Problems?"></a>
+# {anchor:problems} Problems?
+
+If you are having problems with the installation, please send a message to
+the OpenEJB users [mailing list](mailing-lists.html)
+ containing any error message(s) and the following information:
+
+* OpenEJB Version
+* Spring Version
+* Java Version (execute java -version)
+* Operating System Type and Version
+
+<a name="Spring-Limitations"></a>
+# Limitations
+
+ *JavaAgent* - OpenEJB uses OpenJPA to provide JPA and CMP persistence, and
+OpenJPA currently requires a JavaAgent to function properly in a Java 1.5
+environment. OpenJPA does not require a JavaAgent in Java 1.6. Use
+Hibernate as your the provider in your persistence.xml files if you wish to
+avoid this requirement.
+
+ *EntityManager* - Having an OpenEJB created EntityManager or
+EntityManagerFactory injected into Spring beans is currently not supported.
+ This will be added to the next release. A small workaround for this is to
+use an EJB as a factory by adding a 'getEntityManager' method an using it
+as a [Spring instance factory method](http://static.springframework.org/spring/docs/2.5.x/reference/beans.html#beans-factory-class-instance-factory-method)
+.
+
http://git-wip-us.apache.org/repos/asf/tomee/blob/f779264f/docs/ssh.mdtext
----------------------------------------------------------------------
diff --git a/docs/ssh.mdtext b/docs/ssh.mdtext
new file mode 100644
index 0000000..998ad1b
--- /dev/null
+++ b/docs/ssh.mdtext
@@ -0,0 +1,48 @@
+Title: SSH
+
+# Connecting To OpenEJB or TomEE Through SSH
+## Description
+
+It can be very useful to connect to the server to get some informations.
+
+## Solution
+
+For such a case OpenEJB/TomEE proposes to start with the Java EE server a SSH server. Currently the security
+is based on JAAS (see how to configure JAAS for TomEE for more information about it).
+
+## Installation
+
+Simply extract the openejb-ssh jar in the lib of tomee (webapps/tomee/lib) or openejb libs (lib folder).
+Then simply connect using your JAAS credential.
+
+Note: you can use the provisioning features of openejb to do this job!
+
+Then simply activate the service manage: it is done setting the system property
+openejb.servicemanager.enabled to true.
+
+Note: it can be done through the conf/system.properties file.
+Note2: please take care to not add space after true (not 'true ' for instance).
+
+## OpenEJB SSH Shell
+
+Once you are connected you get some commands:
+
+* deploy <path>: deploy an application
+* undeploy <path>: undeploy an application
+* list: list deployed EJBs
+* classloader <app id>: print the classloader tree of the app specified by the id
+* jmx <operation> <options>: interact with JMX
+** jmx list: list mbeans
+** jmx get <attribute> <objectname>
+** jmx set <attribute> <objectname> <new value>
+** jmx invoke <methodname>([<arg1>, ...) <objectname>
+* properties: print server configuration as properties
+* script <language> <script code>: execute the following script code using the following language with the JSR 223
+* script file <script file>: execute the following script using the language (from the extension of the file) with the JSR 223
+* ls [<path>]: list the file in path is specified or in the base of the server if not
+* cat <path>: print a file
+* part <start>-<end> <path>: print the part of a file
+
+Note1: JSR 223 can need to add some jar to openejb/tomee lib folder (groovy-all for instance to use groovy)
+Note2: ls, part, cat commands have to use $home and $base properties to specified the path
+
http://git-wip-us.apache.org/repos/asf/tomee/blob/f779264f/docs/standalone-server.mdtext
----------------------------------------------------------------------
diff --git a/docs/standalone-server.mdtext b/docs/standalone-server.mdtext
new file mode 100644
index 0000000..4eee836
--- /dev/null
+++ b/docs/standalone-server.mdtext
@@ -0,0 +1,23 @@
+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.
+
+#Links to guide you through OpenEJB-Standalone-Server
+
+- [Startup](startup.html)
+- [Deploy Tool](deploy-tool.html)
+- [Properties Tool](properties-tool.html)
http://git-wip-us.apache.org/repos/asf/tomee/blob/f779264f/docs/startup.mdtext
----------------------------------------------------------------------
diff --git a/docs/startup.mdtext b/docs/startup.mdtext
new file mode 100644
index 0000000..a258232
--- /dev/null
+++ b/docs/startup.mdtext
@@ -0,0 +1,293 @@
+Title: Startup
+<a name="Startup-NAME"></a>
+# NAME
+
+openejb start - OpenEJB Remote Server
+
+<a name="Startup-SYNOPSIS"></a>
+# SYNOPSIS
+
+openejb start [#options](#options.html)
+
+<a name="Startup-NOTE"></a>
+# NOTE
+
+The OpenEJB Remote Server can be started by running the openejb.bat script
+for windows and the openejb script for Linux and other Unix based OSes.
+Before running these scripts you need to set the environment variable
+_OPENEJB_HOME_ to the path of the directory where you unpacked the OpenEJB
+installation.
+
+From now on we will refer to this directory as <OPENEJB_HOME> and assume
+that you unpacked OpenEJB into the directory *C:\openejb-3.0* The startup
+scripts are present in the <OPENEJB_HOME>/bin directory. You can set this
+directory in the system _PATH_ for starting openejb from the command shell.
+
+In Windows, the remote server can be executed as follows:
+
+*C:\openejb-3.0> bin\openejb start*
+
+In UNIX, Linux, or Mac OS X, the deploy tool can be executed as follows:
+
+`\[user@host openejb-3.0](user@host-openejb-3.0.html)
+# ./bin/openejb start`
+
+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.0](user@host-openejb-3.0.html)
+# 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 start -help*
+
+<a name="Startup-DESCRIPTION"></a>
+# DESCRIPTION
+
+Starts OpenEJB as an EJB Server that can be accessed by remote clients via
+the OpenEJB Remote Server.
+
+ALWAYS check your openejb.log file for warnings immediately after starting
+the Remote Server.
+
+OpenEJB issues warnings when it works around a potential problem,
+encounters something it didn't expect, or when OpenEJB wants to let you
+know something may not work as you expected it.
+
+OpenEJB itself is configured with the OpenEJB configuration file, which is
+extremely simple and self-documenting. This file is located at
+c:\openejb-3.0\conf\openejb.xml.
+
+<a name="Startup-OPTIONS"></a>
+# OPTIONS
+
+ | _-D<name>=<value>_ | Specifies a system property passed
+into OpenEJB at startup. |
+ | _--admin-bind <host>_ | Sets the host to which the admin
+service should be bound.|
+ | _--admin-port <int>_ | Sets the port to which the admin
+service should be bound.|
+ | _--conf <file>_ | Sets the OpenEJB configuration to
+the specified file. |
+ | _--ejbd-bind <host>_ | Sets the host to which the ejbd
+service should be bound. |
+ | _--ejbd-port <int>_ | Sets the port to which the ejbd
+service should be bound. |
+ | _--examples_ | Show examples of how to use the
+options. |
+ | -h, --_help_ | Print this help message. |
+ | _--hsql-bind <host>_ | Sets the host to which the hsql
+service should be bound.|
+ | _--hsql-port <int>_ | Sets the port to which the hsql
+service should be bound.|
+ | _--httpejbd-bind <host>_ | Sets the host to which the httpejbd
+service should be bound.|
+ | _--httpejbd-port <int>_ | Sets the port to which the httpejbd
+service should be bound.|
+ | _--local-copy <boolean>_ | Instructs the container system to
+marshal (ie, copy) all calls between beans. |
+ | _--telnet-bind <host>_ | Sets the host to which the telnet
+service should be bound.|
+ | _--telnet-port <int>_ | Sets the port to which the telnet
+service should be bound.|
+ | -v, --_version_ | Print the version. |
+
+<a name="Startup-EXAMPLES"></a>
+# EXAMPLES
+
+<a name="Startup-Example:Simplestscenario"></a>
+## Example: Simplest scenario
+
+*openejb start*
+
+That's it. The ejbd will start up and bind to IP 127.0.0.1 and port 4201.
+
+The following properties would then be used to get an InitialContext from
+the Remote Server.
+
+
+ java.naming.factory.initial =
+org.apache.openejb.client.RemoteInitialContextFactory
+ java.naming.provider.url = ejbd://127.0.0.1:4201
+ java.naming.security.principal = myuser
+ java.naming.security.credentials = mypass
+
+
+<a name="Startup-Example:--conf=file"></a>
+## Example: --conf=file
+
+*openejb start --conf=C:\openejb-3.0\conf\mytest.conf*
+
+ Sets the openejb.configuration system variable to the file
+*C:\openejb\conf\mytest.conf*. When the server starts up and initializes
+OpenEJB, this configuration will be used to assemble the container system
+and load beans.
+
+<a name="Startup-Example:--local-copy"></a>
+## Example: --local-copy
+
+The local-copy option controls whether Remote interface arguments and
+results are always copied.
+
+*openejb start --local-copy=true* (default)
+
+Remote interface business method arguments and results are always copied
+(via serialization), which is compliant with the EJB standard.
+
+*openejb start --local-copy=false*
+
+Remote interface business method arguments and results are copied only when
+the client is in a different JVM. Otherwise, they are passed by reference -
+as if it were a Local interface. This is faster, of course, but
+non-compliant with the EJB standard.
+
+Local interfaces are not affected; their arguments and results are passed
+by reference and never copied.
+
+<a name="Startup-CONFIGOVERRIDEEXAMPLES"></a>
+## CONFIG OVERRIDE EXAMPLES
+
+<a name="Startup-Example:-D<service>.bind=<address>"></a>
+## Example: -D<service>.bind=<address>
+
+ *openejb start -Dejbd.bind=10.45.67.8*
+
+ This is the most common way to use the EJBd Server Service. The service
+will start up and bind to IP 10.45.67.8 and port 4201. The following
+properties would then be used to get an InitialContext from the EJBd Server
+Service.
+
+
+ java.naming.factory.initial =
+org.apache.openejb.client.RemoteInitialContextFactory
+ java.naming.provider.url = ejbd://10.45.67.8:4201
+ java.naming.security.principal = myuser
+ java.naming.security.credentials = mypass
+
+
+ DNS names can also be used.
+
+ *openejb start -Dejbd.bind=myhost.foo.com*
+
+ The following properties would then be used to get an InitialContext from
+the Remote Server.
+
+
+ java.naming.factory.initial =
+org.apache.openejb.client.RemoteInitialContextFactory
+ java.naming.provider.url = ejbd://myhost.foo.com:4201
+ java.naming.security.principal = myuser
+ java.naming.security.credentials = mypass
+
+
+ *openejb start -Dtelnet.bind=myhost.foo.com*
+
+ The following properties would then be used to log into the server via a
+telnet client as such:
+
+ *telnet myhost.foo.com 4202*
+
+
+<a name="Startup-Example:-D<service>.port=<port>"></a>
+## Example: -D<service>.port=<port>
+
+ *openejb start -Dejbd.port=8765*
+
+ The server will start up and bind to IP 127.0.0.1 and port 8765.
+
+ The following properties would then be used to get an InitialContext from
+the Remote Server.
+
+
+ java.naming.factory.initial =
+org.apache.openejb.client.RemoteInitialContextFactory
+ java.naming.provider.url = ejbd://127.0.0.1:8765
+ java.naming.security.principal = myuser
+ java.naming.security.credentials = mypass
+
+
+ *openejb start -Dhttpejbd.port=8888*
+
+ The server will start up and the EJB over HTTP service will bind to IP
+127.0.0.1 and port 8888.
+
+ The following properties would then be used to get an InitialContext from
+the HTTP/Remote Server.
+
+
+ java.naming.factory.initial =
+org.apache.openejb.client.RemoteInitialContextFactory
+ java.naming.provider.url = http://127.0.0.1:8888/openejb
+ java.naming.security.principal = myuser
+ java.naming.security.credentials = mypass
+
+
+<a name="Startup-Example:-D<service>.only_from=<addresses>"></a>
+## Example: -D<service>.only_from=<addresses>
+
+ *openejb start -Dadmin.only_from=192.168.1.12*
+
+ Adds 192.168.1.12 to the list of IP addresses that are authorized to
+shutdown the server or access the server
+ via a telnet client. The host that this server was started on is always
+allowed to administer the server.
+
+ Multiple hosts can be given administrative access to this server by
+listing all the host names separated
+ by commas as such:
+
+ *openejb start -Dadmin.only_from=192.168.1.12,joe.foo.com,robert*
+
+ The first host in the string names the host explicitly using an IP address
+(192.168.1.12).
+
+ The second host uses a DNS name (joe.foo.com) to refer to the hosts IP
+address. The DNS name will be resolved and the IP will be added to the
+admin list.
+
+ The third address refers to a the host by a name (robert)that the
+opperating system is able to resolve into a valid IP address. This is
+usually done via a hosts file, interal DNS server, or Windows Domain
+Server.
+
+<a name="Startup-Example:-D<service>.threads=<max>"></a>
+## Example: -D<service>.threads=<max>
+
+ *openejb start -Dejbd.threads=200*
+
+ Sets the max number of concurrent threads that can enter the EJBd Server
+Service to 200.
+
+<a name="Startup-Example:-D<service>.disabled=<true/false>"></a>
+## Example: -D<service>.disabled=<true/false>
+
+ *openejb start -Dtelnet.disabled=true*
+
+ Prevents the Telnet Server Service from starting when the OpenEJB Server
+starts.
+
+<a name="Startup-CONSOLEOUTPUT"></a>
+# CONSOLE OUTPUT
+
+Once you start OpenEJB using the *openejb start* command the following
+output will be seen on the console
+
+
+ Apache OpenEJB 3.0 build: 20070825-01:10
+ http://tomee.apache.org/
+ OpenEJB ready.
+ [OPENEJB:init]
+ OpenEJB Remote Server
+ ** Starting Services **
+ NAME IP PORT
+ httpejbd 0.0.0.0 4204
+ telnet 0.0.0.0 4202
+ ejbd 0.0.0.0 4201
+ hsql 0.0.0.0 9001
+ admin thread 0.0.0.0 4200
+ -------
+ Ready!
+
http://git-wip-us.apache.org/repos/asf/tomee/blob/f779264f/docs/statefulcontainer-config.mdtext
----------------------------------------------------------------------
diff --git a/docs/statefulcontainer-config.mdtext b/docs/statefulcontainer-config.mdtext
new file mode 100644
index 0000000..d823619
--- /dev/null
+++ b/docs/statefulcontainer-config.mdtext
@@ -0,0 +1,157 @@
+Title: StatefulContainer Configuration
+
+
+A StatefulContainer 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="myStatefulContainer" type="STATEFUL">
+ accessTimeout = 30 seconds
+ bulkPassivate = 100
+ cache = org.apache.openejb.core.stateful.SimpleCache
+ capacity = 1000
+ frequency = 60
+ passivator = org.apache.openejb.core.stateful.SimplePassivater
+ timeOut = 20
+ </Container>
+
+Alternatively, a StatefulContainer 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`
+
+ myStatefulContainer = new://Container?type=STATEFUL
+ myStatefulContainer.accessTimeout = 30 seconds
+ myStatefulContainer.bulkPassivate = 100
+ myStatefulContainer.cache = org.apache.openejb.core.stateful.SimpleCache
+ myStatefulContainer.capacity = 1000
+ myStatefulContainer.frequency = 60
+ myStatefulContainer.passivator = org.apache.openejb.core.stateful.SimplePassivater
+ myStatefulContainer.timeOut = 20
+
+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 StatefulContainer a warning will be logged. If a StatefulContainer is needed by the application and one is not declared, TomEE will create one dynamically using default settings. Multiple StatefulContainer declarations are allowed.
+# Supported Properties
+<table>
+<tr>
+<th>Property</th>
+<th>Type</th>
+<th>Default</th>
+<th>Description</th>
+</tr>
+<tr>
+ <td><a href="#accessTimeout">accessTimeout</a></td>
+ <td><a href="configuring-durations.html">time</a></td>
+ <td>30 seconds</td>
+ <td>
+Specifies the maximum time an invocation could wait for the
+`@Stateful` bean instance to become available before giving up.
+</td>
+</tr>
+<tr>
+ <td>bulkPassivate</td>
+ <td>int</td>
+ <td>100</td>
+ <td>
+Property name that specifies the number of instances
+to passivate at one time when doing bulk passivation.
+</td>
+</tr>
+<tr>
+ <td>cache</td>
+ <td>String</td>
+ <td>org.apache.openejb.core.stateful.SimpleCache</td>
+ <td>
+The cache is responsible for managing stateful bean
+instances. The cache can page instances to disk as memory
+is filled and can destroy abandoned instances. A different
+cache implementation can be used by setting this property
+to the fully qualified class name of the Cache implementation.
+</td>
+</tr>
+<tr>
+ <td>capacity</td>
+ <td>int</td>
+ <td>1000</td>
+ <td>
+Specifies the size of the bean pools for this
+stateful SessionBean container.
+</td>
+</tr>
+<tr>
+ <td>frequency</td>
+ <td>int</td>
+ <td>60</td>
+ <td>
+Specifies the frequency (in seconds) at which the bean cache is checked for
+idle beans.
+</td>
+</tr>
+<tr>
+ <td><a href="#passivator">passivator</a></td>
+ <td>String</td>
+ <td>org.apache.openejb.core.stateful.SimplePassivater</td>
+ <td>
+The passivator is responsible for writing beans to disk
+at passivation time. Different passivators can be used
+by setting this property to the fully qualified class name
+of the `PassivationStrategy` implementation. The passivator
+is not responsible for invoking any callbacks or other
+processing, its only responsibly is to write the bean state
+to disk.
+</td>
+</tr>
+<tr>
+ <td><a href="#timeOut">timeOut</a></td>
+ <td><a href="configuring-durations.html">time</a></td>
+ <td>20</td>
+ <td>
+Specifies the time a bean can be idle before it is removed by the container.
+</td>
+</tr>
+</table>
+
+
+
+<a name="accessTimeout"></a>
+## accessTimeout
+
+Specifies the maximum time an invocation could wait for the
+`@Stateful` bean instance to become available before giving up.
+
+After the timeout is reached a `javax.ejb.ConcurrentAccessTimeoutException`
+will be thrown.
+
+Usable time units: nanoseconds, microsecons, milliseconds,
+seconds, minutes, hours, days. Or any combination such as
+"1 hour and 27 minutes and 10 seconds"
+
+Any usage of the `javax.ejb.AccessTimeout` annotation will
+override this setting for the bean or method where the
+annotation is used.
+
+
+<a name="passivator"></a>
+## passivator
+
+The passivator is responsible for writing beans to disk
+at passivation time. Different passivators can be used
+by setting this property to the fully qualified class name
+of the `PassivationStrategy` implementation. The passivator
+is not responsible for invoking any callbacks or other
+processing, its only responsibly is to write the bean state
+to disk.
+
+Known implementations:
+
+- org.apache.openejb.core.stateful.RAFPassivater
+- org.apache.openejb.core.stateful.SimplePassivater
+
+
+<a name="timeOut"></a>
+## timeOut
+
+Specifies the time a bean can be idle before it is removed by the container.
+
+This value is measured in minutes. A value of 5 would
+result in a time-out of 5 minutes between invocations.
+A value of -1 would mean no timeout.
+A value of 0 would mean a bean can be immediately removed by the container.
+
+Any usage of the `javax.ejb.StatefulTimeout` annotation will
+override this setting for the bean where the annotation is used.
+