tomee-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From jlmonte...@apache.org
Subject [22/44] tomee git commit: TOMEE-2316 Convert Markdown files to Asciidoc in the docs folder - 9
Date Thu, 06 Dec 2018 08:53:07 GMT
TOMEE-2316 Convert Markdown files to Asciidoc in the docs folder - 9


Project: http://git-wip-us.apache.org/repos/asf/tomee/repo
Commit: http://git-wip-us.apache.org/repos/asf/tomee/commit/9b209c98
Tree: http://git-wip-us.apache.org/repos/asf/tomee/tree/9b209c98
Diff: http://git-wip-us.apache.org/repos/asf/tomee/diff/9b209c98

Branch: refs/heads/master
Commit: 9b209c980a4317e9e0e9e3144759d87a9b23d04a
Parents: 388460f
Author: Carlos Chacin <cchacin@gmail.com>
Authored: Wed Dec 5 22:07:25 2018 -0800
Committer: Carlos Chacin <cchacin@gmail.com>
Committed: Wed Dec 5 22:07:25 2018 -0800

----------------------------------------------------------------------
 docs/queue-config.adoc                        |  48 ++++
 docs/queue-config.md                          |  36 ---
 docs/quickstart.adoc                          |  69 +++++
 docs/quickstart.md                            |  71 -----
 docs/remote-server.adoc                       |  69 +++++
 docs/remote-server.md                         |  64 -----
 docs/resource-injection.adoc                  | 201 ++++++++++++++
 docs/resource-injection.md                    | 184 -------------
 docs/resource-ref-for-datasource.adoc         |  53 ++++
 docs/resource-ref-for-datasource.md           |  46 ----
 docs/running-a-standalone-openejb-server.adoc |  77 ++++++
 docs/running-a-standalone-openejb-server.md   |  95 -------
 docs/securing-a-web-service.adoc              | 235 ++++++++++++++++
 docs/securing-a-web-service.md                | 242 -----------------
 docs/security-annotations.adoc                | 292 ++++++++++++++++++++
 docs/security-annotations.md                  | 296 ---------------------
 docs/security.adoc                            | 200 ++++++++++++++
 docs/security.md                              | 148 -----------
 docs/securityservice-config.adoc              |  50 ++++
 docs/securityservice-config.md                |  36 ---
 docs/service-locator.adoc                     | 159 +++++++++++
 docs/service-locator.md                       | 171 ------------
 docs/services.adoc                            |  28 ++
 docs/services.md                              |  20 --
 docs/singleton-beans.adoc                     | 228 ++++++++++++++++
 docs/singleton-beans.md                       | 226 ----------------
 docs/singleton-ejb.adoc                       |   7 +
 docs/singleton-ejb.md                         |   6 -
 docs/singletoncontainer-config.adoc           |  69 +++++
 docs/singletoncontainer-config.md             |  56 ----
 30 files changed, 1785 insertions(+), 1697 deletions(-)
----------------------------------------------------------------------


http://git-wip-us.apache.org/repos/asf/tomee/blob/9b209c98/docs/queue-config.adoc
----------------------------------------------------------------------
diff --git a/docs/queue-config.adoc b/docs/queue-config.adoc
new file mode 100644
index 0000000..ac7dd91
--- /dev/null
+++ b/docs/queue-config.adoc
@@ -0,0 +1,48 @@
+# Queue Configuration
+:index-group: Unrevised
+:jbake-date: 2018-12-05
+:jbake-type: page
+:jbake-status: published
+
+
+A Queue 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.
+
+....
+<Resource id="myQueue" type="javax.jms.Queue">
+    destination = 
+</Resource>
+....
+
+Alternatively, a Queue 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`
+
+....
+myQueue = new://Resource?type=javax.jms.Queue
+myQueue.destination = 
+....
+
+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 Queue a warning will
+be logged. If a Queue is needed by the application and one is not
+declared, TomEE will create one dynamically using default settings.
+Multiple Queue declarations are allowed. # Supported Properties
+
+Property
+
+Type
+
+Default
+
+Description
+
+destination
+
+String
+
+Specifies the name of the queue

http://git-wip-us.apache.org/repos/asf/tomee/blob/9b209c98/docs/queue-config.md
----------------------------------------------------------------------
diff --git a/docs/queue-config.md b/docs/queue-config.md
deleted file mode 100644
index 51b30ed..0000000
--- a/docs/queue-config.md
+++ /dev/null
@@ -1,36 +0,0 @@
-index-group=Unrevised
-type=page
-status=published
-title=Queue Configuration
-~~~~~~
-
-
-A Queue 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.
-
-    <Resource id="myQueue" type="javax.jms.Queue">
-        destination = 
-    </Resource>
-
-Alternatively, a Queue 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`
-
-    myQueue = new://Resource?type=javax.jms.Queue
-    myQueue.destination = 
-
-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 Queue a warning will be logged.  If a Queue is needed by the application and one is not declared, TomEE will create one dynamically using default settings.  Multiple Queue declarations are allowed.
-# Supported Properties
-<table class="mdtable">
-<tr>
-<th>Property</th>
-<th>Type</th>
-<th>Default</th>
-<th>Description</th>
-</tr>
-<tr>
-  <td>destination</td>
-  <td>String</td>
-  <td></td>
-  <td>
-Specifies the name of the queue
-</td>
-</tr>
-</table>

