http://git-wip-us.apache.org/repos/asf/tomee/blob/c3f8984b/docs/security.mdtext ---------------------------------------------------------------------- diff --git a/docs/security.mdtext b/docs/security.mdtext deleted file mode 100644 index cfe223b..0000000 --- a/docs/security.mdtext +++ /dev/null @@ -1,144 +0,0 @@ -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 class="mdtable"> -<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 class="mdtable"> -<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/c3f8984b/docs/securityservice-config.mdtext ---------------------------------------------------------------------- diff --git a/docs/securityservice-config.mdtext b/docs/securityservice-config.mdtext deleted file mode 100644 index 5f5c1f7..0000000 --- a/docs/securityservice-config.mdtext +++ /dev/null @@ -1,34 +0,0 @@ -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 class="mdtable"> -<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/c3f8984b/docs/service-locator.mdtext ---------------------------------------------------------------------- diff --git a/docs/service-locator.mdtext b/docs/service-locator.mdtext deleted file mode 100644 index b96344c..0000000 --- a/docs/service-locator.mdtext +++ /dev/null @@ -1,169 +0,0 @@ -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/c3f8984b/docs/services.mdtext ---------------------------------------------------------------------- diff --git a/docs/services.mdtext b/docs/services.mdtext deleted file mode 100644 index 5e3bc4b..0000000 --- a/docs/services.mdtext +++ /dev/null @@ -1,16 +0,0 @@ -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/c3f8984b/docs/singleton-beans.mdtext ---------------------------------------------------------------------- diff --git a/docs/singleton-beans.mdtext b/docs/singleton-beans.mdtext deleted file mode 100644 index 3cee7d2..0000000 --- a/docs/singleton-beans.mdtext +++ /dev/null @@ -1,223 +0,0 @@ -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/c3f8984b/docs/singleton-ejb.mdtext ---------------------------------------------------------------------- diff --git a/docs/singleton-ejb.mdtext b/docs/singleton-ejb.mdtext deleted file mode 100644 index 3297c07..0000000 --- a/docs/singleton-ejb.mdtext +++ /dev/null @@ -1,2 +0,0 @@ -Title: Singleton EJB -{include:OPENEJBx30:Singleton Beans} http://git-wip-us.apache.org/repos/asf/tomee/blob/c3f8984b/docs/singletoncontainer-config.mdtext ---------------------------------------------------------------------- diff --git a/docs/singletoncontainer-config.mdtext b/docs/singletoncontainer-config.mdtext deleted file mode 100644 index c6350df..0000000 --- a/docs/singletoncontainer-config.mdtext +++ /dev/null @@ -1,53 +0,0 @@ -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 class="mdtable"> -<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/c3f8984b/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 deleted file mode 100644 index 7ac4cce..0000000 --- a/docs/spring-and-openejb-3.0.mdtext +++ /dev/null @@ -1,190 +0,0 @@ -title=Spring and OpenEJB 3.0 -type=page -status=published -~~~~~~ - -{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/c3f8984b/docs/spring-ejb-and-jpa.mdtext ---------------------------------------------------------------------- diff --git a/docs/spring-ejb-and-jpa.mdtext b/docs/spring-ejb-and-jpa.mdtext deleted file mode 100644 index 7cb9200..0000000 --- a/docs/spring-ejb-and-jpa.mdtext +++ /dev/null @@ -1,170 +0,0 @@ -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 class="mdtable"> -<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/c3f8984b/docs/spring.mdtext ---------------------------------------------------------------------- diff --git a/docs/spring.mdtext b/docs/spring.mdtext deleted file mode 100644 index a24d8e7..0000000 --- a/docs/spring.mdtext +++ /dev/null @@ -1,121 +0,0 @@ -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 class="mdtable"> -<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/c3f8984b/docs/ssh.mdtext ---------------------------------------------------------------------- diff --git a/docs/ssh.mdtext b/docs/ssh.mdtext deleted file mode 100644 index 998ad1b..0000000 --- a/docs/ssh.mdtext +++ /dev/null @@ -1,48 +0,0 @@ -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/c3f8984b/docs/standalone-server.mdtext ---------------------------------------------------------------------- diff --git a/docs/standalone-server.mdtext b/docs/standalone-server.mdtext deleted file mode 100644 index 4eee836..0000000 --- a/docs/standalone-server.mdtext +++ /dev/null @@ -1,23 +0,0 @@ -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/c3f8984b/docs/startup.mdtext ---------------------------------------------------------------------- diff --git a/docs/startup.mdtext b/docs/startup.mdtext deleted file mode 100644 index a258232..0000000 --- a/docs/startup.mdtext +++ /dev/null @@ -1,293 +0,0 @@ -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]([email protected]) -# ./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]([email protected]) -# 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/c3f8984b/docs/statefulcontainer-config.mdtext ---------------------------------------------------------------------- diff --git a/docs/statefulcontainer-config.mdtext b/docs/statefulcontainer-config.mdtext deleted file mode 100644 index dce7bb4..0000000 --- a/docs/statefulcontainer-config.mdtext +++ /dev/null @@ -1,157 +0,0 @@ -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 class="mdtable"> -<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. - http://git-wip-us.apache.org/repos/asf/tomee/blob/c3f8984b/docs/statelesscontainer-config.mdtext ---------------------------------------------------------------------- diff --git a/docs/statelesscontainer-config.mdtext b/docs/statelesscontainer-config.mdtext deleted file mode 100644 index 33cd88a..0000000 --- a/docs/statelesscontainer-config.mdtext +++ /dev/null @@ -1,458 +0,0 @@ -Title: StatelessContainer Configuration - - -A StatelessContainer 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="myStatelessContainer" type="STATELESS"> - accessTimeout = 30 seconds - callbackThreads = 5 - closeTimeout = 5 minutes - garbageCollection = false - idleTimeout = 0 minutes - maxAge = 0 hours - maxAgeOffset = -1 - maxSize = 10 - minSize = 0 - replaceAged = true - replaceFlushed = false - strictPooling = true - sweepInterval = 5 minutes - </Container> - -Alternatively, a StatelessContainer 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` - - myStatelessContainer = new://Container?type=STATELESS - myStatelessContainer.accessTimeout = 30 seconds - myStatelessContainer.callbackThreads = 5 - myStatelessContainer.closeTimeout = 5 minutes - myStatelessContainer.garbageCollection = false - myStatelessContainer.idleTimeout = 0 minutes - myStatelessContainer.maxAge = 0 hours - myStatelessContainer.maxAgeOffset = -1 - myStatelessContainer.maxSize = 10 - myStatelessContainer.minSize = 0 - myStatelessContainer.replaceAged = true - myStatelessContainer.replaceFlushed = false - myStatelessContainer.strictPooling = true - myStatelessContainer.sweepInterval = 5 minutes - -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 StatelessContainer a warning will be logged. If a StatelessContainer is needed by the application and one is not declared, TomEE will create one dynamically using default settings. Multiple StatelessContainer declarations are allowed. -# Supported Properties -<table class="mdtable"> -<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 time an invokation should wait for an instance -of the pool to become available. -</td> -</tr> -<tr> - <td><a href="#callbackThreads">callbackThreads</a></td> - <td>int</td> - <td>5</td> - <td> -The number of threads for constructing and destroying beans. -</td> -</tr> -<tr> - <td><a href="#closeTimeout">closeTimeout</a></td> - <td><a href="configuring-durations.html">time</a></td> - <td>5 minutes</td> - <td> -Maximum time to wait for instances to be destroyed when shutting down the pool -</td> -</tr> -<tr> - <td><a href="#garbageCollection">garbageCollection</a></td> - <td>boolean</td> - <td>false</td> - <td> -Allows Garbage Collection to be used as a mechanism for shrinking -the pool. -</td> -</tr> -<tr> - <td><a href="#idleTimeout">idleTimeout</a></td> - <td><a href="configuring-durations.html">time</a></td> - <td>0 minutes</td> - <td> -Specifies the maximum time that an instance should be allowed to -sit idly in the pool without use before it should be retired and -removed. -</td> -</tr> -<tr> - <td><a href="#maxAge">maxAge</a></td> - <td><a href="configuring-durations.html">time</a></td> - <td>0 hours</td> - <td> -Specifies the maximum time that an instance should live before -it should be retired and removed from use. -</td> -</tr> -<tr> - <td><a href="#maxAgeOffset">maxAgeOffset</a></td> - <td>int</td> - <td>-1</td> - <td> -Applies to MaxAge usage and would rarely be changed, but is a -nice feature to understand. -</td> -</tr> -<tr> - <td><a href="#maxSize">maxSize</a></td> - <td>int</td> - <td>10</td> - <td> -Specifies the size of the instance pool for this stateless -SessionBean container. -</td> -</tr> -<tr> - <td><a href="#minSize">minSize</a></td> - <td>int</td> - <td>0</td> - <td> -Specifies the minimum number of bean instances that should be in -the pool for each bean. -</td> -</tr> -<tr> - <td><a href="#replaceAged">replaceAged</a></td> - <td>boolean</td> - <td>true</td> - <td> -When `ReplaceAged` is enabled, any instances in the pool that -expire due to reaching their `MaxAge` will be replaced immediately -so that the pool will remain at its current size. -</td> -</tr> -<tr> - <td><a href="#replaceFlushed">replaceFlushed</a></td> - <td>boolean</td> - <td>false</td> - <td> -When `ReplaceFlushed` is enabled, any instances in the pool that -are flushed will be replaced immediately so that the pool will -remain at its current size. -</td> -</tr> -<tr> - <td><a href="#strictPooling">strictPooling</a></td> - <td>boolean</td> - <td>true</td> - <td> -StrictPooling tells the container what to do when the pool -reaches it's maximum size and there are incoming requests that -need instances. -</td> -</tr> -<tr> - <td><a href="#sweepInterval">sweepInterval</a></td> - <td><a href="configuring-durations.html">time</a></td> - <td>5 minutes</td> - <td> -The frequency in which the container will sweep the pool and -evict expired instances. -</td> -</tr> -</table> - - - -<a name="accessTimeout"></a> -## accessTimeout - -Specifies the time an invokation should wait for an instance -of the pool to become available. - -After the timeout is reached, if an instance in the pool cannot -be obtained, the method invocation will fail. - -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="callbackThreads"></a> -## callbackThreads - -The number of threads for constructing and destroying beans. - -When sweeping the pool for expired instances a thread pool is -used to process calling `@PreDestroy` on expired instances as well -as creating new instances as might be required to fill the pool -to the minimum after a Flush or `MaxAge` expiration. The -`CallbackThreads` setting dictates the size of the thread pool and -is shared by all beans deployed in the container. - - -<a name="closeTimeout"></a> -## closeTimeout - -Maximum time to wait for instances to be destroyed when shutting down the pool - -PostConstruct methods are invoked on all instances in the pool -when the bean is undeployed and its pool is closed. The -`CloseTimeout` specifies the maximum time to wait for the pool to -close and `PostConstruct` methods to be invoked. - -Usable time units: nanoseconds, microsecons, milliseconds, -seconds, minutes, hours, days. Or any combination such as -`1 hour and 27 minutes and 10 seconds` - - -<a name="garbageCollection"></a> -## garbageCollection - -Allows Garbage Collection to be used as a mechanism for shrinking -the pool. - -When set to true all instances in the pool, excluding -the minimum, are eligible for garbage collection by the virtual -machine as per the rules of `java.lang.ref.SoftReference` and can be -claimed by the JVM to free memory. Instances garbage collected -will have their `@PreDestroy` methods called during finalization. - -In the OpenJDK VM the `-XX:SoftRefLRUPolicyMSPerMB` flag can adjust -how aggressively SoftReferences are collected. The default -OpenJDK setting is 1000, resulting in inactive pooled instances -living one second of lifetime per free megabyte in the heap, which -is very aggressive. The setting should be increased to get the -most out of the `GarbageCollection` feature of the pool. Much -higher settings are safe. Even a setting as high as 3600000 (1 -hour per free MB in the heap) does not affect the ability for the -VM to garbage collect SoftReferences in the event that memory is -needed to avoid an `OutOfMemoryException`. - - -<a name="idleTimeout"></a> -## idleTimeout - -Specifies the maximum time that an instance should be allowed to -sit idly in the pool without use before it should be retired and -removed. - -Only instances -in surplus of the pool's `MinSize` are eligible to expire via `IdleTimeout` -Instances that expire due to `IdleTimeout` will have their `@PreDestroy` -methods invoked before being completely destroyed. - -Usable time units: nanoseconds, microsecons, milliseconds, -seconds, minutes, hours, days. Or any combination such as -"1 hour and 27 minutes and 10 seconds" - - -<a name="maxAge"></a> -## maxAge - -Specifies the maximum time that an instance should live before -it should be retired and removed from use. - -This will happen -gracefully. Useful for situations where bean instances are -designed to hold potentially expensive resources such as memory -or file handles and need to be periodically cleared out. - -Usable time units: nanoseconds, microsecons, milliseconds, -seconds, minutes, hours, days. Or any combination such as -`1 hour and 27 minutes and 10 seconds` - - -<a name="maxAgeOffset"></a> -## maxAgeOffset - -Applies to MaxAge usage and would rarely be changed, but is a -nice feature to understand. - -When the container first starts and the pool is filled to the -minimum size, all those "minimum" instances will have the same -creation time and therefore all expire at the same time dictated -by the `MaxAge` setting. To protect against this sudden drop -scenario and provide a more gradual expiration from the start -the container will spread out the age of the instances that fill -the pool to the minimum using an offset. - -The `MaxAgeOffset` is not the final value of the offset, but -rather it is used in creating the offset and allows the -spreading to push the initial ages into the future or into the -past. The pool is filled at startup as follows: - - for (int i = 0; i < poolMin; i++) { - long ageOffset = (maxAge / poolMin * i * maxAgeOffset) % maxAge; - pool.add(new Bean(), ageOffset)); - } - -The default `MaxAgeOffset` is -1 which causes the initial -instances in the pool to live a bit longer before expiring. As -a concrete example, let's say the MinSize is 4 and the MaxAge is -100 years. The generated offsets for the four instances created -at startup would be 0, -25, -50, -75. So the first instance -would be "born" at age 0, die at 100, living 100 years. The -second instance would be born at -25, die at 100, living a total -of 125 years. The third would live 150 years. The fourth 175 -years. - -A `MaxAgeOffset` of 1 would cause instances to be "born" older -and therefore die sooner. Using the same example `MinSize` of 4 -and `MaxAge` of `100 years`, the life spans of these initial four -instances would be 100, 75, 50, and 25 years respectively. - -A `MaxAgeOffset` of 0 will cause no "spreading" of the age of the -first instances used to fill the pool to the minimum and these -instances will of course reach their MaxAge at the same time. -It is possible to set to decimal values such as -0.5, 0.5, -1.2, -or 1.2. - - -<a name="maxSize"></a> -## maxSize - -Specifies the size of the instance pool for this stateless -SessionBean container. - -Each `@Stateless` bean will get its own instance pool. -If StrictPooling is not used, instances -will still be created beyond this number if there is demand, but -they will not be returned to the pool and instead will be -immediately expire. - - -<a name="minSize"></a> -## minSize - -Specifies the minimum number of bean instances that should be in -the pool for each bean. - -Pools are prefilled to the minimum on -startup. Note this will create start order dependencies between -other beans that also eagerly start, such as other `@Stateless` -beans with a minimum or `@Singleton` beans using `@Startup`. The -`@DependsOn` annotation can be used to appropriately influence -start order. - -The minimum pool size is rigidly maintained. Instances in the -minimum side of the pool are not eligible for `IdleTimeout` or -`GarbageCollection`, but are subject to `MaxAge` and flushing. - -If the pool is flushed it is immediately refilled to the minimum -size with `MaxAgeOffset` applied. If an instance from the minimum -side of the pool reaches its `MaxAge`, it is also immediately -replaced. Replacement is done in a background queue using the -number of threads specified by `CallbackThreads`. - - -<a name="replaceAged"></a> -## replaceAged - -When `ReplaceAged` is enabled, any instances in the pool that -expire due to reaching their `MaxAge` will be replaced immediately -so that the pool will remain at its current size. - -Replacement -is done in a background queue so that incoming threads will not -have to wait for instance creation. - -The aim of his option is to prevent user requests from paying -the instance creation cost as `MaxAge` is enforced, potentially -while under heavy load at peak hours. - -Instances from the minimum side of the pool are always replaced -when they reach their `MaxAge`, this setting dictates the -treatment of non-minimum instances. - - -<a name="replaceFlushed"></a> -## replaceFlushed - -When `ReplaceFlushed` is enabled, any instances in the pool that -are flushed will be replaced immediately so that the pool will -remain at its current size. - -Replacement is done in a background -queue so that incoming threads will not have to wait for -instance creation. - -The aim of his option is to prevent user requests from paying -the instance creation cost if a flush performed while under -heavy load at peak hours. - -Instances from the minimum side of the pool are always replaced -when they are flushed, this setting dictates the treatment of -non-minimum instances. - -A bean may flush its pool by casting the `SessionContext` to -`Flushable` and calling `flush()`. See `SweepInterval` for details on -how flush is performed. - - import javax.annotation.Resource; - import javax.ejb.SessionContext; - import javax.ejb.Stateless; - import java.io.Flushable; - import java.io.IOException; - - public class MyBean { - - private SessionContext sessionContext; - - public void flush() throws IOException { - - ((Flushable) sessionContext).flush(); - } - } - - -<a name="strictPooling"></a> -## strictPooling - -StrictPooling tells the container what to do when the pool -reaches it's maximum size and there are incoming requests that -need instances. - -With strict pooling, requests will have to wait for instances to -become available. The pool size will never grow beyond the the -set `MaxSize` value. The maximum amount of time a request should -wait is specified via the `AccessTimeout` setting. - -Without strict pooling, the container will create temporary -instances to meet demand. The instances will last for just one -method invocation and then are removed. - -Setting `StrictPooling` to `false` and `MaxSize` to `0` will result in -no pooling. Instead instances will be created on demand and live -for exactly one method call before being removed. - - -<a name="sweepInterval"></a> -## sweepInterval - -The frequency in which the container will sweep the pool and -evict expired instances. - -Eviction is how the `IdleTimeout`, -`MaxAge`, and pool "flush" functionality is enforced. Higher -intervals are better. - -Instances in use are excluded from sweeping. Should an instance -expire while in use it will be evicted immediately upon return -to the pool. Effectively `MaxAge` and flushes will be enforced as -a part of normal activity or sweeping, while IdleTimeout is only -enforcable via sweeping. This makes aggressive sweeping less -important for a pool under moderate load. - -Usable time units: nanoseconds, microsecons, milliseconds, -seconds, minutes, hours, days. Or any combination such as -`1 hour and 27 minutes and 10 seconds` -
