You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@tomee.apache.org by db...@apache.org on 2018/12/02 02:20:44 UTC
[17/30] tomee git commit: Rename *.mdtext files to *.md
http://git-wip-us.apache.org/repos/asf/tomee/blob/b93bd755/docs/remote-server.md
----------------------------------------------------------------------
diff --git a/docs/remote-server.md b/docs/remote-server.md
new file mode 100644
index 0000000..460dfc0
--- /dev/null
+++ b/docs/remote-server.md
@@ -0,0 +1,64 @@
+index-group=Unrevised
+type=page
+status=published
+title=Remote Server
+~~~~~~
+
+!http://www.openejb.org/images/diagram-remote-server.gif|valign=top,
+align=right, hspace=15!
+<a name="RemoteServer-AccessingEJBsRemotely"></a>
+# Accessing EJBs Remotely
+
+When using OpenEJB as a stand-alone server you can connect across a network
+and access EJBs from a remote client. The client code for accessing an
+EJB's Remote Interface is the same, however to actually connect across a
+network to the server, you need to specify different JNDI parameters.
+
+<a name="RemoteServer-Shortversion"></a>
+# Short version
+
+Using OpenEJB's default remote server implementation is pretty straight
+forward. You simply need to:
+
+1. Deploy your bean.
+1. Start the server on the IP and Port you want, 25.14.3.92 and 4201 for
+example.
+1. Use that information in your client to create an initial context
+1. Add the right jars to your client's classpath
+
+So, here it is in short.
+
+Deploy your bean with the Deploy Tool:
+
+ c:\openejb> openejb.bat deploy beans\myBean.jar
+
+See the [OPENEJBx30:Deploy Tool](openejbx30:deploy-tool.html)
+ documentation for more details on deploying beans.
+
+Start the server:
+
+ c:\openejb> openejb.bat start -h 25.14.3.92 -p 4201
+
+See the Remote Server command-line guide for more details on starting the
+Remote Server.
+
+Create an initial context in your client as such:
+
+
+ Properties p = new Properties();
+ p.put("java.naming.factory.initial", "org.apache.openejb.client.RemoteInitialContextFactory");
+ p.put("java.naming.provider.url", "ejbd://25.14.3.92:4201");
+ p.put("java.naming.security.principal", "myuser");
+ p.put("java.naming.security.credentials", "mypass");
+
+ InitialContext ctx = new InitialContext(p);
+
+
+If you don't have any EJBs or clients to run, try the ubiquitous [Hello World](openejbx30:hello-world.html)
+ example.
+Add the following library to your clients classpath:
+
+* openejb-client-x.x.x.jar
+* javaee-api-x.x.jar
+
+Both can be found in the lib directory where you installed OpenEJB or in Maven repositories.
http://git-wip-us.apache.org/repos/asf/tomee/blob/b93bd755/docs/resource-injection.md
----------------------------------------------------------------------
diff --git a/docs/resource-injection.md b/docs/resource-injection.md
new file mode 100644
index 0000000..ac019ed
--- /dev/null
+++ b/docs/resource-injection.md
@@ -0,0 +1,184 @@
+index-group=Unrevised
+type=page
+status=published
+~~~~~~
+<a name="ResourceInjection-Overview"></a>
+# @Resource Overview
+
+This example demonstrates the use of the injection of environment entries
+using <span style="color: #217D18;">**@Resource**</span> annotation.
+
+The EJB 3.0 specification (*EJB Core Contracts and Requirements*) section
+16.2.2 reads:
+
+*A field or method of a bean class may be annotated to request that an entry from the bean's environment be injected. Any of the types of resources or other environment entries described in this chapter may be injected. Injection may also be requested using entries in the deployment descriptor corresponding to each of these
+resource types.*
+
+*Environment entries may also be injected into the bean through bean methods that follow the naming conventions for JavaBeans properties. The annotation is applied to the set method for the property, which is the method that is called to inject the environment entry. The JavaBeans property name (not the method name) is used as the default JNDI name.*
+
+The *PurchaseOrderBean* class shows use of field-level **@Resource**
+annotation.
+
+The *InvoiceBean* class shows the use of method-level **@Resource**
+annotation.
+
+The source for this example can be checked out from svn:
+
+> $ svn co
+http://svn.apache.org/repos/asf/tomee/tomee/trunk/examples/injection-of-env-entry
+
+To run it change your working directory to the directory
+*injection-of-env-entry* and run the following maven2 commands:
+
+>$ cd injection-of-env-entry
+
+>$ mvn clean install
+
+<a name="ResourceInjection-TheCode"></a>
+# The Code
+
+<a name="ResourceInjection-Injectionthroughfield(field-levelinjection)"></a>
+## Injection through field (field-level injection)
+
+The *maxLineItem* field in *PurchaseOrderBean* class is annotated with **@Resource** annotation to inform the EJB container the location where in the code the injection of a simple environment entry should take place. The default value of 10 is assigned. You can modify the value of the environment entries at deployment time using deployment descriptor (**ejb-jar.xml**).
+
+<a name="ResourceInjection-@Resourceannotationofafield"></a>
+#### @Resource annotation of a field
+
+
+ @Resource
+ int maxLineItems = 10;
+
+
+<a name="ResourceInjection-Injectionthroughasettermethod(method-levelinjection)"></a>
+## Injection through a setter method (method-level injection)
+
+The *setMaxLineItem* method in *InvoiceBean* class is annotated with
+*@Resource* annotation to inject the simple environment entry. Only setters
+can be used as a way to inject environment entry values.
+
+You could look up the env-entry using JNDI lookup() method and the
+following name:
+
+ java:comp/env/org.apache.openejb.examples.resource.InvoiceBean/maxLineItems
+
+The pattern is to combine the fully-qualified class name and the name of a
+instance field (or a name of the setter method without _set_ prefix and the
+first letter lowercased).
+
+<a name="ResourceInjection-@Resourceannotationofasettermethod"></a>
+#### @Resource annotation of a setter method
+
+
+ @Resource
+ public void setMaxLineItems(int maxLineItems) {
+ this.maxLineItems = maxLineItems;
+ }
+
+
+<a name="ResourceInjection-env-entryinejb-jar.xml"></a>
+#### Using env-entry in ejb-jar.xml
+
+ <env-entry>
+ <description>The maximum number of line items per invoice.</description>
+ <env-entry-name>org.apache.openejb.examples.injection.InvoiceBean/maxLineItems</env-entry-name>
+ <env-entry-type>java.lang.Integer</env-entry-type>
+ <env-entry-value>15</env-entry-value>
+ </env-entry>
+
+
+<a name="ResourceInjection-Using@Resourceannotatedenv-entry"></a>
+#### Using @Resource annotated env-entry
+
+ public void addLineItem(LineItem item) throws TooManyItemsException {
+ if (item == null) {
+ throw new IllegalArgumentException("Line item must not be null");
+ }
+
+ if (itemCount <= maxLineItems) {
+ items.add(item);
+ itemCount++;
+ } else {
+ throw new TooManyItemsException("Number of items exceeded the maximum limit");
+ }
+ }
+
+
+<a name="ResourceInjection-JUnitTest"></a>
+# JUnit Test
+
+Writing an JUnit test for this example is quite simple. We need just to
+write a setup method to create and initialize the InitialContext, and then
+write our test methods.
+
+<a name="ResourceInjection-Testfixture"></a>
+#### Test fixture
+
+
+ protected void setUp() throws Exception {
+ Properties properties = new Properties();
+ properties.setProperty(Context.INITIAL_CONTEXT_FACTORY, "org.apache.openejb.client.LocalInitialContextFactory");
+ properties.setProperty("openejb.deployments.classpath.include", ".*resource-injection.*");
+ initialContext = new InitialContext(properties);
+ }
+
+
+<a name="ResourceInjection-Testmethods"></a>
+#### Test methods
+
+ public void testAddLineItem() throws Exception {
+ Invoice order = (Invoice)initialContext.lookup("InvoiceBeanBusinessRemote");
+ assertNotNull(order);
+ LineItem item = new LineItem("ABC-1", "Test Item");
+
+ try {
+ order.addLineItem(item);
+ } catch (TooManyItemsException tmie) {
+ fail("Test failed due to: " + tmie.getMessage());
+ }
+ }
+
+
+<a name="ResourceInjection-Running"></a>
+# Running
+
+Running the example is fairly simple. Just execute the following commands:
+
+>$ cd injection-of-env-entry
+>
+>$ mvn clean test
+
+
+ -------------------------------------------------------
+ T E S T S
+ -------------------------------------------------------
+ Running org.superbiz.injection.PurchaseOrderBeanTest
+ Apache OpenEJB 3.0.0-SNAPSHOT build: 20071218-01:41
+ http://tomee.apache.org/
+ INFO - openejb.home = c:\oss\openejb3\examples\injection-of-env-entry
+ INFO - openejb.base = c:\oss\openejb3\examples\injection-of-env-entry
+ WARN - Cannot find the configuration file [conf/openejb.xml]. Will attempt to create one for the beans deployed.
+ INFO - Configuring Service(id=Default Security Service,type=SecurityService, provider-id=Default Security Service)
+ INFO - Configuring Service(id=Default Transaction Manager, type=TransactionManager, provider-id=Default Transaction Manager)
+ INFO - Configuring Service(id=Default JDK 1.3 ProxyFactory, type=ProxyFactory, provider-id=Default JDK 1.3 ProxyFactory)
+ INFO - Found EjbModule in classpath: c:\oss\openejb3\examples\injection-of-env-entry\target\classes
+ INFO - Configuring app: c:\oss\openejb3\examples\injection-of-env-entry\target\classes
+ INFO - Configuring Service(id=Default Stateful Container, type=Container, provider-id=Default Stateful Container)
+ INFO - Auto-creating a container for bean InvoiceBean: Container(type=STATEFUL, id=Default Stateful Container)
+ INFO - Loaded Module: c:\oss\openejb3\examples\injection-of-env-entry\target\classes
+ INFO - Assembling app: c:\oss\openejb3\examples\injection-of-env-entry\target\classes
+ INFO - Jndi(name=InvoiceBeanRemote) --> Ejb(deployment-id=InvoiceBean)
+ INFO - Jndi(name=PurchaseOrderBeanRemote) --> Ejb(deployment-id=PurchaseOrderBean)
+ INFO - Created Ejb(deployment-id=InvoiceBean, ejb-name=InvoiceBean, container=Default Stateful Container)
+ INFO - Created Ejb(deployment-id=PurchaseOrderBean, ejb-name=PurchaseOrderBean, container=Default Stateful Container)
+ INFO - Deployed Application(path=c:\oss\openejb3\examples\injection-of-env-entry\target\classes)
+ INFO - OpenEJB ready.
+ OpenEJB ready.
+ Tests run: 2, Failures: 0, Errors: 0, Skipped: 0, Time elapsed: 2.859 sec
+ Running org.superbiz.injection.InvoiceBeanTest
+ Tests run: 2, Failures: 0, Errors: 0, Skipped: 0, Time elapsed: 0.031 sec
+
+ Results :
+
+ Tests run: 4, Failures: 0, Errors: 0, Skipped: 0
+
http://git-wip-us.apache.org/repos/asf/tomee/blob/b93bd755/docs/resource-ref-for-datasource.md
----------------------------------------------------------------------
diff --git a/docs/resource-ref-for-datasource.md b/docs/resource-ref-for-datasource.md
new file mode 100644
index 0000000..d27fb04
--- /dev/null
+++ b/docs/resource-ref-for-datasource.md
@@ -0,0 +1,46 @@
+index-group=Unrevised
+type=page
+status=published
+~~~~~~
+# Via annotation
+
+ package org.superbiz.refs;
+
+ import javax.annotation.Resource;
+ import javax.ejb.Stateless;
+ import javax.naming.InitialContext;
+ import javax.sql.DataSource;
+
+ @Stateless
+ @Resource(name = "myFooDataSource", type = DataSource.class)
+ public class MyDataSourceRefBean implements MyBeanInterface {
+
+ @Resource
+ private DataSource myBarDataSource;
+
+ public void someBusinessMethod() throws Exception {
+ if (myBarDataSource == null) throw new NullPointerException("myBarDataSource not injected");
+
+ // Both can be looked up from JNDI as well
+ InitialContext context = new InitialContext();
+ DataSource fooDataSource = (DataSource) context.lookup("java:comp/env/myFooDataSource");
+ DataSource barDataSource = (DataSource) context.lookup("java:comp/env/org.superbiz.refs.MyDataSourceRefBean/myBarDataSource");
+ }
+ }
+
+# Via xml
+
+The above @Resource annotation usage is 100% equivalent to the following xml.
+
+ <resource-ref>
+ <res-ref-name>myFooDataSource</res-ref-name>
+ <res-type>javax.sql.DataSource</res-type>
+ </resource-ref>
+ <resource-ref>
+ <res-ref-name>org.superbiz.refs.MyDataSourceRefBean/myBarDataSource</res-ref-name>
+ <res-type>javax.sql.DataSource</res-type>
+ <injection-target>
+ <injection-target-class>org.superbiz.refs.MyDataSourceRefBean</injection-target-class>
+ <injection-target-name>myBarDataSource</injection-target-name>
+ </injection-target>
+ </resource-ref>
http://git-wip-us.apache.org/repos/asf/tomee/blob/b93bd755/docs/running-a-standalone-openejb-server.md
----------------------------------------------------------------------
diff --git a/docs/running-a-standalone-openejb-server.md b/docs/running-a-standalone-openejb-server.md
new file mode 100644
index 0000000..ca81014
--- /dev/null
+++ b/docs/running-a-standalone-openejb-server.md
@@ -0,0 +1,95 @@
+index-group=Unrevised
+type=page
+status=published
+title=Running a standalone OpenEJB server
+~~~~~~
+
+<a name="RunningastandaloneOpenEJBserver-ConfiguringtheOpenEJBRuntime"></a>
+# Configuring the OpenEJB Runtime
+The OpenEJB Eclipse plugin provides support for running OpenEJB as a
+standalone server in Eclipse using WTP.
+
+To setup a server, first of all, you will need to have a copy of OpenEJB
+extracted on your machine. Once you have that, the next step is to set up a
+runtime.
+
+To set up a new runtime, click on Window, Preferences, and select Installed
+Runtimes under the Server category. Click the Add button.
+
+![http://people.apache.org/~jgallimore/images/server_step_4.jpg][1]
+
+Select OpenEJB 3.0.0 from the Apache category, and click next. If you
+choose to 'also create a new server' on this panel, you can add a server
+straight after configuring the runtime.
+
+![http://people.apache.org/~jgallimore/images/server_step_5.jpg][2]
+
+Browse to, or enter the path to your copy of OpenEJB. Click on Finish.
+
+<a name="RunningastandaloneOpenEJBserver-ConfiguringtheOpenEJBServer"></a>
+# Configuring the OpenEJB Server
+Open the Servers view (if it isn't already), and right click and select
+New->Server.
+
+![http://people.apache.org/~jgallimore/images/server_step_8.jpg][3]
+
+Select OpenEJB 3.0.0 from the Apache category, ensure you have the OpenEJB
+runtime selected, and click Next.
+
+![http://people.apache.org/~jgallimore/images/server_step_9.jpg][4]
+
+Select the EJB port for the server, and select Finish.
+
+![http://people.apache.org/~jgallimore/images/server_step_10.jpg][5]
+
+<a name="RunningastandaloneOpenEJBserver-Deployingaproject"></a>
+# Deploying a project
+In order to deploy your project to an OpenEJB server in Eclipse, your
+project must be a Java EE project, with the EJB facet enabled. If your
+project doesn't have the Faceted nature, you can use the OpenEJB plugin to
+add it. Simply select OpenEJB->Add Faceted Nature from the menu bar.
+
+![http://people.apache.org/~jgallimore/images/server_step_1.jpg][6]
+
+To add the EJB facet, right click on the project in the navigator, and
+select Properties. Select Project Facets on the left hand side. Click on
+the Modify Project button.
+
+![http://people.apache.org/~jgallimore/images/server_step_2.jpg][7]
+
+Select the EJB Module facet, and the Java Facet. Remember to select your
+OpenEJB runtime too. Click Next.
+
+![http://people.apache.org/~jgallimore/images/server_step_6.jpg][8]
+
+Enter the source folder for the EJBs in your project and click Finish.
+
+![http://people.apache.org/~jgallimore/images/server_step_7.jpg][9]
+
+Now right click on your OpenEJB server in the servers view, and select Add
+and Remove Projects.
+
+![http://people.apache.org/~jgallimore/images/server_step_11.jpg][10]
+
+Add your project to the server, and click Finish.
+
+![http://people.apache.org/~jgallimore/images/server_step_12.jpg][11]
+
+To start the server, Right click on your OpenEJB server, and select Start.
+
+![http://people.apache.org/~jgallimore/images/server_step_13.jpg][12]
+
+
+
+ [1]: http://people.apache.org/~jgallimore/images/server_step_4.jpg
+ [2]: http://people.apache.org/~jgallimore/images/server_step_5.jpg
+ [3]: http://people.apache.org/~jgallimore/images/server_step_8.jpg
+ [4]: http://people.apache.org/~jgallimore/images/server_step_9.jpg
+ [5]: http://people.apache.org/~jgallimore/images/server_step_10.jpg
+ [6]: http://people.apache.org/~jgallimore/images/server_step_1.jpg
+ [7]: http://people.apache.org/~jgallimore/images/server_step_2.jpg
+ [8]: http://people.apache.org/~jgallimore/images/server_step_6.jpg
+ [9]: http://people.apache.org/~jgallimore/images/server_step_6.jpg
+ [10]: http://people.apache.org/~jgallimore/images/server_step_11.jpg
+ [11]: http://people.apache.org/~jgallimore/images/server_step_12.jpg
+ [12]: http://people.apache.org/~jgallimore/images/server_step_13.jpg
http://git-wip-us.apache.org/repos/asf/tomee/blob/b93bd755/docs/securing-a-web-service.md
----------------------------------------------------------------------
diff --git a/docs/securing-a-web-service.md b/docs/securing-a-web-service.md
new file mode 100644
index 0000000..3c3ec18
--- /dev/null
+++ b/docs/securing-a-web-service.md
@@ -0,0 +1,242 @@
+index-group=Unrevised
+type=page
+status=published
+title=Securing a Web Service
+~~~~~~
+
+Web Services are a very common way to implement a Service Oriented
+Architecture (SOA).
+
+There are lots of web service standards/specifications (XML, SOAP, WSDL,
+UUDI, WS-*, ...) coming from organizations like W3C, OASIS, WS-I, ...
+And there are java web service standards like JAX-WS 1.x (JSR 181), JAX-WS
+2.0 (JSR 224).
+
+OpenEJB provides a standard way to implement web services transport
+protocol throughout the JAX-WS specification.
+Java basic standards for web services (JAX-WS) do lack some features that
+are required in most real world applications, e.g. standard ways for
+handling security and authentication (there is no java specification for
+Oasis's WS-Security specification).
+
+OpenEJB provides two mechanisms to secure webservices - HTTP authentication
+and WS-Security:
+
+HTTPS : works at the transport level, enables a point-to-point security.
+It has no impact on developments. It allows you :
+
+1. To secure data over the network with data encrypted during transport
+2. To identify the end user with SSLv3 with client certificate required
+3. OpenEJB supports BASIC authentication over HTTP(S), using the configured
+JAAS provider. This will honour any EJB security roles you have setup using
+@RolesAllowed. See the webservice-security example in the OpenEJB codebase [http://svn.apache.org/repos/asf/tomee/tomee/trunk/examples/](http://svn.apache.org/repos/asf/tomee/tomee/trunk/examples/)
+
+*Warning:
+Currently only BASIC is the only HTTP authentication mechanism available
+when running OpenEJB standalone or in a unit test, but we hope to support
+DIGEST in the future.*
+
+
+WS-Security: works at the message (SOAP) level, enables a higher-level
+security,
+Nowadays, SOAP implementations use other protocols than just HTTP so we
+need to apply security to the message itself and not only at the transport
+layer. Moreover, HTTPS can only be used for securing point-to-point
+services which tend to decrease with Enterprise Service Bus for example.
+
+The Oasis organization has defined a standard (part of well-known WS-*)
+which aims at providing high level features in the context of web services:
+WS-Security. It provides a standard way to secure your services above and
+beyond transport level protocols such as HTTPS. WS-Security relies on other
+standards like XML-Encryption.
+
+Main features are:
+
+1. Timestamp a message,
+2. Pass credentials (plain text and/or ciphered) between services,
+3. Sign messages,
+4. Encrypt messages or part of messages.
+
+Again, JAX-WS doesn't standardize security for web services. OpenEJB
+provides a common and highly configurable way to configure WS-Security in
+association with the JAX-WS usage without vendor dependence. Internally,
+OpenEJB integrates Apache WSS4J as the WS-Security implementation. To use
+the integration, you will need to configure WSS4J using the
+*openejb-jar.xml*.
+
+*Warning:
+the proposed WS-Security integration is only used at server side.
+Currently, WS-Security client configuration is not managed by OpenEJB. You
+can use the JAX-WS API to create a stub and then rely on the implementation
+to set up WS-Security properties.*
+
+This configuration file lets you set up incoming and outgoing security
+parameters. Incoming and outgoing configuration is independent so that you
+can configure either one or the other or both. You can decide to check
+client credentials for incoming messages and sign outgoing messages
+(response).
+
+<a name="SecuringaWebService-Configurationprinciples"></a>
+# Configuration principles
+The configuration is made in the *openejb-jar.xml*. Each endpoint web
+service can provide a set of properties to customize WS-Security behavior
+through the <properties> element. The content of this element is consistent
+with the overall structure of *openejb.xml*. The format for properties is
+the same as if you would use a common java property file.
+
+
+
+ <properties>
+ wss4j.in.action = UsernameToken
+ wss4j.in.passwordType = PasswordDigest
+ wss4j.in.passwordCallbackClass=org.superbiz.calculator.CustomPasswordHandler
+ </properties>
+
+
+
+In order to recover WSS4J properties both for input and output, we use
+naming conventions.
+Each property is made of
+ <wss4j>.<in|out>.<wss4j property name>=<wss4j property value>
+
+For example : *wss4j.in.action = UsernameToken*
+
+<a name="SecuringaWebService-UsernameToken(Passworddigest)example"></a>
+# Username Token (Password digest) example
+<a name="SecuringaWebService-Excerptfrom*openejb-jar.xml*."></a>
+#### Excerpt from *openejb-jar.xml*.
+
+
+ <openejb-jar xmlns="http://tomee.apache.org/xml/ns/openejb-jar-2.2">
+ <enterprise-beans>
+ ...
+ <session>
+ <ejb-name>CalculatorImpl</ejb-name>
+ <web-service-security>
+ <security-realm-name/>
+ <transport-guarantee>NONE</transport-guarantee>
+ <auth-method>WS-SECURITY</auth-method>
+ <properties>
+ wss4j.in.action = UsernameToken
+ wss4j.in.passwordType = PasswordDigest
+ wss4j.in.passwordCallbackClass=org.superbiz.calculator.CustomPasswordHandler
+ </properties>
+ </web-service-security>
+ </session>
+ ...
+ </enterprise-beans>
+ </openejb-jar>
+
+
+<a name="SecuringaWebService-Requestsentbytheclient."></a>
+#### Request sent by the client.
+This request contains SOAP headers to manage security. You can see
+*UsernameToken* tag from the WS-Security specification.
+
+ POST /CalculatorImplUsernameTokenHashedPassword HTTP/1.1
+ Content-Type: text/xml; charset=UTF-8
+ SOAPAction: ""
+ Accept: *
+ Cache-Control: no-cache
+ Pragma: no-cache
+ User-Agent: Java/1.5.0_05
+ Host: 127.0.0.1:8204
+ Connection: keep-alive
+ Transfer-Encoding: chunked
+
+ 524
+ <soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
+ <soap:Header>
+ <wsse:Security xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd" soap:mustUnderstand="1">
+ <wsse:UsernameToken xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd"
+ wsu:Id="UsernameToken-22402238"
+ xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd">
+ <wsse:Username xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd">jane</wsse:Username>
+ <wsse:Password Type="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-username-token-profile-1.0#PasswordDigest"
+ xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd">tf7k3a4GREIt1xec/KXVmBdRNIg=</wsse:Password>
+ <wsse:Nonce xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd">cKhUhmjQ1hGYPsdOLez5kA==</wsse:Nonce>
+ <wsu:Created xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd">2009-04-14T20:16:26.203Z</wsu:Created>
+ </wsse:UsernameToken>
+ </wsse:Security>
+ </soap:Header>
+ <soap:Body>
+ <ns1:sum xmlns:ns1="http://superbiz.org/wsdl">
+ <arg0>4</arg0>
+ <arg1>6</arg1>
+ </ns1:sum>
+ </soap:Body>
+ </soap:Envelope>
+
+
+<a name="SecuringaWebService-Theresponsereturnedfromtheserver."></a>
+#### The response returned from the server.
+
+ HTTP/1.1 200 OK
+ Content-Length: 200
+ Connection: close
+ Content-Type: text/xml; charset=UTF-8
+ Server: OpenEJB/??? (unknown os)
+
+ <soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
+ <soap:Body>
+ <ns1:sumResponse xmlns:ns1="http://superbiz.org/wsdl">
+ <return>10</return>
+ </ns1:sumResponse>
+ </soap:Body>
+ </soap:Envelope>
+
+
+<a name="SecuringaWebService-JAASwithWS-Security"></a>
+# JAAS with WS-Security
+
+@RolesAllowed doesn't work straight off with WS-Security, but you can add
+calls to the OpenEJB SecurityService to login to a JAAS provider to a
+CallbackHandler. Once you have done this, any permissions configured with
+@RolesAllowed should be honoured.
+
+Here is a snippet from the webservice-ws-security example demonstrating
+this:
+
+
+ public class CustomPasswordHandler implements CallbackHandler {
+
+ public void handle(Callback[] callbacks) throws IOException, UnsupportedCallbackException {
+ WSPasswordCallback pc = (WSPasswordCallback) callbacks[0];
+
+ if (pc.getUsage() == WSPasswordCallback.USERNAME_TOKEN) {
+ // TODO get the password from the users.properties if possible
+ pc.setPassword("waterfall");
+
+ } else if (pc.getUsage() == WSPasswordCallback.DECRYPT) {
+
+ pc.setPassword("serverPassword");
+
+ } else if (pc.getUsage() == WSPasswordCallback.SIGNATURE) {
+
+ pc.setPassword("serverPassword");
+
+ }
+
+ if ((pc.getUsage() == WSPasswordCallback.USERNAME_TOKEN) || (pc.getUsage() == WSPasswordCallback.USERNAME_TOKEN_UNKNOWN)) {
+
+ SecurityService securityService = SystemInstance.get().getComponent(SecurityService.class);
+ Object token = null;
+ try {
+ securityService.disassociate();
+
+ token = securityService.login(pc.getIdentifer(), pc.getPassword());
+ securityService.associate(token);
+
+ } catch (LoginException e) {
+ e.printStackTrace();
+ throw new SecurityException("wrong password");
+ }
+ }
+ }
+ }
+
+
+
+<a name="SecuringaWebService-Examples"></a>
+# Examples
+A full example (webservice-ws-security) is available with OpenEJB Examples.
http://git-wip-us.apache.org/repos/asf/tomee/blob/b93bd755/docs/security-annotations.md
----------------------------------------------------------------------
diff --git a/docs/security-annotations.md b/docs/security-annotations.md
new file mode 100644
index 0000000..f951cd6
--- /dev/null
+++ b/docs/security-annotations.md
@@ -0,0 +1,296 @@
+index-group=Unrevised
+type=page
+status=published
+title=Security Annotations
+~~~~~~
+This page shows the correct usage of the security related annotations:
+
+ - javax.annotation.security.RolesAllowed
+ - javax.annotation.security.PermitAll
+ - javax.annotation.security.DenyAll
+ - javax.annotation.security.RunAs
+ - javax.annotation.security.DeclareRoles
+
+<a name="SecurityAnnotations-Basicidea"></a>
+## Basic idea
+
+- By default all methods of a business interface are accessible, logged in
+or not
+- The annotations go on the bean class, not the business interface
+- Security annotations can be applied to entire class and/or individual
+methods
+- The names of any security roles used must be declared via @DeclareRoles
+
+<a name="SecurityAnnotations-Norestrictions"></a>
+## No restrictions
+
+Allow anyone logged in or not to invoke 'svnCheckout'.
+
+These three examples are all equivalent.
+
+
+ @Stateless
+ public class OpenSourceProjectBean implements Project {
+
+ public String svnCheckout(String s) {
+ return s;
+ }
+ }
+
+
+ @Stateless
+ @PermitAll
+ public class OpenSourceProjectBean implements Project {
+
+ public String svnCheckout(String s) {
+ return s;
+ }
+ }
+
+
+ @Stateless
+ public class OpenSourceProjectBean implements Project {
+
+ @PermitAll
+ public String svnCheckout(String s) {
+ return s;
+ }
+ }
+
+
+ - Allow anyone logged in or not to invoke 'svnCheckout'.
+
+<a name="SecurityAnnotations-RestrictingaMethod"></a>
+## Restricting a Method
+
+Restrict the 'svnCommit' method to only individuals logged in and part of
+the "committer" role. Note that more than one role can be listed.
+
+
+ @Stateless
+ @DeclareRoles({"committer"})
+ public class OpenSourceProjectBean implements Project {
+
+ @RolesAllowed({"committer"})
+ public String svnCommit(String s) {
+ return s;
+ }
+
+ public String svnCheckout(String s) {
+ return s;
+ }
+ }
+
+
+ - Allow only logged in users in the "committer" role to invoke
+'svnCommit'.
+ - Allow anyone logged in or not to invoke 'svnCheckout'.
+
+
+<a name="SecurityAnnotations-DeclareRoles"></a>
+## DeclareRoles
+
+You need to update the @DeclareRoles when referencing roles via
+isCallerInRole(roleName).
+
+
+ @Stateless
+ @DeclareRoles({"committer", "contributor"})
+ public class OpenSourceProjectBean implements Project {
+
+ @Resource SessionContext ctx;
+
+ @RolesAllowed({"committer"})
+ public String svnCommit(String s) {
+ ctx.isCallerInRole("committer"); // Referencing a Role
+ return s;
+ }
+
+ @RolesAllowed({"contributor"})
+ public String submitPatch(String s) {
+ return s;
+ }
+ }
+
+
+<a name="SecurityAnnotations-Restrictingallmethodsinaclass"></a>
+## Restricting all methods in a class
+
+Placing the annotation at the class level changes the default of PermitAll
+
+
+ @Stateless
+ @DeclareRoles({"committer"})
+ @RolesAllowed({"committer"})
+ public class OpenSourceProjectBean implements Project {
+
+ public String svnCommit(String s) {
+ return s;
+ }
+
+ public String svnCheckout(String s) {
+ return s;
+ }
+
+ public String submitPatch(String s) {
+ return s;
+ }
+ }
+
+
+- Allow only logged in users in the "committer" role to invoke 'svnCommit',
+'svnCheckout' or 'submitPatch'.
+
+<a name="SecurityAnnotations-Mixingclassandmethodlevelrestrictions"></a>
+## Mixing class and method level restrictions
+
+Security annotations can be used at the class level and method level at the
+same time. These rules do not stack, so marking 'submitPatch' overrides
+the default of "committers".
+
+
+ @Stateless
+ @DeclareRoles({"committer", "contributor"})
+ @RolesAllowed({"committer"})
+ public class OpenSourceProjectBean implements Project {
+
+ public String svnCommit(String s) {
+ return s;
+ }
+
+ public String svnCheckout(String s) {
+ return s;
+ }
+
+ @RolesAllowed({"contributor"})
+ public String submitPatch(String s) {
+ return s;
+ }
+ }
+
+
+ - Allow only logged in users in the "committer" role to invoke 'svnCommit'
+or 'svnCheckout'
+ - Allow only logged in users in the "contributor" role to invoke
+'submitPatch'.
+
+<a name="SecurityAnnotations-PermitAll"></a>
+## PermitAll
+
+When annotating a bean class with @RolesAllowed, the @PermitAll annotation
+becomes very useful on individual methods to open them back up again.
+
+
+ @Stateless
+ @DeclareRoles({"committer", "contributor"})
+ @RolesAllowed({"committer"})
+ public class OpenSourceProjectBean implements Project {
+
+ public String svnCommit(String s) {
+ return s;
+ }
+
+ @PermitAll
+ public String svnCheckout(String s) {
+ return s;
+ }
+
+ @RolesAllowed({"contributor"})
+ public String submitPatch(String s) {
+ return s;
+ }
+ }
+
+
+ - Allow only logged in users in the "committer" role to invoke
+'svnCommit'.
+ - Allow only logged in users in the "contributor" role to invoke
+'submitPatch'.
+ - Allow anyone logged in or not to invoke 'svnCheckout'.
+
+
+<a name="SecurityAnnotations-DenyAll"></a>
+## DenyAll
+
+The @DenyAll annotation can be used to restrict business interface access
+from anyone, logged in or not. The method is still invokable from within
+the bean class itself.
+
+
+ @Stateless
+ @DeclareRoles({"committer", "contributor"})
+ @RolesAllowed({"committer"})
+ public class OpenSourceProjectBean implements Project {
+
+ public String svnCommit(String s) {
+ return s;
+ }
+
+ @PermitAll
+ public String svnCheckout(String s) {
+ return s;
+ }
+
+ @RolesAllowed({"contributor"})
+ public String submitPatch(String s) {
+ return s;
+ }
+
+ @DenyAll
+ public String deleteProject(String s) {
+ return s;
+ }
+ }
+
+
+ - Allow only logged in users in the "committer" role to invoke
+'svnCommit'.
+ - Allow only logged in users in the "contributor" role to invoke
+'submitPatch'.
+ - Allow anyone logged in or not to invoke 'svnCheckout'.
+ - Allow *no one* logged in or not to invoke 'deleteProject'.
+
+<a name="SecurityAnnotations-IllegalUsage"></a>
+# Illegal Usage
+
+Generally, security restrictions cannot be made on AroundInvoke methods and
+most callbacks.
+
+The following usages of @RolesAllowed have no effect.
+
+
+ @Stateful
+ @DecalredRoles({"committer"})
+ public class MyStatefulBean implements MyBusinessInterface {
+
+ @PostConstruct
+ @RolesAllowed({"committer"})
+ public void constructed(){
+
+ }
+
+ @PreDestroy
+ @RolesAllowed({"committer"})
+ public void destroy(){
+
+ }
+
+ @AroundInvoke
+ @RolesAllowed({"committer"})
+ public Object invoke(InvocationContext invocationContext) throws
+Exception {
+ return invocationContext.proceed();
+ }
+
+ @PostActivate
+ @RolesAllowed({"committer"})
+ public void activated(){
+
+ }
+
+ @PrePassivate
+ @RolesAllowed({"committer"})
+ public void passivate(){
+
+ }
+ }
http://git-wip-us.apache.org/repos/asf/tomee/blob/b93bd755/docs/security.md
----------------------------------------------------------------------
diff --git a/docs/security.md b/docs/security.md
new file mode 100644
index 0000000..5ff4ed7
--- /dev/null
+++ b/docs/security.md
@@ -0,0 +1,148 @@
+index-group=Unrevised
+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/b93bd755/docs/securityservice-config.md
----------------------------------------------------------------------
diff --git a/docs/securityservice-config.md b/docs/securityservice-config.md
new file mode 100644
index 0000000..0856536
--- /dev/null
+++ b/docs/securityservice-config.md
@@ -0,0 +1,36 @@
+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/b93bd755/docs/service-locator.md
----------------------------------------------------------------------
diff --git a/docs/service-locator.md b/docs/service-locator.md
new file mode 100644
index 0000000..b4a58e9
--- /dev/null
+++ b/docs/service-locator.md
@@ -0,0 +1,171 @@
+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/b93bd755/docs/services.md
----------------------------------------------------------------------
diff --git a/docs/services.md b/docs/services.md
new file mode 100644
index 0000000..5cac11a
--- /dev/null
+++ b/docs/services.md
@@ -0,0 +1,20 @@
+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/b93bd755/docs/singleton-beans.md
----------------------------------------------------------------------
diff --git a/docs/singleton-beans.md b/docs/singleton-beans.md
new file mode 100644
index 0000000..1f67561
--- /dev/null
+++ b/docs/singleton-beans.md
@@ -0,0 +1,226 @@
+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/b93bd755/docs/singleton-ejb.md
----------------------------------------------------------------------
diff --git a/docs/singleton-ejb.md b/docs/singleton-ejb.md
new file mode 100644
index 0000000..38e039f
--- /dev/null
+++ b/docs/singleton-ejb.md
@@ -0,0 +1,6 @@
+index-group=Unrevised
+type=page
+status=published
+title=Singleton EJB
+~~~~~~
+{include:OPENEJBx30:Singleton Beans}
http://git-wip-us.apache.org/repos/asf/tomee/blob/b93bd755/docs/singletoncontainer-config.md
----------------------------------------------------------------------
diff --git a/docs/singletoncontainer-config.md b/docs/singletoncontainer-config.md
new file mode 100644
index 0000000..c630a8d
--- /dev/null
+++ b/docs/singletoncontainer-config.md
@@ -0,0 +1,56 @@
+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.
http://git-wip-us.apache.org/repos/asf/tomee/blob/b93bd755/docs/spring-and-openejb-3.0.md
----------------------------------------------------------------------
diff --git a/docs/spring-and-openejb-3.0.md b/docs/spring-and-openejb-3.0.md
new file mode 100644
index 0000000..7ac4cce
--- /dev/null
+++ b/docs/spring-and-openejb-3.0.md
@@ -0,0 +1,190 @@
+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/b93bd755/docs/spring-ejb-and-jpa.md
----------------------------------------------------------------------
diff --git a/docs/spring-ejb-and-jpa.md b/docs/spring-ejb-and-jpa.md
new file mode 100644
index 0000000..105f691
--- /dev/null
+++ b/docs/spring-ejb-and-jpa.md
@@ -0,0 +1,173 @@
+index-group=Unrevised
+type=page
+status=published
+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/b93bd755/docs/spring.md
----------------------------------------------------------------------
diff --git a/docs/spring.md b/docs/spring.md
new file mode 100644
index 0000000..6273dc9
--- /dev/null
+++ b/docs/spring.md
@@ -0,0 +1,124 @@
+index-group=Unrevised
+type=page
+status=published
+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)
+.