http://git-wip-us.apache.org/repos/asf/tomee/blob/9b209c98/docs/quickstart.adoc
----------------------------------------------------------------------
diff --git a/docs/quickstart.adoc b/docs/quickstart.adoc
new file mode 100644
index 0000000..f8ce3f6
--- /dev/null
+++ b/docs/quickstart.adoc
@@ -0,0 +1,69 @@
+# Quickstart
+:index-group: Unrevised
+:jbake-date: 2018-12-05
+:jbake-type: page
+:jbake-status: published
+
+# Installation
+
+To install OpenEJB, simply link:downloads.html[download the latest
+binary] and unpack your zip or tar.gz into the directory where you want
+OpenEJB to live.
+
+Windows users can download the zip and unpack it with the WinZip
+program.
+
+Linux users can download the tar.gz and unpack it with the following
+command:
+
+_tar xzvf openejb-3.0.tar.gz_
+
+Congratulations, you've installed OpenEJB.
+
+If you've unpacked OpenEJB into the directory C:-3.0, for example, then
+this directory is your OPENEJB_HOME directory. The OPENEJB_HOME
+directory is referred to in various parts of the documentation, so it's
+good to remember where it is.
+
+# Using OpenEJB
+
+Now all you need to do is move to the bin directory in OPENEJB_HOME, the
+directory where OpenEJB was unpacked, and type:
+
+_openejb_
+
+For Windows users, that looks like this:
+
+*C:-3.0> bin
+
+For UNIX/Linux/Mac OS X users, that looks like this:
+
+`[user@host openejb-3.0](user@host-openejb-3.0.html) # ./bin/openejb`
+
+You really only need to know two commands to use OpenEJB,
+openejbx30:deploy-tool.html[deploy] and [start|OPENEJBx30:Startup] .
+Both are completely documented and have examples.
+
+For help information and command options, try this:
+
+__________________________________________
+openejb deploy --help openejb start --help
+__________________________________________
+
+For examples on using the start command and options, try this:
+
+________________________
+openejb start --examples
+________________________
+
+That's it!
+
+If you don't have any EJBs or clients to run, try the ubiquitous
+openejbx30:hello-world.html[Hello World] example.
+
+# Join the mailing list
+
+The OpenEJB User list is where the general OpenEJB community goes to ask
+questions, make suggestions, chat with other users, and keep a finger on
+the pulse of the project. More information about the user list and dev
+list can be found link:mailing-lists.html[here]

