tomee-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From dblev...@apache.org
Subject [03/20] tomee git commit: Docs old and new
Date Fri, 30 Nov 2018 23:04:18 GMT
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&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</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&nbsp;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&nbsp;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.
+


Mime
View raw message