http://git-wip-us.apache.org/repos/asf/tomee/blob/9b209c98/docs/security.md ---------------------------------------------------------------------- diff --git a/docs/security.md b/docs/security.md deleted file mode 100644 index 2f39aa2..0000000 --- a/docs/security.md +++ /dev/null @@ -1,148 +0,0 @@ -index-group=Configuration -type=page -status=published -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/9b209c98/docs/securityservice-config.adoc ---------------------------------------------------------------------- diff --git a/docs/securityservice-config.adoc b/docs/securityservice-config.adoc new file mode 100644 index 0000000..3b6f6cd --- /dev/null +++ b/docs/securityservice-config.adoc @@ -0,0 +1,50 @@ +# SecurityService Configuration +:index-group: Unrevised +:jbake-date: 2018-12-05 +:jbake-type: page +:jbake-status: published + + +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 + +Property + +Type + +Default + +Description + +defaultUser + +String + +guest http://git-wip-us.apache.org/repos/asf/tomee/blob/9b209c98/docs/securityservice-config.md ---------------------------------------------------------------------- diff --git a/docs/securityservice-config.md b/docs/securityservice-config.md deleted file mode 100644 index 0856536..0000000 --- a/docs/securityservice-config.md +++ /dev/null @@ -1,36 +0,0 @@ -index-group=Unrevised -type=page -status=published -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/9b209c98/docs/service-locator.adoc ---------------------------------------------------------------------- diff --git a/docs/service-locator.adoc b/docs/service-locator.adoc new file mode 100644 index 0000000..e14857f --- /dev/null +++ b/docs/service-locator.adoc @@ -0,0 +1,159 @@ +# Service Locator +:index-group: Unrevised +:jbake-date: 2018-12-05 +:jbake-type: page +:jbake-status: published + +The functionality of the +link:jndi-names.html[openejb.jndiname.format] 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. + +# 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); + } + } +} +.... + +== 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); +.... + +== 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 lookup(String prefix, Class 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); +.... + +== 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); +.... + +== 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/9b209c98/docs/service-locator.md ---------------------------------------------------------------------- diff --git a/docs/service-locator.md b/docs/service-locator.md deleted file mode 100644 index b4a58e9..0000000 --- a/docs/service-locator.md +++ /dev/null @@ -1,171 +0,0 @@ -index-group=Unrevised -type=page -status=published -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/9b209c98/docs/services.adoc ---------------------------------------------------------------------- diff --git a/docs/services.adoc b/docs/services.adoc new file mode 100644 index 0000000..140aeba --- /dev/null +++ b/docs/services.adoc @@ -0,0 +1,28 @@ +# ServicePool and Services +:index-group: Unrevised +:jbake-date: 2018-12-05 +:jbake-type: page +:jbake-status: published + + +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/9b209c98/docs/services.md ---------------------------------------------------------------------- diff --git a/docs/services.md b/docs/services.md deleted file mode 100644 index 5cac11a..0000000 --- a/docs/services.md +++ /dev/null @@ -1,20 +0,0 @@ -index-group=Unrevised -type=page -status=published -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/9b209c98/docs/singleton-beans.adoc ---------------------------------------------------------------------- diff --git a/docs/singleton-beans.adoc b/docs/singleton-beans.adoc new file mode 100644 index 0000000..906b897 --- /dev/null +++ b/docs/singleton-beans.adoc @@ -0,0 +1,228 @@ +# Singleton Beans +:index-group: Unrevised +:jbake-date: 2018-12-05 +:jbake-type: page +:jbake-status: published + +# 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 +, 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 link:singleton-example.html[Singleton Example] for sample bean +code and client. + +== Concurrency + +Singletons support two modes of concurrent access, Container-Managed +Concurrency (the default) and Bean-Managed Concurrency. + +=== 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. + +=== 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. + +==== 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 +_http://java.sun.com/j2se/1.5.0/docs/api/java/util/concurrent/locks/ReadWriteLock.html[java.util.concurrent.ReadWriteLock] +_ 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 +http://java.sun.com/j2se/1.5.0/docs/api/java/util/concurrent/locks/ReentrantReadWriteLock.html[java.util.concurrent.ReentrantReadWriteLock] +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] +. + +==== 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 +http://java.sun.com/j2se/1.5.0/docs/api/java/util/concurrent/locks/Lock.html[java.util.concurrent.locks.Lock] +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. + +==== 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: + +[arabic] +. bean-level in openejb-jar.xml/// +. jar-level in openejb-jar.xml// +. container-level in openejb.xml// +. boot-level via InitialContext(Properties) or +EJBContainer.createEjbContainer(Map<Object,Object>) +. 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 +link:configuring-durations.html[Configuring Durations] for details. + +== 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. + +# 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/9b209c98/docs/singleton-beans.md ---------------------------------------------------------------------- diff --git a/docs/singleton-beans.md b/docs/singleton-beans.md deleted file mode 100644 index 1f67561..0000000 --- a/docs/singleton-beans.md +++ /dev/null @@ -1,226 +0,0 @@ -index-group=Unrevised -type=page -status=published -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/9b209c98/docs/singleton-ejb.adoc ---------------------------------------------------------------------- diff --git a/docs/singleton-ejb.adoc b/docs/singleton-ejb.adoc new file mode 100644 index 0000000..689e308 --- /dev/null +++ b/docs/singleton-ejb.adoc @@ -0,0 +1,7 @@ +# Singleton EJB +:index-group: Unrevised +:jbake-date: 2018-12-05 +:jbake-type: page +:jbake-status: published + +\{include:OPENEJBx30:Singleton Beans} http://git-wip-us.apache.org/repos/asf/tomee/blob/9b209c98/docs/singleton-ejb.md ---------------------------------------------------------------------- diff --git a/docs/singleton-ejb.md b/docs/singleton-ejb.md deleted file mode 100644 index 38e039f..0000000 --- a/docs/singleton-ejb.md +++ /dev/null @@ -1,6 +0,0 @@ -index-group=Unrevised -type=page -status=published -title=Singleton EJB -~~~~~~ -{include:OPENEJBx30:Singleton Beans} http://git-wip-us.apache.org/repos/asf/tomee/blob/9b209c98/docs/singletoncontainer-config.adoc ---------------------------------------------------------------------- diff --git a/docs/singletoncontainer-config.adoc b/docs/singletoncontainer-config.adoc new file mode 100644 index 0000000..353c841 --- /dev/null +++ b/docs/singletoncontainer-config.adoc @@ -0,0 +1,69 @@ +# SingletonContainer Configuration +:index-group: Unrevised +:jbake-date: 2018-12-05 +:jbake-type: page +:jbake-status: published + + +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 + +Property + +Type + +Default + +Description + +accessTimeout + +time + +30Â seconds + +Specifies the maximum time an invocation could wait for the `@Singleton` +bean instance to become available before giving up. + +== 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/9b209c98/docs/singletoncontainer-config.md ---------------------------------------------------------------------- diff --git a/docs/singletoncontainer-config.md b/docs/singletoncontainer-config.md deleted file mode 100644 index c630a8d..0000000 --- a/docs/singletoncontainer-config.md +++ /dev/null @@ -1,56 +0,0 @@ -index-group=Unrevised -type=page -status=published -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.