http://git-wip-us.apache.org/repos/asf/tomee/blob/9b209c98/docs/quickstart.md
----------------------------------------------------------------------
diff --git a/docs/quickstart.md b/docs/quickstart.md
deleted file mode 100644
index 5631362..0000000
--- a/docs/quickstart.md
+++ /dev/null
@@ -1,71 +0,0 @@
-index-group=Unrevised
-type=page
-status=published
-title=Quickstart
-~~~~~~
-<a name="Quickstart-Installation"></a>
-# Installation
-
-
-To install OpenEJB, simply [download the latest binary](downloads.html)
- and unpack your zip or tar.gz into the directory where you want OpenEJB to
-live.
-
-Windows users can download the zip and unpack it with the WinZip program.
-
-Linux users can download the tar.gz and unpack it with the following
-command:
-
-*tar xzvf openejb-3.0.tar.gz*
-
-
-Congratulations, you've installed OpenEJB.
-
-If you've unpacked OpenEJB into the directory C:\openejb-3.0, for example,
-then this directory is your OPENEJB_HOME directory. The OPENEJB_HOME
-directory is referred to in various parts of the documentation, so it's
-good to remember where it is.
-
-<a name="Quickstart-UsingOpenEJB"></a>
-# Using OpenEJB
-
-
-Now all you need to do is move to the bin directory in OPENEJB_HOME, the
-directory where OpenEJB was unpacked, and type:
-
-*openejb*
-
-For Windows users, that looks like this:
-
-*C:\openejb-3.0> bin\openejb*
-
-For UNIX/Linux/Mac OS X users, that looks like this:
-
-`[user@host openejb-3.0](user@host-openejb-3.0.html)
-# ./bin/openejb`
-
-You really only need to know two commands to use OpenEJB, [deploy](openejbx30:deploy-tool.html)
- and [start|OPENEJBx30:Startup]
-. Both are completely documented and have examples.
-
-For help information and command options, try this:
-
-> openejb deploy --help
-> openejb start --help
-
-For examples on using the start command and options, try this:
-
-> openejb start --examples
-
-That's it!
-
-If you don't have any EJBs or clients to run, try the ubiquitous [Hello World](openejbx30:hello-world.html)
- example.
-
-<a name="Quickstart-Jointhemailinglist"></a>
-# Join the mailing list
-
-The OpenEJB User list is where the general OpenEJB community goes to ask
-questions, make suggestions, chat with other users, and keep a finger on
-the pulse of the project. More information about the user list and dev list
-can be found [here](mailing-lists.html)

http://git-wip-us.apache.org/repos/asf/tomee/blob/9b209c98/docs/remote-server.adoc
----------------------------------------------------------------------
diff --git a/docs/remote-server.adoc b/docs/remote-server.adoc
new file mode 100644
index 0000000..8fdb19d
--- /dev/null
+++ b/docs/remote-server.adoc
@@ -0,0 +1,69 @@
+# Remote Server
+:index-group: Unrevised
+:jbake-date: 2018-12-05
+:jbake-type: page
+:jbake-status: published
+
+
+!http://www.openejb.org/images/diagram-remote-server.gif|valign=top,
+align=right, hspace=15! # 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.
+
+# Short version
+
+Using OpenEJB's default remote server implementation is pretty straight
+forward. You simply need to:
+
+[arabic]
+. Deploy your bean.
+. Start the server on the IP and Port you want, 25.14.3.92 and 4201 for
+example.
+. Use that information in your client to create an initial context
+. 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.html[OPENEJBx30:Deploy Tool]
+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
+openejbx30:hello-world.html[Hello World] 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/9b209c98/docs/remote-server.md
----------------------------------------------------------------------
diff --git a/docs/remote-server.md b/docs/remote-server.md
deleted file mode 100644
index 460dfc0..0000000
--- a/docs/remote-server.md
+++ /dev/null
@@ -1,64 +0,0 @@
-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/9b209c98/docs/resource-injection.adoc
----------------------------------------------------------------------
diff --git a/docs/resource-injection.adoc b/docs/resource-injection.adoc
new file mode 100644
index 0000000..7b4824b
--- /dev/null
+++ b/docs/resource-injection.adoc
@@ -0,0 +1,201 @@
+:index-group: Unrevised
+:jbake-date: 2018-12-05
+:jbake-type: page
+:jbake-status: published
+
+
+# @Resource
+Overview
+
+This example demonstrates the use of the injection of environment
+entries using *@Resource* 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
+___________________
+
+# The Code
+
+== 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*).
+
+==== @Resource annotation of a field
+
+....
+@Resource
+int maxLineItems = 10;
+....
+
+== 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).
+
+==== @Resource annotation of a setter method
+
+....
+@Resource
+public void setMaxLineItems(int maxLineItems) {
+    this.maxLineItems = maxLineItems;
+}
+....
+
+==== 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>
+....
+
+==== 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");
+   }
+}
+....
+
+# 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.
+
+==== 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);
+}
+....
+
+==== 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());
+    }
+}
+....
+
+# 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/9b209c98/docs/resource-injection.md
----------------------------------------------------------------------
diff --git a/docs/resource-injection.md b/docs/resource-injection.md
deleted file mode 100644
index ac019ed..0000000
--- a/docs/resource-injection.md
+++ /dev/null
@@ -1,184 +0,0 @@
-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/9b209c98/docs/resource-ref-for-datasource.adoc
----------------------------------------------------------------------
diff --git a/docs/resource-ref-for-datasource.adoc b/docs/resource-ref-for-datasource.adoc
new file mode 100644
index 0000000..c2e1ff9
--- /dev/null
+++ b/docs/resource-ref-for-datasource.adoc
@@ -0,0 +1,53 @@
+:index-group: Unrevised
+:jbake-date: 2018-12-05
+:jbake-type: page
+:jbake-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/9b209c98/docs/resource-ref-for-datasource.md
----------------------------------------------------------------------
diff --git a/docs/resource-ref-for-datasource.md b/docs/resource-ref-for-datasource.md
deleted file mode 100644
index d27fb04..0000000
--- a/docs/resource-ref-for-datasource.md
+++ /dev/null
@@ -1,46 +0,0 @@
-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/9b209c98/docs/running-a-standalone-openejb-server.adoc
----------------------------------------------------------------------
diff --git a/docs/running-a-standalone-openejb-server.adoc b/docs/running-a-standalone-openejb-server.adoc
new file mode 100644
index 0000000..acd1583
--- /dev/null
+++ b/docs/running-a-standalone-openejb-server.adoc
@@ -0,0 +1,77 @@
+# Running a standalone OpenEJB server
+:index-group: Unrevised
+:jbake-date: 2018-12-05
+:jbake-type: page
+:jbake-status: published
+
+
+# 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.
+
+image:http://people.apache.org/~jgallimore/images/server_step_4.jpg[http://people.apache.org/~jgallimore/images/server_step_4.jpg]
+
+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.
+
+image:http://people.apache.org/~jgallimore/images/server_step_5.jpg[http://people.apache.org/~jgallimore/images/server_step_5.jpg]
+
+Browse to, or enter the path to your copy of OpenEJB. Click on Finish.
+
+# Configuring the OpenEJB Server Open the Servers view (if it isn't
+already), and right click and select New->Server.
+
+image:http://people.apache.org/~jgallimore/images/server_step_8.jpg[http://people.apache.org/~jgallimore/images/server_step_8.jpg]
+
+Select OpenEJB 3.0.0 from the Apache category, ensure you have the
+OpenEJB runtime selected, and click Next.
+
+image:http://people.apache.org/~jgallimore/images/server_step_9.jpg[http://people.apache.org/~jgallimore/images/server_step_9.jpg]
+
+Select the EJB port for the server, and select Finish.
+
+image:http://people.apache.org/~jgallimore/images/server_step_10.jpg[http://people.apache.org/~jgallimore/images/server_step_10.jpg]
+
+# 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.
+
+image:http://people.apache.org/~jgallimore/images/server_step_1.jpg[http://people.apache.org/~jgallimore/images/server_step_1.jpg]
+
+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.
+
+image:http://people.apache.org/~jgallimore/images/server_step_2.jpg[http://people.apache.org/~jgallimore/images/server_step_2.jpg]
+
+Select the EJB Module facet, and the Java Facet. Remember to select your
+OpenEJB runtime too. Click Next.
+
+image:http://people.apache.org/~jgallimore/images/server_step_6.jpg[http://people.apache.org/~jgallimore/images/server_step_6.jpg]
+
+Enter the source folder for the EJBs in your project and click Finish.
+
+image:http://people.apache.org/~jgallimore/images/server_step_6.jpg[http://people.apache.org/~jgallimore/images/server_step_7.jpg]
+
+Now right click on your OpenEJB server in the servers view, and select
+Add and Remove Projects.
+
+image:http://people.apache.org/~jgallimore/images/server_step_11.jpg[http://people.apache.org/~jgallimore/images/server_step_11.jpg]
+
+Add your project to the server, and click Finish.
+
+image:http://people.apache.org/~jgallimore/images/server_step_12.jpg[http://people.apache.org/~jgallimore/images/server_step_12.jpg]
+
+To start the server, Right click on your OpenEJB server, and select
+Start.
+
+image:http://people.apache.org/~jgallimore/images/server_step_13.jpg[http://people.apache.org/~jgallimore/images/server_step_13.jpg]

http://git-wip-us.apache.org/repos/asf/tomee/blob/9b209c98/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
deleted file mode 100644
index ca81014..0000000
--- a/docs/running-a-standalone-openejb-server.md
+++ /dev/null
@@ -1,95 +0,0 @@
-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/9b209c98/docs/securing-a-web-service.adoc
----------------------------------------------------------------------
diff --git a/docs/securing-a-web-service.adoc b/docs/securing-a-web-service.adoc
new file mode 100644
index 0000000..05cfa33
--- /dev/null
+++ b/docs/securing-a-web-service.adoc
@@ -0,0 +1,235 @@
+# Securing a Web Service
+:index-group: Unrevised
+:jbake-date: 2018-12-05
+:jbake-type: page
+:jbake-status: published
+
+
+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 :
+
+[arabic]
+. To secure data over the network with data encrypted during transport
+. To identify the end user with SSLv3 with client certificate required
+. OpenEJB supports BASIC authentication over HTTP(S), using the
+configured JAAS provider. This will honour any EJB security roles you
+have setup using
+
+. See the webservice-security example in the OpenEJB codebase
+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:
+
+[arabic]
+. Timestamp a message,
+. Pass credentials (plain text and/or ciphered) between services,
+. Sign messages,
+. 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).
+
+# 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 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 .<in|out>.=
+
+For example : _wss4j.in.action = UsernameToken_
+
+# Username Token (Password digest) example #### 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>
+....
+
+==== 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>
+....
+
+==== 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>
+....
+
+# JAAS with WS-Security
+
+1 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 1 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");
+            }
+        }
+    }
+}
+....
+
+# Examples A full example (webservice-ws-security) is available with
+OpenEJB Examples.

http://git-wip-us.apache.org/repos/asf/tomee/blob/9b209c98/docs/securing-a-web-service.md
----------------------------------------------------------------------
diff --git a/docs/securing-a-web-service.md b/docs/securing-a-web-service.md
deleted file mode 100644
index 3c3ec18..0000000
--- a/docs/securing-a-web-service.md
+++ /dev/null
@@ -1,242 +0,0 @@
-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/9b209c98/docs/security-annotations.adoc
----------------------------------------------------------------------
diff --git a/docs/security-annotations.adoc b/docs/security-annotations.adoc
new file mode 100644
index 0000000..11e27f1
--- /dev/null
+++ b/docs/security-annotations.adoc
@@ -0,0 +1,292 @@
+# Security Annotations
+:index-group: Unrevised
+:jbake-date: 2018-12-05
+:jbake-type: page
+:jbake-status: published
+
+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
+
+== 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
+
+== 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'.
+
+== 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'.
+
+== 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;
+    }
+}
+....
+
+== 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'.
+
+== 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'.
+
+== 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'.
+
+== 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'.
+
+# 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/9b209c98/docs/security-annotations.md
----------------------------------------------------------------------
diff --git a/docs/security-annotations.md b/docs/security-annotations.md
deleted file mode 100644
index f951cd6..0000000
--- a/docs/security-annotations.md
+++ /dev/null
@@ -1,296 +0,0 @@
-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/9b209c98/docs/security.adoc
----------------------------------------------------------------------
diff --git a/docs/security.adoc b/docs/security.adoc
new file mode 100644
index 0000000..785c8d6
--- /dev/null
+++ b/docs/security.adoc
@@ -0,0 +1,200 @@
+# Security 
+:index-group: Configuration
+:jbake-date: 2018-12-05
+:jbake-type: page
+:jbake-status: published
+
+# 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
+http://java.sun.com/javase/6/docs/technotes/guides/security/jaas/JAASRefGuide.html[JAAS
+Reference Guide] .
+
+== PropertiesLoginModule
+
+Supported options:
+
+Option
+
+Description
+
+Required
+
+UsersFile
+
+name of the properties file that contains the users and their passwords
+
+_yes_
+
+GroupsFile
+
+name of the properties file that contains the groups and their member
+lists
+
+_yes_
+
+_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.
+
+== 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
+http://java.sun.com/javase/6/docs/technotes/guides/jdbc/[JDBC Guide]
+
+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:
+
+Option
+
+Description
+
+Required
+
+dataSourceName
+
+the name of a data source
+
+_yes_ (alternative 1)
+
+jdbcURL
+
+a standard JDBC URL
+
+_yes_ (alternative 2)
+
+jdbcDriver
+
+the fully qualified class name of the database driver
+
+no
+
+jdbcUser
+
+the user name for accessing the database
+
+no
+
+jdbcPassword
+
+the password for accessing the database
+
+no
+
+userSelect
+
+the SQL query that returns a list of users and their passwords
+
+_yes_
+
+groupSelect
+
+the SQL query that returns a list of users and groups (roles)
+
+_yes_
+
+digest
+
+the name of the digest algorithm (e.g. "MD5" or "SHA") for digest
+authentication
+
+no
+
+encoding
+
+the digest encoding, can be "hex" or "base64"
+
+no
+
+# 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
+http://java.sun.com/javase/6/docs/technotes/guides/security/jaas/JAASLMDevGuide.html[JAAS
+LoginModule Developer's Guide] 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.


Mime
View raw message