[prev in list] [next in list] [prev in thread] [next in thread]
List: openejb-development
Subject: Re: [tomee] branch tomee-7.1.x updated: Adding docs
From: David Jencks <david.a.jencks () gmail ! com>
Date: 2020-02-14 6:21:39
Message-ID: 5EAF154E-27AB-434D-BF5C-994AA281FF1E () gmail ! com
[Download RAW message or body]
Hi Jonathan,
Where did these come from? Did you write them all yourself on the 20th? :-) Or \
perhaps they are copied from master?
I really like tying all commits to jira issues so there's some explanation of the \
context and less opportunity to ask silly questions like this one… although I'd \
really like to know.
Similarly, 99e036881f9a0d409614d2744b256cb17dca47cc looks sort of similar for the \
7.0.x branch… are those also copied from the same place, perhaps master?
Many thanks,
David Jencks
> On Jan 20, 2020, at 8:41 AM, jgallimore@apache.org wrote:
>
> This is an automated email from the ASF dual-hosted git repository.
>
> jgallimore pushed a commit to branch tomee-7.1.x
> in repository https://gitbox.apache.org/repos/asf/tomee.git
>
>
> The following commit(s) were added to refs/heads/tomee-7.1.x by this push:
> new 9a3837d Adding docs
> 9a3837d is described below
>
> commit 9a3837d3a9ed4ab66680fb07be4b08e53c596416
> Author: Jonathan Gallimore <jon@jrg.me.uk>
> AuthorDate: Mon Jan 20 16:41:13 2020 +0000
>
> Adding docs
> ---
> docs/Configuring-in-tomee.adoc | 37 +
> docs/admin/.DS_Store | Bin 0 -> 6148 bytes
> docs/admin/cluster/index.adoc | 232 +++
> docs/admin/configuration/application.adoc | 100 ++
> docs/admin/configuration/containers.adoc | 585 ++++++++
> docs/admin/configuration/index.adoc | 25 +
> docs/admin/configuration/log4j2.adoc | 71 +
> docs/admin/configuration/resources.adoc | 570 +++++++
> docs/admin/configuration/server.adoc | 86 ++
> docs/admin/file-layout.adoc | 144 ++
> docs/admin/index.adoc | 7 +
> docs/advanced/.DS_Store | Bin 0 -> 6148 bytes
> docs/advanced/applicationcomposer/index.adoc | 76 +
> docs/advanced/client/jndi.adoc | 96 ++
> docs/advanced/index.adoc | 7 +
> docs/advanced/jms/jms-configuration.adoc | 67 +
> docs/advanced/setup/index.adoc | 141 ++
> docs/advanced/shading/index.adoc | 276 ++++
> docs/advanced/tomee-embedded/foo.ado | 0
> docs/advanced/tomee-embedded/index.adoc | 223 +++
> docs/alternate-descriptors.adoc | 124 ++
> docs/annotations,-xml-and-defaults.adoc | 22 +
> docs/app-clients-and-jndi.adoc | 74 +
> docs/application-composer/advanced.adoc | 111 ++
> docs/application-composer/getting-started.adoc | 234 +++
> docs/application-composer/history.adoc | 48 +
> docs/application-composer/index.adoc | 20 +
> docs/application-deployment-solutions.adoc | 92 ++
> docs/application-discovery-via-the-classpath.adoc | 111 ++
> docs/application-resources.adoc | 375 +++++
> docs/arquillian-available-adapters.adoc | 319 ++++
> docs/arquillian-getting-started.adoc | 44 +
> docs/basics---getting-things.adoc | 108 ++
> docs/basics---security.adoc | 55 +
> docs/basics---transactions.adoc | 67 +
> docs/bouncy-castle.adoc | 40 +
> docs/built-in-type-converters.adoc | 101 ++
> docs/callbacks.adoc | 169 +++
> docs/changing-jms-implementations.adoc | 161 ++
> docs/client-server-transports.adoc | 39 +
> docs/clients.adoc | 101 ++
> docs/collapsed-ear.adoc | 49 +
> docs/common-datasource-configurations.adoc | 123 ++
> docs/common-errors.adoc | 31 +
> docs/common-persistenceprovider-properties.adoc | 50 +
> docs/concepts.adoc | 83 ++
> docs/configuration.adoc | 151 ++
> docs/configuring-containers-in-tests.adoc | 30 +
> docs/configuring-datasources-in-tests.adoc | 68 +
> docs/configuring-datasources.adoc | 204 +++
> docs/configuring-durations.adoc | 70 +
> docs/configuring-javamail.adoc | 44 +
> docs/configuring-logging-in-tests.adoc | 121 ++
> docs/configuring-persistenceunits-in-tests.adoc | 160 ++
> docs/constructor-injection.adoc | 103 ++
> docs/containers-and-resources.adoc | 474 ++++++
> docs/contrib/.DS_Store | Bin 0 -> 6148 bytes
> docs/contrib/debug/debug-intellij.adoc | 182 +++
> docs/contrib/debug/idea1.png | Bin 0 -> 48995 bytes
> docs/contrib/debug/idea10.png | Bin 0 -> 54939 bytes
> docs/contrib/debug/idea2.png | Bin 0 -> 36567 bytes
> docs/contrib/debug/idea3.png | Bin 0 -> 20165 bytes
> docs/contrib/debug/idea4.png | Bin 0 -> 55824 bytes
> docs/contrib/debug/idea6.png | Bin 0 -> 19286 bytes
> docs/contrib/debug/idea7.png | Bin 0 -> 19805 bytes
> docs/contrib/debug/idea8.png | Bin 0 -> 55721 bytes
> docs/contrib/debug/idea9.png | Bin 0 -> 19477 bytes
> docs/custom-injection.adoc | 209 +++
> docs/datasource-configuration-by-creator.adoc | 160 ++
> docs/datasource-password-encryption.adoc | 168 +++
> docs/deamon/lin-service.adoc | 44 +
> docs/deamon/win-service.adoc | 140 ++
> docs/declaring-references.adoc | 5 +
> docs/deploy-tool.adoc | 167 +++
> docs/deploying-in-tomee.adoc | 73 +
> docs/deployment-id.adoc | 236 +++
> docs/deployments.adoc | 153 ++
> docs/details-on-openejb-jar.adoc | 156 ++
> docs/developer/.DS_Store | Bin 0 -> 6148 bytes
> docs/developer/classloading/index.adoc | 58 +
> docs/developer/configuration/cxf.adoc | 93 ++
> docs/developer/ide/index.adoc | 23 +
> docs/developer/index.adoc | 7 +
> docs/developer/json/index.adoc | 205 +++
> docs/developer/migration/tomee-1-to-7.adoc | 33 +
> .../testing/applicationcomposer/index.adoc | 335 +++++
> docs/developer/testing/arquillian/index.adoc | 421 ++++++
> docs/developer/testing/index.adoc | 9 +
> docs/developer/testing/other/index.adoc | 134 ++
> docs/developer/tools/gradle-plugins.adoc | 50 +
> docs/developer/tools/index.adoc | 8 +
> docs/developer/tools/maven-plugins.adoc | 13 +
> .../developer/tools/maven/applicationcomposer.adoc | 47 +
> docs/developer/tools/maven/embedded.adoc | 53 +
> docs/developer/tools/maven/tomee.adoc | 184 +++
> docs/docs.adoc | 26 +
> docs/documentation.adoc | 103 ++
> docs/documentation.old.adoc | 98 ++
> docs/dynamic-datasource.adoc | 224 +++
> docs/eclipse-plugin.adoc | 41 +
> docs/ejb-failover.adoc | 93 ++
> docs/ejb-local-ref.adoc | 56 +
> docs/ejb-over-ssl.adoc | 137 ++
> docs/ejb-ref.adoc | 55 +
> docs/ejb-refs.adoc | 199 +++
> docs/ejb-request-logging.adoc | 158 ++
> docs/ejbd-transport.adoc | 212 +++
> docs/embedded-and-remotable.adoc | 177 +++
> docs/embedded-configuration.adoc | 138 ++
> docs/embedding.adoc | 34 +
> docs/failover-logging.adoc | 58 +
> docs/faq.adoc | 108 ++
> docs/features.adoc | 5 +
> docs/from-glassfish-to-tomee.adoc | 11 +
> ...l-testing-with-openejb,-jetty-and-selenium.adoc | 238 +++
> docs/generating-ejb-3-annotations.adoc | 65 +
> docs/getting-started.adoc | 178 +++
> docs/hello-world.adoc | 263 ++++
> docs/hibernate.adoc | 103 ++
> docs/installation-drop-in-war.adoc | 55 +
> docs/installation.adoc | 92 +-
> docs/{installation.adoc => installing-tomee.adoc} | 18 +-
> docs/java-compatibility.adoc | 11 +-
> docs/java7.adoc | 40 +
> docs/javaagent-with-maven-surefire.adoc | 38 +
> docs/javaagent.adoc | 66 +
> docs/javaee7-status.adoc | 218 +++
> docs/jms-resources-and-mdb-container.adoc | 286 ++++
> docs/jndi-names.adoc | 401 +++++
> docs/jpa-concepts.adoc | 227 +++
> docs/jpa-usage.adoc | 48 +
> docs/local-client-injection.adoc | 87 ++
> docs/local-server.adoc | 56 +
> docs/lookup-of-other-ejbs-example.adoc | 148 ++
> docs/manual-installation.adoc | 148 ++
> docs/maven.adoc | 63 +
> docs/maven/build-mojo.adoc | 1169 +++++++++++++++
> docs/maven/configtest-mojo.adoc | 1086 ++++++++++++++
> docs/maven/debug-mojo.adoc | 1139 ++++++++++++++
> docs/maven/deploy-mojo.adoc | 196 +++
> docs/maven/exec-mojo.adoc | 1277 ++++++++++++++++
> docs/maven/favicon.ico | Bin 0 -> 3638 bytes
> docs/maven/help-mojo.adoc | 115 ++
> docs/maven/index.adoc | 178 +++
> docs/maven/list-mojo.adoc | 132 ++
> docs/maven/run-mojo.adoc | 1139 ++++++++++++++
> docs/maven/start-mojo.adoc | 1139 ++++++++++++++
> docs/maven/stop-mojo.adoc | 1086 ++++++++++++++
> docs/maven/undeploy-mojo.adoc | 159 ++
> docs/multicast-discovery.adoc | 93 ++
> docs/multiple-business-interface-hazzards.adoc | 209 +++
> docs/multipoint-considerations.adoc | 31 +
> docs/multipoint-discovery.adoc | 87 ++
> docs/multipoint-recommendations.adoc | 153 ++
> docs/multipulse-discovery.adoc | 112 ++
> docs/new-in-openejb-3.0.adoc | 157 ++
> docs/openejb-3.adoc | 69 +
> docs/openejb-binaries.adoc | 34 +
> docs/openejb-eclipse-plugin.adoc | 22 +
> docs/openejb-jsr-107-integration.adoc | 24 +
> docs/openejb.xml.adoc | 100 ++
> docs/openjpa.adoc | 132 ++
> docs/persistence-context.adoc | 61 +
> docs/persistence-unit-ref.adoc | 95 ++
> docs/properties-listing.adoc | 729 +++++++++
> docs/properties-tool.adoc | 219 +++
> docs/property-overriding.adoc | 64 +
> docs/provisioning.adoc | 102 ++
> docs/quickstart.adoc | 69 +
> docs/refcard/.DS_Store | Bin 0 -> 6148 bytes
> docs/refcard/css/cypher_main.css | 493 +++++++
> docs/refcard/css/github.min.css | 129 ++
> docs/refcard/css/refcard.css | 491 ++++++
> docs/refcard/css/style.css | 102 ++
> docs/refcard/favicon.ico | Bin 0 -> 3638 bytes
> docs/refcard/images/github.png | Bin 0 -> 2473 bytes
> docs/refcard/images/tomee.png | Bin 0 -> 1914 bytes
> docs/refcard/js/highlight.min.js | 1 +
> docs/refcard/js/jquery.min.js | 5 +
> docs/refcard/js/modernizr.custom.2.6.2.js | 4 +
> docs/refcard/js/refcard.js | 74 +
> docs/refcard/refcard.html | 1556 ++++++++++++++++++++
> docs/remote-server.adoc | 72 +
> docs/resource-injection.adoc | 209 +++
> docs/resource-ref-for-datasource.adoc | 55 +
> docs/running-a-standalone-openejb-server.adoc | 77 +
> docs/securing-a-web-service.adoc | 240 +++
> docs/security-annotations.adoc | 301 ++++
> docs/security.adoc | 201 +++
> docs/service-locator.adoc | 168 +++
> docs/services.adoc | 28 +
> docs/singleton-beans.adoc | 232 +++
> docs/singleton-ejb.adoc | 7 +
> docs/spring-and-openejb-3.0.adoc | 238 +++
> docs/spring-ejb-and-jpa.adoc | 197 +++
> docs/spring.adoc | 139 ++
> docs/ssh.adoc | 63 +
> docs/standalone-server.adoc | 24 +
> docs/startup.adoc | 272 ++++
> docs/system-properties-files.adoc | 25 +
> docs/system-properties.adoc | 71 +
> docs/telnet-console.adoc | 165 +++
> docs/tip-concurrency.adoc | 34 +
> docs/tip-jersey-client.adoc | 35 +
> docs/tip-weblogic.adoc | 22 +
> docs/tomcat-object-factory.adoc | 17 +
> docs/tomee-and-eclipse.adoc | 140 ++
> docs/tomee-and-hibernate.adoc | 173 +++
> docs/tomee-and-intellij.adoc | 82 ++
> docs/tomee-and-netbeans.adoc | 107 ++
> docs/tomee-and-security.adoc | 56 +
> docs/tomee-and-webspheremq.adoc | 26 +
> docs/tomee-cluster.txt | 72 +
> docs/tomee-directory-structure.adoc | 25 +
> docs/tomee-embedded-maven-plugin.adoc | 680 +++++++++
> docs/tomee-jaas.adoc | 93 ++
> docs/tomee-logging-in-eclipse.adoc | 19 +
> docs/tomee-logging.adoc | 32 +
> docs/tomee-mp-getting-started.adoc | 103 ++
> docs/tomee-version-policies.adoc | 55 +
> docs/tomee-webaccess.adoc | 18 +
> docs/tomee-webapp.adoc | 75 +
> docs/transaction-annotations.adoc | 230 +++
> docs/understanding-callbacks.adoc | 98 ++
> docs/understanding-the-directory-layout.adoc | 74 +
> docs/unix-daemon.adoc | 158 ++
> docs/validation-tool.adoc | 143 ++
> docs/version-checker.adoc | 13 +
> 228 files changed, 34585 insertions(+), 78 deletions(-)
>
> diff --git a/docs/Configuring-in-tomee.adoc b/docs/Configuring-in-tomee.adoc
> new file mode 100644
> index 0000000..ce572e0
> --- /dev/null
> +++ b/docs/Configuring-in-tomee.adoc
> @@ -0,0 +1,37 @@
> += Apache TomEE configuration
> +:index-group: Configuration
> +:jbake-date: 2018-12-05
> +:jbake-type: page
> +:jbake-status: published
> +
> +
> +== Configuring Resources:
> +
> +* Drivers are dropped into tomeeDir/lib
> +* Resources are configured in tomeeDir/conf/tomee.xml. +
> +* The configurations take a very simple (XML+Property-file) syntax.
> +* Tag names match annotation names
> +
> +For example,
> +
> +[source,java]
> +----
> +@Resource DataSource moviesDatabase
> +----
> +
> +is injected with the following resource:
> +
> +[source,xml]
> +----
> +<Resource id="moviesDatabase" type="DataSource">
> +JdbcDriver org.hsqldb.jdbcDriver
> +JdbcUrl jdbc:mysql:localhost:3306/moviesdb
> +UserName sa
> +Password secret
> +JtaManaged true
> +</Resource>
> +----
> +
> +For more on how to configure, read through
> +link:/configuring-datasources.html[configuring-datasources],
> +link:containers-and-resources.html[containers-and-resources] docs.
> diff --git a/docs/admin/.DS_Store b/docs/admin/.DS_Store
> new file mode 100644
> index 0000000..2c461b9
> Binary files /dev/null and b/docs/admin/.DS_Store differ
> diff --git a/docs/admin/cluster/index.adoc b/docs/admin/cluster/index.adoc
> new file mode 100644
> index 0000000..c2927f8
> --- /dev/null
> +++ b/docs/admin/cluster/index.adoc
> @@ -0,0 +1,232 @@
> += Clustering and High Availability (HA)
> +:jbake-date: 2018-12-05
> +:jbake-type: page
> +:jbake-status: published
> +
> +== Session clustering
> +
> +TomEE fully relies on Tomcat clustering: \
> https://tomcat.apache.org/tomcat-7.0-doc/cluster-howto.html[Tomcat Clustering]. +
> +The configuration is mainly in `conf/server.xml` and since TomEE 7 CDI \
> `@SessionScoped` is transparently clustered +through the session.
> +
> +== Hazelcast as session provider
> +
> +Hazelcast did a post on this topic on \
> https://hazelcast.com/use-cases/web-session-clustering/session-clustering-tomee/[Session \
> Clustering With TomEE]. +
> +Tomitribe also demonstrated you can distributed `@Stateful` beans easily relying \
> on hazelcast: https://github.com/tomitribe/hazelcast-tomee-poc[Hazelcast TomEE \
> PoC]. +
> +== Load balancing
> +
> +TomEE being a HTTP server all HTTP load balancer such as HTTPd (a.k.a. Apache2), \
> ngnix, F5 etc... will work. +
> +More documentation on HTTPd link can be found on \
> https://tomcat.apache.org/connectors-doc/webserver_howto/apache.html[Tomcat] \
> website. +
> +== EJBd
> +
> +If you use the EJBd protocol (`@Remote` EJB proprietary protocol of TomEE) you can \
> get cluster features on the client +part.
> +
> +=== Multicast
> +
> +Multicast is the preferred way to broadcast the heartbeat on the network. The \
> simple technique of broadcasting a non-changing service URI on the network has \
> specific advantages to multicast. The URI itself is essentially stateless and there \
> is no "i'm alive" URI or an "i'm dead" URI. +
> +In this way the issues with UDP being unordered and unreliable melt away as state \
> is no longer a concern and packet sizes are always small. Complicated libraries \
> that ride atop UDP and attempt to offer reliability (retransmission) and ordering \
> on UDP can be avoided. As well the advantages UDP has over TCP are retained as \
> there are no java layers attempting to force UDP communication to be more TCP-like. \
> The simple design means UDP/Multicast is only used for discovery and from there on \
> ou [...] +
> +==== Server Configuration
> +
> +When you boot the server there should be a conf/multicast.properties file \
> containing: +
> +[source,properties]
> +----
> +server = org.apache.openejb.server.discovery.MulticastDiscoveryAgent
> +bind = 239.255.2.3
> +port = 6142
> +disabled = true
> +group = default
> +----
> +
> +Just need to enable that by setting disabled=false. All of the above settings \
> except server can be changed. The port and bind must be valid for general \
> multicast/udp network communication. +
> +The group setting can be changed to further group servers that may use the same \
> multicast channel. As shown below the client also has a group setting which can be \
> used to select an appropriate server from the multicast channel. +
> +IMPORTANT: for multicast to work you need to have ejbd activated as a normal \
> service. This can be done setting in `conf/system.properties` the entry: \
> `openejb.service.manager.class = org.apache.openejb.server.SimpleServiceManager`. +
> +NOTE: for multicast to work you need to have ejbd activated as a normal service. \
> This can be done setting in `conf/system.properties` the entry: \
> `openejb.service.manager.class = org.apache.openejb.server.SimpleServiceManager`. +
> +TIP: for multicast to work you need to have ejbd activated as a normal service. \
> This can be done setting in `conf/system.properties` the entry: \
> `openejb.service.manager.class = org.apache.openejb.server.SimpleServiceManager`. +
> +CAUTION: for multicast to work you need to have ejbd activated as a normal \
> service. This can be done setting in `conf/system.properties` the entry: \
> `openejb.service.manager.class = org.apache.openejb.server.SimpleServiceManager`. +
> +WARNING: for multicast to work you need to have ejbd activated as a normal \
> service. This can be done setting in `conf/system.properties` the entry: \
> `openejb.service.manager.class = org.apache.openejb.server.SimpleServiceManager`. +
> +===== Multicast Client
> +
> +The multicast functionality is not just for servers to find each other in a \
> cluster, it can also be used for EJB clients to discover a server. A special \
> multicast:// URL can be used in the InitialContext properties to signify that \
> multicast should be used to seed the connection process. Such as: +
> +[source,java]
> +----
> +Properties p = new Properties();
> +p.put(Context.INITIAL_CONTEXT_FACTORY,
> +"org.apache.openejb.client.RemoteInitialContextFactory");
> +p.put(Context.PROVIDER_URL, "multicast://239.255.2.3:6142?group=default");
> +InitialContext remoteContext = new InitialContext(p);
> +----
> +
> +The URL has optional query parameters such as schemes and group and timeout which \
> allow you to zero in on a particular type of service of a particular cluster group \
> as well as set how long you are willing to wait in the discovery process till \
> finally giving up. The first matching service that it sees "flowing" around on the \
> UDP stream is the one it picks and sticks to for that and subsequent requests, \
> ensuring UDP is only used when there are no other servers to talk to. +
> +Note that EJB clients do not need to use multicast to find a server. If the client \
> knows the URL of a server in the cluster, it may use it and connect directly to \
> that server, at which point that server will share the full list of its peers. +
> +===== Multicast Servers with TCP Clients
> +
> +Note that clients do not need to use multicast to communicate with servers. \
> Servers can use multicast to discover each other, but clients are still free to \
> connect to servers in the network using the server's TCP address. +
> +[source,java]
> +----
> +Properties p = new Properties();
> +p.put(Context.INITIAL_CONTEXT_FACTORY, \
> "org.apache.openejb.client.RemoteInitialContextFactory"); \
> +p.put(Context.PROVIDER_URL, "ejbd://192.168.1.30:4201"); +InitialContext \
> remoteContext = new InitialContext(p); +When the client connects, the server will \
> send the URLs of all the servers in the group and failover will take place \
> normally. +----
> +
> +==== Multipulse
> +
> +MultiPulse is an alternative multicast lookup that does not use a regular \
> heartbeat. Instead, servers listen for a multicast request packet (a pulse) to \
> which a response is then sent. Multicast network traffic is effectively reduced to \
> an absolute minimum. +
> +MultiPulse is only useful in network scenarios where both client and server can be \
> configured to send multicast UDP packets. +
> +===== Server Configuration
> +
> +After you boot the server for the first time the default configuration will create \
> the file conf/conf.d/multipulse.properties containing: +
> +[source,properties]
> +----
> +server = org.apache.openejb.server.discovery.MulticastPulseAgent
> +bind = 239.255.2.3
> +port = 6142
> +disabled = true
> +group = default
> +----
> +
> +You just need to enable the agent by setting disabled = false. It is advisable to \
> disable multicast in the multicast.properties file, or at least to use a different \
> bind address or port should you wish to use both. +
> +All of the above settings except server can be modified as required. The port and \
> bind must be valid for general multicast/udp network communication. +
> +The group setting can be changed to further group/cluster servers that may use the \
> same multicast channel. As shown below the client also has an optional group \
> setting which can be used to select an appropriate server cluster from the \
> multicast channel (See MultiPulse Client). +
> +The next step is to ensure that the advertised services are configured for \
> discovery. Edit the ejbd.properties file (and any other enabled services such as \
> http, etc.) and ensure that the discovery option is set to a value that remote \
> clients will be able to resolve. +
> +[source,properties]
> +----
> +server = org.apache.openejb.server.ejbd.EjbServer
> +bind = 0.0.0.0
> +port = 4201
> +disabled = false
> +threads = 20
> +discovery = ejb:ejbd://{bind}:{port}
> +----
> +
> +NOTE: If either 0.0.0.0 (IPv4) or [::] (IPv6) wildcard bind addresses are used \
> then the server will actually broadcast all of it's known public hosts to clients. \
> Clients will then cycle though and attempt to connect to the provided hosts until \
> successful. +
> +If localhost is used then only clients on the same physical machine will actually \
> 'see' the server response. +
> +===== MultiPulse Client
> +
> +The multipulse functionality is not just for servers to find each other in a \
> cluster, it can also be used for EJB clients to discover a server. A special \
> multipulse:// URL can be used in the InitialContext properties to signify that \
> multipulse should be used to seed the connection process. Such as: +
> +[source,java]
> +----
> +Properties p = new Properties();
> +p.put(Context.INITIAL_CONTEXT_FACTORY, \
> "org.apache.openejb.client.RemoteInitialContextFactory"); \
> +p.put(Context.PROVIDER_URL, \
> "multipulse://239.255.2.3:6142?group=default&timeout=250"); +InitialContext \
> remoteContext = new InitialContext(p); +----
> +
> +The URL has optional query parameters such as schemes and group and timeout which \
> allow you to zero in on a particular type of service of a particular cluster group \
> as well as set how long you are willing to wait in the discovery process till \
> finally giving up. The first matching service that it sees "flowing" around on the \
> UDP stream is the one it picks and sticks to for that and subsequent requests, \
> ensuring UDP is only used when there are no other servers to talk to. +
> +Note that EJB clients do not need to use multipulse to find a server. If the \
> client knows the URL of a server in the cluster, it may use it and connect directly \
> to that server, at which point that server will share the full list of its peers. +
> +Multicast Servers with TCP Clients
> +
> +Note that clients do not need to use multipulse to communicate with servers. \
> Servers can use multicast to discover each other, but clients are still free to \
> connect to servers in the network using the server's TCP address. +[source,java]
> +----
> +Properties p = new Properties();
> +p.put(Context.INITIAL_CONTEXT_FACTORY, \
> "org.apache.openejb.client.RemoteInitialContextFactory"); \
> +p.put(Context.PROVIDER_URL, "ejbd://192.168.1.30:4201"); +InitialContext \
> remoteContext = new InitialContext(p); +----
> +
> +When the client connects, the server will send the URLs of all the servers in the \
> group and failover will take place normally. +
> +==== Multipoint
> +
> +As TCP has no real broadcast functionality to speak of, communication of who is in \
> the network is achieved by each server having a physical connection to each other \
> server in the network. +
> +To join the network, the server must be configured to know the address of at least \
> one server in the network and connect to it. When it does both servers will \
> exchange the full list of all the other servers each knows about. Each server will \
> then connect to any new servers they've just learned about and repeat the processes \
> with those new servers. The end result is that everyone has a direct connection to \
> everyone 100% of the time, hence the made-up term "multipoint" to describe this sit \
> [...] +
> +On the client side things are similar. It needs to know the address of at least \
> one server in the network and be able to connect to it. When it does it will get \
> the full (and dynamically maintained) list of every server in the network. The \
> client doesn't connect to each of those servers immediately, but rather consults \
> the list in the event of a failover, using it to decide who to connect to next. +
> +The entire process is essentially the art of using a statically maintained list to \
> bootstrap getting the more valuable dynamically maintained list. +
> +===== Server Configuration
> +
> +In the server this list can be specified via the conf/multipoint.properties file \
> like so: +
> +[source,properties]
> +----
> +server = org.apache.openejb.server.discovery.MultipointDiscoveryAgent
> +bind = 127.0.0.1
> +port = 4212
> +disabled = false
> +initialServers = 192.168.1.20:4212, 192.168.1.30:4212, 192.168.1.40:4212
> +----
> +
> +The above configuration shows the server has an port 4212 open for connections by \
> other servers for multipoint communication. The initialServers list should be a \
> comma separated list of other similar servers on the network. Only one of the \
> servers listed is required to be running when this server starts up -- it is not \
> required to list all servers in the network. +
> +===== Client Configuration
> +
> +Configuration in the client is similar, but note that EJB clients do not \
> participate directly in multipoint communication and do not connect to the \
> multipoint port. The server list is simply a list of the regular ejbd:// urls that \
> a client normally uses to connect to a server. +
> +[source,java]
> +----
> +Properties p = new Properties();
> +p.put(Context.INITIAL_CONTEXT_FACTORY, \
> "org.apache.openejb.client.RemoteInitialContextFactory"); \
> +p.put(Context.PROVIDER_URL, \
> "failover:ejbd://192.168.1.20:4201,ejbd://192.168.1.30:4201"); +InitialContext \
> remoteContext = new InitialContext(p); +----
> +
> +Failover can work entirely driven by the server, the client does not need to be \
> configured to participate. A client can connect as usual to the server. +
> +[source,java]
> +----
> +Properties p = new Properties();
> +p.put(Context.INITIAL_CONTEXT_FACTORY, \
> "org.apache.openejb.client.RemoteInitialContextFactory"); \
> +p.put(Context.PROVIDER_URL, "ejbd://192.168.1.20:4201"); +InitialContext \
> remoteContext = new InitialContext(p); +----
> +
> +If the server at 192.168.1.20:4201 supports failover, so will the client.
> +
> +In this scenario the list of servers used for failover is supplied entirely by the \
> server at 192.168.1.20:4201. The server could have aquired the list via multicast \
> or multipoint (or both), but this detail is not visible to the client. +
> +===== Considerations
> +
> +====== Network size
> +
> +The general disadvantage of this topology is the number of connections required. \
> The number of connections for the network of servers is equal to (n * n - n) / 2, \
> where n is the number of servers. For example, with 5 servers you need 10 \
> connections, with 10 servers you need 45 connections, and with 50 servers you need \
> 1225 connections. This is of course the number of connections across the entire \
> network, each individual server only needs n - 1 connections. +
> +The handling of these sockets is all asynchronous Java NIO code which allows the \
> server to handle many connections (all of them) with one thread. From a pure \
> threading perspective, the option is extremely efficient with just one thread to \
> listen and broadcast to many peers. +
> +====== Double connect
> +
> +It is possible in this process that two servers learn of each other at the same \
> time and each attempts to connect to the other simultaneously, resulting in two \
> connections between the same two servers. When this happens both servers will \
> detect the extra connection and one of the connections will be dropped and one will \
> be kept. In practice this race condition rarely happens and can be avoided almost \
> entirely by fanning out server startup by as little as 100 milliseconds. +
> +===== Recommandation
> +
> +As mentioned the initialServers is only used for bootstrapping the multipoint \
> network. Once running, all servers will dynamically establish direct connections \
> with each other and there is no single point of failure. +
> +However to ensure that the bootstrapping process can occur successfully, the \
> initialServers property of the conf/multipoint.properties file must be set \
> carefully and with a specific server start order in mind. Each server consults its \
> initialServers list exactly once in the bootstrapping phase at startup, after that \
> time connections are made dynamically. +
> +This means that at least one of the servers listed in initialServers must already \
> be running when the server starts or the server might never become introduced and \
> connected to all the other servers in the network.
> diff --git a/docs/admin/configuration/application.adoc \
> b/docs/admin/configuration/application.adoc new file mode 100644
> index 0000000..775492e
> --- /dev/null
> +++ b/docs/admin/configuration/application.adoc
> @@ -0,0 +1,100 @@
> += Application Configuration
> +:jbake-date: 2016-03-16
> +:jbake-type: page
> +:jbake-status: published
> +:jbake-tomeepdf:
> +
> +== `application.properties`
> +
> +This file is located in `WEB-INF` for a war and `META-INF` for an ear.
> +
> +=== `@Asynchronous` configuration
> +
> +Default pool size for `@Asynchronous` is 5. It can be very small for some \
> applications highly relying on +asynchronism or reactive patterns. Therefore it is \
> possible to customize it adding these entries in `application.properties`: +
> +[.table.table-bordered,options="header"]
> +|===
> +| Name | Default| Description
> +| AsynchronousPool.Size | 5 | Core size of the pool
> +| AsynchronousPool.CorePoolSize | 5 | Core size of the pool (inherit its default \
> from .Size alias) +| AsynchronousPool.MaximumPoolSize | 5 | Maximum size of the \
> pool +| AsynchronousPool.QueueSize | 5 | Maximum size of the pool
> +| AsynchronousPool.KeepAliveTime | 1 minute | Thread keep alive duration
> +| AsynchronousPool.AllowCoreThreadTimeOut | true | Should thread timeout
> +| AsynchronousPool.QueueType | LINKED (or SYNCHRONOUS if size == 0) | The type of \
> queue of the pool in ARRAY, LINKED, PRIORITY or SYNCHRONOUS (same behavior as java \
> implementations of the same name) +| AsynchronousPool.ShutdownWaitDuration | 1 \
> minute | How many time to wait for the pool to shutdown when undeploying the \
> application +| AsynchronousPool.RejectedExecutionHandlerClass | - | A fully \
> qualified name of a `java.util.concurrent.RejectedExecutionHandler` +|===
> +
> +=== TimerService and `@Scheduled`
> +
> +`timerStore.class` allows to switch from the in memory \
> (`org.apache.openejb.core.timer.MemoryTimerStore`) timer storage +for quartz tasks \
> to a custom implementation (using a database or anything for instance). Constructor \
> can take a `TransactionManager` +or nothing.
> +
> +All quartz properties prefixed with `org.apache.openejb.quartz.` (instead of \
> `org.quartz.`) are passthrough to quartz. +
> +=== CDI
> +
> +The boolean `openejb.cdi.skip-resource-validation` allows to not validate \
> resources ie `@EJB` and `@Resource` usages in CDI beans. +
> +All properties understood by OpenWebBeans will also be passthrough to OpenWebBeans \
> from this location, see http://openwebbeans.apache.org/owbconfig.html[OWB config] \
> for more details. +
> +=== `@WebServiceRef`
> +
> +[.table.table-bordered,options="header"]
> +|===
> +| Name | Description
> +| cxf.jaxws.client.wsFeatures | Allows to set WSFeature on the client injection. \
> Values is a list (comma separated) of resource id in resources.xml or fully \
> qualified names. +|===
> +
> +=== `@Stateless`
> +
> +[.table.table-bordered,options="header"]
> +|===
> +| Name | Description
> +| AccessTimeout or Timeout | container timeout
> +| CloseTimeout | container timeout
> +| BackgroundStartup | Don't create instances in parallel if minimum count is > 0, \
> default to false +|===
> +
> +== `resources.xml`
> +
> +`resources.xml` is a tomee.xml using application classloader.
> +
> +As `tomee.xml` it supports filtering so you can use environment variables and \
> system properties, for instance +to use a MySQL database on OpenShift you can do:
> +
> +[source,xml]
> +----
> +<?xml version="1.0" encoding="UTF-8"?>
> +<resources>
> + <Resource id="MySQL" aliases="myAppDataSourceName" type="DataSource">
> + JdbcDriver = com.mysql.jdbc.Driver
> + JdbcUrl = jdbc:mysql://${OPENSHIFT_MYSQL_DB_HOST}:${OPENSHIFT_MYSQL_DB_PORT}/rmannibucau?tcpKeepAlive=true
> + UserName = ${OPENSHIFT_MYSQL_DB_USERNAME}
> + Password = ${OPENSHIFT_MYSQL_DB_PASSWORD}
> + ValidationQuery = SELECT 1
> + ValidationInterval = 30000
> + NumTestsPerEvictionRun = 5
> + TimeBetweenEvictionRuns = 30 seconds
> + TestWhileIdle = true
> + MaxActive = 200
> + </Resource>
> +</resources>
> +----
> +
> +`resources.xml` supports `Resource`, `Service` and `Container`.
> +
> +=== `resources.xml` mecanism
> +
> +`resources.xml` resources are still available globally like any `tomee.xml` \
> resource. +
> +The actual resource is bound in an application subtree called with the application \
> name and a resource facade is bound +in the global naming tree to be able to route \
> the requests depending the application. +
> +Typically if your application is named `myapp` and your resource id is \
> `myresource` then instead of being registered +as `myresource`, it will get \
> registered as `myapp/myresource`. +
> +If you get any ambiguity in resource name matching try to fully qualified your \
> resource prefixing it with the application name.
> diff --git a/docs/admin/configuration/containers.adoc \
> b/docs/admin/configuration/containers.adoc new file mode 100644
> index 0000000..f4c82ad
> --- /dev/null
> +++ b/docs/admin/configuration/containers.adoc
> @@ -0,0 +1,585 @@
> += Resources
> +:jbake-date: 2016-03-16
> +:jbake-type: page
> +:jbake-status: published
> +:jbake-tomeepdf:
> +
> +All containers will be created automatically - which means you don't need to \
> define them +if you don't need to tune their configuration - when a bean of their \
> type if found. +
> +To avoid that use `openejb.offline` property and set it to `true`. See \
> link:server.html[Server Configuration] for more detail. +
> +== @Stateless
> +
> +A `@Stateless` container.
> +
> +Declarable in tomee.xml via
> +
> +[source,xml]
> +----
> +<Container id="Foo" type="STATELESS">
> + AccessTimeout = 30 seconds
> + MaxSize = 10
> + MinSize = 0
> + StrictPooling = true
> + MaxAge = 0 hours
> + ReplaceAged = true
> + ReplaceFlushed = false
> + MaxAgeOffset = -1
> + IdleTimeout = 0 minutes
> + GarbageCollection = false
> + SweepInterval = 5 minutes
> + CallbackThreads = 5
> + CloseTimeout = 5 minutes
> + UseOneSchedulerThreadByBean = false
> + EvictionThreads = 1
> +</Container>
> +----
> +
> +Declarable in properties via
> +
> +[source,properties]
> +----
> +Foo = new://Container?type=STATELESS
> +Foo.AccessTimeout = 30 seconds
> +Foo.MaxSize = 10
> +Foo.MinSize = 0
> +Foo.StrictPooling = true
> +Foo.MaxAge = 0 hours
> +Foo.ReplaceAged = true
> +Foo.ReplaceFlushed = false
> +Foo.MaxAgeOffset = -1
> +Foo.IdleTimeout = 0 minutes
> +Foo.GarbageCollection = false
> +Foo.SweepInterval = 5 minutes
> +Foo.CallbackThreads = 5
> +Foo.CloseTimeout = 5 minutes
> +Foo.UseOneSchedulerThreadByBean = false
> +Foo.EvictionThreads = 1
> +----
> +
> +=== Configuration
> +
> +==== AccessTimeout
> +
> +Specifies the time an invokation should wait for an instance
> +of the pool to become available.
> +
> +After the timeout is reached, if an instance in the pool cannot
> +be obtained, the method invocation will fail.
> +
> +Usable time units: nanoseconds, microsecons, milliseconds,
> +seconds, minutes, hours, days. Or any combination such as
> +"1 hour and 27 minutes and 10 seconds"
> +
> +Any usage of the `javax.ejb.AccessTimeout` annotation will
> +override this setting for the bean or method where the
> +annotation is used.
> +
> +==== MaxSize
> +
> +Specifies the size of the bean pools for this stateless
> +SessionBean container. If StrictPooling is not used, instances
> +will still be created beyond this number if there is demand, but
> +they will not be returned to the pool and instead will be
> +immediately destroyed.
> +
> +==== MinSize
> +
> +Specifies the minimum number of bean instances that should be in
> +the pool for each bean. Pools are prefilled to the minimum on
> +startup. Note this will create start order dependencies between
> +other beans that also eagerly start, such as other `@Stateless`
> +beans with a minimum or `@Singleton` beans using `@Startup`. The
> +start order.
> +
> +The minimum pool size is rigidly maintained. Instances in the
> +minimum side of the pool are not eligible for `IdleTimeout` or
> +`GarbageCollection`, but are subject to `MaxAge` and flushing.
> +
> +If the pool is flushed it is immediately refilled to the minimum
> +size with `MaxAgeOffset` applied. If an instance from the minimum
> +side of the pool reaches its `MaxAge`, it is also immediately
> +replaced. Replacement is done in a background queue using the
> +number of threads specified by `CallbackThreads`.
> +
> +==== StrictPooling
> +
> +StrictPooling tells the container what to do when the pool
> +reaches it's maximum size and there are incoming requests that
> +need instances.
> +
> +With strict pooling, requests will have to wait for instances to
> +become available. The pool size will never grow beyond the the
> +set `MaxSize` value. The maximum amount of time a request should
> +wait is specified via the `AccessTimeout` setting.
> +
> +Without strict pooling, the container will create temporary
> +instances to meet demand. The instances will last for just one
> +method invocation and then are removed.
> +
> +Setting `StrictPooling` to `false` and `MaxSize` to `0` will result in
> +no pooling. Instead instances will be created on demand and live
> +for exactly one method call before being removed.
> +
> +==== MaxAge
> +
> +Specifies the maximum time that an instance should live before
> +it should be retired and removed from use. This will happen
> +gracefully. Useful for situations where bean instances are
> +designed to hold potentially expensive resources such as memory
> +or file handles and need to be periodically cleared out.
> +
> +Usable time units: nanoseconds, microsecons, milliseconds,
> +seconds, minutes, hours, days. Or any combination such as
> +`1 hour and 27 minutes and 10 seconds`
> +
> +==== ReplaceAged
> +
> +When `ReplaceAged` is enabled, any instances in the pool that
> +expire due to reaching their `MaxAge` will be replaced immediately
> +so that the pool will remain at its current size. Replacement
> +is done in a background queue so that incoming threads will not
> +have to wait for instance creation.
> +
> +The aim of his option is to prevent user requests from paying
> +the instance creation cost as `MaxAge` is enforced, potentially
> +while under heavy load at peak hours.
> +
> +Instances from the minimum side of the pool are always replaced
> +when they reach their `MaxAge`, this setting dictates the
> +treatment of non-minimum instances.
> +
> +==== ReplaceFlushed
> +
> +When `ReplaceFlushed` is enabled, any instances in the pool that
> +are flushed will be replaced immediately so that the pool will
> +remain at its current size. Replacement is done in a background
> +queue so that incoming threads will not have to wait for
> +instance creation.
> +
> +The aim of his option is to prevent user requests from paying
> +the instance creation cost if a flush performed while under
> +heavy load at peak hours.
> +
> +Instances from the minimum side of the pool are always replaced
> +when they are flushed, this setting dictates the treatment of
> +non-minimum instances.
> +
> +A bean may flush its pool by casting the `SessionContext` to
> +`Flushable` and calling `flush()`. See `SweepInterval` for details on
> +how flush is performed.
> +
> +[source,java]
> +----
> +import javax.annotation.Resource;
> +import javax.ejb.SessionContext;
> +import javax.ejb.Stateless;
> +import java.io.Flushable;
> +import java.io.IOException;
> +
> +public class MyBean {
> +
> + private SessionContext sessionContext;
> +
> + public void flush() throws IOException {
> +
> + ((Flushable) sessionContext).flush();
> + }
> +}
> +----
> +
> +==== MaxAgeOffset
> +
> +Applies to MaxAge usage and would rarely be changed, but is a
> +nice feature to understand.
> +
> +When the container first starts and the pool is filled to the
> +minimum size, all those "minimum" instances will have the same
> +creation time and therefore all expire at the same time dictated
> +by the `MaxAge` setting. To protect against this sudden drop
> +scenario and provide a more gradual expiration from the start
> +the container will spread out the age of the instances that fill
> +the pool to the minimum using an offset.
> +
> +The `MaxAgeOffset` is not the final value of the offset, but
> +rather it is used in creating the offset and allows the
> +spreading to push the initial ages into the future or into the
> +past. The pool is filled at startup as follows:
> +
> +[source,java]
> +----
> +for (int i = 0; i < poolMin; i++) {
> + long ageOffset = (maxAge / poolMin * i * maxAgeOffset) % maxAge;
> + pool.add(new Bean(), ageOffset));
> +}
> +----
> +
> +The default `MaxAgeOffset` is -1 which causes the initial
> +instances in the pool to live a bit longer before expiring. As
> +a concrete example, let's say the MinSize is 4 and the MaxAge is
> +100 years. The generated offsets for the four instances created
> +at startup would be 0, -25, -50, -75. So the first instance
> +would be "born" at age 0, die at 100, living 100 years. The
> +second instance would be born at -25, die at 100, living a total
> +of 125 years. The third would live 150 years. The fourth 175
> +years.
> +
> +A `MaxAgeOffset` of 1 would cause instances to be "born" older
> +and therefore die sooner. Using the same example `MinSize` of 4
> +and `MaxAge` of `100 years`, the life spans of these initial four
> +instances would be 100, 75, 50, and 25 years respectively.
> +
> +A `MaxAgeOffset` of 0 will cause no "spreading" of the age of the
> +first instances used to fill the pool to the minimum and these
> +instances will of course reach their MaxAge at the same time.
> +It is possible to set to decimal values such as -0.5, 0.5, -1.2,
> +or 1.2.
> +
> +==== IdleTimeout
> +
> +Specifies the maximum time that an instance should be allowed to
> +sit idly in the pool without use before it should be retired and
> +removed.
> +
> +Usable time units: nanoseconds, microsecons, milliseconds,
> +seconds, minutes, hours, days. Or any combination such as
> +"1 hour and 27 minutes and 10 seconds"
> +
> +==== GarbageCollection
> +
> +Allows Garbage Collection to be used as a mechanism for shrinking
> +the pool. When set to true all instances in the pool, excluding
> +the minimum, are eligible for garbage collection by the virtual
> +machine as per the rules of `java.lang.ref.SoftReference` and can be
> +claimed by the JVM to free memory. Instances garbage collected
> +will have their `@PreDestroy` methods called during finalization.
> +
> +In the OpenJDK VM the `-XX:SoftRefLRUPolicyMSPerMB` flag can adjust
> +how aggressively SoftReferences are collected. The default
> +OpenJDK setting is 1000, resulting in inactive pooled instances
> +living one second of lifetime per free megabyte in the heap, which
> +is very aggressive. The setting should be increased to get the
> +most out of the `GarbageCollection` feature of the pool. Much
> +higher settings are safe. Even a setting as high as 3600000 (1
> +hour per free MB in the heap) does not affect the ability for the
> +VM to garbage collect SoftReferences in the event that memory is
> +needed to avoid an `OutOfMemoryException`.
> +
> +==== SweepInterval
> +
> +The frequency in which the container will sweep the pool and
> +evict expired instances. Eviction is how the `IdleTimeout`,
> +`MaxAge`, and pool "flush" functionality is enforced. Higher
> +intervals are better.
> +
> +Instances in use are excluded from sweeping. Should an instance
> +expire while in use it will be evicted immediately upon return
> +to the pool. Effectively `MaxAge` and flushes will be enforced as
> +a part of normal activity or sweeping, while IdleTimeout is only
> +enforcable via sweeping. This makes aggressive sweeping less
> +important for a pool under moderate load.
> +
> +Usable time units: nanoseconds, microsecons, milliseconds,
> +seconds, minutes, hours, days. Or any combination such as
> +`1 hour and 27 minutes and 10 seconds`
> +
> +==== CallbackThreads
> +
> +When sweeping the pool for expired instances a thread pool is
> +used to process calling `@PreDestroy` on expired instances as well
> +as creating new instances as might be required to fill the pool
> +to the minimum after a Flush or `MaxAge` expiration. The
> +`CallbackThreads` setting dictates the size of the thread pool and
> +is shared by all beans deployed in the container.
> +
> +==== CloseTimeout
> +
> +PostConstruct methods are invoked on all instances in the pool
> +when the bean is undeployed and its pool is closed. The
> +`CloseTimeout` specifies the maximum time to wait for the pool to
> +close and `PostConstruct` methods to be invoked.
> +
> +Usable time units: nanoseconds, microsecons, milliseconds,
> +seconds, minutes, hours, days. Or any combination such as
> +`1 hour and 27 minutes and 10 seconds`
> +
> +==== UseOneSchedulerThreadByBean
> +
> +back to previous behavior (TomEE 1.x) where 1 scheduler thread was used for \
> stateless eviction +by bean (ie for 500 stateless beans you get 500 eviction \
> threads) +
> +==== EvictionThreads
> +
> +number of threads to associate to eviction threads (1 is not bad for most \
> applications) +
> +
> +== @Stateful
> +
> +A `@Stateful` container.
> +
> +Declarable in tomee.xml via
> +
> +[source,xml]
> +----
> +<Container id="Foo" type="STATEFUL">
> + AccessTimeout = 30 seconds
> + Cache = org.apache.openejb.core.stateful.SimpleCache
> + Passivator = org.apache.openejb.core.stateful.SimplePassivater
> + TimeOut = 20
> + Frequency = 60
> + Capacity = 1000
> + BulkPassivate = 100
> +</Container>
> +----
> +
> +Declarable in properties via
> +
> +[source,properties]
> +----
> +Foo = new://Container?type=STATEFUL
> +Foo.AccessTimeout = 30 seconds
> +Foo.Cache = org.apache.openejb.core.stateful.SimpleCache
> +Foo.Passivator = org.apache.openejb.core.stateful.SimplePassivater
> +Foo.TimeOut = 20
> +Foo.Frequency = 60
> +Foo.Capacity = 1000
> +Foo.BulkPassivate = 100
> +----
> +
> +=== Configuration
> +
> +==== AccessTimeout
> +
> +Specifies the maximum time an invocation could wait for the
> +`@Stateful` bean instance to become available before giving up.
> +
> +After the timeout is reached a `javax.ejb.ConcurrentAccessTimeoutException`
> +will be thrown.
> +
> +Usable time units: nanoseconds, microsecons, milliseconds,
> +seconds, minutes, hours, days. Or any combination such as
> +"1 hour and 27 minutes and 10 seconds"
> +
> +Any usage of the `javax.ejb.AccessTimeout` annotation will
> +override this setting for the bean or method where the
> +annotation is used.
> +
> +==== Cache
> +
> +The cache is responsible for managing stateful bean
> +instances. The cache can page instances to disk as memory
> +is filled and can destroy abandoned instances. A different
> +cache implementation can be used by setting this property
> +to the fully qualified class name of the Cache implementation.
> +
> +==== Passivator
> +
> +The passivator is responsible for writing beans to disk
> +at passivation time. Different passivators can be used
> +by setting this property to the fully qualified class name
> +of the `PassivationStrategy` implementation. The passivator
> +is not responsible for invoking any callbacks or other
> +processing, its only responsibly is to write the bean state
> +to disk.
> +
> +Known implementations:
> +
> +- org.apache.openejb.core.stateful.RAFPassivater
> +- org.apache.openejb.core.stateful.SimplePassivater
> +
> +==== TimeOut
> +
> +Specifies the time a bean can be idle before it is removed by the container.
> +
> +This value is measured in minutes. A value of 5 would
> +result in a time-out of 5 minutes between invocations.
> +A value of -1 would mean no timeout.
> +A value of 0 would mean a bean can be immediately removed by the container.
> +
> +Any usage of the `javax.ejb.StatefulTimeout` annotation will
> +override this setting for the bean where the annotation is used.
> +
> +==== Frequency
> +
> +Specifies the frequency (in seconds) at which the bean cache is checked for
> +idle beans.
> +
> +==== Capacity
> +
> +Specifies the size of the bean pools for this
> +stateful SessionBean container.
> +
> +==== BulkPassivate
> +
> +Property name that specifies the number of instances
> +to passivate at one time when doing bulk passivation.
> +
> +
> +== @Singleton
> +
> +A `@Singleton` container.
> +
> +Declarable in tomee.xml via
> +
> +[source,xml]
> +----
> +<Container id="Foo" type="SINGLETON">
> + AccessTimeout = 30 seconds
> +</Container>
> +----
> +
> +Declarable in properties via
> +
> +[source,properties]
> +----
> +Foo = new://Container?type=SINGLETON
> +Foo.AccessTimeout = 30 seconds
> +----
> +
> +=== Configuration
> +
> +==== 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.
> +
> +
> +== @MessageDriven
> +
> +A MDB container.
> +
> +Declarable in tomee.xml via
> +
> +[source,xml]
> +----
> +<Container id="Foo" type="MESSAGE">
> + ResourceAdapter = Default JMS Resource Adapter
> + MessageListenerInterface = javax.jms.MessageListener
> + ActivationSpecClass = org.apache.activemq.ra.ActiveMQActivationSpec
> + InstanceLimit = 10
> + FailOnUnknowActivationSpec = true
> +</Container>
> +----
> +
> +Declarable in properties via
> +
> +[source,properties]
> +----
> +Foo = new://Container?type=MESSAGE
> +Foo.ResourceAdapter = Default JMS Resource Adapter
> +Foo.MessageListenerInterface = javax.jms.MessageListener
> +Foo.ActivationSpecClass = org.apache.activemq.ra.ActiveMQActivationSpec
> +Foo.InstanceLimit = 10
> +Foo.FailOnUnknowActivationSpec = true
> +----
> +
> +=== Configuration
> +
> +==== ResourceAdapter
> +
> +The resource adapter delivers messages to the container
> +
> +==== MessageListenerInterface
> +
> +Specifies the message listener interface handled by this container
> +
> +==== ActivationSpecClass
> +
> +Specifies the activation spec class
> +
> +==== InstanceLimit
> +
> +Specifies the maximum number of bean instances that are
> +allowed to exist for each MDB deployment.
> +
> +==== FailOnUnknowActivationSpec
> +
> +Log a warning if true or throw an exception if false is an activation spec can't \
> be respected +
> +
> +== @Managed
> +
> +A managed bean container.
> +
> +Declarable in tomee.xml via
> +
> +[source,xml]
> +----
> +<Container id="Foo" type="MANAGED" />
> +----
> +
> +Declarable in properties via
> +
> +[source,properties]
> +----
> +Foo = new://Container?type=MANAGED
> +----
> +
> +
> +== CMP entity
> +
> +A CMP bean container.
> +
> +Declarable in tomee.xml via
> +
> +[source,xml]
> +----
> +<Container id="Foo" type="CMP_ENTITY">
> + CmpEngineFactory = org.apache.openejb.core.cmp.jpa.JpaCmpEngineFactory
> +</Container>
> +----
> +
> +Declarable in properties via
> +
> +[source,properties]
> +----
> +Foo = new://Container?type=CMP_ENTITY
> +Foo.CmpEngineFactory = org.apache.openejb.core.cmp.jpa.JpaCmpEngineFactory
> +----
> +
> +=== Configuration
> +
> +==== CmpEngineFactory
> +
> +The engine to use for this container. By default TomEE only provides the JPA \
> implementation. +
> +
> +== BMP entity
> +
> +A BMP entity container.
> +
> +Declarable in tomee.xml via
> +
> +[source,xml]
> +----
> +<Container id="Foo" type="BMP_ENTITY">
> + PoolSize = 10
> +</Container>
> +----
> +
> +Declarable in properties via
> +
> +[source,properties]
> +----
> +Foo = new://Container?type=BMP_ENTITY
> +Foo.PoolSize = 10
> +----
> +
> +=== Configuration
> +
> +==== PoolSize
> +
> +Specifies the size of the bean pools for this
> +bmp entity container.
> diff --git a/docs/admin/configuration/index.adoc \
> b/docs/admin/configuration/index.adoc new file mode 100644
> index 0000000..3c2f39c
> --- /dev/null
> +++ b/docs/admin/configuration/index.adoc
> @@ -0,0 +1,25 @@
> += Server Configuration
> +:jbake-date: 2016-03-16
> +:jbake-type: page
> +:jbake-status: published
> +:jbake-tomeepdf:
> +
> +== Container
> +
> +TomEE specific configuration (ie not inherited one from Tomcat) is based on \
> properties. Therefore +you can fully configure TomEE using properties in \
> `conf/system.properties`. +However for convenience it also provides a hybrid XML \
> alternative a.k.a. `conf/tomee.xml`. +
> +- link:server.html[Server Configuration: Properties].
> +- link:resources.html[Resources]
> +- link:containers.html[Containers]
> +- link:log4j2.html[Using log4j2]
> +
> +== Application
> +
> +Some settings can be specific to applications, these ones are also properties \
> based and +are read in `WEB-INF/application.properties`. When you can't use \
> `tomee.xml` to configure +resources you can use `WEB-INF/resources.xml` which \
> inherit from `tomee.xml` its syntax +but binds the resources to the application and \
> reuses the application classloader. +
> +More about link:application.html[Container Configuration].
> diff --git a/docs/admin/configuration/log4j2.adoc \
> b/docs/admin/configuration/log4j2.adoc new file mode 100644
> index 0000000..bd6cb6b
> --- /dev/null
> +++ b/docs/admin/configuration/log4j2.adoc
> @@ -0,0 +1,71 @@
> += Log4j2 Configuration
> +:index-group: Configuration
> +:jbake-date: 2019-07-09
> +:jbake-type: page
> +:jbake-status: published
> +:jbake-tomeepdf:
> +
> +Title: Log4j2 with TomEE
> +
> +Out of the box, TomEE is uses a Java-Util-Logging (JUL) based logging system, \
> which is configured using conf/logging.properties. +
> +Occassionally, users may wish to swap over to using Log4j2. These instructions \
> detail how to do this with the latest TomEE versions. +These instructions have been \
> tested with TomEE 7.x and TomEE 8 SNAPSHOT (master) on July 9th, 2019. +
> +== Setup
> +
> +You'll need to obtain the following jars: log4j-core, log4j-api and log4j-jul. \
> These instructions were tested with the 2.12.0 versions: +
> +https://repo1.maven.org/maven2/org/apache/logging/log4j/log4j-core/2.12.0/log4j-core-2.12.0.jar
> +https://repo1.maven.org/maven2/org/apache/logging/log4j/log4j-api/2.12.0/log4j-api-2.12.0.jar
> +https://repo1.maven.org/maven2/org/apache/logging/log4j/log4j-jul/2.12.0/log4j-jul-2.12.0.jar
> +
> +Add these to the TomEE bin directory. Add the following to setenv.sh on *nix:
> +
> +```
> + JAVA_OPTS="$JAVA_OPTS \
> -Djava.util.logging.manager=org.apache.logging.log4j.jul.LogManager" + \
> LOGGING_CONFIG="-DnoOp" + \
> LOGGING_MANAGER="-Djava.util.logging.manager=org.apache.logging.log4j.jul.LogManager"
> + CLASSPATH=".:$CATALINA_BASE/bin:$CATALINA_BASE/bin/log4j-core-2.12.0.jar:$CATALINA_BASE/bin/log4j-api-2.12.0.jar:$CATALINA_BASE/bin/log4j-jul-2.12.0.jar"
> +```
> +
> +or add the following to setenv.bat on Windows:
> +
> +```
> + @echo off
> + set "JAVA_OPTS=%JAVA_OPTS% \
> -Djava.util.logging.manager=org.apache.logging.log4j.jul.LogManager + set \
> LOGGING_CONFIG=-DnoOpp + set \
> LOGGING_MANAGER=-Djava.util.logging.manager=org.apache.logging.log4j.jul.LogManager \
> + set "CLASSPATH=.;%CATALINA_BASE%\bin;%CATALINA_BASE%\bin\log4j-core-2.12.0.jar; \
> %CATALINA_BASE%\bin\log4j-api-2.12.0.jar;%CATALINA_BASE%\bin\log4j-jul-2.12.0.jar" \
> +``` +
> +Take care to match the jar filenames if you have downloaded jars for a slightly \
> different version of log4j2. +
> +== Configuration
> +
> +Add your log4j2.xml config in the `bin` directory. Here's a simple config you can \
> use to help you get started: +
> +```
> + <?xml version="1.0" encoding="UTF-8" ?>
> + <Configuration status="warn" name="catalina" packages="">
> + <Appenders>
> + <Console name="console" target="SYSTEM_OUT">
> + <PatternLayout pattern="%d %p %c{1.} [%t] %m%n" />
> + </Console>
> + <File name="catalina" \
> fileName="${sys:catalina.base}/logs/catalina.log"> + <PatternLayout>
> + <Pattern>%d %p %c{1.} [%t] %m%n</Pattern>
> + </PatternLayout>
> + </File>
> + <Async name="Async">
> + <AppenderRef ref="catalina" />
> + </Async>
> + </Appenders>
> + <Loggers>
> + <Root level="info">
> + <AppenderRef ref="Async" />
> + <AppenderRef ref="console" />
> + </Root>
> + </Loggers>
> + </Configuration>
> +```
> \ No newline at end of file
> diff --git a/docs/admin/configuration/resources.adoc \
> b/docs/admin/configuration/resources.adoc new file mode 100644
> index 0000000..1263c74
> --- /dev/null
> +++ b/docs/admin/configuration/resources.adoc
> @@ -0,0 +1,570 @@
> += Resources
> +:jbake-date: 2016-03-16
> +:jbake-type: page
> +:jbake-status: published
> +:jbake-tomeepdf:
> +
> +In TomEE resources are mainly "singleton" (understood as defined once per server \
> or application). Technically +it can be anything but you will probably meet more \
> Datasources than other type of resources. +
> +
> +Most resources will be created automatically if there is no matching resources - \
> by name and type - +when an injection will be found. To avoid that use \
> `openejb.offline` property and set it to `true`. +See link:server.html[Server \
> Configuration] for more detail. +
> +== Definition a resource: how does it work?
> +
> +Before all let see how properties syntax is equivalent to XML one \
> (system.properties and tomee.xml typically). +
> +Properties syntax uses dot notation to represent setters/properties which are \
> plain properties in XML syntax +and a URL syntax with query parameters to define \
> the resource where it is directly the resource and tag attributes in XML. +Finally \
> the id is an attribute in XML and the key of the resource definition in properties. \
> + +Let see it with a sample, both delcarations are the same:
> +
> +[source,properties]
> +----
> +myDataSource = new://Resource?type=DataSource
> +myDataSource.JdbcUrl = jdbc:hsqldb:mem:site
> +myDataSource.UserName = sa
> +----
> +
> +[source,xml]
> +----
> +<Resource id="myDataSource" type="DataSource">
> + JdbcUrl = jdbc:hsqldb:mem:site
> + UserName = sa
> +</Resource>
> +----
> +
> +One started you can get injected any resource using `@Resource`:
> +
> +[source,java]
> +----
> +@Resource(name = "myDataSource")
> +private DataSource dataSource;
> +----
> +
> +== Factory syntax
> +
> +Here are the attributes of a resource:
> +
> +[.table.table-bordered,options="header"]
> +|===
> +| Name | Optional |Description
> +| id | false | name of the resource, will match `openejb:Resource/id` in JNDI \
> tree. +| provider | true | define a default resource definition using \
> service-jar.xml +| class-name | true |specify which class to instantiate
> +| factory-name | true |specify which method to invoke on the class-name when \
> specified to create the resource +| properties-provider | true |a class responsible \
> to provide to tomee the properties to use, it can have a property `serviceId` to \
> know which resource it is. +| classpath | true | a classpath to use to create the \
> resource. Note: if not implementing an interface the resource will be isolated from \
> the applications. +| aliases | true | other names for the resource, allows for \
> instance to share the same pool for a datasource used with multiple names in \
> applications. +| post-construct/pre-destroy | true | methods called when \
> creating/destroying the resources. +| Lazy | true | for resources set them to be \
> created when first accessed and not when deployed +|===
> +
> +TomEE supports some implicit properties for resources but sometimes you just want \
> to fully control the +resource and not use implicit properties which can be \
> affected to a property which doesn't expect such a value (typically the case +if \
> you create a custom Oracle datasource). For such case you can set \
> `SkipImplicitAttributes` property to `true` and your resource +will ignore implicit \
> properties. +
> +Implicit properties are:
> +
> +[.table.table-bordered,options="header"]
> +|===
> +| Name | Description
> +| transactionManager | The JTA transaction manager
> +| ServiceId | the "id" of the resource (its name)
> +|===
> +
> +In the same spirit you can skip properties fallback using `SkipPropertiesFallback` \
> and setting it to `true`. It typically avoids to +fallback all unset properties (no \
> matching property found) to a `Properties` instance and set it if one matching \
> property is found. +In Oracle case for instance it matches the connection \
> properties which can have side effects. +
> +=== Value ciphering
> +
> +The propertie values support ciphering using the syntax \
> `cipher:{algorithm}:{cipheredValue}`, for instance \
> `cipher:Static3DES:xMH5uM1V9vQzVUv5LG7YLA==` will +be read as `Passw0rd`. Ciphers \
> can be computed using `tomee.sh` script: `${tomee.home}/bin/tomee.sh cipher \
> Passw0rd`. +
> +== Common Resources
> +
> +=== DataSources
> +
> +DataSources have defaults for all values and a default datasource can be provided \
> automatically but if you want to +configure it here are the common properties:
> +
> +You can set the boolean `JtaManaged` to false if you don't want your datasource to \
> be using JTA - if you manage transactions yourself. +
> +Then other configurations are linked the pool the datasource is using. By default \
> TomEE uses https://tomcat.apache.org/tomcat-7.0-doc/jdbc-pool.html[tomcat-jdbc] but \
> we also provide +https://commons.apache.org/proper/commons-dbcp/configuration.html[commons-dbcp] \
> (2 for TomEE 7.x and 1 for TomEE 1.x). +The properties are then the related \
> configurations with these particular +entries we try to keep in sync for both:
> +
> +[.table.table-bordered,options="header"]
> +|===
> +| Name|Description
> +| JdbcDriver | the jdbc driver of the datasource
> +| JdbcUrl | the jdbc url of the datasource
> +| Username | the user to use
> +| Password | the password of the user
> +|===
> +
> +==== Password and ciphering
> +
> +DataSource were the first resource to support password ciphering. Originally it \
> was another property which is still supported. +It is called `PasswordCipher`. Its \
> value is the ciphering algorithm and it affects the password value. However \
> `cipher:xxx` +is still supported on `Password` value. Default `PasswordCipher` \
> being `PlainText` it behaves as no ciphering is in place by default. +
> +Sample:
> +
> +[source,properties]
> +----
> +ds = new://Resource?type=javax.sql.DataSource
> +# our password is "Passw0rd"
> +ds.Password = xMH5uM1V9vQzVUv5LG7YLA==
> +ds.PasswordCipher = Static3DES
> +----
> +
> +==== Advanced DataSource configuration
> +
> +TomEE also provides few utilities you can add in DataSource properties:
> +
> +[.table.table-bordered,options="header"]
> +|===
> +| Name | Description
> +| LogSql | Should SQL be logged (using TomEE logger)
> +| LogSqlPackages | if set the logging will show the matching packages (separated \
> by comma) inline when logging the query, allows to know where a query comes from +| \
> Flushable| if true the datasource can be casted as a Flushable to recreate the pool \
> +| ResetOnError | if a `SQLException` happens the pool is automatically recreated. \
> Configuration is either "true" to do it each time an exception occurs, `x` or \
> `retry(x)` to do it and retry until maximum `x` times +| ResetOnErrorMethods | \
> which methods are handled by ResetOnError +| TomEEProxyHandler | Custom \
> `InvocationHandler` wrapping the datasource calls +| DataSourceCreator | which pool \
> to use, `dbcp`, `tomcat`, `dbcp-alternative` (DBCP and TomEE proxying instead of \
> DBCP JTA integration), `simple` (no pooling) +|===
> +
> +==== DataSource and JTA
> +
> +`JtaManaged` determines wether or not this data source should be JTA managed
> +or user managed. If set to 'true' it will automatically be enrolled
> +in any ongoing transactions. Calling begin/commit/rollback or setAutoCommit
> +on the datasource or connection will not be allowed. If you need to perform
> +these functions yourself, set `JtaManaged` to `false`
> +
> +==== DataSource and JPA
> +
> +In terms of JPA persistence.xml:
> +
> +- `JtaManaged=true` can be used as a 'jta-data-source'
> +- `JtaManaged=false` can be used as a 'non-jta-data-source'
> +
> +== ActiveMQResourceAdapter
> +
> +Declarable in tomee.xml via
> +
> +[source,xml]
> +----
> +<Resource id="Foo" type="ActiveMQResourceAdapter">
> + BrokerXmlConfig = broker:(tcp://localhost:61616)?useJmx=false
> + ServerUrl = vm://localhost?waitForStart=20000&async=true
> + DataSource = Default Unmanaged JDBC Database
> + StartupTimeout = 10 seconds
> +</Resource>
> +----
> +
> +Declarable in properties via
> +
> +[source,properties]
> +----
> +Foo = new://Resource?type=ActiveMQResourceAdapter
> +Foo.BrokerXmlConfig = broker:(tcp://localhost:61616)?useJmx=false
> +Foo.ServerUrl = vm://localhost?waitForStart=20000&async=true
> +Foo.DataSource = Default Unmanaged JDBC Database
> +Foo.StartupTimeout = 10 seconds
> +----
> +
> +=== Configuration
> +
> +==== BrokerXmlConfig
> +
> +Broker configuration URI as defined by ActiveMQ
> +see http://activemq.apache.org/broker-configuration-uri.html
> +BrokerXmlConfig xbean:file:conf/activemq.xml - Requires xbean-spring.jar and \
> dependencies +
> +==== ServerUrl
> +
> +Broker address
> +
> +==== DataSource
> +
> +DataSource for persistence messages
> +
> +==== StartupTimeout
> +
> +How long to wait for broker startup
> +
> +
> +== javax.jms.ConnectionFactory
> +
> +An ActiveMQ (JMS) connection factory.
> +
> +Declarable in tomee.xml via
> +
> +[source,xml]
> +----
> +<Resource id="Foo" type="javax.jms.ConnectionFactory">
> + ResourceAdapter = Default JMS Resource Adapter
> + TransactionSupport = xa
> + PoolMaxSize = 10
> + PoolMinSize = 0
> + ConnectionMaxWaitTime = 5 seconds
> + ConnectionMaxIdleTime = 15 Minutes
> +</Resource>
> +----
> +
> +Declarable in properties via
> +
> +[source,properties]
> +----
> +Foo = new://Resource?type=javax.jms.ConnectionFactory
> +Foo.ResourceAdapter = Default JMS Resource Adapter
> +Foo.TransactionSupport = xa
> +Foo.PoolMaxSize = 10
> +Foo.PoolMinSize = 0
> +Foo.ConnectionMaxWaitTime = 5 seconds
> +Foo.ConnectionMaxIdleTime = 15 Minutes
> +----
> +
> +=== Configuration
> +
> +==== ResourceAdapter
> +
> +An ActiveMQ (JMS) resource adapter.
> +
> +==== TransactionSupport
> +
> +Specifies if the connection is enrolled in global transaction
> +allowed values: `xa`, `local` or `none`. Default to `xa`.
> +
> +==== PoolMaxSize
> +
> +Maximum number of physical connection to the ActiveMQ broker.
> +
> +==== PoolMinSize
> +
> +Minimum number of physical connection to the ActiveMQ broker.
> +
> +==== ConnectionMaxWaitTime
> +
> +Maximum amount of time to wait for a connection.
> +
> +==== ConnectionMaxIdleTime
> +
> +Maximum amount of time a connection can be idle before being reclaimed.
> +
> +
> +== javax.jms.Queue
> +
> +An ActiveMQ (JMS) queue.
> +
> +Declarable in tomee.xml via
> +
> +[source,xml]
> +----
> +<Resource id="Foo" type="javax.jms.Queue">
> + # not set means id
> + destination =
> +</Resource>
> +----
> +
> +Declarable in properties via
> +
> +[source,properties]
> +----
> +Foo = new://Resource?type=javax.jms.Queue
> +# not set means id
> +Foo.destination =
> +----
> +
> +=== Configuration
> +
> +==== destination
> +
> +Specifies the name of the queue
> +
> +
> +== javax.jms.Topic
> +
> +An ActiveMQ (JMS) topic.
> +
> +Declarable in tomee.xml via
> +
> +[source,xml]
> +----
> +<Resource id="Foo" type="javax.jms.Topic">
> + # not set means id
> + destination =
> +</Resource>
> +----
> +
> +Declarable in properties via
> +
> +[source,properties]
> +----
> +Foo = new://Resource?type=javax.jms.Topic
> +# not set means id
> +Foo.destination =
> +----
> +
> +=== Configuration
> +
> +==== destination
> +
> +Specifies the name of the topic
> +
> +
> +== org.omg.CORBA.ORB
> +
> +NOTE: to use it you need to add an implementation of corba.
> +
> +Declarable in tomee.xml via
> +
> +[source,xml]
> +----
> +<Resource id="Foo" type="org.omg.CORBA.ORB" />
> +----
> +
> +Declarable in properties via
> +
> +[source,properties]
> +----
> +Foo = new://Resource?type=org.omg.CORBA.ORB
> +----
> +
> +
> +== javax.mail.Session
> +
> +A mail session.
> +
> +Declarable in tomee.xml via
> +
> +[source,xml]
> +----
> +<Resource id="mail/mysession" type="javax.mail.Session">
> + mail.transport.protocol = smtp
> + mail.smtp.host = smtp.provider.com
> + mail.smtp.auth = true
> + mail.smtp.starttls.enable = true
> + mail.smtp.port = 587
> + mail.smtp.user = user@provider.com
> + password = abcdefghij
> +</Resource>
> +----
> +
> +Declarable in properties via
> +
> +[source,properties]
> +----
> +mail/mysession = new://Resource?type=javax.mail.Session
> +mail/mysession.mail.transport.protocol = smtp
> +mail/mysession.mail.smtp.host = smtp.provider.com
> +mail/mysession.mail.smtp.auth = true
> +mail/mysession.mail.smtp.starttls.enable = true
> +mail/mysession.mail.smtp.port = 587
> +mail/mysession.mail.smtp.user = user@provider.com
> +mail/mysession.password = abcdefghij
> +----
> +
> +The properties are `javax.mail.Session` ones with the addition of `useDefault` \
> which specifies if `getDefaultInstance()` +or `getInstance` is used to create the \
> session. `getDefaultInstance()` will ensure that several calls are done with the \
> +same configuration and return the same instance. For tomee it is likely better to \
> rely on `getInstance()`(ie keep `useDefault` to false) +and use `aliases` option of \
> the resource to define an alias if you need to share the same instance accross \
> multiple names. +
> +
> +== ManagedExecutorService
> +
> +A concurrency utility for EE executor service.
> +
> +Declarable in tomee.xml via
> +
> +[source,xml]
> +----
> +<Resource id="Foo" type="ManagedExecutorService">
> + Core = 5
> + Max = 25
> + KeepAlive = 5 s
> + Queue = 15
> + ThreadFactory = org.apache.openejb.threads.impl.ManagedThreadFactoryImpl
> + Lazy = true
> +</Resource>
> +----
> +
> +Declarable in properties via
> +
> +[source,properties]
> +----
> +Foo = new://Resource?type=ManagedExecutorService
> +Foo.Core = 5
> +Foo.Max = 25
> +Foo.KeepAlive = 5 s
> +Foo.Queue = 15
> +Foo.ThreadFactory = org.apache.openejb.threads.impl.ManagedThreadFactoryImpl
> +Foo.Lazy = true
> +----
> +
> +=== Configuration
> +
> +==== Core
> +
> +The pool core size.
> +
> +==== Max
> +
> +The pool max size.
> +
> +==== KeepAlive
> +
> +The thread keep alive time (in duration format)
> +
> +==== Queue
> +
> +The queue type size.
> +
> +==== ThreadFactory
> +
> +The thread factory implementation class.
> +
> +==== Lazy
> +
> +If set to true the pool is created when first accessed otherwise it is created at \
> startup. +
> +
> +== ManagedScheduledExecutorService
> +
> +Inherit from `ManagedExecutorService` and adds scheduling abilities.
> +
> +Declarable in tomee.xml via
> +
> +[source,xml]
> +----
> +<Resource id="Foo" type="ManagedScheduledExecutorService">
> + Core = 5
> + ThreadFactory = org.apache.openejb.threads.impl.ManagedThreadFactoryImpl
> + Lazy = true
> +</Resource>
> +----
> +
> +Declarable in properties via
> +
> +[source,properties]
> +----
> +Foo = new://Resource?type=ManagedScheduledExecutorService
> +Foo.Core = 5
> +Foo.ThreadFactory = org.apache.openejb.threads.impl.ManagedThreadFactoryImpl
> +Foo.Lazy = true
> +----
> +
> +=== Configuration
> +
> +See `ManagedExecutorService`.
> +
> +
> +== ManagedThreadFactory
> +
> +A thread factory for a `ManagedExecutorService`.
> +
> +Declarable in tomee.xml via
> +
> +[source,xml]
> +----
> +<Resource id="Foo" type="ManagedThreadFactory">
> + Prefix = openejb-managed-thread-
> + Lazy = true
> +</Resource>
> +----
> +
> +Declarable in properties via
> +
> +[source,properties]
> +----
> +Foo = new://Resource?type=ManagedThreadFactory
> +Foo.Prefix = openejb-managed-thread-
> +Foo.Lazy = true
> +----
> +
> +=== Configuration
> +
> +==== Prefix
> +
> +The thread prefix (suffixed with thread id).
> +
> +
> +
> +== ContextService
> +
> +A concurrency utilities for JavaEE context service. It allows to create
> +contextual proxies (inheriting from security, classloader...contexts).
> +
> +Declarable in tomee.xml via
> +
> +[source,xml]
> +----
> +<Resource id="Foo" type="ContextService" />
> +----
> +
> +Declarable in properties via
> +
> +[source,properties]
> +----
> +Foo = new://Resource?type=ContextService
> +----
> +
> +
> +== JndiProvider: inject remote clients
> +
> +A thread factory for a `ManagedExecutorService`.
> +Default implementation is \
> `org.apache.openejb.threads.impl.ManagedThreadFactoryImpl`. +
> +Declarable in tomee.xml via
> +
> +[source,xml]
> +----
> +<Resource id="Foo" type="ManagedThreadFactory">
> + Prefix = openejb-managed-thread-
> + Lazy = true
> +</Resource>
> +----
> +
> +Declarable in properties via
> +
> +[source,properties]
> +----
> +Foo = new://Resource?type=ManagedThreadFactory
> +Foo.Prefix = openejb-managed-thread-
> +Foo.Lazy = true
> +----
> +
> +=== Configuration
> +
> +==== Prefix
> +
> +The thread prefix (suffixed with thread id).
> +
> +
> +
> +== ContextService
> +
> +A concurrency utilities for JavaEE context service. It allows to create
> +contextual proxies (inheriting from security, classloader...contexts).
> +
> +Declarable in tomee.xml via
> +
> +[source,xml]
> +----
> +<Resource id="Foo" type="ContextService" />
> +----
> +
> +Declarable in properties via
> +
> +[source,properties]
> +----
> +Foo = new://Resource?type=ContextService
> +----
> diff --git a/docs/admin/configuration/server.adoc \
> b/docs/admin/configuration/server.adoc new file mode 100644
> index 0000000..dd02733
> --- /dev/null
> +++ b/docs/admin/configuration/server.adoc
> @@ -0,0 +1,86 @@
> += Container Configuration
> +:jbake-date: 2016-03-16
> +:jbake-type: page
> +:jbake-status: published
> +:jbake-tomeepdf:
> +
> +== Server
> +
> +[.table.table-bordered,options="header"]
> +|===
> +|Name |Value| Description
> +|openejb.embedded.remotable| bool| activate or not the remote services when \
> available +|.bind, <service prefix>.port, <service prefix>.disabled, <service \
> prefix>.threads | host or IP, port, bool|override the host. Available for ejbd and \
> httpejbd services (used by jaxws and jaxrs), number of thread to manage requests \
> +|openejb.embedded.initialcontext.close |LOGOUT or DESTROY| configure the hook \
> called when closing the initial context. Useful when starting OpenEJB from a new \
> InitialContext([properties]) instantiation. By default it simply logs out the \
> logged user if it exists. DESTROY means clean the container. \
> +|javax.persistence.provider |string| override the JPA provider value \
> +|javax.persistence.transactionType |string| override the transaction type for \
> persistence contexts +|javax.persistence.jtaDataSource |string| override the JTA \
> datasource value for persistence contexts \
> +|javax.persistence.nonJtaDataSource| string |override the non JTA datasource value \
> for persistence contexts +|openejb.descriptors.output |bool| dump memory deployment \
> descriptors. Can be used to set complete metadata to true and avoid scanning when \
> starting the container or to check the used configuration. \
> +|openejb.deployments.classpath.require.descriptor |CLIENT or EJB| can allow to \
> filter what you want to scan (client modules or ejb modules) \
> +|openejb.descriptors.output.folder| path| where to dump deployement descriptors if \
> activated. +|openejb.strict.interface.declaration |bool| add some validations on \
> session beans (spec validations in particular). false by default. \
> +|openejb.conf.file or openejb.configuration| string| OpenEJB configuration file \
> path +|openejb.debuggable-vm-hackery |bool| remove JMS informations from deployment
> +|openejb.validation.skip |bool |skip the validations done when OpenEJB deploys \
> beans +|openejb.deployments.classpath.ear |bool| deploy the classpath as an ear
> +|openejb.webservices.enabled| bool |activate or not webservices
> +|openejb.validation.output.level| TERSE or MEDIUM or VERBOSE| level of the logs \
> used to report validation errors +|openejb.user.mbeans.list * or a list of classes \
> separated by ,| list of mbeans to deploy automatically \
> +|openejb.deploymentId.format composition (+string) of {ejbName} {ejbType} \
> {ejbClass} and {ejbClass.simpleName} default {ejbName}. The format to use to deploy \
> ejbs. +|openejb.deployments.classpath |bool| whether or not deploy from classpath
> +|openejb.deployments.classpath.include and \
> openejb.deployments.classpath.exclude |regex| regex to filter the scanned classpath \
> (when you are in this case) +|openejb.deployments.package.include and \
> openejb.deployments.package.exclude| regex| regex to filter scanned packages \
> +|openejb.autocreate.jta-datasource-from-non-jta-one| bool| whether or not auto \
> create the jta datasource if it doesn't exist but a non jta datasource exists. \
> Useful when using hibernate to be able to get a real non jta datasource. \
> +|openejb.altdd.prefix |string| prefix use for altDD (example test to use a \
> test.ejb-jar.xml). +|org.apache.openejb.default.system.interceptors |class \
> names|list of interceptor (qualified names) separated by a comma or a space add \
> these interceptor on all beans +|openejb.jndiname.strategy.class |class name| an \
> implementation of org.apache.openejb.assembler.classic.JndiBuilder.JndiNameStrategy \
> +|openejb.jndiname.failoncollision| bool| if a NameAlreadyBoundException is thrown \
> or not when 2 EJBs have the same name +|openejb.jndiname.format |string|composition \
> of these properties: ejbType, ejbClass, ejbClass.simpleName, ejbClass.packageName, \
> ejbName, deploymentId, interfaceType, interfaceType.annotationName, \
> interfaceType.annotationNameLC, interfaceType.xmlName, interfaceType.xmlNameCc, \
> interfaceType.openejbLegacyName, interfaceClass, interfaceClass.simpleName, \
> interfaceClass.packageName default {deploymentId}{interfaceType.annotationName}. \
> Change the name used for the ejb. +|openejb.org.quartz.threadPool.class |class| \
> qualified name which implements org.quartz.spi.ThreadPool the thread pool used by \
> quartz (used to manage ejb timers) +|openejb.localcopy |bool| default true. whether \
> or not copy EJB arguments[/method/interface] for remote invocations. \
> +|openejb.cxf.jax-rs.providers |string|the list of the qualified name of the JAX-RS \
> providers separated by comma or space. Note: to specify a provider for a specific \
> service suffix its class qualified name by ".providers", the value follow the same \
> rules. Note 2: default is a shortcut for jaxb and json providers. \
> +|openejb.wsAddress.format |string| composition of {ejbJarId}, ejbDeploymentId, \
> ejbType, ejbClass, ejbClass.simpleName, ejbName, portComponentName, wsdlPort, \
> wsdlService default /{ejbDeploymentId}. The WS name format. \
> +|org.apache.openejb.server.webservices.saaj.provider| axis2, sun or \
> null |specified the saaj configuration +|[<uppercase service name>.]<service \
> id>.<name> or [<uppercase service name>.]<service id> |whatever is supported \
> (generally string, int ...)| set this value to the corresponding service. example: \
> [EnterpriseBean.]<ejb-name>.activation.<property>, [PERSISTENCEUNIT.]<persistence \
> unit name>.<property>, [RESOURCE.]<name> +|log4j.category.OpenEJB.options| DEBUG, \
> INFO, ... |active one OpenEJB log level. need log4j in the classpath \
> +|openejb.jmx.active| bool| activate (by default) or not the OpenEJB JMX MBeans \
> +|openejb.nobanner |bool| activate or not the OpenEJB banner (activated by default) \
> +|openejb.check.classloader |bool| if true print some information about duplicated \
> classes +|openejb.check.classloader.verbose| bool| if true print classes \
> intersections +|openejb.additional.exclude |string separated by comma| list of \
> prefixes you want to exclude and are not in the default list of exclusion \
> +|openejb.additional.include |string separated by comma| list of prefixes you want \
> to remove from thedefault list of exclusion +|openejb.offline |bool| if true can \
> create datasources and containers automatically \
> +|openejb.exclude-include.order| include-exclude or exclude-include| if the \
> inclusion/exclusion should win on conflicts (intersection) \
> +|openejb.log.color |bool| activate or not the color in the console in embedded \
> mode +|openejb.log.color.<level in lowercase> |color in uppercase |set a color for \
> a particular level. Color are BLACK, RED, GREEN, YELLOW, BLUE, MAGENTA, CYAN, \
> WHITE, DEFAULT. +|tomee.serialization.class.blacklist| string |default list of \
> packages/classnames excluded for EJBd deserialization (needs to be set on server \
> and client sides). Please see the description of Ejbd Transport for details. \
> +|tomee.serialization.class.whitelist| string| default list of packages/classnames \
> allowed for EJBd deserialization (blacklist wins over whitelist, needs to be set on \
> server and client sides). Please see the description of Ejbd Transport for details. \
> +|tomee.remote.support |boolean |if true /tomee webapp is auto-deployed and EJBd is \
> active (true by default for 1.x, false for 7.x excepted for tomee maven plugin and \
> arquillian) +|openejb.crosscontext |bool| set the cross context property on tomcat \
> context (can be done in the traditionnal way if the deployment is don through the \
> webapp discovery and not the OpenEJB Deployer EJB) \
> +|openejb.jsessionid-support |bool| remove URL from session tracking modes for this \
> context (see javax.servlet.SessionTrackingMode) \
> +|openejb.myfaces.disable-default-values |bool| by default TomEE will initialize \
> myfaces with some its default values to avoid useless logging \
> +|openejb.web.xml.major |int| major version of web.xml. Can be useful to force \
> tomcat to scan servlet 3 annotatino when deploying with a servlet 2.x web.xml \
> +|tomee.jaxws.subcontext |string| sub context used to bind jaxws web services, \
> default is webservices +|openejb.servicemanager.enabled |bool| run all services \
> detected or only known available services (WS and RS \
> +|tomee.jaxws.oldsubcontext |bool| wether or not activate old way to bind jaxws \
> webservices directly on root context +|openejb.modulename.useHash |bool| add a hash \
> after the module name of the webmodule if it is generated from the webmodule \
> location, it avoids conflicts between multiple deployment (through ear) of the same \
> webapp. Note: it disactivated by default since names are less nice this way. \
> +|openejb.session.manager |qualified name (string)| configure a session managaer to \
> use for all contexts +|tomee.tomcat.resource.wrap |bool|wrap tomcat resources \
> (context.xml) as tomee resources if possible (true by default) \
> +|tomee.tomcat.datasource.wrap |bool|same as tomee.tomcat.resource.wrap for \
> datasource (false by default). Note that setting it to true will create tomee \
> datasources but can have the side effect to create twice singleton resources \
> +|openejb.environment.default |bool|should default JMS resources be created or not, \
> default to false to ensure no port is bound or multiple resources are created and \
> completely uncontrolled (doesn't apply to datasources etc for compatibility). For \
> tests only! +|===
> +
> +== Client
> +
> +[.table.table-bordered,options="header"]
> +|===
> +|Name| Value |Description
> +|openejb.client.identityResolver |implementation of \
> org.apache.openejb.client.IdentityResolver| default \
> org.apache.openejb.client.JaasIdentityResolver. The class to get the client \
> identity. +|openejb.client.connection.pool.timeout or \
> openejb.client.connectionpool.timeout |int (ms)| the timeout of the client \
> +|openejb.client.connection.pool.size or \
> openejb.client.connectionpool.size |int| size of the socket pool \
> +|openejb.client.keepalive |int (ms)| the keepalive duration \
> +|openejb.client.protocol.version |string| Optional legacy server protocol \
> compatibility level. Allows 4.6.x clients to potentially communicate with older \
> servers. OpenEJB 4.5.2 and older use version "3.1", and 4.6.x currently uses \
> version "4.6" (Default). This does not allow old clients to communicate with new \
> servers prior to 4.6.0 +|tomee.serialization.class.blacklist| string |default list \
> of packages/classnames excluded for EJBd deserialization (needs to be set on server \
> and client sides). Please see the description of Ejbd Transport for details. \
> +|tomee.serialization.class.whitelist| string| default list of packages/classnames \
> allowed for EJBd deserialization (blacklist wins over whitelist, needs to be set on \
> server and client sides). Please see the description of Ejbd Transport for details. \
> +|===
> diff --git a/docs/admin/file-layout.adoc b/docs/admin/file-layout.adoc
> new file mode 100644
> index 0000000..433fea3
> --- /dev/null
> +++ b/docs/admin/file-layout.adoc
> @@ -0,0 +1,144 @@
> += Directory Structure
> +:jbake-date: 2016-03-16
> +:jbake-type: page
> +:jbake-status: published
> +:jbake-tomeepdf:
> +
> +ifndef::backend-pdf[]
> +
> +[#filetree.col-md-4]
> +[
> + {
> + label: 'apps',
> + description: 'A common but optional folder containing the applications \
> (war, ear, jar). Note: this folder needs to be activated in tomee.xml for instance \
> and is not there by default.', + children: [
> + {label:'module1.jar',description:'An ejbmodule'},
> + {label:'myapp',description:'An exploded war or ear'},
> + {label:'anotherapp.war',description:'A war'},
> + {label:'anotherapp',description:'By default TomEE will explode the war \
> next to the .war file, this is customizable.'}, + \
> {label:'anotherapp2.ear',description:'An ear'}, + \
> {label:'anotherapp2',description:'By default TomEE will explode the ear next to the \
> .ear file, this is customizable.'} + ]
> + },
> + {
> + label: 'bin',
> + description: 'The executable and boot related files',
> + children: [
> + {label:'bootstrap.jar',description:'The jar allowing Tomcat to \
> start'}, + {label:'catalina.bat',description:'The windows main Tomcat \
> script'}, + {label:'catalina.bat.original',description:'The original \
> catalina.bat from Tomcat. TomEE customizes it.'}, + \
> {label:'catalina.sh',description:'The UNIx main Tomcat script'}, + \
> {label:'catalina.sh.original',description:'The original catalina.sh from Tomcat. \
> TomEE customizes it.'}, + {label:'catalina-tasks.xml',description:'Some \
> Ant tasks Tomcat provides to work with JMX'}, + \
> {label:'commons-daemon.jar',description:'When setting up TomEE as a service you \
> need this jar.'}, + \
> {label:'commons-daemon-native.tar.gz',description:'The native needed by \
> commons-daemon'}, + {label:'configtest.bat',description:'A windows \
> script to validate the server.xml'}, + \
> {label:'configtest.sh',description:'A UNIx script to validate the server.xml'}, + \
> {label:'daemon.sh',description:'A script which can be used as init.d script'}, + \
> {label:'digest.bat',description:'A windows script to compute a digest'}, + \
> {label:'digest.sh',description:'A UNIx script to compute a digest'}, + \
> {label:'service.bat',description:'The windows service script'}, + \
> {label:'service.install.as.admin.bat',description:'Install TomEE as a service on \
> windows'}, + {label:'service.readme.txt',description:'The explanations \
> on how to setup TomEE as a windows service'}, + \
> {label:'service.remove.as.admin.bat',description:'Uninstall TomEE service on \
> windows'}, + {label:'setclasspath.bat',description:'The script called by \
> catalina.bat to initialize Tomcat classpath'}, + \
> {label:'setclasspath.sh',description:'The script called by catalina.bat to \
> initialize TomEE classpath'}, + {label:'setenv.sh',description:'A UNIx \
> user script (optional) where you can specify some JVM options like CATALINA_OPTS \
> environment variable'}, + {label:'setenv.bat',description:'A windows \
> user script (optional) where you can specify some JVM options like CATALINA_OPTS \
> environment variable'}, + {label:'shutdown.bat',description:'Stop the \
> server on windows, it is commonly used with -force and a timeout as options'}, + \
> {label:'shutdown.sh',description:'Stop the server on UNIx, it is commonly used with \
> -force and a timeout as options'}, + \
> {label:'startup.bat',description:'Start (and forget) TomEE on windows'}, + \
> {label:'startup.sh',description:'Start (and forget) TomEE on UNIx'}, + \
> {label:'tomcat-juli.jar',description:'The Tomcat Java Util Logging extensions which \
> allow for instance to configure the logging per application'}, + \
> {label:'tomcat-native.tar.gz',description:'The Tomcat native used by some \
> connectors'}, + {label:'TomEE....exe',description:'TomEE windows \
> executables when setup as a service for amd64 architectures'}, + \
> {label:'tomee.bat',description:'TomEE utility script for windows, allows to compute \
> ciphers for instance'}, + {label:'tomee.sh',description:'TomEE utility \
> script for UNIx, allows to compute ciphers for instance'}, + \
> {label:'tool-wrapper.bat',description:'Windows script calling Tomcat Tool utility. \
> It executes a command line with Tomcat classloader.'}, + \
> {label:'tool-wrapper.sh',description:'UNIx script calling Tomcat Tool utility. It \
> executes a command line with Tomcat classloader.'}, + \
> {label:'version.bat',description:'Print Tomcat version (for windows)'}, + \
> {label:'version.sh',description:'Print Tomcat version (for UNIx)'} + ]
> + },
> + {
> + label: 'conf',
> + description: 'Folder containing the configuration of TomEE',
> + children: [
> + {label:'Catalina',description:'A folder where Tomcat can copy web \
> application configuration (typically context.xml can be overriden from there)'}, + \
> {label:'catalina.policy',description:'The server security policy rules'}, + \
> {label:'catalina.properties',description:'The server boot configuration \
> (classloader etc...)'}, + {label:'conf.d',description:'A TomEE folder \
> where services can pick configuration'}, + \
> {label:'context.xml',description:'The default context.xml configuration'}, + \
> {label:'logging.properties',description:'The logging configuration for the server \
> and applications (overridable)'}, + {label:'server.xml',description:'The \
> server configuration (Host, Context, Valves, ...)'}, + \
> {label:'server.xml.original',description:'The original server.xml, TomEE updates it \
> to add its lifecycle manager.'}, + \
> {label:'system.properties',description:'TomEE global configuration'}, + \
> {label:'tomcat-users.xml',description:'The default location where tomcat stores \
> users.'}, + {label:'tomcat-users.xml.original',description:'The Tomcat \
> tomcat-users.xml (TomEE add comments)'}, + \
> {label:'tomcat-users.xsd',description:'The XSD for tomcat-users.xml'}, + \
> {label:'tomee.xml',description:'The TomEE configuration file, syntax is hybrid \
> between XML and Properties and it is fully replaceable with system.properties but \
> users generally prefer this file.'}, + {label:'web.xml',description:'The \
> default web.xml'} + ]
> + },
> + {
> + label: 'lib',
> + description: 'Folder containing TomEE binaries',
> + children: [
> + {label:'*.jar',description:'Tomcat + TomEE libraries'}
> + ]
> + },
> + {
> + label: 'logs',
> + description: 'Default location of log files',
> + children: [
> + {label:'catalina.$day.log',description:'By default container logs go \
> there'}, + {label:'xxx.2016-03-16.log',description:'By default \
> application xxx logs go there (when using servlet API)'}, + \
> {label:'localhost.$day.log',description:'By default host related logs go there'}, + \
> {label:'localhost_access_log.$day.txt',description:'By default access logs (request \
> the container processed) go there'} + ]
> + },
> + {
> + label: 'temp',
> + description: 'Java temporary directory is redirected by default to this \
> folder', + children: [
> + {label:'OpenEJB-dejlzdbhjzbfrzeofrh',description:'A temporary file \
> TomEE can create (suffix depends the startup) to check the instance'} + ]
> + },
> + {
> + label: 'webapps',
> + description: 'Folder containing the web applications',
> + children: [
> + {label:'myapp',description:'An exploded war'},
> + {label:'anotherapp.war',description:'A war'},
> + {label:'anotherapp',description:'By default TomEE will explode the war \
> next to the .war file, this is customizable.'} + ]
> + },
> + {
> + label: 'work',
> + description: 'Folder where Tomcat and TomEE can work',
> + children: [
> + {
> + label:'Catalina',description:'By default Tomcat Engine is called \
> Catalina. This folder matches engine name.', + children: [
> + {
> + label:'localhost',description:'A folder by host by engine \
> to seggregate data of each ones', + children: [
> + {
> + label:'myapp',description:'An application deployed \
> on the previous level host', + children: [
> + { \
> label:'org.apache.jsp.index_jsp.java',description:'The generated JSP source \
> (index.jsp there)' }, + { \
> label:'org.apache.jsp.index_jsp.class',description:'The compiled JSP binary' } + \
> ] + }
> + ]
> + }
> + ]
> + }
> + ]
> + }
> +]
> +
> +[#filetreedetail.col-md-8.bs-callout.bs-callout-primary]
> +Click on a tree node or open a folder to see the detail there.
> +
> +endif::[]
> diff --git a/docs/admin/index.adoc b/docs/admin/index.adoc
> new file mode 100644
> index 0000000..57239ad
> --- /dev/null
> +++ b/docs/admin/index.adoc
> @@ -0,0 +1,7 @@
> += Administrator
> +:jbake-date: 2016-03-16
> +:jbake-type: page
> +:jbake-status: published
> +:jbake-tomeepdf:
> +
> +Click link:../docs.html[here] to find the documentation for administrators.
> diff --git a/docs/advanced/.DS_Store b/docs/advanced/.DS_Store
> new file mode 100644
> index 0000000..2718e5f
> Binary files /dev/null and b/docs/advanced/.DS_Store differ
> diff --git a/docs/advanced/applicationcomposer/index.adoc \
> b/docs/advanced/applicationcomposer/index.adoc new file mode 100644
> index 0000000..50390cc
> --- /dev/null
> +++ b/docs/advanced/applicationcomposer/index.adoc
> @@ -0,0 +1,76 @@
> += ApplicationComposer with JBatch
> +:jbake-date: 2016-03-16
> +:jbake-type: page
> +:jbake-status: published
> +:jbake-tomeepdf:
> +
> +ApplicationComposer can be a way to run a JBatch not needing any HTTP connector.
> +
> +Here is an example making batch integration easy - note you can extract the \
> generic part in a library very easily: +
> +TIP: if you didn't check yet BatchEE provides some standalone utilities for JBatch \
> but the idea of this page can be reused for a lot of applications. +
> +[source,java]
> +----
> +// helper class reusable for any batch
> +abstract class BatchApplication {
> + private static final DateTimeFormatter DATE = \
> DateTimeFormatter.ofPattern("YYYYMMddHHmmss"); +
> + protected Report runBatch(final String batchName, final Properties config) {
> + final JobOperator operator = BatchRuntime.getJobOperator();
> + final long id = operator.start(batchName, config);
> + Batches.waitForEnd(operator, id);
> + return new Report(operator.getJobExecution(id), \
> operator.getParameters(id)); + }
> +
> + @Module // we enforce BatchEE to be initialized as an EJB context to get JNDI \
> for JTA init, needed for TomEE 1 + public EjbModule \
> ensureBatchEESetupIsDoneInTheRightContext() { + final EjbJar ejbJar = new \
> EjbJar().enterpriseBean(new SingletonBean(BatchEEBeanManagerInitializer.class)); +
> + final Beans beans = new Beans();
> + beans.addManagedClass(BatchEEBeanManagerInitializer.Init.class);
> +
> + final EjbModule ejbModule = new EjbModule(ejbJar);
> + ejbModule.setModuleId("batchee-shared-components");
> + ejbModule.setBeans(beans);
> + return ejbModule;
> + }
> +
> + public static class Report {
> + private final JobExecution execution;
> + private final Properties properties;
> +
> + public Report(final JobExecution execution, final Properties properties) {
> + this.execution = execution;
> + this.properties = properties;
> + }
> +
> + public JobExecution getExecution() {
> + return execution;
> + }
> +
> + public Properties getProperties() {
> + return properties;
> + }
> + }
> +}
> +
> +@Classes(cdi = true, value = { MyFilter.class, MoveFile.class, InputFile.class, \
> MyReader.class, LoggingListener.class }) +public class MyBatch extends \
> BatchApplication { + private final Properties config;
> +
> + public Mybatch(final String[] args) { // main args
> + this.config = new Properties() {{ // create the batch config
> + setProperty("input-directory", args[0]);
> + }};
> + }
> +
> + public Report execute(final String inputDirectory) {
> + return runBatch("sunstone", config);
> + }
> +
> + public static void main(final String[] args) throws Exception {
> + ApplicationComposers.run(MyBatch.class, args);
> + }
> +}
> +----
> diff --git a/docs/advanced/client/jndi.adoc b/docs/advanced/client/jndi.adoc
> new file mode 100644
> index 0000000..7f47e81
> --- /dev/null
> +++ b/docs/advanced/client/jndi.adoc
> @@ -0,0 +1,96 @@
> += Java Naming and Directory Interface (JNDI)
> +:jbake-date: 2018-12-05
> +:jbake-type: page
> +:jbake-status: published
> +
> +TomEE has several JNDI client intended for multiple usages.
> +
> +== Default one
> +
> +In a standalone instance you generally don't need (or want) to specify anything
> +to do a lookup. Doing so you will inherit from the contextual environment:
> +
> +[source,java]
> +----
> +final Context ctx = new InitialContext();
> +ctx.lookup("java:....");
> +----
> +
> +== LocalInitialContextFactory
> +
> +This is the legacy context factory used by OpenEJB. It is still useful to fallback
> +on the "default" one in embedded mode where sometimes classloaders or libraries \
> can mess +up the automatic conextual context.
> +
> +Usage:
> +
> +[source,java]
> +----
> +Properties properties = new Properties();
> +properties.setProperty(Context.INITIAL_CONTEXT_FACTORY, \
> "org.apache.openejb.core.LocalInitialContextFactory"); +final Context ctx = new \
> InitialContext(properties); +ctx.lookup("java:....");
> +----
> +
> +This context factory supports few more options when *you boot the container* \
> creating a context: +
> +|===
> +| Name | Description
> +| openejb.embedded.remotable | true/false: starts embedded services
> +| Context.SECURITY_PRINCIPAL/Context.SECURITY_CREDENTIALS | the *global* security \
> identity for the whole container +|===
> +
> +IMPORTANT: `Context.SECURITY_*` shouldn't be used for runtime lookups with \
> `LocalInitialContextFactory`, it would leak a security identity and make the \
> runtime no more thread safe. +This factory was deprecated starting with 7.0.2 in \
> favor of `org.apache.openejb.core.OpenEJBInitialContextFactory`. +
> +== OpenEJBInitialContextFactory
> +
> +This factory allows you to access local EJB and container resources.
> +
> +[source,java]
> +----
> +Properties properties = new Properties();
> +properties.setProperty(Context.INITIAL_CONTEXT_FACTORY, \
> "org.apache.openejb.core.OpenEJBInitialContextFactory"); +final Context ctx = new \
> InitialContext(properties); +ctx.lookup("java:....");
> +----
> +
> +== RemoteInitialContextFactory
> +
> +Intended to be used to contact a remote server, the \
> `org.apache.openejb.client.RemoteInitialContextFactory` relies on the provider url \
> +to contact a tomee instance: +
> +[source,java]
> +----
> +Properties p = new Properties();
> +p.put(Context.INITIAL_CONTEXT_FACTORY, \
> "org.apache.openejb.client.RemoteInitialContextFactory"); \
> +p.put(Context.PROVIDER_URL, \
> "failover:ejbd://192.168.1.20:4201,ejbd://192.168.1.30:4201"); +
> +final InitialContext remoteContext = new InitialContext(p);
> +ctx.lookup("java:....");
> +----
> +
> +Contrarly to local one, the remote factory supports `Context.SECURITY_*` options \
> in a thread safe manner and you can do lookups at runtime using them. +
> +See link:../../admin/cluster/index.html[Cluster] page for more details on the \
> options. +
> +=== Security
> +
> +The context configuration can take additional configuration to handle EJB \
> security: +
> +[source,properties]
> +----
> +p.put("openejb.authentication.realmName", "my-realm"); // optional
> +p.put(Context.SECURITY_PRINCIPAL, "alfred");
> +p.put(Context.SECURITY_CREDENTIALS, "bat");
> +----
> +
> +The realm will be used by JAAS to get the right LoginModules and \
> principal/credentials to +do the actual authentication.
> +
> +==== HTTP case
> +
> +Often HTTP layer is secured and in this case you need to authenticate before the \
> EJBd (remote EJB TomEE protocol) layer. +Thanks to TomEE/Tomcat integration login \
> there will propagate to the EJBd context. +
> +This can be done passing the token you need to set as `Authorization` header in \
> the `PROVIDER_URL`:
> diff --git a/docs/advanced/index.adoc b/docs/advanced/index.adoc
> new file mode 100644
> index 0000000..28c1b23
> --- /dev/null
> +++ b/docs/advanced/index.adoc
> @@ -0,0 +1,7 @@
> += Advanced
> +:jbake-date: 2016-03-16
> +:jbake-type: page
> +:jbake-status: published
> +:jbake-tomeepdf:
> +
> +Click link:../docs.html[here] to find advanced documentation.
> diff --git a/docs/advanced/jms/jms-configuration.adoc \
> b/docs/advanced/jms/jms-configuration.adoc new file mode 100644
> index 0000000..d4cdec1
> --- /dev/null
> +++ b/docs/advanced/jms/jms-configuration.adoc
> @@ -0,0 +1,67 @@
> += Why is my ActiveMQ/JMS MDB not scaling as expected?
> +:jbake-date: 2017-02-22
> +:jbake-type: page
> +:jbake-status: published
> +:jbake-tomeepdf:
> +
> +== Why my ActiveMQ/JMS MDB is not scaling as expected?
> +
> +There are multiple configurations points to ensure you scale as much as you want.
> +
> +Here some common configuration to validate (note that when possible the sample \
> value is the default): +
> +- The resource adapter thread pool ("worker threads" or `WorkManager`) limits the \
> number of max work threads: +
> +[source,xml]
> +----
> +<Resource id="my resource adapter" ....>
> + # using -1 will make the server using cached threads (unbounded)
> + # min recommanded: maxSessions + 1 (for connect())
> + threadPoolSize = 30
> +</Resource>
> +----
> +
> +- Then the MDB container itself has a upper bound through `InstanceLimit` which \
> controls the max MDB instance count: +
> +[source,xml]
> +----
> +<Container id="my mdb container" type="MESSAGE">
> + # -1 will disable it
> + # min recommanded = maxSessions
> + InstanceLimit = 10
> +</Container>
> +----
> +
> +- ActiveMQ `maxSessions` controls how many sessions a MDB can use:
> +
> +[source,java]
> +----
> +@MessageDriven(activationConfig = {
> + @javax.ejb.ActivationConfigProperty(propertyName = "maxSessions", \
> propertyValue = "1"), + @javax.ejb.ActivationConfigProperty(propertyName = \
> "destination", propertyValue = "target-queue") +})
> +public static class MyMdb implements MessageListener {
> + @Override
> + public void onMessage(final Message message) {
> + // ...
> + }
> +}
> +----
> +
> +- The ConnectionFactory has also an instance pool through geronimo-connector \
> logic, configuration + can make the behavior changing but this is controlled \
> through pool related variables (the pool and resource properties are merged in the \
> definition): +
> +[source,xml]
> +----
> +<Resource id="my connection factory" type="ConnectionFactory">
> + # recommanded to be aligned on maxSessions
> + PoolMaxSize = 10
> + # for 100% MDB (no client) you can evaluate to turn it off/false, for client \
> it can still be useful depending what you do + Pooling = true
> +</Resource>
> +----
> +
> +== Slow Message Consumption
> +
> +If you find you have a slow consumption of messages there are several options to \
> have a look (activemq website explains it very well) +but one very impacting option \
> can be the prefetch size.
> diff --git a/docs/advanced/setup/index.adoc b/docs/advanced/setup/index.adoc
> new file mode 100644
> index 0000000..bb4a200
> --- /dev/null
> +++ b/docs/advanced/setup/index.adoc
> @@ -0,0 +1,141 @@
> += How to Setup TomEE in production
> +:jbake-date: 2016-03-16
> +:jbake-type: page
> +:jbake-status: published
> +
> +
> +You can use TomEE as described on \
> link:../../admin/directory-structure.html[Directory Structure] page but in \
> production it is better to +split TomEE and application binaries and configuration.
> +
> +Idea is to have this kind of layout (the root is the one you prefer):
> +
> +ifndef::backend-pdf[]
> +
> +[#filetree.col-md-4]
> +[{
> + label: '/some/path',
> + description: 'any location on your file system',
> + children: [
> + {
> + label: 'tomee',
> + description: 'all tomee binaries will be there, note: you often do the \
> same for the JVM versions you have', + children: [
> + {
> + label: 'tomee-1.7.1',
> + description: 'a particular tomee version (just unzip it \
> there)', + children: [
> + { label: 'bin', description: 'the startup \
> binaries/scripts' }, + { label: 'conf', description: \
> 'default shared configuration for this version, can be overwritten by instance' }, \
> + { label: 'lib', description: 'the binaries' } + \
> ] + },
> + {
> + label: 'tomee-1.7.2',
> + description: 'a particular tomee version (just unzip it \
> there)', + children: [
> + { label: 'bin', description: 'the startup \
> binaries/scripts' }, + { label: 'conf', description: \
> 'default shared configuration for this version, can be overwritten by instance' }, \
> + { label: 'lib', description: 'the binaries' } + \
> ] + },
> + {
> + label: 'tomee-7.0.0-M3',
> + description: 'a particular tomee version (just unzip it \
> there)', + children: [
> + { label: 'bin', description: 'the startup \
> binaries/scripts' }, + { label: 'conf', description: \
> 'default shared configuration for this version, can be overwritten by instance' }, \
> + { label: 'lib', description: 'the binaries' } + \
> ] + }
> + ]
> + },
> + {
> + label: 'applications',
> + description: 'all applications',
> + children: [
> + {
> + label: 'application1',
> + description: 'any application instance (ie configuration + \
> binaries)', + children: [
> + { label: 'bin', description: 'provide scripts for this \
> instance (see under that file layout)' }, + { label: 'conf', \
> description: 'the instance configuration, typically what is in tomee/conf when used \
> in standalone' }, + { label: 'lib', description: 'some \
> additional binaries like JDBC drivers' }, + { label: 'logs', \
> description: 'instances logs location' }, + { label: 'work', \
> description: 'dedicated work directory' }, + { label: \
> 'temp', description: 'instance temporary folder' }, + { \
> label: 'webapps', description: 'instance webapp folder' } + ]
> + },
> + {
> + label: 'application2',
> + description: 'any application instance (ie configuration + \
> binaries)', + children: [
> + { label: 'bin', description: 'provide scripts for this \
> instance (see under that file layout)' }, + { label: 'conf', \
> description: 'the instance configuration, typically what is in tomee/conf when used \
> in standalone' }, + { label: 'lib', description: 'some \
> additional binaries like JDBC drivers' }, + { label: 'logs', \
> description: 'instances logs location' }, + { label: 'work', \
> description: 'dedicated work directory' }, + { label: \
> 'temp', description: 'instance temporary folder' }, + { \
> label: 'webapps', description: 'instance webapp folder' } + ]
> + }
> + ]
> + }
> + ]
> +}]
> +
> +
> +[#filetreedetail.col-md-8.bs-callout.bs-callout-primary]
> +Click on a tree node or open a folder to see the detail there.
> +
> +[.clearfix]
> +
> +
> +endif::[]
> +
> +== Instance scripts
> +
> +The idea for instances (applications) scripts is to simply delegate to tomcat ones \
> but customizing the JVM and TomEE versions. +
> +Customizing the version (and locations) is done in `bin/setenv.sh` of instances.
> +
> +Here are an example for the common scripts (of course you can write helper version \
> like restart etc). +
> +=== setenv.sh
> +
> +[source,bash]
> +----
> +#! /bin/sh
> +
> +# which java
> +export JAVA_HOME="/some/path/java/jdk-8u60"
> +# which tomee
> +export CATALINA_HOME="/some/path/tomee/tomee-7.0.0-M3"
> +# where is the application - to let tomcat/tomee finds the configuration
> +export CATALINA_BASE="/some/path/application1/"
> +# to let tomee be able to kill the instance if shutdown doesn't work (see shutdown \
> script) +export CATALINA_PID="/some/path/application1/work/tomee.pid"
> +----
> +
> +=== startup
> +
> +[source,bash]
> +----
> +#! /bin/bash
> +
> +proc_script_base="`cd $(dirname $0) && cd .. && pwd`"
> +source "$proc_script_base/bin/setenv.sh"
> +nohup "$CATALINA_HOME/bin/startup.sh" "$@" > $proc_script_base/logs/nohup.log &
> +----
> +
> +=== shutdown
> +
> +[source,bash]
> +----
> +#! /bin/bash
> +
> +proc_script_base="`cd $(dirname $0) && cd .. && pwd`"
> +source "$proc_script_base/bin/setenv.sh"
> +# we support parameters like timeout and force, typically we would call it this \
> way: ./shutdown 1200 -force +"$CATALINA_HOME/bin/shutdown.sh" "$@"
> +----
> diff --git a/docs/advanced/shading/index.adoc b/docs/advanced/shading/index.adoc
> new file mode 100644
> index 0000000..0e1f0f2
> --- /dev/null
> +++ b/docs/advanced/shading/index.adoc
> @@ -0,0 +1,276 @@
> += Fat / Uber jars - Using the Shade Plugin
> +:jbake-date: 2016-03-16
> +:jbake-type: page
> +:jbake-status: published
> +:jbake-tomeepdf:
> +
> +Shading the container and the application has some challenges like merging \
> correctly resources (`META-INF/services/` typically). +
> +Here is a maven shade plugin configuration working for most cases:
> +
> +[source,xml]
> +----
> +<plugin>
> + <groupId>org.apache.maven.plugins</groupId>
> + <artifactId>maven-shade-plugin</artifactId>
> + <version>2.3</version>
> + <executions>
> + <execution>
> + <phase>package</phase>
> + <goals>
> + <goal>shade</goal>
> + </goals>
> + <configuration>
> + <dependencyReducedPomLocation>${project.build.directory}/reduced-pom.xml</dependencyReducedPomLocation>
> + <transformers>
> + <transformer \
> implementation="org.apache.maven.plugins.shade.resource.ManifestResourceTransformer">
> + <mainClass>org.apache.tomee.embedded.FatApp</mainClass>
> + </transformer>
> + <transformer \
> implementation="org.apache.maven.plugins.shade.resource.AppendingTransformer"> + \
> <resource>META-INF/cxf/bus-extensions.txt</resource> + </transformer>
> + <transformer \
> implementation="org.apache.openwebbeans.maven.shade.OpenWebBeansPropertiesTransformer" \
> /> + </transformers>
> + <filters>
> + <filter> <!-- we don't want JSF to be activated -->
> + <artifact>*:*</artifact>
> + <excludes>
> + <exclude>META-INF/faces-config.xml</exclude>
> + </excludes>
> + </filter>
> + </filters>
> + </configuration>
> + </execution>
> + </executions>
> + <dependencies>
> + <dependency>
> + <groupId>org.apache.openwebbeans</groupId>
> + <artifactId>openwebbeans-maven</artifactId>
> + <version>1.7.0/version>
> + </dependency>
> + </dependencies>
> +</plugin>
> +----
> +
> +NOTE: see link:../tomee-embedded/index.html[TomEE Embedded] page for more \
> information about tomee embedded options. +
> +IMPORTANT: this shade uses TomEE Embedded but you can do the same with an \
> link:../applicationcomposer/index.html[Application Composer] application. +
> +TIP: if you have `META-INF/web-fragment.xml` in your application you will need to \
> merge them in a single one in the shade. Note that tomcat provides one +which can \
> be skipped in this operation since it is there only as a marker for jasper \
> detection. +
> +Then just build the jar:
> +
> +[source,bash]
> +----
> +mvn clean package
> +----
> +
> +And you can run it:
> +
> +[source,bash]
> +----
> +java -jar myapp-1.0-SNAPSHOT.jar
> +----
> +
> +== Fat Jars with Gradle
> +
> +With gradle you can rely on either jar plugin, fatjar plugin or shadowjar plugin. \
> Last one is likely the closer to maven shade plugin +so that's the one used for \
> next sample: +
> +[source,groovy]
> +----
> +// run $ gradle clean shadowJar
> +import org.apache.openwebbeans.gradle.shadow.OpenWebBeansPropertiesTransformer
> +
> +buildscript {
> + repositories {
> + mavenLocal()
> + jcenter()
> + }
> + dependencies {
> + classpath 'com.github.jengelman.gradle.plugins:shadow:1.2.3'
> + classpath 'org.apache.openwebbeans:openwebbeans-gradle:1.7.0'
> + }
> +}
> +
> +apply plugin: 'com.github.johnrengelman.shadow'
> +
> +group 'org.apache.tomee.demo.gradle'
> +version '1.0-SNAPSHOT'
> +
> +apply plugin: 'idea'
> +apply plugin: 'java'
> +
> +sourceCompatibility = 1.8
> +
> +repositories {
> + mavenLocal()
> + mavenCentral()
> +}
> +
> +dependencies {
> + compileOnly 'org.projectlombok:lombok:1.16.10'
> + compile 'org.apache.tomee:tomee-embedded:7.0.2-SNAPSHOT'
> +}
> +
> +// customize exclusions depending your app
> +
> +// first the not used dependencies like JSF, JAXWS, JMS ones
> +def excludedDependenciesGroups = [
> + // gradle is buggy with poms, scope provided and optional I think
> + 'com.google.code.findbugs',
> + 'com.google.guava',
> + 'javax.annotation',
> + 'javax.ws.rs',
> + 'net.sf.ehcache',
> + 'org.apache.httpcomponents',
> + 'org.ow2.asm',
> + // tomee jaxws, jms, etc...
> + 'commons-codec',
> + 'com.sun.xml.messaging.saaj',
> + 'joda-time',
> + 'junit',
> + 'net.shibboleth.utilities',
> + 'org.apache.activemq',
> + 'org.apache.activemq.protobuf',
> + 'org.apache.myfaces.core',
> + 'org.apache.neethi',
> + 'org.apache.santuario',
> + 'org.apache.ws.xmlschema',
> + 'org.apache.wss4j',
> + 'org.bouncycastle',
> + 'org.cryptacular',
> + 'org.fusesource.hawtbuf',
> + 'org.jasypt',
> + 'org.jvnet.mimepull',
> + 'org.opensaml',
> + 'wsdl4j',
> + 'xml-resolver'
> +]
> +
> +// then cxf+tomee specific dependencies so we need to be more precise than the \
> group +// to not exclude everything
> +def excludedDependenciesArtifacts = [
> + 'cxf-rt-bindings-soap',
> + 'cxf-rt-bindings-xml',
> + 'cxf-rt-databinding-jaxb',
> + 'cxf-rt-frontend-jaxws',
> + 'cxf-rt-frontend-simple',
> + 'cxf-rt-security-saml',
> + 'cxf-rt-ws-addr',
> + 'cxf-rt-wsdl',
> + 'cxf-rt-ws-policy',
> + 'cxf-rt-ws-security',
> + 'openejb-cxf',
> + 'openejb-webservices',
> + 'tomee-webservices',
> + 'geronimo-connector',
> + 'geronimo-javamail_1.4_mail'
> +]
> +shadowJar {
> + classifier = 'bundle'
> +
> + // merge SPI descriptors
> + mergeServiceFiles()
> + append 'META-INF/cxf/bus-extensions.txt'
> + transform(OpenWebBeansPropertiesTransformer.class)
> +
> + // switch off JSF + JMS + JAXWS
> + exclude 'META-INF/faces-config.xml'
> + dependencies {
> + exclude(dependency {
> + excludedDependenciesGroups.contains(it.moduleGroup) ||
> + excludedDependenciesArtifacts.contains(it.moduleName)
> + })
> + }
> +
> + // ensure we define the expected Main (if you wrap tomee main use your own \
> class) + manifest {
> + attributes 'Main-Class': 'org.apache.tomee.embedded.FatApp'
> + }
> +}
> +----
> +
> +Then run:
> +
> +[source,properties]
> +----
> +gradle clean build shadowJar
> +----
> +
> +and you'll get `build/libs/demo-gradle-tomee-embedded-shade-1.0-SNAPSHOT-bundle.jar` \
> ready to run with: +
> +[source,bash]
> +----
> +java -jar build/libs/demo-gradle-tomee-embedded-shade-1.0-SNAPSHOT-bundle.jar \
> --as-war --simple-log=true +----
> +
> +== Fat Wars
> +
> +Fat Wars are executable wars. Note they can be fancy for demos but they have the \
> drawback to put the server in web resources +at packaging time (to ensure the war \
> is actually an executable jar) so adding a filter preventing these files to be read \
> +can be needed if you don't already use a web technology doing it (a servlet bound \
> to /*). +
> +Here how to do a fat war:
> +
> +[source,xml]
> +----
> +<properties>
> + <!-- can be uber (for all), jaxrs, jaxws for lighter ones -->
> + <tomee.flavor>uber</tomee.flavor>
> +</properties>
> +
> +<dependencies>
> + <!-- ...your dependencies as usual... -->
> + <dependency>
> + <groupId>org.apache.tomee</groupId>
> + <artifactId>tomee-embedded</artifactId>
> + <classifier>${tomee.flavor}</classifier>
> + <version>7.0.0</version>
> + <scope>provided</scope>
> + </dependency>
> +</dependencies>
> +
> +<build>
> + <plugins>
> + <plugin>
> + <groupId>org.apache.maven.plugins</groupId>
> + <artifactId>maven-war-plugin</artifactId>
> + <version>2.6</version>
> + <configuration>
> + <failOnMissingWebXml>false</failOnMissingWebXml>
> + <archive>
> + <manifest>
> + <mainClass>org.apache.tomee.embedded.Main</mainClass>
> + </manifest>
> + </archive>
> + <dependentWarExcludes />
> + <overlays>
> + <overlay>
> + <groupId>org.apache.tomee</groupId>
> + <artifactId>tomee-embedded</artifactId>
> + <classifier>${tomee.flavor}</classifier>
> + <type>jar</type>
> + <excludes />
> + </overlay>
> + </overlays>
> + </configuration>
> + </plugin>
> + </plugins>
> +</build>
> +----
> +
> +Then just build the war:
> +
> +[source,bash]
> +----
> +mvn clean package
> +----
> +
> +And you can run it:
> +
> +[source,bash]
> +----
> +java -jar myapp-1.0-SNAPSHOT.war
> +----
> diff --git a/docs/advanced/tomee-embedded/foo.ado \
> b/docs/advanced/tomee-embedded/foo.ado new file mode 100644
> index 0000000..e69de29
> diff --git a/docs/advanced/tomee-embedded/index.adoc \
> b/docs/advanced/tomee-embedded/index.adoc new file mode 100644
> index 0000000..874e691
> --- /dev/null
> +++ b/docs/advanced/tomee-embedded/index.adoc
> @@ -0,0 +1,223 @@
> += TomEE Embedded
> +:jbake-date: 2016-03-16
> +:jbake-type: page
> +:jbake-status: published
> +:jbake-tomeepdf:
> +
> +TomEE Embedded is based on Tomcat embedded and starts a real TomEE in the \
> launching JVM. It is also +able to deploy the classpath as a webapp and to use \
> either `META-INF/resources` or a folder as web resources. +
> +Here is a basic programmatic usage based on `org.apache.tomee.embedded.Container` \
> class: +
> +[source,java]
> +----
> +try (final Container container = new Container(new \
> Configuration()).deployClasspathAsWebApp()) { + System.out.println("Started on \
> http://localhost:" + container.getConfiguration().getHttpPort()); +
> + // do something or wait until the end of the application
> +}
> +----
> +
> +All EE features are then accessible directly in the same JVM.
> +
> +== TomEE Embedded Configuration
> +
> +The default configuration allows to start tomee without issue but you can desire \
> to customize some of them. +
> +[.table.table-bordered,options="header"]
> +|===
> +| Name | Default | Description
> +|httpPort | 8080| http port
> +|stopPort | 8005| shutdown port
> +|host |localhost| host
> +|dir|-|where to create a file hierarchy for tomee (conf, temp, ...)
> +|serverXml|-|which server.xml to use
> +|keepServerXmlAsThis|false|don't adjust ports/host from the configuration and keep \
> the ones in server.xml +|properties|-|container properties
> +|quickSession | true|use Random instead of SecureRandom (for dev)
> +|skipHttp|false|don't use the http connector
> +|httpsPort | 8443|https potr
> +|ssl|false| activate https
> +|withEjbRemote|false|use EJBd
> +|keystoreFile|-|https keystore location
> +|keystorePass|-|https keystore password
> +|keystoreType |JKS|https keystore type
> +|clientAuth|-|https client auth
> +|keyAlias|-|https alias
> +|sslProtocol|-|SSL protocol for https connector
> +|webXml|-|default web.xml to use
> +|loginConfig|-|which LoginConfig to use, relies on \
> `org.apache.tomee.embedded.LoginConfigBuilder` to create it \
> +|securityConstraints|-|add some security constraints, use \
> `org.apache.tomee.embedded.SecurityConstaintBuilder` to build them +|realm|-|which \
> realm to use (useful to switch to `JAASRealm` for instance) without modifying the \
> application +|deployOpenEjbApp|false|should internal openejb application be \
> delpoyed +|users|-|a map of user/password
> +|roles|-|a map of role/users
> +|tempDir|${java.io.tmpdir}/tomee-embedded_${timestamp}|tomcat needs a docBase, in \
> case you don't provide one one will be created there +|webResourceCached \
> |true|should web resources be cached by tomcat (set false in frontend dev) \
> +|configuration-location|-|location (classpath or file) to a .properties to \
> configure the server +[pre-task|-|Runnable or \
> org.apache.tomee.embedded.LifecycleTask implementations to execute before the \
> container starts +|classes-filter|-|implementation of a custom xbean Filter to \
> ignore not desired classes during scanning +|basic|-|set /* under BASIC \
> authentication for the realm "Security", authentication role being "*" +|===
> +
> +Note: passing to `Container` constructor a `Configuration` it will start the \
> container automatically but using `setup(Configuration)` +to initialize the \
> configuration you will need to call `start()`. +
> +You can also pass through the properties `connector.xxx` and \
> `connector.attributes.xxx` to customize connector(s) +configuration directly.
> +
> +== Standalone applications or TomEE Embedded provided main(String[])
> +
> +Deploying an application in a server is very nice cause the application is \
> generally small and it allows to update the +container without touching the \
> application (typically insanely important in case of security issues for instance). \
> + +However sometimes you don't have the choice so TomEE Embedded provides a \
> built-in `main(String[])`. Here are its options: +
> +NOTE: this is still a TomEE so all system properties work (for instance to create \
> a resource). +
> +[.table.table-bordered,options="header"]
> +|===
> +|Name|Default|Description
> +|--path|-|location of application(s) to deploy
> +|--context|-|Context name for applications (same order than paths)
> +|-p or --port|8080|http port
> +|-s or --shutdown|8005|shutdown port
> +|-d or --directory|./.apache-tomee|tomee work directory
> +|-c or --as-war|-|deploy classpath as a war
> +|-b or --doc-base|-|where web resources are for classpath deployment
> +|--renaming|-|for fat war only, is renaming of the context supported
> +|--serverxml|-|the server.xml location
> +|--tomeexml|-|the server.xml location
> +|--property|-|a list of container properties (values follow the format x=y)
> +|===
> +
> +Note that since 7.0.0 TomEE provides 3 flavors (qualifier) of tomee-embedded as \
> fat jars: +
> +- uber (where we put all request features by users, this is likely the most \
> complete and the biggest) +- jaxrs: webprofile minus JSF
> +- jaxws: webprofile plus JAX-WS
> +
> +These different uber jars are interesting in mainly 2 cases:
> +
> +- you do a war shade (it avoids to list a bunch of dependencies but still get a \
> customized version) +- you run your application using `--path` option
> +
> +NOTE: if you already do a custom shade/fatjar this is not really impacting since \
> you can depend on `tomee-embedded` and exclude/include what you want. +
> +== FatApp a shortcut main
> +
> +`FatApp` main (same package as tomee embedded `Main`) just wraps the default main \
> ensuring: +
> +- ̀`--as-war` is used
> +- ̀`--single-classloader` is used
> +- `--configuration-location=tomee-embedded.properties` is set if \
> `tomee-embedded.properties` is found in the classpath +
> +== configuration-location
> +
> +`--configuration-location` option allows to simplify the configuration of tomee \
> embedded through properties. +
> +Here are the recognized entries (they match the configuration, see \
> org.apache.tomee.embedded.Configuration for the detail): +
> +|===
> +|Name|
> +|http|
> +|https|
> +|stop|
> +|host|
> +|dir|
> +|serverXml|
> +|keepServerXmlAsThis|
> +|quickSession|
> +|skipHttp|
> +|ssl|
> +|http2|
> +|webResourceCached|
> +|withEjbRemote|
> +|deployOpenEjbApp|
> +|keystoreFile|
> +|keystorePass|
> +|keystoreType|
> +|clientAuth|
> +|keyAlias|
> +|sslProtocol|
> +|webXml|
> +|tempDir|
> +|classesFilter|
> +|conf|
> +|properties.x (set container properties x with the associated value)|
> +|users.x (for default in memory realm add the user x with its password - the \
> value)| +|roles.x (for default in memory realm add the role x with its comma \
> separated users - the value)| +|connector.x (set the property x on the connector)|
> +|realm=fullyqualifiedname,realm.prop=xxx (define a custom realm with its \
> configuration)| +|login=,login.prop=xxx (define a \
> org.apache.tomee.embedded.LoginConfigBuilder == define a LoginConfig)| \
> +|securityConstraint=,securityConstraint.prop=xxx (define a \
> org.apache.tomee.embedded.SecurityConstaintBuilder == define webapp security)| \
> +|configurationCustomizer.alias=,configurationCustomizer.alias.class=class,configurationCustomizer.alias.prop=xxx \
> (define a ConfigurationCustomizer)| +|===
> +
> +Here is a sample to add BASIC security on `/api/*`:
> +
> +[source,properties]
> +----
> +# security configuration
> +securityConstraint =
> +securityConstraint.authConstraint = true
> +securityConstraint.authRole = **
> +securityConstraint.collection = api:/api/*
> +
> +login =
> +login.realmName = app
> +login.authMethod = BASIC
> +
> +realm = org.apache.catalina.realm.JAASRealm
> +realm.appName = app
> +
> +properties.java.security.auth.login.config = configuration/login.jaas
> +----
> +
> +And here a configuration to exclude jackson packages from scanning and use log4j2 \
> as main logger (needs it as dependency): +
> +[source,properties]
> +----
> +properties.openejb.log.factory = log4j2
> +properties.openejb.container.additional.include = \
> com.fasterxml.jackson,org.apache.logging.log4j +----
> +
> +== Application Runner
> +
> +SInce TomEE 7.0.2, TomEE provide a light ApplicationComposer integration for TomEE \
> Embedded (all features are not yet supported but the main ones are): \
> +`org.apache.tomee.embedded.TomEEEmbeddedApplicationRunner`. It relies on the \
> definition of an `@Application`: +
> +[source,java]
> +----
> +@Application
> +@Classes(context = "app")
> +@ContainerProperties(@ContainerProperties.Property(name = "t", value = "set"))
> +@TomEEEmbeddedApplicationRunner.LifecycleTasks(MyTask.class) // can start a \
> ftp/sftp/elasticsearch/mongo/... server before tomee \
> +@TomEEEmbeddedApplicationRunner.Configurers(SetMyProperty.class) +public class \
> TheApp { + @RandomPort("http")
> + private int port;
> +
> + @RandomPort("http")
> + private URL base;
> +
> + @org.apache.openejb.testing.Configuration
> + public Properties add() {
> + return new PropertiesBuilder().p("programmatic", "property").build();
> + }
> +
> + @PostConstruct
> + public void appStarted() {
> + // ...
> + }
> +}
> +----
> +
> +Then just start it with:
> +
> +[source,java]
> +----
> +TomEEEmbeddedApplicationRunner.run(TheApp.class, "some arg1", "other arg");
> +----
> +
> +TIP: `@Classes(values)` and `@Jars` are supported too which can avoid a huge \
> scanning if you run with a lot of not CDI dependencies which would boost the \
> startup of your application.
> diff --git a/docs/alternate-descriptors.adoc b/docs/alternate-descriptors.adoc
> new file mode 100644
> index 0000000..8797386
> --- /dev/null
> +++ b/docs/alternate-descriptors.adoc
> @@ -0,0 +1,124 @@
> += Alternate Descriptors
> +:index-group: Testing Techniques
> +:jbake-date: 2018-12-05
> +:jbake-type: page
> +:jbake-status: published
> +
> +As of OpenEJB 3.1.1, you have the
> +ability to specify an alternate set of deployment descriptors to use for
> +a given environment. This is focused mostly on testing where it is often
> +desirable to use a slightly different configuration for a set of tests
> +or even a specific test.
> +
> +== When nothing else does the trick
> +
> +Note that this approach was added as a catch-all for when one of the
> +simpler overriding techniques will not work. For the common case of
> +needing to tweak your persistence.xml, see the
> +link:configuring-persistenceunits-in-tests.html[Configuring
> +PersistenceUnits in Tests] page for a simpler approach.
> +
> +For many reasons it is very inconvenient to have to maintain two sets of
> +descriptors, one for production and one for testing. We aggressively add
> +features based on user feedback and questions. If you are looking for a
> +way to solve a problem without duplicating entire descriptors, please
> +let us know. You should never have to go the long way to do something
> +simple.
> +
> += openejb.altdd.prefix
> +
> +To use this functionality, just set the new "openejb.altdd.prefix"
> +system property or `InitialContext` property to something like "_test_",
> +then any descriptors in your META-INF/ directory that start with
> +"_test._" will override the regular descriptor. So for example with an
> +app like this:
> +
> +* META-INF/ejb-jar.xml
> +* META-INF/_test_.ejb-jar.xml
> +* META-INF/persistence.xml
> +* META-INF/_test_.env-entry.properties
> +
> +Just initialize your test case like so:
> +
> +[source,java]
> +----
> + Properties properties = new Properties();
> + properties.setProperty(Context.INITIAL_CONTEXT_FACTORY,
> + "org.apache.openejb.client.LocalInitialContextFactory");
> + properties.setProperty("openejb.altdd.prefix", "test");
> +
> + InitialContext initialContext = new InitialContext(properties);
> +----
> +
> +The logical result will be the prefixed file replacing the non-prefixed
> +file as the active descriptor:
> +
> +* META-INF/ejb-jar.xml -> _test_.ejb-jar.xml
> +* META-INF/persistence.xml
> +* META-INF/env-entry.properties -> _test_.env-entry.properties
> +
> +This will work in any environment in which OpenEJB works (embedded,
> +standalone, tomcat, geronimo, etc.).
> +
> +Note that there does _not_ have to be an equivalent non-prefixed version
> +of the file. In the example above, only a "test.env-entry.properties"
> +file exists and there is no equivalent plain "env-entry.properties"
> +file. This prefixing works for any deployment descriptor in the
> +META-INF/ directory or WEB-INF/ directory. The prefix does not have to
> +be "test" and could be anything you choose. You can also have as many
> +prefixed files as you need and could even go as far as to have one
> +prefix per individual test.
> +
> += More than one prefix
> +
> +It is possible to have several prefixes, specified in order of
> +preference, so that it is possible to avoid duplicating descriptors that
> +are used in more than one "profile". For example, the "foo" test case
> +uses the same "env-entries.properties" file as the "bar" test case, but
> +both have their own ejb-jar.xml files:
> +
> +* META-INF/ejb-jar.xml
> +* META-INF/test.ejb-jar.xml
> +* META-INF/footest.ejb-jar.xml
> +* META-INF/bartest.ejb-jar.xml
> +* META-INF/persistence.xml
> +* META-INF/test.env-entry.properties
> +
> +The "foo" test case could set the _openejb.altdd.prefix_ as follows:
> +
> +[source,java]
> +----
> + //...
> + properties.setProperty("openejb.altdd.prefix", "footest, test");
> +
> + InitialContext initialContext = new InitialContext(properties);
> +----
> +
> +Resulting the following logical view of the app:
> +
> +* META-INF/ejb-jar.xml -> _footest_.ejb-jar.xml
> +* META-INF/persistence.xml
> +* META-INF/env-entry.properties -> test.env-entry.properties
> +
> +And the "bar" test case could set the _openejb.altdd.prefix_ as follows:
> +
> +[source,java]
> +----
> + //...
> + properties.setProperty("openejb.altdd.prefix", "footest, test");
> +
> + InitialContext initialContext = new InitialContext(properties);
> +----
> +
> +Resulting the following logical view of the app:
> +
> +* META-INF/ejb-jar.xml -> _bartest_.ejb-jar.xml
> +* META-INF/persistence.xml
> +* META-INF/env-entry.properties -> test.env-entry.properties
> +
> +In both scenarios the same env-entry.properties file
> +(test.env-entry.properties) is shared.
> +
> +Note that there is a "test.ejb-jar.xml" file that is present, however in
> +both cases it is not used as the order of preference in the list is
> +"left to right" meaning most preferred first.
> diff --git a/docs/annotations,-xml-and-defaults.adoc \
> b/docs/annotations,-xml-and-defaults.adoc new file mode 100644
> index 0000000..dbde52b
> --- /dev/null
> +++ b/docs/annotations,-xml-and-defaults.adoc
> @@ -0,0 +1,22 @@
> += Annotations, XML and Defaults
> +:index-group: Unrevised
> +:jbake-date: 2018-12-05
> +:jbake-type: page
> +:jbake-status: published
> +
> +
> +[source,xml]
> +----
> + <p>The following is a list of all annotations and their attributes, the \
> xml tags that correspond to them (for overriding), and what the default values are \
> when left unspecified.</p> +----
> +
> +Annotation
> +
> +xml element(s)
> +
> +default value
> +
> +[source,xml]
> +----
> + </div>
> +----
> diff --git a/docs/app-clients-and-jndi.adoc b/docs/app-clients-and-jndi.adoc
> new file mode 100644
> index 0000000..d9d61a9
> --- /dev/null
> +++ b/docs/app-clients-and-jndi.adoc
> @@ -0,0 +1,74 @@
> += App Clients and JNDI
> +:index-group: Unrevised
> +:jbake-date: 2018-12-05
> +:jbake-type: page
> +:jbake-status: published
> +
> +There are some slight differences between the way OpenEJB
> +does app clients and the way Geronimo does app clients
> +
> +Neither uses the names created via the openejb.jndiname.format. So
> +changing that will (should) have no affect. The idea is that users
> +should be able to set it to be whatever they want it to be and that
> +should not break the App Client code. The openejb.jndiname.format is
> +specifically for "plain" clients and allows them to get the names as
> +they want them.
> +
> +Internally, we bind each EJB proxy under essentially a hardcoded and
> +predictable format and then again using the user supplied format. So
> +there are at minimum two JNDI trees with every EJB proxy. It used to be
> +two at least. Now we have quite a few because of Java EE 6 global JNDI
> +and the support we added for `@LocalClient` and allowing the same
> +interface to be used as both `@Local` and `@Remote`.
> +
> +Basically we have:
> +
> +* openejb/Deployment/<hardcoded internal format>
> +* openejb/local/<strategy format>
> +* openejb/remote/<strategy format>
> +
> +The 'openejb/Deployment' section is the non-changing fully qualified
> +name for use internally and by app clients.
> +
> +The 'openejb/remote' section is for "pretty" names looked up via plain
> +clients using the RemoteInitialContextFactory. The protocol can tell
> +the difference between app clients and plain clients and knows which
> +area to look in.
> +
> +The 'openejb/local' section is for "pretty" names looked up via the
> +LocalInitialContextFactory.
> +
> +The "pretty" names are defined by the openejb.jndiname.format and since
> +the user has control of that formatting it's possible that not all
> +proxies can be bound. Say the bean has both a local and remote
> +interface and the user has just "\{deploymentId}" or "\{ejbName}" as the
> +format. Hence those bind calls use the "optional" set of binding
> +methods.
> +
> +The format of the internal names bound into openejb/Deployment is
> +guaranteed to be unique. It's not pretty to look at obviously, but
> +every possible proxy will be bound there guaranteed. For binding into
> +'openejb/Deployment' we don't use the "optional" set of binding methods.
> + If something can't be bound it's a deployment issue.
> +
> +The home interface is bound, but with the name of the corresponding
> +business interface rather than the home interface.
> +
> +To be a little bit more clear - Both OpenEJB and Geronimo build their
> +own JNDI trees for the App Client. Geronimo prefers to have its own
> +JNDI tree for the App Client as there are other things in it that are
> +not EJB related. Either way the OpenEJB EJBd protocol can carry the
> +"id" of the App Client and both Geronimo and OpenEJB rely on that.
> +
> +In Geronimo App Clients the id is set to "Deployments" and that tells
> +OpenEJB not to look in the "openejb/remote" section of JNDI as it
> +normally would. It will instead use the "openejb/Deployments" section
> +of JNDI were the names follow a predictable and unchanging format.
> +
> +In OpenEJB App Clients the id is set to the name of the App Client and
> +we instead look in "openejb/client//" where names are formatted by the
> +user via the application-client.xml.
> +
> +When calls are made from client to server and the App Client module id
> +is not present, we look in openejb/remote/ where names are formatted
> +using the openejb.jndi.format
> diff --git a/docs/application-composer/advanced.adoc \
> b/docs/application-composer/advanced.adoc new file mode 100644
> index 0000000..781a676
> --- /dev/null
> +++ b/docs/application-composer/advanced.adoc
> @@ -0,0 +1,111 @@
> += Application Composer Advanced
> +
> +link:getting-started.html[Getting Started] page gives you already a lot
> +of inputs but you caneven go further.
> +
> +== @Descriptors
> +
> +You can reuse existing file descriptors using `@Descriptors`. The name
> +is the file name and the path either a classpath path or a file path:
> +
> +[source,java]
> +----
> +// runner if needed etc...
> +@Descriptors(@Descriptor(name = "persistence.xml", path = \
> "META-INF/persistence.xml")) +public class MyTest {
> + //...
> +}
> +----
> +
> +Note: this can be put in a `@Module` method as well.
> +
> +== Services
> +
> +If you want to test a JAXRS or JAXWS service you need to activate these
> +services.
> +
> +To do so just add the needed dependency and use `@EnableServices`:
> +
> +[source,java]
> +----
> +// runner if needed etc...
> +@EnableService("jaxrs") // jaxws supported as well
> +public class MyTest {
> + //...
> +}
> +----
> +
> +== Random port
> +
> +Services like JAXRS and JAXWS relies on HTTP. Often it is nice to have a
> +random port to be able to deploy multiple tests/projects on the same CI
> +platform at the same time.
> +
> +To shortcut all the needed logic you can use `@RandomPort`. It is simply
> +an injection giving you either the port (`int`) or the root context
> +(`URL`):
> +
> +[source,java]
> +----
> +// runner, services if needed etc...
> +public class MyTest {
> + @RandomPort("http")
> + private int port;
> +}
> +----
> +
> +Note: you can generate this way multiple ports. The value is the name of
> +the service it will apply on (being said http is an alias for httpejbd
> +which is our embedded http layer).
> +
> +== Nice logs
> +
> +`@SimpleLog` annotation allows you to have one liner logs
> +
> +== @JaxrsProvider
> +
> +`@JaxrsProvider` allows you to specify on a `@Module` method the list of
> +JAXRS provider you want to use.
> +
> +== Dependencies without hacky code
> +
> +`@Jars` allows you to add dependencies (scanned) to your application
> +automatically (like CDI libraries):
> +
> +[source,java]
> +----
> +@Module
> +@Classes(cdi = true, value = { C1.class, C2.class, E1.class })
> +@Jars("deltaspike-")
> +public WebApp app() {
> + return new WebApp();
> +}
> +----
> +
> +== @Default
> +
> +`@Default` automatically adds in the application `target/classes` as
> +binaries and `src/main/webapp` as resources for maven projects.
> +
> +== @CdiExtensions
> +
> +This annotation allows you to control which extensions are activated
> +during the test.
> +
> +== @AppResource
> +
> +This annotation allows injection of few particular test resources like:
> +
> +* the test `AppModule` (application meta)
> +* the test `Context` (JNDI)
> +* the test `ApplicationComposers` (underlying runner)
> +* `ContextProvider`: allow to mock JAXRS contexts
> +
> +== @MockInjector
> +
> +Allows to mock EJB injections. It decorates a dedicated method returning
> +an instance (or Class) implementing `FallbackPropertyInjector`.
> +
> +== @WebResource
> +
> +Allow for web application to add folders containing web resources.
> diff --git a/docs/application-composer/getting-started.adoc \
> b/docs/application-composer/getting-started.adoc new file mode 100644
> index 0000000..337a6c6
> --- /dev/null
> +++ b/docs/application-composer/getting-started.adoc
> @@ -0,0 +1,234 @@
> += Application Composer Getting Started
> +
> +ApplicationComposer API is mainly contained in
> +`org.apache.openejb.testing` package (historically, today we would have
> +called the package `org.apache.tomee.applicationcomposer`).
> +
> +== Dependencies
> +
> +To start using ApplicationComposer you need to add some dependencies.
> +
> +The minimum required one is `openejb-core`:
> +
> +[source,xml]
> +----
> +<dependency>
> + <groupId>org.apache.openejb</groupId>
> + <artifactId>openejb-core</artifactId>
> + <version>${openejb.version></version>
> +</dependency>
> +----
> +
> +If you need JAXRS services you'll add (or replace thanks to transitivity
> +of maven) `openejb-cxf-rs`:
> +
> +[source,xml]
> +----
> +<dependency>
> + <groupId>org.apache.openejb</groupId>
> + <artifactId>openejb-cxf-rs</artifactId>
> + <version>${openejb.version></version>
> +</dependency>
> +----
> +
> +If you need JAXWS services you'll add (or replace thanks to transitivity
> +of maven) `openejb-cxf`:
> +
> +[source,xml]
> +----
> +<dependency>
> + <groupId>org.apache.openejb</groupId>
> + <artifactId>openejb-cxf</artifactId>
> + <version>${openejb.version></version>
> +</dependency>
> +----
> +
> +etc...
> +
> +== ApplicationComposer Components
> +
> +=== @Module
> +
> +An ApplicationComposer needs at minimum a module (the application you
> +need to deploy).
> +
> +To do so you have two cases:
> +
> +* before TomEE 2.x: you can only write method(s) decorated with
> +`@Module`
> +* since TomEE 2.x: you can skip it and use `@Classes` directly on the
> +ApplicationComposer class as a shortcut for:
> ++
> +@Module public WebApp app() \{ return new WebApp(); }
> +
> +The expected returned type of these methods are in
> +`org.apache.openejb.jee` package:
> +
> +* `Application`: entry point to create an ear
> +* `WebApp`: a web application
> +* `EjbJar`: an ejb module
> +* `EnterpriseBean` children: a simple EJB
> +* `Persistence`: a persistence module with multiple units
> +* `PersistenceUnit`: a simple unit (automatically wrapped in a
> +`Persistence`)
> +* `Connector`: a JCA connector module
> +* `Beans`: a CDI module,
> +* `Class[]` or `Class`: a set of classes scanned to discover annotations
> +
> +Note that for easiness `@Classes` was added to be able to describe a
> +module and some scanned classes. For instance the following snippet will
> +create a web application with classes C1, C2 as CDI beans and E1 as an
> +EJB automatically:
> +
> +[source,java]
> +----
> +@Module
> +@Classes(cdi = true, value = { C1.class, C2.class, E1.class })
> +public WebApp app() {
> + return new WebApp();
> +}
> +----
> +
> +=== @Configuration
> +
> +Often you need to customize a bit the container or at least create some
> +resources like test databases. To do so you can create a method
> +returning `Properties` which will be the container properties.
> +
> +Note: to simplify writing properties you can use `PropertiesBuilder`
> +util class which is just a fluent API to write properties.
> +
> +In these properties you can reuse OpenEJB/TomEE property syntax for
> +resources.
> +
> +Here is a sample:
> +
> +[source,java]
> +----
> +@Configuration
> +public Properties configuration() {
> + return new PropertiesBuilder()
> + .p("db", "new://Resource?type=DataSource")
> + .p("db.JdbcUrld", "jdbc:hsqldb:mem:test")
> + .build();
> +}
> +----
> +
> +Since TomEE 2.x you can also put properties on ApplicationComposer class
> +using `@ContainerProperties` API:
> +
> +[source,java]
> +----
> +@ContainerProperties({
> + @ContainerProperties.Property(name = "db", value = \
> "new://Resource?type=DataSource"), + @ContainerProperties.Property(name = \
> "db.JdbcUrl", value = "jdbc:hsqldb:mem:test") +})
> +public class MyAppComposer() {
> + // ...
> +}
> +----
> +
> +=== @Component
> +
> +Sometimes you need to customize a container component. The most common
> +use case is the security service to mock a little bit authorization if
> +you don't care in your test.
> +
> +To do so just write a method decorated with `@Component` returning the
> +instance you desire.
> +
> +Components in TomEE are stored in a container Map and the key needs to
> +be a `Class`. This one is deduced from the returned type of the
> +`@Component` method:
> +
> +[source,java]
> +----
> +@Component
> +public SecurityService mockSecurity() {
> + return new MySecurityService();
> +}
> +----
> +
> +== How to run it?
> +
> +=== JUnit
> +
> +If you use JUnit you have mainly 2 solutions to run you "model" using
> +the ApplicationComposer:
> +
> +* using `ApplicationComposer` runner:
> ++
> +@RunWith(ApplicationComposer.class) public class MyTest \{ // ... }
> +* using `ApplicationComposerRule` rule:
> ++
> +public class MyTest \{ `@Rule` // or `@ClassRule` if you want the
> +container/application lifecycle be bound to the class and not test
> +methods public final ApplicationComposerRule rule = new
> +ApplicationComposerRule(this); }
> +
> +Tip: since TomEE 2.x ApplicationComposerRule is decomposed in 2 rules if
> +you need: `ContainerRule` and `DeployApplication`. Using JUnit
> +`RuleChain` you can chain them to get the samebehavior as
> +`ApplicationComposerRule` or better deploy multiple ApplicationComposer
> +models and controlling their deployment ordering (to mock a remote
> +service for instance).
> +
> +Finally just write `@Test` method using test class injections as if the
> +test class was a managed bean!
> +
> +=== TestNG
> +
> +TestNG integration is quite simple today and mainly
> +`ApplicationComposerListener` class you can configure as a listener to
> +get ApplicationComposer features.
> +
> +Finally just write TestNG `@Test` method using test class injections as
> +if the test class was a managed bean!
> +
> +=== Standalone
> +
> +Since TomEE 2.x you can also use `ApplicationComposers` to directly run
> +you ApplicationComposer model as a standalone application:
> +
> +[source,java]
> +----
> +public class MyApp {
> + public static void main(String[] args) {
> + ApplicationComposers.run(MyApp.class, args);
> + }
> +
> + // @Module, @Configuration etc...
> +}
> +----
> +
> +Tip: if `MyApp` has `@PostConstruct` methods they will be respected and
> +if `MyApp` has a constructor taking an array of String it will be
> +instantiated getting the second parameter as argument (ie you can
> +propagate your main parameter to your model to modify your application
> +depending it!)
> +
> +== JUnit Sample
> +
> +[source,java]
> +----
> +@Classes(cdi = true, value = { MyService.class, MyOtherService.class })
> +@ContainerProperties(@ContainerProperties.Property(name = "myDb", value = \
> "new://Resource?type=DataSource")) +@RunWith(ApplicationComposer.class)
> +public class MyTest {
> + @Resource(name = "myDb")
> + private DataSource ds;
> +
> + @Inject
> + private MyService service;
> +
> + @Test
> + public void myTest() {
> + // do test using injections
> + }
> +}
> +----
> +
> +== Going further
> +
> +If you want to learn more about ApplicationComposer see
> +link:advanced.html[Advanced] page.
> diff --git a/docs/application-composer/history.adoc \
> b/docs/application-composer/history.adoc new file mode 100644
> index 0000000..fdc33ea
> --- /dev/null
> +++ b/docs/application-composer/history.adoc
> @@ -0,0 +1,48 @@
> += Application Composer History
> +
> +ApplicationComposer can look like a long story but following it you'll
> +realize it is finally quite natural.
> +
> +== Internal tool
> +
> +TomEE (former OpenEJB) is an Application Server. One of the most
> +important task writing an Application Server is to ensure the
> +implemented features do what is expected. However it is hard to write N
> +test applications, in N modules to ensure it works smoothly. In
> +particular when you want to test a small part of the whole server.
> +
> +So you immediately think to mocking what is not needed. It works but has
> +a big pitfall: test is often a noop or hide a lot of issues.
> +
> +So the idea came to be able to shortcut the part we don't care much
> +about runtime: the application packaging.
> +
> +Here what is the ApplicationComposer: an (originally test) API to create
> +a EE application programmatically.
> +
> +== Designs
> +
> +ApplicationComposer design was aligned on this simple need. An
> +ApplicationComposer "test" (browsing other pages you'll see it is much
> +more than test today) is composed of mainly 2 parts:
> +
> +* modules: methods describing a module of an application. It can be a
> +persistence.xml, an ejb-jar.xml, a web.xml...but all programmatically.
> +* configuration: container configuration allowing to interact with
> +container (creating resources for instance)
> +
> +== Test but not only
> +
> +ApplicationComposer was originally a JUnit only runner but was pretty
> +quickly extended to TestNG too and today you can even use it to write
> +`main(String[])` - even in a shade!
> +
> +API was greatly simplified and it allows you pretty easily to deploy
> +with a simple shade a JAXRS/JAXWS/JMS service!
> +
> +== Going further
> +
> +If you want to go further you can browse:
> +
> +* link:getting-started.html[Getting Started]
> +* link:advanced.html[Advanced]
> diff --git a/docs/application-composer/index.adoc \
> b/docs/application-composer/index.adoc new file mode 100644
> index 0000000..0e05d4d
> --- /dev/null
> +++ b/docs/application-composer/index.adoc
> @@ -0,0 +1,20 @@
> += Application Composer
> +
> +Here is the subdomain dedicated to the Application Composer.
> +
> +If you don't know at all what ApplicationComposer means,
> +link:history.html[History] page will explain you where does it come from
> +and what it can be used to today.
> +
> +If you are already familiar with ApplicationComposer concept and are
> +just looking for a sample, link:getting-started.html[Getting Started] is
> +designed for you.
> +
> +Finally if you already use ApplicationComposer and just desire to go
> +further, link:advanced.html[Advanced] page is the one you need to look!
> +
> +Children:
> +
> +* link:history.html[History]
> +* link:getting-started.html[Getting Started]
> +* link:advanced.html[Advanced]
> diff --git a/docs/application-deployment-solutions.adoc \
> b/docs/application-deployment-solutions.adoc new file mode 100644
> index 0000000..1b759c8
> --- /dev/null
> +++ b/docs/application-deployment-solutions.adoc
> @@ -0,0 +1,92 @@
> += Deploying An Application To TomEE Or OpenEJB
> +:index-group: EJB
> +:jbake-date: 2018-12-05
> +:jbake-type: page
> +:jbake-status: published
> +
> +
> +== Deploying An Application To TomEE Or OpenEJB
> +
> +=== How to deploy my application under TomEE
> +
> +==== Description
> +
> +This aims to be more dynamic in the way you deploy your applications. It
> +is clearly cloud oriented.
> +
> +==== Webapp and TomEE deployment
> +
> +Webapp can be deployed as Tomcat does. Simply put it in webapps folder
> +(or the one you configured) and start TomEE.
> +
> +==== TomEE specific deployment
> +
> +By default TomEE deploys applications (ear, war, jar) contained in
> +$CATALINA_BASE/apps directory at start up.
> +
> +==== Deployer
> +
> +OpenEJB provides a Deployer EJB to do this task. It can be used in your
> +own software looking up remotely the "openejb/DeployerBusinessRemote"
> +EJB. Its interface is "org.apache.openejb.assembler.Deployer". The
> +needed dependency is org.apache.openejb:openejb-core.
> +
> +Once you got your deployer simply invoke the "deploy" method. Give it
> +the location of your application (can be a file, http, https, maven
> +location depending on the way you configured your container, for more
> +information have a look to TomEE provisionning).
> +
> +Note: the "undeploy" method exists too and take the same path.
> +
> +The Deployer is the base of all other solutions
> +
> +==== Maven plugin
> +
> +link:maven/index.html[org.apache.openejb:tomee-maven-plugin] can be used
> +to deploy/undeploy your application. Once this plugin is added to your
> +pom you have access to the following configuration:
> +
> +* tomeeHttpPort
> +* tomeeHost
> +
> +Then simply run
> +
> +[source,bash]
> +----
> +mvn tomee:deploy <path>
> +----
> +
> +or
> +
> +[source,bash]
> +----
> +mvn tomee:undeploy <path>
> +----
> +
> +===== The Deployer through TomEE Webapp
> +
> +When you start TomEE you can locally access the TomEE webapps
> +(http://host:ip/tomee/).
> +
> +Then simply go to JNDI tree, select the deployer in the tree, then click
> +on "invoke this ejb", select the deploy (or undeploy) method, fill the
> +path and click on "invoke".
> +
> +===== Cloud idea
> +
> +If you want to cloudify your application, you'll get a configuration
> +database (or any other storage system ;)).
> +
> +So it means it is easy for you to get a host and a port...so it is easy
> +to deploy on all your server using the deployer: simply use the maven
> +provisioning then run the deployer on all your nodes and that's all!
> +
> +==== Doing it with camel?
> +
> +If you are using a route to deploy/undeploy your applications you can
> +have a look to the proposed camel-openejb component:
> +
> +* base code:
> +http://svn.apache.org/repos/asf/tomee/sandbox/camel/camel-openejb/
> +* proposed to be added to camel:
> +https://issues.apache.org/jira/browse/CAMEL-4935
> diff --git a/docs/application-discovery-via-the-classpath.adoc \
> b/docs/application-discovery-via-the-classpath.adoc new file mode 100644
> index 0000000..4c22c5a
> --- /dev/null
> +++ b/docs/application-discovery-via-the-classpath.adoc
> @@ -0,0 +1,111 @@
> += Application discovery via the classpath
> +:index-group: Testing Techniques
> +:jbake-date: 2018-12-05
> +:jbake-type: page
> +:jbake-status: published
> +
> +This document
> +details the various ways to get OpenEJB to detect applications you would
> +like deployed while in an embedded mode.
> +
> += Empty ejb-jar.xml approach (recommended)
> +
> +Simplify the issue of searching for annotated applications by adding an
> +ejb-jar.xml like this to your app:
> +
> +[source,xml]
> +----
> +<ejb-jar/>
> +----
> +
> +OpenEJB will find the app in the classpath and deploy it along with any
> +annotated beans it may contain.
> +
> +The ejb-jar.xml can contain more than just "" as usual.
> +
> +This is the recommended approach for people using OpenEJB for unit
> +testing as it allows OpenEJB to find your application in the classpath
> +without the need for you to specify any path information which tends to
> +complicate builds.
> +
> +== Including/Excluding paths (advanced)
> +
> +If you do not like the idea of having the ejb-jar.xml in your app or an
> +openejb.xml, we can search the classpath for annotated beans
> +(`@Stateless`, `@Stateful`, `@MessageDriven`) and load them automatically just
> +as if they contained an ejb-jar.xml.
> +
> +This form of searching, however, is very expensive as it involves
> +iterating over every path in the classpath and reading in each class
> +definition contained thereunder and checking it for annotations.
> +
> +This approach can only be made faster by helping us trim down or
> +pinpoint the paths we should search via the
> +_openejb.deployments.classpath.include_ property which can be specified
> +as a _system property_ or a property passed into the _InitialContext_.
> +
> +The value of this property is a regular expression and therefore can be
> +absolute or relative. For example the path
> +"/Users/dblevins/work/swizzle/swizzle-stream/target/classes" which
> +contains the class files of an application you wish to test could be
> +included in any of the following values to the
> +"openejb.deployments.classpath.include" property:
> +
> +* "file:///Users/dblevins/work/swizzle/swizzle-stream/target/classes/"
> +_(an absolute path)_
> +* "file:///Users/dblevins/work/swizzle/.*" _(relative)_
> +* ".*swizzle-stream.*" _(very relative)_
> +* ".*(swizzle-stream|swizzle-jira|acme-rocket-app).*" _(including
> +several paths)_
> +* ".*(swizzle-stream^|swizzle-jira^|acme-rocket-app).*" _(including
> +several paths with Win specific escapes)_
> +
> +Note the filtering is done on URLs in the classpath, so forward slashes
> +should always be used even on OSs using backslash ("").
> +
> +There are also the _openejb.deployments.classpath.exclude_ and
> +_openejb.exclude-include.order_ properties if you wish to work in the
> +opposite direction or change the processing order. The default values
> +for the properties are as follows:
> +
> +[source,properties]
> +----
> + openejb.exclude-include.order=include-exclude //Defines the processing order
> + openejb.deployments.classpath.include="" //Include nothing
> + openejb.deployments.classpath.exclude=".*" //Exclude everything
> +----
> +
> +The exclude and the include are applied separately and the results of
> +each are combined together to create the list of paths OpenEJB will
> +scrape for annotations.
> +
> +[source,java]
> +----
> +*Note:* by default these settings will only affect which jars OpenEJB will
> + scan for annotated components when no descriptor is found. If you would
> + like to use these settings to also filter out jars that do contain
> + descriptors, set the *openejb.deployments.classpath.filter.descriptors*
> + property to _true_. The default is _false_.
> +----
> +
> +== Troubleshooting
> +
> +If the include/exclude is not being processed as you expect first try
> +reversing the order to __openejb.exclude-include.order__=exclude-include
> +There are a number internal filters that may result in an unexpected
> +exclusion.
> +
> +If you're having trouble determining if the META-INF/ejb-jar.xml file
> +for your ejb module is in the classpath, a little debug code like this
> +in your test setup will help you see what OpenEJB sees (which may be
> +nothing):
> +
> +[source,properties]
> +----
> +Enumeration<URL> ejbJars =
> +this.getClass().getClassLoader().getResources("META-INF/ejb-jar.xml");
> +while (ejbJars.hasMoreElements()) {
> + URL url = ejbJars.nextElement();
> + System.out.println("app = " + url);
> +}
> +----
> diff --git a/docs/application-resources.adoc b/docs/application-resources.adoc
> new file mode 100644
> index 0000000..9242118
> --- /dev/null
> +++ b/docs/application-resources.adoc
> @@ -0,0 +1,375 @@
> += Application Resources
> +:index-group: Unrevised
> +:jbake-date: 2018-12-05
> +:jbake-type: page
> +:jbake-status: published
> +
> +
> +== Resources
> +
> +TomEE provides a simple but powerful way to define resources that can be
> +injected into managed components inside your application, or looked up
> +via JNDI. To use a resource, it needs to be defined in the `tomee.xml`
> +configuration file, a `resources.xml` file within an application, or as
> +a system property. Defining a resource in `tomee.xml` will make it
> +available server-wide, whereas defining the resource within a
> +`resources.xml` file makes it available to a specific application.
> +
> +As a simple example, a JMS queue can be defined within `tomee.xml` with
> +the following configuration.
> +
> +[source,xml]
> +----
> +<tomee>
> + <Resource id="MyQueue" type="javax.jms.Queue"/>
> +</tomee>
> +----
> +
> +Once the resource has been defined, the server will create an instance
> +of the resource during startup, and it will be available to be injected
> +into managed components using the `@Resource` annotation, as shown
> +below. The `name` attribute on the `@Resource` annotation should match
> +the `id` attribute on the `Resource` tag.
> +
> +[source,java]
> +----
> +public class JmsClient {
> +
> + @Resource(name="MyQueue")
> + private Queue queue;
> +
> + public void sendMessage() {
> + // implementation here...
> + }
> +
> +}
> +----
> +
> +As an alternative to defining a resource in XML, resources can also be
> +defined using system properties:
> +
> +[source,properties]
> +----
> +MyQueue = new://Resource?type=javax.jms.Queue
> +----
> +
> +Resources, or attributes for resources specified using system properties
> +will override definitions specified in `tomee.xml`. Server-wide
> +resources can be looked up in JNDI under the following name:
> +openejb:Resources/resource id.
> +
> +== Defining Resources
> +
> +The `<Resource>` tag has a number of attributes, and a resource may also
> +have a number of fields that can be configured by adding properties to
> +the body of the `Resource` tag.
> +
> +For example, a DataSource resource needs a JDBC driver, URL, username
> +and password to be able to connect to a database. That would be
> +configured with the following syntax. Notice the key/value pair syntax
> +for the properties within the `<Resource>` tag.
> +
> +[source,xml]
> +----
> +<Resource id="DB" type="DataSource">
> + JdbcDriver com.mysql.jdbc.Driver
> + JdbcUrl jdbc:mysql://localhost/test
> + UserName test
> + Password password
> +</Resource>
> +----
> +
> +Specifying the key/value pairs specific to a Resource can also be done
> +when defining the resource via system properties. This is done be
> +specifying an additional property for each key/value pair, using the
> +resource ID as a prefix: `<resourceId>.<propertyName>=<value>`. The
> +system properties equivalent of the resource above is:
> +
> +[source,java]
> +----
> +p.setProperty("DB", "new://Resource?type=DataSource");
> +p.setProperty("DB.JdbcDriver", "com.mysql.jdbc.Driver");
> +p.setProperty("DB,JdbcUrl", "jdbc:mysql://localhost/test");
> +p.setProperty("DB.UserName", "test");
> +p.setProperty("DB.Password", "password");
> +----
> +
> +The `<Resource>` tag has a number of attributes which control the way
> +that the resource get created.
> +
> +* type
> +
> +A type that TomEE knows. The type is associated with a provider that
> +knows how to create that type, and also any default properties that the
> +resource should have if they are not specified in the resource
> +definition. See service-jar.xml for an example set of service providers
> +that come with TomEE.
> +
> +* provider
> +
> +Explicitly specifies a provider to create the resource, using defaults
> +for any properties not specified.
> +
> +* class-name
> +
> +The fully qualified class that creates the resource. This might the
> +resource class itself, which is created by calling the constructor, or a
> +factory class that provides a specific factory method to create the
> +resource.
> +
> +* factory-name
> +
> +The name of the method to call to create the resource. If this is not
> +specified, the constructor for the class specified by class-name will be
> +used.
> +
> +* constructor
> +
> +Specifies a comma separated list of constructor arguments. These can be
> +other services, or attributes on the resource itself.
> +
> +== Custom resources
> +
> +TomEE allows you to define resources using your own Java classes, and
> +these can also be injected into managed components in the same way as
> +known resource types are.
> +
> +So the following simple resource
> +
> +[source,java]
> +----
> +public class Configuration {
> +
> + private String url;
> + private String username;
> + private int poolSize;
> +
> + // getters and setters
> +}
> +----
> +
> +Can be defined in `tomee.xml` using the following configuration (note
> +the `class-name` attribute):
> +
> +[source,xml]
> +----
> +<Resource id="config" class-name="org.superbiz.Configuration">
> + url http://localhost
> + username tomee
> + poolSize 20
> +</Resource>
> +----
> +
> +This resource must be available in TomEE's system classpath - i.e. it
> +must be defined in a .jar within the `lib/` directory.
> +
> +== Field and properties
> +
> +As shown above, a resource class can define a number of fields, and
> +TomEE will attempt to apply the values from the resource definition onto
> +those fields.
> +
> +As an alternative to this, you can also add a properties field as shown
> +below, and this will have any used properties from the resource
> +configuration set added to it. So as an alternative to the above code,
> +you could do:
> +
> +[source,java]
> +----
> +public class Configuration {
> +
> + private Properties properties;
> +
> + public Properties getProperties() {
> + return properties;
> + }
> +
> + public void setProperties(final Properties properties) {
> + this.properties = properties;
> + }
> +
> +}
> +----
> +
> +Using the same resource definition:
> +
> +[source,xml]
> +----
> +<Resource id="config" class-name="org.superbiz.Configuration">
> + url http://localhost
> + username tomee
> + poolSize 20
> +</Resource>
> +----
> +
> +the url, username and poolSize values will now be available in the
> +properties field, so for example, the username property could be
> +accessed via properties.getProperty("username");
> +
> +== Application resources
> +
> +Resources can also be defined within an application, and optionally use
> +classes from the application's classpath. To define resources in a .war
> +file, include a `WEB-INF/resources.xml`. For an ejb-jar module, use
> +`META-INF/resources.xml`.
> +
> +The format of `resources.xml` uses the same `<Resource>` tag as
> +`tomee.xml`. One key difference is the root element of the XML is
> +`<resources>` and not `<tomee>`.
> +
> +[source,xml]
> +----
> +<resources>
> + <Resource id="config" class-name="org.superbiz.Configuration">
> + url http://localhost
> + username tomee
> + poolSize 20
> + </Resource>
> +</resources>
> +----
> +
> +This mechanism allows you to package your custom resources within your
> +application, alongside your application code, rather than requiring a
> +.jar file in the `lib/` directory.
> +
> +Application resources are bound in JNDI under
> +openejb:Resource/appname/resource id.
> +
> +== Additional resource properties
> +
> +Resources are typically discovered, created, and bound to JNDI very
> +early on in the deployment process, as other components depend on them.
> +This may lead to problems where the final classpath for the application
> +has not yet been determined, and therefore TomEE is unable to load your
> +custom resource.
> +
> +The following properties can be used to change this behavior.
> +
> +* Lazy
> +
> +This is a boolean value, which when true, creates a proxy that defers
> +the actual instantiation of the resource until the first time it is
> +looked up from JNDI. This can be useful if the resource's classpath
> +until the application is started (see below), or to improve startup time
> +by not fully initializing resources that might not be used.
> +
> +* UseAppClassLoader
> +
> +This boolean value forces a lazily instantiated resource to use the
> +application classloader, instead of the classloader available when the
> +resources were first processed.
> +
> +* InitializeAfterDeployment
> +
> +This boolean setting forces a resource created with the Lazy property to
> +be instantiated once the application has started, as opposed to waiting
> +for it to be looked up. Use this flag if you require the resource to be
> +loaded, irrespective of whether it is injected into a managed component
> +or manually looked up.
> +
> +By default, all of these settings are `false`, unless TomEE encounters a
> +custom application resource that cannot be instantiated until the
> +application has started. In this case, it will set these three flags to
> +`true`, unless the `Lazy` flag has been explicitly set.
> +
> +== Initializing resources
> +
> +=== constructor
> +
> +By default, if no factory-name attribute and no constructor attribute is
> +specified on the `Resource`, TomEE will instantiate the resource using
> +its no-arg constructor. If you wish to pass constructor arguments,
> +specify the arguments as a comma separated list:
> +
> +[source,xml]
> +----
> +<Resource id="config" class-name="org.superbiz.Configuration" constructor="id, \
> poolSize"> + url http://localhost
> + username tomee
> + poolSize 20
> +</Resource>
> +----
> +
> +=== factory-name method
> +
> +In some circumstances, it may be desirable to add some additional logic
> +to the creation process, or to use a factory pattern to create
> +resources. TomEE also provides this facility via the `factory-name`
> +method. The `factory-name` attribute on the resource can reference any
> +no argument method that returns an object on the class specified in the
> +`class-name` attribute.
> +
> +For example:
> +
> +[source,java]
> +----
> +public class Factory {
> +
> + private Properties properties;
> +
> + public Object create() {
> +
> + MyResource resource = new MyResource();
> + // some custom logic here, maybe using this.properties
> +
> + return resource;
> + }
> +
> + public Properties getProperties() {
> + return properties;
> + }
> +
> + public void setProperties(final Properties properties) {
> + this.properties = properties;
> + }
> +
> +}
> +
> +<resources>
> + <Resource id="MyResource" class-name="org.superbiz.Factory" \
> factory-name="create"> + UserName tomee
> + </Resource>
> +</resources>
> +----
> +
> +=== @PostConstruct / @PreDestroy
> +
> +As an alternative to using a factory method or a constructor, you can
> +use `@PostConstruct` and `@PreDestroy` methods within your resource class
> +(note that you cannot use this within a different factory class) to
> +manage any additional creation or cleanup activities. TomEE will
> +automatically call these methods when the application is started and
> +destroyed. Using `@PostConstruct` will effectively force a lazily loaded
> +resource to be instantiated when the application is starting - in the
> +same way that the `InitializeAfterDeployment` property does.
> +
> +[source,java]
> +----
> +public class MyClass {
> +
> + private Properties properties;
> +
> + public Properties getProperties() {
> + return properties;
> + }
> +
> + public void setProperties(final Properties properties) {
> + this.properties = properties;
> + }
> +
> + @PostConstruct
> + public void postConstruct() throws MBeanRegistrationException {
> + // some custom initialization
> + }
> + }
> +
> +}
> +----
> +
> +== Examples
> +
> +The following examples demonstrate including custom resources within
> +your application:
> +
> +* resources-jmx-example
> +* resources-declared-in-webapp
> diff --git a/docs/arquillian-available-adapters.adoc \
> b/docs/arquillian-available-adapters.adoc new file mode 100644
> index 0000000..94affb9
> --- /dev/null
> +++ b/docs/arquillian-available-adapters.adoc
> @@ -0,0 +1,319 @@
> += TomEE and Arquillian
> +:index-group: Arquillian
> +:jbake-date: 2018-12-05
> +:jbake-type: page
> +:jbake-status: published
> +
> +
> +Check out the link:arquillian-getting-started.html[Getting started] page
> +if you are not at all familiar with Arquillian.
> +
> +All the Arquillian Adapters for TomEE support the following
> +configuration options in the *src/test/resources/arquillian.xml*:
> +
> +[source,xml]
> +----
> +<container qualifier="tomee" default="true">
> + <configuration>
> + <property name="httpPort">-1</property>
> + <property name="stopPort">-1</property>
> + <!--Optional Container Properties-->
> + <property name="properties">
> + aproperty=something
> + </property>
> + <!--Optional Remote Adapter Deployer Properties
> + <property name="deployerProperties">
> + aproperty=something
> + </property>
> + -->
> + </configuration>
> +</container>
> +----
> +
> +The above can also be set as system properties rather than via the
> +*src/test/resources/arquillian.xml* file.
> +
> +[source,xml]
> +----
> +<build>
> + <plugins>
> + <plugin>
> + <groupId>org.apache.maven.plugins</groupId>
> + <artifactId>maven-surefire-plugin</artifactId>
> + <configuration>
> + <systemPropertyVariables>
> + <tomee.httpPort>-1</tomee.httpPort>
> + <tomee.stopPort>-1</tomee.stopPort>
> + </systemPropertyVariables>
> + </configuration>
> + </plugin>
> + </plugins>
> +</build>
> +----
> +
> +When a port is set to -1, a random port will be chosen. This is key to
> +avoiding port conflicts on CI systems or for just plain clean testing.
> +
> +The TomEE Arquillian adapters will export the actual port chosen back as
> +a system property using the same name. The test case can use the
> +property to retrieve the port and contact the server.
> +
> +[source,java]
> +----
> +URL url = new URL("http://localhost:" + System.getProperty("tomee.httpPort");
> +// use the URL to connect to the server
> +----
> +
> +If that property returns null
> +
> +When you are actually using a test on the client side, you can use
> +instead
> +
> +[source,java]
> +----
> +import org.jboss.arquillian.test.api.ArquillianResource;
> +...
> +@ArquillianResource private URL url;
> +----
> +
> +The URL will get injected by Arquillian. Be careful, that injection only
> +works if your are on the client side (it does not make sense in the
> +server side). So, if for a specific need to need it, just use the system
> +property.
> +
> +== TomEE Embedded Adapter
> +
> +The TomEE Embedded Adapter will boot TomEE right inside the test case
> +itself resulting in one JVM running both the application and the test
> +case. This is generally much faster than the TomEE Remote Adapter and
> +great for development. That said, it is strongly recommended to also run
> +all tests in a Continuous Integration system using the TomEE Remote
> +Adapter.
> +
> +To use the TomEE Embedded Arquillian Adapter, simply add these Maven
> +dependencies to your Maven pom.xml:
> +
> +[source,xml]
> +----
> +<dependency>
> + <groupId>org.apache.openejb</groupId>
> + <artifactId>arquillian-tomee-embedded</artifactId>
> + <version>1.7.1</version> <!--Current version-->
> +</dependency>
> +<dependency>
> + <groupId>org.apache.openejb</groupId>
> + <artifactId>tomee-embedded</artifactId>
> + <version>1.7.1</version>
> +</dependency>
> +<!--Required for WebServices and RESTful WebServices-->
> +<dependency>
> + <groupId>org.apache.openejb</groupId>
> + <artifactId>tomee-webservices</artifactId>
> + <version>1.7.1</version>
> +</dependency>
> +<dependency>
> + <groupId>org.apache.openejb</groupId>
> + <artifactId>tomee-jaxrs</artifactId>
> + <version>1.7.1</version>
> +</dependency>
> +----
> +
> +As mentioned above the Embedded Adapter has the following properties
> +which can be specified in the *src/test/resources/arquillian.xml* file:
> +
> +* `httpPort`
> +* `stopPort`
> +* `properties` (System properties for container)
> +
> +Or alternatively as System properties, possibly shared with other TomEE
> +Arquillian Adapters:
> +
> +* `tomee.httpPort`
> +* `tomee.stopPort`
> +
> +Or more specifically as a System properties only applicable to the
> +Embedded Adapter:
> +
> +* `tomee.embedded.httpPort`
> +* `tomee.embedded.stopPort`
> +
> +== TomEE Remote Adapter
> +
> +The TomEE Remote Adapter will unzip and setup a TomEE or TomEE Plus
> +distribution. Once setup, the server will execute in a separate process.
> +This will be slower, but with the added benefit it is 100% match with
> +the production system environment.
> +
> +On a local machine clients can get the remote server port using the
> +following System property:
> +
> +[source,java]
> +----
> +final String port = System.getProperty("server.http.port");
> +----
> +
> +The following shows a typical configuration for testing against TomEE
> +(webprofile version). The same can be done against TomEE+ by changing
> +`<tomee.classifier>webprofile</tomee.classifier>` to
> +`<tomee.classifier>plus</tomee.classifier>`
> +
> +[source,xml]
> +----
> +<properties>
> + <tomee.version>1.7.1</tomee.version>
> + <tomee.classifier>webprofile</tomee.classifier>
> +</properties>
> +<build>
> + <plugins>
> + <plugin>
> + <groupId>org.apache.maven.plugins</groupId>
> + <artifactId>maven-surefire-plugin</artifactId>
> + <configuration>
> + <systemPropertyVariables>
> + <tomee.classifier>${tomee.classifier}</tomee.classifier>
> + <tomee.version>${tomee.version}</tomee.version>
> + </systemPropertyVariables>
> + </configuration>
> + </plugin>
> + </plugins>
> +</build>
> +<dependencies>
> + <dependency>
> + <groupId>org.apache.openejb</groupId>
> + <artifactId>arquillian-tomee-remote</artifactId>
> + <version>${tomee.version}</version>
> + </dependency>
> + <dependency>
> + <groupId>org.apache.openejb</groupId>
> + <artifactId>apache-tomee</artifactId>
> + <version>${tomee.version}</version>
> + <classifier>${tomee.classifier}</classifier>
> + <type>zip</type>
> + </dependency>
> +</dependencies>
> +----
> +
> +The Remote Adapter has the following properties which can be specified
> +in the *src/test/resources/arquillian.xml* file:
> +
> +* `httpPort`
> +* `stopPort`
> +* `version`
> +* `classifier` (Must be either `webprofile` or `plus`)
> +* `properties` (System properties for container)
> +* `deployerProperties` (Sent to Deployer)
> +
> +Or alternatively as System properties, possibly shared with other TomEE
> +Arquillian Adapters:
> +
> +* `tomee.httpPort`
> +* `tomee.stopPort`
> +* `tomee.version`
> +* `tomee.classifier`
> +
> +Or more specifically as a System properties only applicable to the
> +Remote Adapter:
> +
> +* `tomee.remote.httpPort`
> +* `tomee.remote.stopPort`
> +* `tomee.remote.version`
> +* `tomee.remote.classifier`
> +
> +== Maven Profiles
> +
> +Setting up both adapters is quite easy via Maven profiles. Here the
> +default adapter is the Embedded Adapter, the Remote Adapter will run
> +with `-Ptomee-webprofile-remote` specified as a `mvn` command argument.
> +
> +[source,xml]
> +----
> +<profiles>
> +
> + <profile>
> + <id>tomee-embedded</id>
> + <activation>
> + <activeByDefault>true</activeByDefault>
> + </activation>
> + <dependencies>
> + <dependency>
> + <groupId>org.apache.openejb</groupId>
> + <artifactId>arquillian-tomee-embedded</artifactId>
> + <version>1.0.0</version>
> + </dependency>
> + </dependencies>
> + </profile>
> +
> + <profile>
> + <id>tomee-webprofile-remote</id>
> + <properties>
> + <tomee.version>1.0.0</tomee.version>
> + <tomee.classifier>webprofile</tomee.classifier>
> + </properties>
> + <build>
> + <plugins>
> + <plugin>
> + <groupId>org.apache.maven.plugins</groupId>
> + <artifactId>maven-surefire-plugin</artifactId>
> + <configuration>
> + <systemPropertyVariables>
> + <tomee.classifier>${tomee.classifier}</tomee.classifier>
> + <tomee.version>${tomee.version}</tomee.version>
> + </systemPropertyVariables>
> + </configuration>
> + </plugin>
> + </plugins>
> + </build>
> + <dependencies>
> + <dependency>
> + <groupId>org.apache.openejb</groupId>
> + <artifactId>arquillian-tomee-remote</artifactId>
> + <version>${tomee.version}</version>
> + </dependency>
> + <dependency>
> + <groupId>org.apache.openejb</groupId>
> + <artifactId>apache-tomee</artifactId>
> + <version>${tomee.version}</version>
> + <classifier>${tomee.classifier}</classifier>
> + <type>zip</type>
> + </dependency>
> + </dependencies>
> + </profile>
> +
> + <profile>
> + <id>tomee-plus-remote</id>
> + <properties>
> + <tomee.version>1.0.0</tomee.version>
> + <tomee.classifier>plus</tomee.classifier>
> + </properties>
> + <build>
> + <plugins>
> + <plugin>
> + <groupId>org.apache.maven.plugins</groupId>
> + <artifactId>maven-surefire-plugin</artifactId>
> + <configuration>
> + <systemPropertyVariables>
> + <tomee.classifier>${tomee.classifier}</tomee.classifier>
> + <tomee.version>${tomee.version}</tomee.version>
> + </systemPropertyVariables>
> + </configuration>
> + </plugin>
> + </plugins>
> + </build>
> + <dependencies>
> + <dependency>
> + <groupId>org.apache.openejb</groupId>
> + <artifactId>arquillian-tomee-remote</artifactId>
> + <version>${tomee.version}</version>
> + </dependency>
> + <dependency>
> + <groupId>org.apache.openejb</groupId>
> + <artifactId>apache-tomee</artifactId>
> + <version>${tomee.version}</version>
> + <classifier>${tomee.classifier}</classifier>
> + <type>zip</type>
> + </dependency>
> + </dependencies>
> + </profile>
> +
> +</profiles>
> +----
> diff --git a/docs/arquillian-getting-started.adoc \
> b/docs/arquillian-getting-started.adoc new file mode 100644
> index 0000000..70cb1ab
> --- /dev/null
> +++ b/docs/arquillian-getting-started.adoc
> @@ -0,0 +1,44 @@
> += Getting started with Arquillian and TomEE
> +:index-group: Arquillian
> +:jbake-date: 2018-12-05
> +:jbake-type: page
> +:jbake-status: published
> +
> +
> +Arquillian is a testing framework on top of JUnit (or TestNG if you
> +prefer). It makes it easier to do integration tests in a managed
> +environment (JEE environment here after).
> +
> +We provide an embedded and remote adapter, see
> +link:arquillian-available-adapters.html[the available adapters] for more
> +details.
> +
> +In a managed environment it is usually quite difficult to perform unit
> +tests, due to the fact that most of the time you have to mock almost the
> +entire environment. It is very time consuming and requires complicated
> +integration tests that must reflect the production environment as best
> +as possible. Unit tests lose their true value.
> +
> +JEE always got seen as an heavy technology, impossible to test and to
> +use in development. OpenEJB always fought against that idea and proved
> +that it's really possible.
> +
> +As David Blevins said:
> +
> +> "Do not blame EJBs (ie. Java EE) because your
> +server is not testable."
> +
> +With latest Java EE specifications (5 and especially 6), it becomes a
> +reality. Arquillian typically addresses that area. It is basically a
> +framework that aims at helping/managing the server/container in an
> +agnostic way. Arquillian is responsible for the lifecycle of the
> +container (start, deploy, undeploy, stop, etc).
> +
> +TomEE community heavily invested on that framework to prove it's really
> +useful and can really help testing Java EE application. That's also an
> +opportunity to get the most out of TomEE (lightweight, fast,
> +feature-rich, etc).
> +
> +[tip]
> +TIP: See http://arquillian.org[Arquillian.org] for a great quick-start
> +tutorial on Arquillian itself.
> diff --git a/docs/basics---getting-things.adoc b/docs/basics---getting-things.adoc
> new file mode 100644
> index 0000000..7dc75ec
> --- /dev/null
> +++ b/docs/basics---getting-things.adoc
> @@ -0,0 +1,108 @@
> += Basics - Getting Things
> +:index-group: Unrevised
> +:jbake-date: 2018-12-05
> +:jbake-type: page
> +:jbake-status: published
> +
> += Getting Stuff from the Container
> +
> +Generally speaking the only way to get a
> +link:container-managed-resource.html[Container-Managed Resource] is via
> +_dependency injection_ or _lookup_ from within a [Container-Managed
> +Component] .
> +
> +The _unbreakable rules_. Read these over and over again when things
> +don't work.
> +
> +[arabic]
> +. java:comp/env is the spec defined namespace for lookup of any
> +link:container-managed-resource.html[Container-Managed Resource]
> +. java:comp/env is _empty_ by default
> +. java:comp/env is _read-only_ at runtime
> +. java:comp/env is populated by link:declaring-references.html[Declaring
> +References] to [Container-Managed Resource] via xml or annotation
> +. only link:container-managed-component.html[Container-Managed
> +Component] s, _not_ their libraries, can [Declare References|Declaring
> +References] via xml or annotation
> +. only link:container-managed-component.html[Container-Managed
> +Component] s, _not_ their libraries, can get dependency injection of
> +[Container-Managed Resource] s
> +. only link:container-managed-component.html[Container-Managed
> +Component] s, _and_ their libraries, may lookup from java:comp/env
> +. you _must_ use the _no-arg_ 'new InitialContext()' constructor to
> +lookup something from java:comp/env
> +. the annotations and xml for link:declaring-references.html[Declaring
> +References] are _identical_ in functionality, both _always_ configure
> +lookup with _optional_ dependency injection
> +
> +== Common mistakes, misunderstandings, and myths
> +
> +* __"I tried it via annotation and it didn't work, so I used xml and
> +then it did work"__
> +
> +See rule 9. If one form worked and the other didn't, it means you simply
> +made a mistake in using one versus the other. Use what works for you,
> +but understand both annotations or xml will work for either lookup or
> +injection if used correctly.
> +
> +* __"I need to use lookups, so I can't use the annotation"__
> +
> +See rule 9. Annotations are not just for injection, that is just how
> +they are typically used. Know that when you use an annotation for
> +injection, it will _always_ create an entry in java:comp/env. As well
> +you can use the annotation at the _class level_ and it will cause no
> +dependency injection and only the entry creation in java:comp/env.
> +
> +* __"I don't want injection, so I can't use the annotation"__
> +
> +See rule 9 and the above. You can use the annotation at the _class
> +level_ and it will cause no dependency injection and only the entry
> +creation in java:comp/env.
> +
> +* __"I tried to list java:comp/env but it's empty?!"__
> +
> +See rule 2 and rule 4. There will be nothing in java:comp/env unless you
> +link:declaring-references.html[Declare a Reference] to it. It does not
> +matter if is a DataSource configured at the server level, etc. Nothing
> +is bound into java:comp/env unless you explicitly declare a reference to
> +it. The Java EE 5 TCK (Technology Compatibility Kit) tests for this
> +extensively and is a rule we cannot break. Java EE 6 does finally offer
> +some new namesaces (java:global, java:app, and java:module) which will
> +offer some great new options for more global-style lookups.
> +
> +* __"I deployed the EJB but can't look it up, it's name is Foo"__
> +
> +See rule 2 and the above. Just creating an EJB doesn't cause it to be
> +added to java:comp/env. If a
> +link:container-managed-component.html[Container-Managed Component] wants
> +to lookup the EJB they must [Declare a Reference|Declaring References]
> +to it via the `@EJB` annotionation or <ejb-local-ref> or <ejb-ref> in xml.
> +In Java EE 6, however, EJBs will be automatically bound to
> +"java:global[/<app-name>]/<module-name>/<bean-name>[!<fully-qualified-interface-name>]"
> +and can be looked up without declaring a reference first.
> +
> +* __"Which InitialContextFactory do I use for java:comp/env?"__
> +
> +See rule 8. You are not allowed to use an InitialContextFactory for
> +java:comp/env lookups. Setting an InitialContextFactory via
> +'java.naming.factory.initial' in either System properties,
> +InitialContext properties, or a jndi.properties file is illegal and will
> +cause java:comp/env lookups to fail.
> +
> +* __"My Client can't lookup the EJB from java:comp/env"__
> +
> +See rule 7. A plain, standalone, Java application cannot use
> +java:comp/env. There is the official concept of a Java EE Application
> +Client which can be packaged in an ear and deployed into the Container.
> +In practice, most people find them restrictive, cumbersome, and hard to
> +use and are therefore rarely employed in "real world" projects. Most
> +people opt to use the non-standard, vendor-specific, approach to looking
> +up EJBs from their plain java clients. In OpenEJB this can be done via
> +either the RemoteInitialContextFactory (for remote clients) or the
> +LocalInitialContextFactory (for local clients of an embedded container).
> +The JNDI names can be configured as link:jndi-names.html[shown here] .
> +
> +* __"I declared the reference, but still can't look it up"__
> +
> +See all of the above and reread the rules a few times. Always check the
> +log output as well.
> diff --git a/docs/basics---security.adoc b/docs/basics---security.adoc
> new file mode 100644
> index 0000000..294e0d4
> --- /dev/null
> +++ b/docs/basics---security.adoc
> @@ -0,0 +1,55 @@
> += Basics - Security
> +:index-group: Unrevised
> +:jbake-date: 2018-12-05
> +:jbake-type: page
> +:jbake-status: published
> +
> +This section is under construction, please check back later.
> +
> +== Related Documents
> +
> +link:security.html[Security] - login module configuration
> +link:security-annotations.html[Security Annotations] - EJB3 related
> +annotation based security.
> +
> +== Server Side Security
> +
> +There's a few things that should be noted about security from the server
> +side perspective.
> +
> +=== Security Propagation Note, this is partially documented in the EJB 3
> +spec section 14.8.1.1.
> +
> +[arabic]
> +. Once a remote bean has been instantiated, from within the container,
> +it inherits the entire security context, and all roles will be inherited
> +the same as the method where the bean is being looked up.
> +. Looking up a bean via an `InitialContext`, or via injection, will
> +inherit the security context (user, roles, etc), thereby propagating the
> +security through to any container bean in the chain of method calls.
> +. No properties are allowed for the `InitialContext`, and you _MUST_ be
> +calling the no args constructor only. There are documents elsewhere that
> +describe using the OpenEJB initial context factories and such, with
> +usernames and passwords, etc; it should be noted that this method of
> +using the factories is OpenEJB specific, to facilitate non-standard
> +clients not running in an EJB container, etc.
> +
> +For example, here is an EJB that returns another bean, through a remote
> +method call. In this case, the _OtherBean_ instance, will have the same
> +security as _MyBean_, including the principal (username), roles, etc.
> +
> +[source,java]
> +----
> +import javax.ejb.EJB;
> +import javax.naming.InitialContext;
> +
> +@EJB(name = "otherBean", beanInterface = IOtherBean.class)
> +public class MyBean
> +{
> + public IOtherBean getOtherBean()
> + {
> + InitialContext context = new InitialContext();
> + return (IOtherBean) context.lookup("java:comp/env/otherBean");
> + }
> +}
> +----
> diff --git a/docs/basics---transactions.adoc b/docs/basics---transactions.adoc
> new file mode 100644
> index 0000000..43f98c7
> --- /dev/null
> +++ b/docs/basics---transactions.adoc
> @@ -0,0 +1,67 @@
> += Basics - Transactions
> +:index-group: Unrevised
> +:jbake-date: 2018-12-05
> +:jbake-type: page
> +:jbake-status: published
> +
> +One of the many benefits of EJB, is that
> +transactions within the EJB container are generally managed entirely
> +automatically. Any EJB component will, by default, partake in that
> +transaction.
> +
> +Here are some basic rules to understand about transactions. Keep note
> +that this is the default behaviour, and the system can be configured to
> +behave differently, depending on the needs of your system, bean, or
> +individual methods of your beans.
> +
> +== Participants
> +
> +Various components and parts of the EJB system can be part of a
> +transaction. Examples are
> +
> +[arabic]
> +. Session bean
> +. Message Driven Bean
> +. EntityManager (a.k.a. Persistence context)
> +
> +== Behaviour
> +
> +The basic default behaviours are 1. A transaction starts at the
> +beginning of the first EJB method call, in a chain of calls that are
> +participating in the given transaction 1. A transaction ends at the end
> +of the first EJB method, in the same chain 1. If a bean that has started
> +a transaction, uses another bean, that bean will automatically use the
> +same transaction as the calling bean.
> +
> +== Configuration
> +
> +You can configure your beans in a variety of ways. Generally speaking, a
> +transaction is started when a method is called, but can be configured
> +using `@TransactionAttribute`(value = TransactionAttributeType.X), where X
> +is one of...
> +
> +[arabic]
> +. REQUIRED - the default, which is to start a transaction if one does
> +not exist, but to use the existing one if it has already been started.
> +. REQUIRES_NEW - the transaction is created on every call, and ends when
> +the call is completed. Beans don't partake in transactions created by
> +other parts of the system.
> +. MANDATORY - a transaction must always exist prior to the call, and it
> +will be used. It is an error otherwise
> +. NOT_SUPPORTED - component not included in the transaction
> +. SUPPORTS - transaction will be used if it exists, but will not be
> +created if it does not exist
> +. NEVER - if a transaction exists, it is an error to call the method
> +
> +@TransactionAttribute applies to both methods and entire beans. You may
> +set one type of transaction behaviour (as seen above) on the bean, and a
> +different one on a specific method of that same bean, which overrides
> +the one configured for the overall bean. For instance, maybe you want to
> +make an audit entry in the database that you are about to attempt a
> +credit card payment. It really needs to be in it's own transaction so
> +that it is IMMEDIATELY committed for audit purposes, if something goes
> +wrong with the credit card payment. So, perhaps you use MANDATORY on the
> +bean, and REQUIRES_NEW on the method for audit logging. As soon as the
> +method that does the audit logging is complete, the transaction is
> +committed, and the credit card payment transaction continues on it's
> +way.
> diff --git a/docs/bouncy-castle.adoc b/docs/bouncy-castle.adoc
> new file mode 100644
> index 0000000..3bf3a7a
> --- /dev/null
> +++ b/docs/bouncy-castle.adoc
> @@ -0,0 +1,40 @@
> += Installing Bouncy Castle
> +:index-group: Unrevised
> +:jbake-date: 2018-12-05
> +:jbake-type: page
> +:jbake-status: published
> +
> +NOTE: Licensed to the Apache Software Foundation (ASF)
> +under one or more contributor license agreements. See the NOTICE file
> +distributed with this work for additional information regarding
> +copyright ownership. The ASF licenses this file to you under the Apache
> +License, Version 2.0 (the "License"); you may not use this file except
> +in compliance with the License. You may obtain a copy of the License at
> +. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by
> +applicable law or agreed to in writing, software distributed under the
> +License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR
> +CONDITIONS OF ANY KIND, either express or implied. See the License for
> +the specific language governing permissions and limitations under the
> +License.
> +
> +Installation of Bouncy Castle for use in TomEE itself is done in two
> +steps:
> +
> +[arabic]
> +. Add the Bouncy Castle provider jar to the `$JAVA_HOME/jre/lib/ext`
> +directory
> +. Create a Bouncy Castle provider entry in the
> +`$JAVA_HOME/jre/lib/security/java.security` file
> +
> +The entry to `java.security` will look something like the following:
> +
> +[source,properties]
> +----
> +security.provider.N=org.bouncycastle.jce.provider.BouncyCastleProvider
> +----
> +
> +Replace `N` with the order of precedence you would like to give Bouncy
> +Castle in comparison to the other providers in the file. *Recommended*
> +would be the last entry in the list -- `N` being the higest number in
> +the list. *Warning* that configuring Bouncy Castle as the first
> +provider, `security.provider.1`, may cause JVM errors.
> diff --git a/docs/built-in-type-converters.adoc \
> b/docs/built-in-type-converters.adoc new file mode 100644
> index 0000000..a3649b3
> --- /dev/null
> +++ b/docs/built-in-type-converters.adoc
> @@ -0,0 +1,101 @@
> += Built-in Type Converters
> +:index-group: Unrevised
> +:jbake-date: 2018-12-05
> +:jbake-type: page
> +:jbake-status: published
> +
> +The following built-in types are supported for
> +@Resource injection in EJBs via elements in a META-INF/ejb-jar.xml or
> +via plain properties in a META-INF/env-entries.properties file.
> +
> +EJB 3.0 required types:
> +
> +* java.lang.Boolean
> +* java.lang.Byte
> +* java.lang.Character
> +* java.lang.Double
> +* java.lang.Float
> +* java.lang.Integer
> +* java.lang.Long
> +* java.lang.Short
> +* java.lang.String
> +
> +OpenEJB 3.0 additional types:
> +
> +* java.lang.Class
> +* java.lang.Enum (any subclass of)
> +* java.io.File
> +* java.math.BigDecimal
> +* java.math.BigInteger
> +* java.net.Inet4Address
> +* java.net.Inet6Address
> +* java.net.InetAddress
> +* java.net.URI
> +* java.net.URL
> +* java.util.ArrayList
> +* java.util.Date
> +* java.util.HashMap
> +* java.util.Hashtable
> +* java.util.IdentityHashMap
> +* java.util.LinkedHashMap
> +* java.util.LinkedHashSet
> +* java.util.LinkedList
> +* java.util.List
> +* java.util.Map
> +* java.util.Properties
> +* java.util.Set
> +* java.util.SortedMap
> +* java.util.TreeMap
> +* java.util.TreeSet
> +* java.util.Vector
> +* java.util.WeakHashMap
> +* java.util.logging.Logger
> +* java.util.regex.Pattern
> +* javax.management.ObjectName
> +* javax.naming.Context
> +* org.apache.commons.logging.Log
> +* org.apache.log4j.Logger
> +
> +To use an OpenEJB additional type in xml, simply declare it as
> +java.lang.String and it will be converted on the fly to the field/setter
> +type used by the bean class. For example:
> +
> +[source,java]
> +----
> +package org.superbiz.foo;
> +
> +import java.util.Date;
> +
> +@Stateless
> +public class MyBean {
> +
> + @Resource
> + private Date myDate;
> +}
> +----
> +
> +Works with an ejb-jar.xml as follows:
> +
> +[source,xml]
> +----
> +<ejb-jar xmlns="http://java.sun.com/xml/ns/javaee" version="3.0"
> +metadata-complete="false">
> + <enterprise-beans>
> + <session>
> + <ejb-name>MyBean</ejb-name>
> + <env-entry>
> + <env-entry-name>org.superbiz.foo.MyBean/myDate</env-entry-name>
> + <env-entry-value>2008-04-19</env-entry-value>
> + <env-entry-type>java.lang.String</env-entry-type>
> + </env-entry>
> + </session>
> + </enterprise-beans>
> +</ejb-jar>
> +----
> +
> +Or with an env-entries.properties file as follows:
> +
> +[source,properties]
> +----
> +org.superbiz.foo.MyBean/myDate = 2008-04-19
> +----
> diff --git a/docs/callbacks.adoc b/docs/callbacks.adoc
> new file mode 100644
> index 0000000..14e7694
> --- /dev/null
> +++ b/docs/callbacks.adoc
> @@ -0,0 +1,169 @@
> += Callbacks
> +:index-group: Unrevised
> +:jbake-date: 2018-12-05
> +:jbake-type: page
> +:jbake-status: published
> +
> +Correct usage of PostConstruct, PreDestroy, PrePassivate, PostActivate,
> +and AroundInvoke for EJBs and Interceptors.
> +
> +For Stateful, Stateless, and MessageDriven, the syntax is as follows:
> +
> +* @PostConstruct <any-scope> void <method-name>()
> +* @PreDestroy <any-scope> void <method-name>()
> +* @PrePassivate <any-scope> void <method-name>()
> +* @PostActivate <any-scope> void <method-name>()
> +
> +For an Interceptor, the syntax includes InvocationContext as follows:
> +
> +* @PostConstruct <any-scope> void <method-name>(InvocationContext)
> +* @PreDestroy <any-scope> void <method-name>(InvocationContext)
> +* @PrePassivate <any-scope> void <method-name>(InvocationContext)
> +* @PostActivate <any-scope> void <method-name>(InvocationContext)
> +
> +The AroundInvoke syntax for an EJB or Interceptor is the same:
> +
> +* @AroundInvoke <any-scope> Object <method-name>(InvocationContext)
> +throws Exception
> +
> +== Stateless
> +
> +[source,java]
> +----
> +import javax.ejb.Stateless;
> +import javax.annotation.PostConstruct;
> +import javax.annotation.PreDestroy;
> +import javax.interceptor.AroundInvoke;
> +import javax.interceptor.InvocationContext;
> +
> +@Stateless
> +public class MyStatelessBean implements MyBusinessInterface {
> +
> + @PostConstruct
> + public void constructed(){
> +
> + }
> +
> + @PreDestroy
> + public void destroy(){
> +
> + }
> +
> + @AroundInvoke
> + public Object invoke(InvocationContext invocationContext) throws Exception {
> + return invocationContext.proceed();
> + }
> +}
> +----
> +
> +== Stateful
> +
> +[source,java]
> +----
> +import javax.ejb.Stateful;
> +import javax.ejb.PostActivate;
> +import javax.ejb.PrePassivate;
> +import javax.annotation.PostConstruct;
> +import javax.annotation.PreDestroy;
> +import javax.interceptor.AroundInvoke;
> +import javax.interceptor.InvocationContext;
> +
> +@Stateful
> +public class MyStatefulBean implements MyBusinessInterface {
> +
> + @PostConstruct
> + public void constructed(){
> +
> + }
> +
> + @PreDestroy
> + public void destroy(){
> +
> + }
> +
> + @AroundInvoke
> + public Object invoke(InvocationContext invocationContext) throws Exception {
> + return invocationContext.proceed();
> + }
> +
> + @PostActivate
> + public void activated(){
> +
> + }
> +
> + @PrePassivate
> + public void passivate(){
> +
> + }
> +}
> +----
> +
> +== MessageDriven
> +
> +[source,java]
> +----
> +import javax.ejb.MessageDriven;
> +import javax.annotation.PostConstruct;
> +import javax.annotation.PreDestroy;
> +import javax.interceptor.AroundInvoke;
> +import javax.interceptor.InvocationContext;
> +
> +@MessageDriven
> +public class MyMessageDrivenBean implements MyListenerInterface {
> +
> + @PostConstruct
> + public void constructed(){
> +
> + }
> +
> + @PreDestroy
> + public void destroy(){
> +
> + }
> +
> + @AroundInvoke
> + public Object invoke(InvocationContext invocationContext) throws Exception {
> + return invocationContext.proceed();
> + }
> +}
> +----
> +
> +== Interceptor
> +
> +[source,java]
> +----
> +import javax.annotation.PostConstruct;
> +import javax.annotation.PreDestroy;
> +import javax.interceptor.InvocationContext;
> +import javax.interceptor.AroundInvoke;
> +import javax.ejb.PostActivate;
> +import javax.ejb.PrePassivate;
> +
> +public class MyInterceptor {
> +
> + @PostConstruct
> + public void constructed(InvocationContext invocationContext){
> +
> + }
> +
> + @PreDestroy
> + public void destroy(InvocationContext invocationContext){
> +
> + }
> +
> + @AroundInvoke
> + public Object invoke(InvocationContext invocationContext) throws Exception {
> + return invocationContext.proceed();
> + }
> +
> + @PostActivate
> + public void activated(InvocationContext invocationContext){
> +
> + }
> +
> + @PrePassivate
> + public void passivate(InvocationContext invocationContext){
> +
> + }
> +}
> +----
> diff --git a/docs/changing-jms-implementations.adoc \
> b/docs/changing-jms-implementations.adoc new file mode 100644
> index 0000000..a56d7c7
> --- /dev/null
> +++ b/docs/changing-jms-implementations.adoc
> @@ -0,0 +1,161 @@
> += Changing JMS Implementations
> +:index-group: Configuration
> +:jbake-date: 2018-12-05
> +:jbake-type: page
> +:jbake-status: published
> +
> +NOTE: Licensed to the Apache Software
> +Foundation (ASF) under one or more contributor license agreements. See
> +the NOTICE file distributed with this work for additional information
> +regarding copyright ownership. The ASF licenses this file to you under
> +the Apache License, Version 2.0 (the "License"); you may not use this
> +file except in compliance with the License. You may obtain a copy of the
> +License at . http://www.apache.org/licenses/LICENSE-2.0 . Unless
> +required by applicable law or agreed to in writing, software distributed
> +under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES
> +OR CONDITIONS OF ANY KIND, either express or implied. See the License
> +for the specific language governing permissions and limitations under
> +the License.
> +
> +ActiveMQ is the default JMS provider in Apache TomEE and OpenEJB.
> +
> +Changing JMS implementation is as simple as using that implementation's
> +Java EE Connector. The connector which will be a `.rar` file should be
> +bundled with the application in a `.ear` file. All JMS usage in that
> +`.ear` will favor the JMS ConnectionFactory and Topic and Queue
> +implementations that are configured in the `.rar` file rather than
> +ActiveMQ.
> +
> +If the JMS implementation does not have a `.rar` file, there are still
> +some options for wiring in an alternate implementation.
> +
> +== Generic JMS Resource Adapter
> +
> +If the JMS implementation does not have a Resource Archive (`.rar` file)
> +that defines a compliant Resource Adapter, the
> +http://genericjmsra.java.net/[Generic Resource Adapter for JMS] should
> +work fine.
> +
> +To use this Adapter in TomEE or OpenEJB you'll need to create a
> +`service-jar.xml` file and include that in a jar file and add it to the
> +`<tomee.home>/lib/` directory. Then you can declare `ConnectionFactory`,
> +`Topic`, and `Queue` and more via the `tomee.xml` file.
> +
> +The one below should be considered boiler plate. Updating it to contain
> +some useful default values for your JMS implementation would be good.
> +These values can be overridden in the `tomee.xml` or `openejb.xml`
> +
> +Let's say that the following file lives in the jar at
> +`META-INF/org.superbiz/service-jar.xml`
> +
> +[source,xml]
> +----
> +<?xml version="1.0" encoding="UTF-8"?>
> +<ServiceJar>
> + <ServiceProvider
> + id="genericra"
> + service="Resource"
> + types="GenericJMSRA"
> + class-name="com.sun.genericra.GenericJMSRA">
> + UserName
> + Password
> + ProviderIntegrationMode
> + ConnectionFactoryClassName
> + QueueConnectionFactoryClassName
> + TopicConnectionFactoryClassName
> + XAConnectionFactoryClassName
> + XAQueueConnectionFactoryClassName
> + XATopicConnectionFactoryClassName
> + UnifiedDestinationClassName
> + TopicClassName
> + QueueClassName
> + SupportsXA
> + ConnectionFactoryProperties
> + JndiProperties
> + CommonSetterMethodName
> + RMPolicy
> + LogLevel
> + DeliveryType
> + UseFirstXAForRedelivery
> + </ServiceProvider>
> +
> + <ServiceProvider
> + id="ConnectionFactory"
> + service="Resource"
> + types="javax.jms.ConnectionFactory, javax.jms.QueueConnectionFactory, \
> javax.jms.TopicConnectionFactory, QueueConnectionFactory, TopicConnectionFactory" + \
> class-name="com.sun.genericra.outbound.ManagedJMSConnectionFactory"> + \
> ConnectionFactoryJndiName + ClientId
> + ConnectionValidationEnabled
> + ResourceAdapter
> + </ServiceProvider>
> +
> + <ServiceProvider
> + id="Queue"
> + service="Resource"
> + types="javax.jms.Queue, Queue"
> + class-name="com.sun.genericra.outbound.QueueProxy">
> + DestinationJndiName
> + ResourceAdapter
> + UserName
> + Password
> + JndiProperties
> + QueueClassName
> + </ServiceProvider>
> +
> + <ServiceProvider
> + id="Topic"
> + service="Resource"
> + types="javax.jms.Topic, Topic"
> + class-name="com.sun.genericra.outbound.TopicProxy">
> + DestinationJndiName
> + ResourceAdapter
> + UserName
> + Password
> + JndiProperties
> + TopicClassName
> + </ServiceProvider>
> +</ServiceJar>
> +----
> +
> +It is strongly recommended to not leave the values in the
> +service-jar.xml file blank as shown above. It is possible to setup
> +several sets of defaults in a `service-jar.xml` or via several
> +`service-jar.xml` files.
> +
> +Once this file is packed in a jar and added to the `<tomee.home>/lib` or
> +`<openejb.home>/lib` directory, you can then declare and configure
> +"instances" of these things in your `tomee.xml` or `openejb.xml` config
> +file as follows:
> +
> +[source,xml]
> +----
> +<Resource id="My Generic Adapter" type="GenericJMSRA" \
> provider="org.superbiz:genericra"> +AdapterProperty1 PropertyValue1
> +AdapterProperty2 PropertyValue2
> +...
> +</Resource>
> +----
> +
> +Or in properties like so:
> +
> +[source,properties]
> +----
> +myGenericAdapter = \
> new://Resource?type=GenericJMSRA&provider=org.superbiz:genericra \
> +myGenericAdapter.AdapterProperty1 = PropertyValue1 \
> +myGenericAdapter.AdapterProperty2 = PropertyValue2 +----
> +
> +This is basically the same as all configuration in TomEE/OpenEJB, but
> +with the addition that you must specify the `provider` attribute so the
> +server knows where to look for the `service-jar.xml` file that defines
> +the resource and all its defaults.
> +
> +In this example:
> +
> +* the file is `META-INF/org.superbiz/service-jar.xml`
> +* so the `provider` attribute is `org.superbiz`
> +
> +You can use whatever prefix you like for the `provider` id, though for
> +obvious reasons we'd advise not using `org.apache.openejb` or
> +`org.apache.tomee` in the prefix.
> diff --git a/docs/client-server-transports.adoc \
> b/docs/client-server-transports.adoc new file mode 100644
> index 0000000..48c5f02
> --- /dev/null
> +++ b/docs/client-server-transports.adoc
> @@ -0,0 +1,39 @@
> += Client-Server Transports
> +:index-group: Unrevised
> +:jbake-date: 2018-12-05
> +:jbake-type: page
> +:jbake-status: published
> +
> += Client/Server transports
> +
> +jar
> +
> +transport description
> +
> +openejb-ejbd-3.0.jar
> +
> +provides the 'ejbd' protocol. A binary protocol traveling over a socket
> +
> +openejb-http-3.0.jar
> +
> +supports the ejbd protocol over http
> +
> +openejb-derbynet-3.0.jar
> +
> +allows for derby to accessed via it's network driver
> +
> +openejb-hsql-3.0.jar
> +
> +allows for hsqldb to be accessed via it's network driver
> +
> +openejb-cxf-3.0.jar
> +
> +turns on webservice ability, soap/http, via cxf
> +
> +openejb-activemq-3.0.jar
> +
> +supports remote jms clients via activemq
> +
> +openejb-telnet-3.0.jar
> +
> +allows for connecting to the server via telnet for monitoring
> diff --git a/docs/clients.adoc b/docs/clients.adoc
> new file mode 100644
> index 0000000..f165dda
> --- /dev/null
> +++ b/docs/clients.adoc
> @@ -0,0 +1,101 @@
> += Clients
> +:index-group: Configuration
> +:jbake-date: 2018-12-05
> +:jbake-type: page
> +:jbake-status: published
> +
> +
> +== Local Client (embedded container)
> +
> +[source,java]
> +----
> +Properties p = new Properties();
> +p.put("java.naming.factory.initial", \
> "org.apache.openejb.client.LocalInitialContextFactory"); +
> +InitialContext ctx = new InitialContext(p);
> +
> +MyBean myBean = (MyBean) ctx.lookup("MyBeanRemote");
> +----
> +
> +== Local Client (non-default realm name)
> +
> +== Login configuration file (conf/login.config)
> +
> +[source,java]
> +----
> +PropertiesLogin {
> + org.apache.openejb.core.security.jaas.PropertiesLoginModule required
> + Debug=true
> + UsersFile="users.properties"
> + GroupsFile="groups.properties";
> +};
> +MyApp {
> + org.apache.openejb.core.security.jaas.SQLLoginModule required
> + dataSourceName="MyDataSource"
> + userSelect="SELECT username, password FROM users WHERE username=?"
> + groupSelect="SELECT username, grp FROM users WHERE username=?";
> +};
> +----
> +
> +== Code
> +
> +[source,java]
> +----
> +Properties p = new Properties();
> +p.put("java.naming.factory.initial", \
> "org.apache.openejb.client.LocalInitialContextFactory"); \
> +p.put("openejb.authentication.realmName", "MyApp"); +
> +InitialContext ctx = new InitialContext(p);
> +
> +MyBean myBean = (MyBean) ctx.lookup("MyBeanRemote");
> +----
> +
> +== Remote Client (openejb standalone)
> +
> +[source,java]
> +----
> +Properties p = new Properties();
> +p.put("java.naming.factory.initial", \
> "org.apache.openejb.client.RemoteInitialContextFactory"); \
> +p.put("java.naming.provider.url", "ejbd://localhost:4201"); +// user and pass \
> optional +p.put("java.naming.security.principal", "myuser");
> +p.put("java.naming.security.credentials", "mypass");
> +
> +InitialContext ctx = new InitialContext(p);
> +
> +MyBean myBean = (MyBean) ctx.lookup("MyBeanRemote");
> +----
> +
> +== Remote Client with HTTP (openejb standalone)
> +
> +[source,java]
> +----
> +Properties p = new Properties();
> +p.put("java.naming.factory.initial", \
> "org.apache.openejb.client.RemoteInitialContextFactory"); \
> +p.put("java.naming.provider.url", "http://localhost:4204/ejb"); +// user and pass \
> optional +p.put("java.naming.security.principal", "myuser");
> +p.put("java.naming.security.credentials", "mypass");
> +
> +InitialContext ctx = new InitialContext(p);
> +
> +MyBean myBean = (MyBean) ctx.lookup("MyBeanRemote");
> +----
> +
> +== Remote Client with HTTP (in TomEE)
> +
> +[source,java]
> +----
> +Properties p = new Properties();
> +p.put("java.naming.factory.initial", \
> "org.apache.openejb.client.RemoteInitialContextFactory"); \
> +p.put("java.naming.provider.url", "http://127.0.0.1:8080/tomee/ejb"); +// user and \
> pass optional +p.put("java.naming.security.principal", "myuser");
> +p.put("java.naming.security.credentials", "mypass");
> +
> +InitialContext ctx = new InitialContext(p);
> +
> +MyBean myBean = (MyBean) ctx.lookup("MyBeanRemote");
> +----
> +
> +== Remote Client using @EJB Injection see here: ejb-refs
> diff --git a/docs/collapsed-ear.adoc b/docs/collapsed-ear.adoc
> new file mode 100644
> index 0000000..ea94f75
> --- /dev/null
> +++ b/docs/collapsed-ear.adoc
> @@ -0,0 +1,49 @@
> += Collapsed EAR
> +:index-group: Unrevised
> +:jbake-date: 2018-12-05
> +:jbake-type: page
> +:jbake-status: published
> +
> += One archive
> +
> +The basic idea of this approach is that your Servlets and EJBs are
> +together in your WAR file as one app.
> +
> +* No classloader boundries between Servlets and EJBs
> +* EJBs and Servlets can share all third-party libraries (like Spring!) -
> +no EAR required.
> +* Can put the web.xml and ejb-jar.xml in the same archive (the WAR
> +file).
> +* EJBs can see Servlet classes and vice versa.
> +
> += Not quite J2EE (it is truly Java EE6)
> +
> +This is very different than J2EE or Java EE 5 as there aren't several
> +levels of separation and classloader hierarchy. This is going to take
> +some getting used to and it should be understood that this style of
> +packaging isn't J2EE compliant. Who would care tough as it is a feature
> +of Java EE 6 we would've been waiting for so long.
> +
> +J2EE classloading rules:
> +
> +* You cannot ever have EJBs and servlets in the same classloader.
> +* Three classloader minimum; a classloader for the ear, one for each
> +ejb-jar, and one for each WAR file.
> +* Servlets can see EJBs, but EJBs cannot see servlets.
> +
> +To pull that off, J2EE has to kill you on packaging: * You cannot have
> +EJB classes and Servlet classes in the same archive. * You need at least
> +three archives to combine servlets and ejbs; 1 EAR containing 1 EJB jar
> +and 1 servlet WAR. * Shared libraries must go in the EAR and be included
> +in a specially formatted 'Class-Path' entry in the EAR's MANIFEST file.
> +
> +Critically speaking, forcing more than one classloader on an application
> +is where J2EE "jumps the shark" for a large majority of people's needs.
> +
> += Example with Tomcat
> +
> +If you want to try to work with Servlets/JSP and OpenEJB using Tomcat,
> +see the openejbx30:tomcat.html[setup page] and the
> +"/webapps/ejb-examples" section of the
> +link:downloads.html[openejb-examples.zip] available on the
> +http://tomee.apache.org/downloads.html[download page].
> diff --git a/docs/common-datasource-configurations.adoc \
> b/docs/common-datasource-configurations.adoc new file mode 100644
> index 0000000..4bec8e6
> --- /dev/null
> +++ b/docs/common-datasource-configurations.adoc
> @@ -0,0 +1,123 @@
> += Common DataSource Configurations
> +:index-group: Datasource
> +:jbake-date: 2018-12-05
> +:jbake-type: page
> +:jbake-status: published
> +
> +
> +See the link:datasource-config.html[DataSource Configuration] for
> +details on all configuration options for DataSources.
> +
> +== HSQLDB
> +
> +The drivers are included with OpenEJB 3.0 and HSQLDB is the default
> +database.
> +
> +[source,xml]
> +----
> +<Resource id="HSQLDB Database" type="DataSource">
> + JdbcDriver org.hsqldb.jdbcDriver
> + JdbcUrl jdbc:hsqldb:file:hsqldb
> + UserName sa
> + Password
> +</Resource>
> +----
> +
> +== Derby (Embedded)
> +
> +[source,xml]
> +----
> +<Resource id="Derby Database" type="DataSource">
> + #Embedded Derby example
> +
> + JdbcDriver org.apache.derby.jdbc.EmbeddedDriver
> + JdbcUrl jdbc:derby:derbyDB;create=true
> + UserName admin
> + Password pass
> +</Resource>
> +----
> +
> +== MySQL
> +
> +[source,xml]
> +----
> +<Resource id="MySQL Database" type="DataSource">
> + # MySQL example
> + #
> + # This connector will not work until you download the driver at:
> + # http://www.mysql.com/downloads/api-jdbc-stable.html
> +
> + JdbcDriver com.mysql.jdbc.Driver
> + JdbcUrl jdbc:mysql://localhost/test
> + UserName test
> +</Resource>
> +----
> +
> +== Oracle
> +
> +[source,xml]
> +----
> +<Resource id="Oracle Database" type="DataSource">
> + # Oracle example
> + #
> + # This connector will not work until you download the driver at:
> + # http://otn.oracle.com/software/tech/java/sqlj_jdbc/content.html
> + JdbcDriver oracle.jdbc.OracleDriver
> + JdbcUrl jdbc:oracle:thin:@localhost:1521:orcl
> + UserName scott
> + Password tiger
> +</Resource>
> +----
> +
> +== OracleXA
> +
> +[source,xml]
> +----
> +<Resource id="OracleXA Database" type="DataSource">
> + # OracleXA example
> + #
> + # This connector will not work until you download the driver at:
> + # http://otn.oracle.com/software/tech/java/sqlj_jdbc/content.html
> + JdbcDriver oracle.jdbc.xa.client.OracleXADataSource
> + JdbcUrl jdbc:oracle:thin:@localhost:1521:orcl
> + UserName scott
> + Password tiger
> +</Resource>
> +----
> +
> +== PosgreSQL
> +
> +[source,xml]
> +----
> +<Resource id="PostgreSQL Database" type="DataSource">
> + # PostgreSQL example
> + #
> + # This connector will not work until you download the driver at:
> + # http://jdbc.postgresql.org/download.html
> + JdbcDriver org.postgresql.Driver
> + JdbcUrl jdbc:postgresql://localhost/test
> + UserName postgres
> + Password pass
> +</Resource>
> +----
> +
> +== InstantDB
> +
> +[source,xml]
> +----
> +<Resource id="InstantDB Database" type="DataSource">
> + # InstantDB example
> + #
> + JdbcDriver org.enhydra.instantdb.jdbc.idbDriver
> + JdbcUrl jdbc:idb:conf/instantdb.properties
> + UserName Admin
> + Password pass
> +</Resource>
> +----
> +
> +Internally, from TomEE 1.5.0, JDBC pools are managed via Tomcat-pool.
> +You can still switch back to Apache Commons DBCP by adding the following
> +property: DataSourceCreator dbcp. To get the full list of available
> +configuration properties, have a look to
> +http://commons.apache.org/dbcp/configuration.html[Apache Commons DBCP
> +configuration].
> diff --git a/docs/common-errors.adoc b/docs/common-errors.adoc
> new file mode 100644
> index 0000000..86d2c6c
> --- /dev/null
> +++ b/docs/common-errors.adoc
> @@ -0,0 +1,31 @@
> += Common Errors
> +:index-group: Unrevised
> +:jbake-date: 2018-12-05
> +:jbake-type: page
> +:jbake-status: published
> +
> +
> +<a name="CommonErrors-Cannotfindcontainer"FOO"forbean"BAR""> # Cannot
> +find container "FOO" for bean "BAR"
> +
> +When a bean gets deployed in OpenEJB, it gets associated with a
> +particular container. Subsequently, that container may not be configured
> +in that instance of the server. When the server loads the Jar with the
> +deployed beans, it places beans in the containers that the beans were
> +configured with. Here, the bean BAR wants to go into the container FOO,
> +which is not currently configured.
> +
> +This message is displayed when the server is starting up. <a
> +name="CommonErrors-Cannotfindbean"FOO"referencedbybean"BAR"."> # Cannot
> +find bean "FOO" referenced by bean "BAR".
> +
> +When a bean gets deployed in OpenEJB, it may contain references to other
> +beans. Subsequently, those beans may not be configured in that instance
> +of the server. When the server loads the Jar with the deployed beans, it
> +stores those references to those beans. Here, the bean BAR references
> +FOO, which is not currently configured in the JNDI namespace.
> +
> +This message is displayed when the server is starting up.
> +
> +This message is usally the result of a deployment descriptor that has
> +been created by hand.
> diff --git a/docs/common-persistenceprovider-properties.adoc \
> b/docs/common-persistenceprovider-properties.adoc new file mode 100644
> index 0000000..4236852
> --- /dev/null
> +++ b/docs/common-persistenceprovider-properties.adoc
> @@ -0,0 +1,50 @@
> += Common PersistenceProvider properties
> +:index-group: Unrevised
> +:jbake-date: 2018-12-05
> +:jbake-type: page
> +:jbake-status: published
> +
> +While not a definitive list, it
> +does help to show a side-by-side view of common properties used by the
> +various persistence providers out there.
> +
> += TopLink
> +
> +[source,xml]
> +----
> +<properties>
> +
> + <!--http://www.oracle.com/technology/products/ias/toplink/JPA/essentials/toplink-jpa-extensions.html-->
> + <property name="toplink.ddl-generation" value="drop-and-create-tables"/>
> + <property name="toplink.logging.level" value="FINEST"/>
> + <property name="toplink.ddl-generation.output-mode" value="both"/>
> + <property name="toplink.target-server" \
> value="pl.zsk.samples.ejbservice.OpenEJBServerPlatform"/> +</properties>
> +----
> +
> += OpenJPA
> +
> +[source,xml]
> +----
> +<properties>
> + <!--http://openjpa.apache.org/faq.html-->
> + <!-- does not create foreign keys, creates schema and deletes content of a \
> database + (deleteTableContents - foreign keys are created twice???), use \
> dropDB instead --> + <property name="openjpa.jdbc.SynchronizeMappings" \
> value="buildSchema(foreignKeys=true,schemaAction='dropDB,add')"/> + <!--Resolves \
> the problem with foreign key integrity - joined entities are persisted sometimes in \
> wrong order??? (verify it)--> + <property name="openjpa.jdbc.SchemaFactory" \
> value="native(foreignKeys=true)" /> + <!--Create foreign keys-->
> + <property name="openjpa.jdbc.MappingDefaults" \
> value="ForeignKeyDeleteAction=restrict, JoinForeignKeyDeleteAction=restrict"/> + \
> <property name="openjpa.Log" value="DefaultLevel=TRACE,SQL=TRACE" /> +</properties>
> +----
> +
> += Hibernate
> +
> +[source,xml]
> +----
> +<properties>
> + <property name="hibernate.hbm2ddl.auto" value="create-drop"/>
> + <property name="hibernate.transaction.manager_lookup_class" \
> value="org.apache.openejb.hibernate.TransactionManagerLookup"/> +</properties>
> +----
> diff --git a/docs/concepts.adoc b/docs/concepts.adoc
> new file mode 100644
> index 0000000..6cd1bf9
> --- /dev/null
> +++ b/docs/concepts.adoc
> @@ -0,0 +1,83 @@
> += Concepts
> +:index-group: Unrevised
> +:jbake-date: 2018-12-05
> +:jbake-type: page
> +:jbake-status: published
> +
> +OpenEJB was founded on the idea that it would be embedded into
> +third-party environments whom would likely already have three things:
> +
> +* their one "server" platform with existing clients and protocols
> +* their own way to configure their platform
> +* existing services like TransactionManager, Security, and Connector
> +
> +Thus the focus of OpenEJB was to create an EJB implementation that would
> +be easily embeddible, configurable, and customizable.
> +
> +Part of achieving that is a drive to be as simple as possible as to not
> +over-define and therefore restrict the ability to be embeddible,
> +configurable and customizable. Smaller third-party environments could
> +easily 'downscale' OpenEJB in their integrations by replacing standard
> +components with lighter implementations or removing them all together
> +and larger environments could 'upscale' OpenEJB by replacing and adding
> +heavier implementations of those standard components likely tailored to
> +their systems and infrastructure.
> +
> +Container and Server are mentioned in the EJB spec as being separate
> +things but are never defined formally. In our world Containers, which
> +implement the basic component contract and lifecycle of a bean are not
> +coupled to any particular Server, which has the job of providing a
> +naming service and providing a way for it's clients to reference and
> +invoke components (beans) hosted in Containers. Because Containers have
> +no dependence at all only Server, you can run OpenEJB without any Server
> +at all in an embedded environment for example without any work or any
> +extra overhead. Similarly you can add as many new Server components as
> +you want without ever having to modify any Containers.
> +
> +There is a very strong pluggability focus in OpenEJB as it was always
> +intended to be embedded and customized in other environments. As a
> +result all Containers are pluggable, isolated from each other, and no
> +one Container is bound to another Container and therefore removing or
> +adding a Container has no repercussions on the other Containers in the
> +system. TransactionManager, SecurityService and Connector also pluggable
> +and are services exposed to Containers. A Container may not be dependent
> +on specific implementations of those services. Service Providers define
> +what services they are offering (Container, Connector, Security,
> +Transaction, etc.) in a file they place in their jar called
> +service-jar.xml.
> +
> +The service-jar.xml should be placed not in the META-INF but somewhere
> +in your package hierarchy (ours is in
> +/org/apache/openejb/service-jar.xml) which allows the services in your
> +service-jar.xml to be referenced by name (such as
> +DefaultStatefulContainer) or more specifically by package and id (such
> +as org.apache.openejb#DefaultStatefulContainer).
> +
> +The same implementation of a service can be declared several times in a
> +service-jar.xml with different ids. This allows for you to setup several
> +several different profiles or pre-configured versions of the services
> +you provide each with a different name and different set of default
> +values for its properties.
> +
> +In your openejb.conf file when you declare Containers and Connectors, we
> +are actually hooking you up with Service Providers automatically. You
> +get what is in the org/apache/openejb/service-jar.xml by default, but
> +you are able to point specifically to a specific Service Provider by the
> +'provider' attribute on the Container, Connector, TransactionManager,
> +SecurityService, etc. elements of the openejb.conf file. When you
> +declare a service (Container, Connector, etc.) in your openejb.conf file
> +the properties you supply override the properties supplied by the
> +Service Provider, thus you only need to specify the properties you'd
> +like to change and can have your openejb.conf file as large or as small
> +as you would like it. The act of doing this can be thought of as
> +essentially instantiating the Service Provider and configuring that
> +instance for inclusion in the runtime system.
> +
> +For example Container(id=NoTimeoutStatefulContainer,
> +provider=DefaultStatefulContainer) could be declared with it's Timeout
> +property set to 0 for never, and a
> +Container(id=ShortTimeoutStatefulContainer,
> +provider=DefaultStatefulContainer) could be declared with it's Timeout
> +property set to 15 minutes. Both would be instances of the
> +DefaultStatefulContainer Service Provider which is a service of type
> +Container.
> diff --git a/docs/configuration.adoc b/docs/configuration.adoc
> new file mode 100644
> index 0000000..519a668
> --- /dev/null
> +++ b/docs/configuration.adoc
> @@ -0,0 +1,151 @@
> += Configuration
> +:index-group: OpenEJB Standalone Server
> +:jbake-date: 2018-12-05
> +:jbake-type: page
> +:jbake-status: published
> +
> += Short Overview
> +
> +== Configuration Properties
> +
> +* _openejb.home_ - OpenEJB home (installation) directory path. All
> +relative paths are resolved against the property unless openejb.base is
> +set. Unless set, the value is assigned to the _user.dir_ Java property.
> +* _openejb.base_ - OpenEJB base directory path. If set, the directory
> +pointed by the property is searched for resources before openejb.home.
> +* _openejb.configuration_ - OpenEJB configuration file path.
> +* _openejb.loader_ - OpenEJB loader that's responsible for loading EJBs.
> +There are 3 different loader types: +
> +** _tomcat-webapp_ - set it when inside of Tomcat scoped at just the
> +webapp, aka. link:collapsed-ear.html[Collapsed EAR] ** _tomcat_ - set it
> +when inside of Tomcat scoped for all webapps to share ** _system_ (also:
> +bootstrap) ** _embedded_ (also: noload)
> +* _openejb.configurator_ (default:
> +_org.openejb.alt.config.ConfigurationFactory_ ) - a class that builds
> +org.openejb.alt.assembler.classic.OpenEjbConfiguration object;
> +implements the
> +org.openejb.alt.assembler.classic.OpenEjbConfigurationFactory interface
> +* _openejb.descriptors.output_ - possible values: true|false - When set
> +OpenEJB saves deployment descriptors - ejb-jar.xml and openejb-jar.xml
> +
> +== Configuration File
> +
> +Show a config file with the elements hyperlinked.
> +
> +[source,xml]
> +----
> +<?xml version="1.0"?>
> +<openejb>
> + <Container id="Default CMP Container" ctype="CMP_ENTITY">
> + Global_TX_Database c:/my/app/conf/postgresql.cmp_global_database.xml
> + Local_TX_Database c:/my/app/conf/postgresql.cmp_local_database.xml
> + </Container>
> + <Connector id="Default JDBC Database">
> + JdbcDriver org.postgresql.Driver
> + JdbcUrl jdbc:postgresql://localhost/mydb
> + UserName username
> + Password password
> + </Connector>
> + <SecurityService id="Default Security Service"/>
> + <TransactionService id="Default Transaction Manager"/>
> + <Deployments jar="c:/my/app/employee.jar"/>
> + <Deployments dir="beans/" />
> +</openejb>
> +----
> +
> +== Basic Layout
> +
> +Basically, openejb.base is the source for 100% of all configuration
> +information and third party config files (log4j, castor, instantdb,
> +whatever). This includes finding where the, possibly many, entries in
> +the openejb.conf point. The openejb.home is where the code loading
> +OpenEJB will look for all the OpenEJB libraries. Usually openejb.base is
> +not explicitly set and defaults to the value of openejb.home, so many
> +people are used to only dealing with openejb.home.
> +
> +The point of having and openejb.base and openejb.home was basically to
> +allow several independently configured instances of OpenEJB running on a
> +system (perhaps embedded in Swing apps, in Tomcat, running as a
> +standalone Server, or even in Groovy as Mr. Strachan did!) but without
> +the need to copy all the OpenEJB system libraries everywhere.
> +
> +_openejb.home_ * can be set explicitly via a system property. * if not
> +set it default's to user.dir, which is the current working directory.
> +
> +_openejb.base_ * can be set explicitly via a system property. * If not
> +set it default's to openejb.home.
> +
> +_openejb.configuration_ * can be set to explicitly point to the file
> +containing your configuration. * If set to a relative path, we first
> +look in user.dir/your-conf-file, then in openejb.base/your-conf-file *
> +If not set we check in openejb.base/conf/openejb.conf * If no conf file
> +is found, we create one in openejb.base/conf/openejb.conf
> +
> +_relative paths in openejb.conf_ * Deployment entries are resolved
> +relative to openejb.base. * Containers use openejb.base to resolve their
> +own config files. For example, Castor JDO to loads the database.xml and
> +all other files from the openejb.base directory. * Resource adapters
> +that are embedded usually have config files of their own and are also
> +loaded from the openeb.base.
> +
> +_log files_ * The log4.configuration file is resolved relative to
> +openejb.base. * The properties in the config file that point to files
> +are also resolved relative to openejb.base.
> +
> +_OpenEJB libraries_ * The jars in the lib and dist directories under
> +openejb.home are added to the classpath.
> +
> +=== Summary
> +
> +A summary of the above in a different notation:
> +
> +[source,properties]
> +----
> +openejb.home = user.dir (can be set explicitly)
> +openejb.base = openejb.home (can be set explicitly)
> +openejb.conf = openejb.base/conf/openejb.conf (can be set explicitly)
> +logging.conf = openejb.base/conf/logging.conf (can be set explicitly)
> +deployments = paths listed in openejb.conf (relative paths resolved from \
> openejb.base) +Classpath includes openejb.home/lib and openejb.home/dist
> +----
> +
> +=== Example layout
> +
> +In this one the openejb.home and openejb.base are set, everything else
> +is defaulted. The openejb.conf file as been updated to point to the ejb
> +jars by name (abc-ejbs.jar and xyz-ejbs.jar).
> +
> +An example layout:
> +
> +[source,java]
> +----
> +/usr/local/openejb (openejb.home)
> +/usr/local/openejb/lib (in classpath)
> +/usr/local/openejb/dist (in classpath)
> +/home/jsmith/foo_app (openejb.base)
> +/home/jsmith/foo_app/conf/openejb.conf
> +/home/jsmith/foo_app/conf/logging.conf
> +/home/jsmith/foo_app/abc-ejbs.jar (Deployment entry in openejb.conf)
> +/home/jsmith/foo_app/xyz-ejbs.jar (Deployment entry in openejb.conf)
> +/home/jsmith/foo_app/logs/
> +----
> +
> +=== Another Example layout
> +
> +In this example openejb.home and openejb.base are setup as well as the
> +explicit paths for the openejb and log4j configuration files.
> +
> +An example layout:
> +
> +[source,java]
> +----
> +/usr/local/openejb (openejb.home)
> +/usr/local/openejb/lib (in classpath)
> +/usr/local/openejb/dist (in classpath)
> +/home/jsmith/foo_app (openejb.base)
> +/home/jsmith/foo_app/openejb.xml (openejb.configuration)
> +/home/jsmith/foo_app/abc-ejbs.jar (Deployment entry in openejb.xml)
> +/home/jsmith/foo_app/xyz-ejbs.jar (Deployment entry in openejb.xml)
> +/home/jsmith/foo_app/log4j.conf (log4j.configuration)
> +/home/jsmith/foo_app/mylogs/ (logging dir as defined in log4j.conf)
> +----
> diff --git a/docs/configuring-containers-in-tests.adoc \
> b/docs/configuring-containers-in-tests.adoc new file mode 100644
> index 0000000..824c8ed
> --- /dev/null
> +++ b/docs/configuring-containers-in-tests.adoc
> @@ -0,0 +1,30 @@
> += Configuring Containers in Tests
> +:index-group: Testing Techniques
> +:jbake-date: 2018-12-05
> +:jbake-type: page
> +:jbake-status: published
> +
> +Like Resources, Containers
> +can also be declared via InitialContext properties as well. The most
> +useful is to declare a Stateful SessionBean container so that it's
> +guaranteed to passivate and activate on each call to the bean, allowing
> +you to test your callbacks behave as you need them to.
> +
> +[source,java]
> +----
> +Properties p = new Properties();
> +p.put(Context.INITIAL_CONTEXT_FACTORY, \
> "org.apache.openejb.core.LocalInitialContextFactory"); +
> +p.put("myStatefulContainer", "new://Container?type=STATEFUL");
> +p.put("myStatefulContainer.PoolSize", "0");
> +p.put("myStatefulContainer.BulkPassivate", "1");
> +
> +Context context = new InitialContext(p);
> +----
> +
> +Note, this only works when using the LocalInitialContextFactory to embed
> +OpenEJB into the vm. Once embedded, further configuration properties are
> +ignored.
> +
> +See link:containers-and-resources.html[Containers and Resources] for a
> +full list of supported Resource types and their properties.
> diff --git a/docs/configuring-datasources-in-tests.adoc \
> b/docs/configuring-datasources-in-tests.adoc new file mode 100644
> index 0000000..0f95166
> --- /dev/null
> +++ b/docs/configuring-datasources-in-tests.adoc
> @@ -0,0 +1,68 @@
> += Configuring DataSources in Tests
> +:index-group: Testing Techniques
> +:jbake-date: 2018-12-05
> +:jbake-type: page
> +:jbake-status: published
> +
> += InitialContext
> +properties
> +
> +You can configure data sources from within your test case (avoiding the
> +need for an `openejb.xml` entirely) like so:
> +
> +[source,java]
> +----
> +Properties p = new Properties();
> +p.put(Context.INITIAL_CONTEXT_FACTORY, \
> "org.apache.openejb.core.LocalInitialContextFactory"); +
> +p.put("myDataSource", "new://Resource?type=DataSource");
> +p.put("myDataSource.JdbcDriver", "org.apache.derby.jdbc.EmbeddedDriver");
> +p.put("myDataSource.JdbcUrl", "jdbc:derby:derbyDB;create=true");
> +p.put("myDataSource.JtaManaged", "true");
> +
> +Context context = new InitialContext(p);
> +----
> +
> +Under certain circumstances it may be necessary to load two versions of
> +the same driver. This is possible by definition of a classpath for the
> +resource which points to the specific driver files required for the
> +DataSource:
> +
> +[source,java]
> +----
> +p.put("myDataSourceOne", \
> "new://Resource?type=DataSource&classpath=/path/to/driverVersionOne.jar"); \
> +p.put("myDataSourceOne.JdbcDriver", "org.apache.derby.jdbc.EmbeddedDriver"); \
> +p.put("myDataSource.JdbcUrl", "jdbc:derby:myDatabaseOne;create=true"); +
> +p.put("myDataSourceTwo", \
> "new://Resource?type=DataSource&classpath=/path/to/driverVersionTwo.jar"); \
> +p.put("myDataSourceTwo.JdbcDriver", "org.apache.derby.jdbc.EmbeddedDriver"); \
> +p.put("myDataSource.JdbcUrl", "jdbc:derby:myDatabaseTwo;create=true"); \
> +[source,java] +----
> +
> +This will allow an application to communicate through legacy drivers to
> +the same JDBC provider.
> +
> +See link:embedded-configuration.html[Embedded Configuration] for further
> +details on properties and overrides.
> +
> +See link:containers-and-resources.html[Containers and Resources] for a
> +full list of supported Resource types and their properties.
> +
> +== Note on <jta-data-source> and <non-jta-data-source>
> +
> +When configuring DataSources to be used by persistence.xml files, the
> +DataSource supplied for `<jta-data-source>` is typically identical to
> +the `<non-jta-data-source>`, but with the `JtaManaged` property set
> +differently. Keeping with our philosophy to free you up from redundant
> +configuration, we will happily auto-create a missing jta-data-source or
> +non-jta-data-source based upon the supplied DataSource.
> +
> +In the example above, a new DataSource would be generated as an exact
> +copy but with the name "myDataSourceUnmanaged" and its `JtaManaged` flag
> +set to `false`. If the supplied DataSource was not `JtaManaged`, then
> +the generated DataSource would be called "myDataSourceJta" and have its
> +`JtaManaged` flag set to `true`.
> +
> +When relying on this functionality it is not necessary to specify the
> +name of the generated DataSource in the `persistence.xml` file.
> diff --git a/docs/configuring-datasources.adoc b/docs/configuring-datasources.adoc
> new file mode 100644
> index 0000000..e3bbaed
> --- /dev/null
> +++ b/docs/configuring-datasources.adoc
> @@ -0,0 +1,204 @@
> += Configuring DataSources in tomee.xml
> +:index-group: Configuration
> +:jbake-date: 2018-12-05
> +:jbake-type: page
> +:jbake-status: published
> +
> +
> +The __ element is used to configure a _javax.sql.DataSource_. It is also
> +used to configure other resources like Timers, Topics, Queues. We will
> +see some examples of using to configure a DataSource.
> +
> +The element is designed after `@Resource` annotation and has similar
> +attributes.
> +
> +For example, this annotation in your bean:
> +
> +[source,java]
> +----
> +@Resource(name = "myDerbyDatasource", type = javax.sql.DataSource.class)
> +----
> +
> +Would map to a Resource declared in your openejb.xml as follows:
> +
> +[source,xml]
> +----
> +<Resource id="myDerbyDatasource" type="javax.sql.DataSource">
> + . . . .
> +<Resource>
> +----
> +
> +Note that in the xml element, the _type_ value of _javax.sql.DataSource_
> +can abbreviated to just _DataSource_ as follows:
> +
> +[source,xml]
> +----
> +<Resource id="myDerbyDatasource" type="DataSource">
> + . . . .
> +<Resource>
> +----
> +
> +It is also possible to specify the path to the driver jar file using a
> +classpath attribute like so:
> +
> +[source,xml]
> +----
> +<Resource id="myDerbyDatasource" type="DataSource" \
> classpath="/path/to/driver.jar"> + . . . .
> +<Resource>
> +----
> +
> +...Or in a http://maven.apache.org/[Maven] environment like so:
> +
> +[source,xml]
> +----
> +<Resource id="myDerbyDatasource" type="DataSource" \
> classpath="mvn:org.apache.derby:derby:10.10.1.1"> + . . . .
> +<Resource>
> +----
> +
> +See link:containers-and-resources.html[Containers and Resources] for a
> +complete list of supported DataSource properties.
> +
> +See link:datasource-password-encryption.html[DataSource Password
> +Encryption] for information on specifying non-plain-text database
> +passwords in your openejb.xml file.
> +
> +See link:common-datasource-configurations.html[Common DataSource
> +Configurations] for a list of the commonly used databases and their
> +driver configurations.
> +
> +See link:datasource-configuration-by-creator.html[DataSource
> +Configuration by Creator] for a list of the different properties
> +supported for each data source creator.
> +
> +You may also need data partitioning per customer or depending on any
> +other business criteria. That's also an available feature. See
> +link:dynamic-datasource.html[Dynamic Datasource] for more details.
> +
> +== JNDI names for configured DataSources
> +
> +=== Example 1
> +
> +[source,xml]
> +----
> +<Resource id="Default JDBC Database" type="DataSource">
> + . . . . .
> +</Resource>
> +----
> +
> +The global jndi name would be _java:openejb/Resource/Default JDBC
> +Database_
> +
> +=== Example 2
> +
> +[source,xml]
> +----
> +<Resource id="Derby Database" type="DataSource">
> + . . . . .
> +</Resource>
> +----
> +
> +The global jndi name would be _java:openejb/Resource/Derby Database_
> +
> +== Obtaining a DataSource
> +
> +DataSource references in your ejb should get automatically mapped to the
> +Resource you declare. The shortest and easiest rule is that _if your
> +reference name matches a Resource in your openejb.xml, that's the one
> +you get_. Essentially, the rules for mapping are as follows.
> +
> +[arabic]
> +. Name Attribute Match - `@Resource` with a name attribute matching the
> +resource name gets that resource injected
> +. Injected Name Match - variable name matching the resource name gets
> +that resource injected
> +. No Match - nothing matches a resource name, so the first resource
> +available gets injected
> +
> +There are various ways one could obtain a DataSource now. Lets take an
> +example of Derby.
> +
> +With a Resource declaration in your openejb.xml like this:
> +
> +[source,xml]
> +----
> +<Resource id="myDerbyDatabase" type="DataSource">
> + . . . . .
> +</Resource>
> +----
> +
> +There are several possible ways to refer to it, as follows.
> +
> +_BY matching variable name to resource name_
> +
> +[source,java]
> +----
> +@Stateless
> +public class FooBean {
> + @Resource DataSource myDerbyDatabase;
> +}
> +----
> +
> +_OR BY matching name_
> +
> +[source,java]
> +----
> +@Stateless
> +public class FooBean {
> + @Resource(name="myDerbyDatabase")
> + DataSource dataSource;
> +}
> +----
> +
> +_OR BY JNDI lookup_
> +
> +[source,java]
> +----
> +@Resource(name="myDerbyDatabase", type=javax.sql.DataSource.class)
> +@Stateless
> +public class FooBean {
> +
> + public void setSessionContext(SessionContext sessionContext) {
> + DataSource dataSource = (DataSource)
> + sessionContext.lookup("myDerbyDatabase");
> + }
> +
> + public void someOtherMethod() throws Exception {
> + InitialContext initialContext = new InitialContext();
> + DataSource dataSource = (DataSource)
> + initialContext.lookup("java:comp/env/myDerbyDatabase");
> + }
> +}
> +----
> +
> +_OR_
> +
> +[source,xml]
> +----
> +<resource-ref>
> + <res-ref-name>myDerbyDatabase</res-ref-name>
> + <res-type>javax.sql.DataSource</res-type>
> +</resource-ref>
> +----
> +
> +_OR_
> +
> +[source,xml]
> +----
> +<resource-ref>
> + <res-ref-name>jdbc/myDerbyDatabase</res-ref-name>
> + <res-type>javax.sql.DataSource</res-type>
> +</resource-ref>
> +----
> +
> +_OR_
> +
> +[source,xml]
> +----
> +<resource-ref>
> + <res-ref-name>someOtherName</res-ref-name>
> + <res-type>javax.sql.DataSource</res-type>
> + <mapped-name>myDerbyDatabase</mapped-name>
> +</resource-ref>
> +----
> diff --git a/docs/configuring-durations.adoc b/docs/configuring-durations.adoc
> new file mode 100644
> index 0000000..8394e60
> --- /dev/null
> +++ b/docs/configuring-durations.adoc
> @@ -0,0 +1,70 @@
> += Configuring Durations
> +:index-group: Unrevised
> +:jbake-date: 2018-12-05
> +:jbake-type: page
> +:jbake-status: published
> +
> +The time based configuration properties of containers
> +and beans support plain english, such as:
> +
> +* "1 hour"
> +* "27 minutes"
> +* "10 seconds"
> +
> +For convenience it is possible to specify a _compound_ form, such as:
> +
> +* "3 days and 2 hours"
> +* "1 hour, 45 minutes"
> +* "15 minutes, 23 seconds, and 10 milliseconds"
> +
> +Spaces are also optional between the number and the time unit, which can
> +be nice when using the abbreviated forms:
> +
> +* "1hr"
> +* "27m"
> +* "10s"
> +* "3d and 2hr"
> +* "1hr, 45min"
> +* "15m, 23s, and 10ms"
> +
> +Abbreviations are accepted as follows:
> +
> +[source,java]
> +----
> + if (u.equalsIgnoreCase("NANOSECONDS")) return TimeUnit.NANOSECONDS;
> + if (u.equalsIgnoreCase("NANOSECOND")) return TimeUnit.NANOSECONDS;
> + if (u.equalsIgnoreCase("NANOS")) return TimeUnit.NANOSECONDS;
> + if (u.equalsIgnoreCase("NANO")) return TimeUnit.NANOSECONDS;
> + if (u.equalsIgnoreCase("NS")) return TimeUnit.NANOSECONDS;
> +
> + if (u.equalsIgnoreCase("MICROSECONDS")) return TimeUnit.MICROSECONDS;
> + if (u.equalsIgnoreCase("MICROSECOND")) return TimeUnit.MICROSECONDS;
> + if (u.equalsIgnoreCase("MICROS")) return TimeUnit.MICROSECONDS;
> + if (u.equalsIgnoreCase("MICRO")) return TimeUnit.MICROSECONDS;
> +
> + if (u.equalsIgnoreCase("MILLISECONDS")) return TimeUnit.MILLISECONDS;
> + if (u.equalsIgnoreCase("MILLISECOND")) return TimeUnit.MILLISECONDS;
> + if (u.equalsIgnoreCase("MILLIS")) return TimeUnit.MILLISECONDS;
> + if (u.equalsIgnoreCase("MILLI")) return TimeUnit.MILLISECONDS;
> + if (u.equalsIgnoreCase("MS")) return TimeUnit.MILLISECONDS;
> +
> + if (u.equalsIgnoreCase("SECONDS")) return TimeUnit.SECONDS;
> + if (u.equalsIgnoreCase("SECOND")) return TimeUnit.SECONDS;
> + if (u.equalsIgnoreCase("SEC")) return TimeUnit.SECONDS;
> + if (u.equalsIgnoreCase("S")) return TimeUnit.SECONDS;
> +
> + if (u.equalsIgnoreCase("MINUTES")) return TimeUnit.MINUTES;
> + if (u.equalsIgnoreCase("MINUTE")) return TimeUnit.MINUTES;
> + if (u.equalsIgnoreCase("MIN")) return TimeUnit.MINUTES;
> + if (u.equalsIgnoreCase("M")) return TimeUnit.MINUTES;
> +
> + if (u.equalsIgnoreCase("HOURS")) return TimeUnit.HOURS;
> + if (u.equalsIgnoreCase("HOUR")) return TimeUnit.HOURS;
> + if (u.equalsIgnoreCase("HRS")) return TimeUnit.HOURS;
> + if (u.equalsIgnoreCase("HR")) return TimeUnit.HOURS;
> + if (u.equalsIgnoreCase("H")) return TimeUnit.HOURS;
> +
> + if (u.equalsIgnoreCase("DAYS")) return TimeUnit.DAYS;
> + if (u.equalsIgnoreCase("DAY")) return TimeUnit.DAYS;
> + if (u.equalsIgnoreCase("D")) return TimeUnit.DAYS;
> +----
> diff --git a/docs/configuring-javamail.adoc b/docs/configuring-javamail.adoc
> new file mode 100644
> index 0000000..5b1e74d
> --- /dev/null
> +++ b/docs/configuring-javamail.adoc
> @@ -0,0 +1,44 @@
> += Configuring JavaMail
> +:index-group: Configuration
> +:jbake-date: 2018-12-05
> +:jbake-type: page
> +:jbake-status: published
> +
> += Declaring a JavaMail Resource
> +
> +The basics are that any properties listed in the element are given
> +directly to the javamail provider via
> +javax.mail.Session.getDefaultInstance(Properties props).
> +
> +Here might be some example properties.
> +
> +[source,xml]
> +----
> +<Resource id="SuperbizMail" type="javax.mail.Session">
> + mail.smtp.host=mail.superbiz.org
> + mail.smtp.port=25
> + mail.transport.protocol=smtp
> + mail.smtp.auth=true
> + mail.smtp.user=someuser
> + password=mypassword
> +</Resource>
> +----
> +
> +You can create as many entries like this as you wish, they just have to
> +have a unique 'id'.
> +
> +Careful not to add whitespace at the end of your property values. A
> +java.util.Properties object will leave those in the property values and
> +they will be passed to the JavaMail provider with the whitespace on the
> +end which may cause issues if the provider does not actively trim the
> +values before attempting to use them.
> +
> +== Overriding
> +
> +If you wanted to do a System property or InitialContext property
> +override of the above example mail session, you could do so like this:
> +
> +[source,bash]
> +----
> +java ... -DSuperbizMail.mail.smtp.host=localhost
> +----
> diff --git a/docs/configuring-logging-in-tests.adoc \
> b/docs/configuring-logging-in-tests.adoc new file mode 100644
> index 0000000..cad3b84
> --- /dev/null
> +++ b/docs/configuring-logging-in-tests.adoc
> @@ -0,0 +1,121 @@
> += Configuring Logging in Tests
> +:index-group: Testing Techniques
> +:jbake-date: 2018-12-05
> +:jbake-type: page
> +:jbake-status: published
> +
> += embedded.logging.properties
> +
> +When in embedded mode OpenEJB uses an embedded.logging.properties file
> +packed in our openejb-core jar which use to configure the logging. This
> +logging configuration is a bit lighter than the conf/logging.properties
> +file created in a full standalone OpenEJB setup.
> +
> +When searching for any config file in the classpath, multiple files with
> +the same name may exist. OpenEJB will always attempt to favor the one
> +closest to the openejb.base variable. This variable is set by default to
> +the current directory where your vm is executing, which is more than
> +likely the directory of your current module. So simply adding a file
> +named embedded.logging.properties to your module may be all that you
> +need to specify a new logging configuration for your tests.
> +
> +Alternatively, you can set "openejb.logger.external" to "true" as a
> +system property (will not work as an InitialContext property). Then
> +OpenEJB will not attempt to configure logging at all and you can
> +configure logging with Log4j directly using any of its APIs; xml,
> +properties, or code.
> +
> +There are a couple good reasons for _not_ replacing the
> +embedded.logging.properties file.
> +
> +[arabic]
> +. If you want to just change 5% of the logging settings, why take
> +control over the other 95% as well.
> +. We do occasionally add new logging categories. If you are not
> +replacing the embedded.logging.properties you will pick these up
> +automatically when you upgrade.
> +
> += Overriding (recommended)
> +
> +As mentioned in link:embedded-configuration.html[Embedded Configuration]
> +much can be done with simple overriding. The default
> +embedded.logging.properties is quite good and there is really no need to
> +replace it completely if all you want to do is tweak a few values.
> +
> +You can also put logging tweaks right in your InitialContext properties
> +like so:
> +
> +[source,java]
> +----
> +Properties p = new Properties();
> +p.put(Context.INITIAL_CONTEXT_FACTORY, \
> "org.apache.openejb.core.LocalInitialContextFactory"); +
> +p.put("log4j.rootLogger", "fatal,C");
> +p.put("log4j.category.OpenEJB", "warn");
> +p.put("log4j.category.OpenEJB.options", "info");
> +p.put("log4j.category.OpenEJB.server", "info");
> +p.put("log4j.category.OpenEJB.startup", "info");
> +p.put("log4j.category.OpenEJB.startup.service", "warn");
> +p.put("log4j.category.OpenEJB.startup.config", "info");
> +p.put("log4j.category.OpenEJB.hsql", "info");
> +p.put("log4j.category.CORBA-Adapter", "info");
> +p.put("log4j.category.Transaction", "warn");
> +p.put("log4j.category.org.apache.activemq", "error");
> +p.put("log4j.category.org.apache.geronimo", "error");
> +p.put("log4j.category.openjpa", "error");
> +p.put("log4j.appender.C", "org.apache.log4j.ConsoleAppender");
> +p.put("log4j.appender.C.layout", "org.apache.log4j.SimpleLayout");
> +
> +Context context = new InitialContext(p);
> +----
> +
> +Essentially, everything starting with "log4j." gets applied as overrides
> +on top of the embedded.logging.properties we find in the classpath. This
> +makes it possible to easily tweak the log levels while debugging a
> +particular test.
> +
> +Note, that InitialContext properties can also be supplied in a
> +jndi.properties file in the classpath or via system properties. The
> +overriding order is as follows: 1 = highest, 4 = lowest.
> +
> +[arabic]
> +. InitialContext properties
> +. jndi.properties in classpath
> +. system propertes
> +. embedded.logging.properties in classpath
> +
> +By default there are no logging settings in 1-3, so #4 is the only
> +source of logging information.
> +
> += Default embedded.logging.properties contents
> +
> +For your purposes, here are the contents of the default
> +embedded.logging.properties file contained in OpenEJB 3.1.1
> +
> +[source,properties]
> +----
> +log4j.rootLogger = fatal,C
> +log4j.category.OpenEJB = warn
> +log4j.category.OpenEJB.server = info
> +log4j.category.OpenEJB.startup = info
> +log4j.category.OpenEJB.startup.service = warn
> +log4j.category.OpenEJB.startup.config = info
> +log4j.category.OpenEJB.hsql = info
> +log4j.category.CORBA-Adapter = info
> +log4j.category.Transaction = warn
> +log4j.category.org.apache.activemq = error
> +log4j.category.org.apache.geronimo = error
> +log4j.category.openjpa = error
> +
> +log4j.appender.C = org.apache.log4j.ConsoleAppender
> +log4j.appender.C.layout = org.apache.log4j.SimpleLayout
> +----
> +
> +Here is that file's location in svn as well as all of the previous
> +versions. Future versions will follow the same pattern.
> +
> +* http://svn.apache.org/repos/asf/openejb/tags/openejb-3.1.1/container/openejb-core/src/main/resources/embedded.logging.properties
> +* http://svn.apache.org/repos/asf/openejb/tags/openejb-3.1/container/openejb-core/src/main/resources/embedded.logging.properties
> +* http://svn.apache.org/repos/asf/openejb/tags/openejb-3.0/container/openejb-core/src/main/resources/embedded.logging.properties
> +* http://svn.apache.org/repos/asf/openejb/tags/openejb-3.0-beta-2/container/openejb-core/src/main/resources/embedded.logging.properties
> +* http://svn.apache.org/repos/asf/openejb/tags/openejb-3.0-beta-1/container/openejb-core/src/main/resources/embedded.logging.properties
>
> diff --git a/docs/configuring-persistenceunits-in-tests.adoc \
> b/docs/configuring-persistenceunits-in-tests.adoc new file mode 100644
> index 0000000..737a2af
> --- /dev/null
> +++ b/docs/configuring-persistenceunits-in-tests.adoc
> @@ -0,0 +1,160 @@
> += Configuring PersistenceUnits in Tests
> +:index-group: Testing Techniques
> +:jbake-date: 2018-12-05
> +:jbake-type: page
> +:jbake-status: published
> +
> += Overriding the
> +persistence.xml
> +
> +The most common situation in EJB related testing by far is the need to
> +alter your persistence.xml for a test environment.
> +
> +== Overriding the jta-data-source and non-jta-data-source
> +
> +OpenEJB will automatically use the DataSources you have setup in your
> +test environment, we're pretty good at guessing the right DataSources
> +you intend even if the names don't match exactly -- or in some cases at
> +all. If there is only one DataSource configured, it's very easy for us
> +to guess the DataSource to use.
> +
> +This allows you to keep your persistence.xml configured for your
> +production environment and helps eliminate the need for a "test"
> +persistence.xml (though we do have that functionality). A log line will
> +be printed saying if we had to adjust the DataSources of your
> +persistence.xml.
> +
> +== Overriding the persistence-unit properties
> +
> +You can override any property in your test setup via either system
> +properties or the initial context properties. The format is:
> +
> +`<unit-name>.<property>=<value>`
> +
> +So for example with the following persistence.xml:
> +
> +[source,xml]
> +----
> +<persistence>
> + <persistence-unit name="movie-unit">
> + <provider>org.hibernate.ejb.HibernatePersistence</provider>
> + <jta-data-source>movieDatabase</jta-data-source>
> + <non-jta-data-source>movieDatabaseUnmanaged</non-jta-data-source>
> + <properties>
> + <property name="hibernate.hbm2ddl.auto" value="create-drop"/>
> + <property name="hibernate.max_fetch_depth" value="3"/>
> + </properties>
> + </persistence-unit>
> +</persistence>
> +----
> +
> +You can override and add persistence unit properties in your test case.
> +There are currently no facilities for removing them (if you have a need
> +for that let us know -- it hasn't really come up so far).
> +
> +[source,java]
> +----
> +Properties p = new Properties();
> +p.put(Context.INITIAL_CONTEXT_FACTORY,"org.apache.openejb.client.LocalInitialContextFactory");
> +
> +p.put("movie-unit.hibernate.hbm2ddl.auto", "update");
> +p.put("movie-unit.hibernate.dialect", "org.hibernate.dialect.HSQLDialect");
> +
> +context = new InitialContext(p);
> +----
> +
> +The overriding order is as follows: 1 = highest, 4 = lowest.
> +
> +[arabic]
> +. InitialContext properties
> +. jndi.properties from the classpath
> +. System properties
> +. persistence.xml properties
> +
> +By default there are no overrides in 1-3, so #4 is the only source of
> +information.
> +
> +In the above example there would be exactly three properties for the
> +"movie-unit" persistence unit:
> +
> +* hibernate.hbm2ddl.auto = update
> +* hibernate.max_fetch_depth = 3
> +* hibernate.dialect = org.hibernate.dialect.HSQLDialect
> +
> +These properties would be passed by OpenEJB directly to the persistence
> +provider (in this case Hibernate). With one exception OpenEJB does not
> +understand or modify these properties. Details on that one exception
> +below.
> +
> +== Common mistakes
> +
> +Note that you *must* use the *unit name* as the prefix. This will not
> +work:
> +
> +[source,java]
> +----
> + Properties p = new Properties();
> + p.put(Context.INITIAL_CONTEXT_FACTORY,"org.apache.openejb.client.LocalInitialContextFactory");
> +
> + p.put("hibernate.hbm2ddl.auto", "update");
> + p.put("hibernate.dialect", "org.hibernate.dialect.HSQLDialect");
> +
> + context = new InitialContext(p);
> +----
> +
> +Currently, only properties that start with the unit name are search and
> +applied.
> +
> +== No need to specify a "transaction lookup" property
> +
> +All vendors have such a property for getting a reference to the
> +container's TransactionManager and nothing works if this is not set
> +correctly to the OpenEJB specific class. To make the lives of users
> +easier, OpenEJB will take the liberty of setting it for you.
> +
> +Here are the persistence provider classes we understand and the defaults
> +we will set for you:
> +
> +=== Provider org.hibernate.ejb.HibernatePersistence
> +
> +When using this provider, the
> +_hibernate.transaction.manager_lookup_class_ will be automatically set
> +by OpenEJB to _org.apache.openejb.hibernate.TransactionManagerLookup_.
> +If the property is already set in the persistence unit it will be
> +overwritten if it starts with the standard "org.hibernate.transaction."
> +prefix.
> +
> +Custom lookup implementations will never be overwritten automatically.
> +
> +=== Provider oracle.toplink.essentials.PersistenceProvider
> +
> +Or _oracle.toplink.essentials.ejb.cmp3.EntityManagerFactoryProvider_.
> +
> +When using this provider, the _toplink.target-server_ will be
> +automatically set by OpenEJB to
> +_org.apache.openejb.toplink.JTATransactionController_. If the property
> +is already set in the persistence unit it will be overwritten if it
> +starts with the standard "oracle.toplink.transaction." prefix.
> +
> +Custom transaction controller implementations will never be overwritten
> +automatically.
> +
> +=== Provider org.eclipse.persistence.jpa.PersistenceProvider
> +
> +Or _org.eclipse.persistence.jpa.osgi.PersistenceProvider_.
> +
> +When using this provider, the _eclipselink.target-server_ will be
> +automatically set by OpenEJB to
> +_org.apache.openejb.eclipselink.JTATransactionController_. If the
> +property is already set in the persistence unit it will be overwritten
> +if it starts with the standard "org.eclipse.persistence.transaction."
> +prefix.
> +
> +Custom transaction controller implementations will never be overwritten
> +automatically.
> +
> +=== Provider org.apache.openjpa.persistence.PersistenceProviderImpl
> +
> +OpenJPA is capable of discovering the correct method for locating the
> +TransactionManager without the need for users to specify the specific
> +strategy. Therefore no specific "magic" is required.
> diff --git a/docs/constructor-injection.adoc b/docs/constructor-injection.adoc
> new file mode 100644
> index 0000000..d654a8f
> --- /dev/null
> +++ b/docs/constructor-injection.adoc
> @@ -0,0 +1,103 @@
> += Constructor Injection
> +:index-group: Unrevised
> +:jbake-date: 2018-12-05
> +:jbake-type: page
> +:jbake-status: published
> +
> +For those of you who would like to use final fields,
> +wish to avoid numerous setters, or dislike private field injection and
> +would like nothing more than to just use plan old java constructors,
> +your wish has come true. This is a feature we intended to add to OpenEJB
> +3.0 but didn't have time for. We're happy to bring it to the OpenEJB 3.1
> +release and with a bit of luck and support from people like yourself,
> +we'll see this as an EJB 3.1 feature as well.
> +
> +[source,java]
> +----
> +@Stateless
> +public class WidgetBean implements Widget {
> +
> + @EJB(beanName = "FooBean")
> + private final Foo foo;
> +
> + @Resource(name = "count")
> + private final int count;
> +
> + @Resource
> + private final DataSource ds;
> +
> + public WidgetBean(Integer count, Foo foo, DataSource ds) {
> + this.count = count;
> + this.foo = foo;
> + this.ds = ds;
> + }
> +
> + public int getCount() {
> + return count;
> + }
> +
> + public Foo getFoo() {
> + return foo;
> + }
> +}
> +----
> +
> +The `@EJB`, `@Resource`, `@PersistenceUnit`, and `@PersistenceContext`
> +annotations can be placed at the class-level instead such as:
> +
> +[source,java]
> +----
> +@Stateless
> +@EJB(name = "foo", beanInterface = Foo.class, beanName = "FooBean")
> +@Resource(name = "count", type = int.class)
> +@Resource(name = "ds", type = DataSource.class)
> +public class WidgetBean implements Widget {
> +
> + public WidgetBean(Integer count, Foo foo, DataSource ds) {
> + // do something
> + }
> +
> + public int getCount() {
> + return count;
> + }
> +
> + public Foo getFoo() {
> + return foo;
> + }
> +}
> +----
> +
> +Currently this functionality relies on classes being compiled with debug
> +symbols (the default compile setting for javac) as we use the debug
> +table in the byte code to discover the constructor arg names.
> +Additionally, you must not have a no-arg constructor. If a no-arg
> +constructor is present, that constructor will be used instead.
> +
> +Ideally, we would like the annotations to be used on the parameters
> +directly as shown below. Unfortunately, this does not work as the Java
> +EE annotation classes do not permit usage on parameters. If you'd like
> +to see that change as much as we do, definitely voice your support by
> +sending note to
> +mailto:jsr-316-comments@jcp.org.html[jsr-316-comments@jcp.org]
> +
> +Not yet possible
> +
> +[source,java]
> +----
> +@Stateless
> +
> +public class WidgetBean implements Widget {
> +
> + public WidgetBean(@Resource(name = "count") Integer count, @EJB Foo foo, \
> @Resource DataSource ds) { + // do something
> + }
> +
> + public int getCount() {
> + return count;
> + }
> +
> + public Foo getFoo() {
> + return foo;
> + }
> +}
> +----
> diff --git a/docs/containers-and-resources.adoc \
> b/docs/containers-and-resources.adoc new file mode 100644
> index 0000000..19c0793
> --- /dev/null
> +++ b/docs/containers-and-resources.adoc
> @@ -0,0 +1,474 @@
> += Containers and Resources
> +:index-group: Configuration
> +:jbake-date: 2018-12-05
> +:jbake-type: page
> +:jbake-status: published
> +
> +
> +[source,xml]
> +----
> + <p><a name="ContainersandResources-containers"></a></p>
> +----
> +
> +CMP_ENTITY
> +
> +Declarable in tomee.xml via
> +
> +Declarable in properties via
> +
> +Foo = new://Container?type=CMP_ENTITY
> +
> +Supports the following properties
> +
> +Property Name
> +
> +Description
> +
> +CmpEngineFactory
> +
> +Default value is org.apache.openejb.core.cmp.jpa.JpaCmpEngineFactory.
> +
> +TransactionManager
> +
> +Declarable in tomee.xml via
> +
> +Supports the following properties
> +
> +Property Name
> +
> +Description
> +
> +defaultTransactionTimeoutSeconds
> +
> +Default value is 10 minutes.
> +
> +BMP_ENTITY
> +
> +Declarable in tomee.xml via
> +
> +Declarable in properties via
> +
> +Foo = new://Container?type=BMP_ENTITY
> +
> +Supports the following properties
> +
> +Property Name
> +
> +Description
> +
> +PoolSize
> +
> +Specifies the size of the bean pools for this bmp entity container.
> +Default value is 10.
> +
> +STATELESS
> +
> +Declarable in tomee.xml via
> +
> +Declarable in properties via
> +
> +Foo = new://Container?type=STATELESS
> +
> +Supports the following properties
> +
> +Property Name
> +
> +Description
> +
> +TimeOut
> +
> +Specifies the time to wait between invocations. This value is measured
> +in milliseconds. A value of 5 would result in a time-out of 5
> +milliseconds between invocations. A value of zero would mean no timeout.
> +Default value is 0.
> +
> +PoolSize
> +
> +Specifies the size of the bean pools for this stateless SessionBean
> +container. Default value is 10.
> +
> +StrictPooling
> +
> +StrictPooling tells the container what to do when the pool reaches it's
> +maximum size and there are incoming requests that need instances. With
> +strict pooling, requests will have to wait for instances to become
> +available. The pool size will never grow beyond the the set PoolSize
> +value. Without strict pooling, the container will create temporary
> +instances to meet demand. The instances will last for just one method
> +invocation and then are removed. Default value is true.
> +
> +STATEFUL
> +
> +Declarable in tomee.xml via
> +
> +Declarable in properties via
> +
> +Foo = new://Container?type=STATEFUL
> +
> +Supports the following properties
> +
> +Property Name
> +
> +Description
> +
> +Passivator
> +
> +The passivator is responsible for writing beans to disk at passivation
> +time. Different passivators can be used by setting this property to the
> +fully qualified class name of the PassivationStrategy implementation.
> +The passivator is not responsible for invoking any callbacks or other
> +processing, its only responsibly is to write the bean state to disk.
> +Known implementations: org.apache.openejb.core.stateful.RAFPassivater
> +org.apache.openejb.core.stateful.SimplePassivater Default value is
> +org.apache.openejb.core.stateful.SimplePassivater.
> +
> +TimeOut
> +
> +Specifies the time to wait between invocations. This value is measured
> +in minutes. A value of 5 would result in a time-out of 5 minutes between
> +invocations. A value of zero would mean no timeout. Default value is 20.
> +
> +PoolSize
> +
> +Specifies the size of the bean pools for this stateful SessionBean
> +container. Default value is 1000.
> +
> +BulkPassivate
> +
> +Property name that specifies the number of instances to passivate at one
> +time when doing bulk passivation. Default value is 100.
> +
> +MESSAGE
> +
> +Declarable in tomee.xml via
> +
> +Declarable in properties via
> +
> +Foo = new://Container?type=MESSAGE
> +
> +Supports the following properties
> +
> +Property Name
> +
> +Description
> +
> +ResourceAdapter
> +
> +The resource adapter delivers messages to the container Default value is
> +Default JMS Resource Adapter.
> +
> +MessageListenerInterface
> +
> +Specifies the message listener interface handled by this container
> +Default value is javax.jms.MessageListener.
> +
> +ActivationSpecClass
> +
> +Specifies the activation spec class Default value is
> +org.apache.activemq.ra.ActiveMQActivationSpec.
> +
> +InstanceLimit
> +
> +Specifies the maximum number of bean instances that are allowed to exist
> +for each MDB deployment. Default value is 10.
> +
> +Resources
> +
> +javax.sql.DataSource
> +
> +Declarable in tomee.xml via
> +
> +Declarable in properties via
> +
> +Foo = new://Resource?type=javax.sql.DataSource
> +
> +Supports the following properties
> +
> +Property Name
> +
> +Description
> +
> +JtaManaged
> +
> +Determines wether or not this data source should be JTA managed or user
> +managed. If set to 'true' it will automatically be enrolled in any
> +ongoing transactions. Calling begin/commit/rollback or setAutoCommit on
> +the datasource or connection will not be allowed. If you need to
> +perform these functions yourself, set JtaManaged to 'false' In terms of
> +JPA persistence.xml: "JtaManaged=true" can be used as a
> +'jta-data-source' "JtaManaged=false" can be used as a
> +'non-jta-data-source' Default value is true.
> +
> +JdbcDriver
> +
> +Driver class name Default value is org.hsqldb.jdbcDriver.
> +
> +JdbcUrl
> +
> +Url for creating connections Default value is
> +jdbc:hsqldb:file:data/hsqldb/hsqldb.
> +
> +UserName
> +
> +Default user name Default value is sa.
> +
> +Password
> +
> +Default password
> +
> +ConnectionProperties
> +
> +The connection properties that will be sent to the JDBC driver when
> +establishing new connections Format of the string must be
> +[propertyName=property;]* NOTE - The "user" and "password" properties
> +will be passed explicitly, so they do not need to be included here.
> +
> +DefaultAutoCommit
> +
> +The default auto-commit state of new connections Default value is true.
> +
> +DefaultReadOnly
> +
> +The default read-only state of new connections If not set then the
> +setReadOnly method will not be called. (Some drivers don't support read
> +only mode, ex: Informix)
> +
> +DefaultTransactionIsolation
> +
> +The default TransactionIsolation state of new connections If not set
> +then the setTransactionIsolation method will not be called. The allowed
> +values for this property are: NONE READ_COMMITTED
> +READ_UNCOMMITTED REPEATABLE_READ SERIALIZABLE Note: Most JDBC
> +drivers do not support all isolation levels
> +
> +InitialSize
> +
> +The initial number of connections that are created when the pool is
> +started Default value is 0.
> +
> +MaxActive
> +
> +The maximum number of active connections that can be allocated from this
> +pool at the same time, or a negative number for no limit. Default value
> +is 20.
> +
> +MaxIdle
> +
> +The maximum number of connections that can remain idle in the pool,
> +without extra ones being released, or a negative number for no limit.
> +Default value is 20.
> +
> +MinIdle
> +
> +The minimum number of connections that can remain idle in the pool,
> +without extra ones being created, or zero to create none. Default value
> +is 0.
> +
> +MaxWait
> +
> +The maximum number of milliseconds that the pool will wait (when there
> +are no available connections) for a connection to be returned before
> +throwing an exception, or -1 to wait indefinitely. Default value is -1.
> +
> +ValidationQuery
> +
> +The SQL query that will be used to validate connections from this pool
> +before returning them to the caller. If specified, this query MUST be an
> +SQL SELECT statement that returns at least one row.
> +
> +TestOnBorrow
> +
> +If true connections will be validated before being borrowed from the
> +pool. If the validation fails, the connection is destroyed, and a new
> +conection will be retrieved from the pool (and validated). NOTE - for a
> +true value to have any effect, the ValidationQuery parameter must be
> +set. Default value is true.
> +
> +TestOnReturn
> +
> +If true connections will be validated before being returned to the
> +pool. If the validation fails, the connection is destroyed instead of
> +being returned to the pool. NOTE - for a true value to have any effect,
> +the ValidationQuery parameter must be set. Default value is false.
> +
> +TestWhileIdle
> +
> +If true connections will be validated by the idle connection evictor (if
> +any). If the validation fails, the connection is destroyed and removed
> +from the pool NOTE - for a true value to have any effect, the
> +timeBetweenEvictionRunsMillis property must be a positive number and the
> +ValidationQuery parameter must be set. Default value is false.
> +
> +TimeBetweenEvictionRunsMillis
> +
> +The number of milliseconds to sleep between runs of the idle connection
> +evictor thread. When set to a negative number, no idle connection
> +evictor thread will be run. Default value is -1.
> +
> +NumTestsPerEvictionRun
> +
> +The number of connectionss to examine during each run of the idle
> +connection evictor thread (if any). Default value is 3.
> +
> +MinEvictableIdleTimeMillis
> +
> +The minimum amount of time a connection may sit idle in the pool before
> +it is eligable for eviction by the idle connection evictor (if any).
> +Default value is 1800000.
> +
> +PoolPreparedStatements
> +
> +If true, a statement pool is created for each Connection and
> +PreparedStatements created by one of the following methods are
> +pooled: public PreparedStatement prepareStatement(String
> +sql); public PreparedStatement prepareStatement(String
> +sql, int resultSetType, int resultSetConcurrency)
> +Default value is false.
> +
> +MaxOpenPreparedStatements
> +
> +The maximum number of open statements that can be allocated from the
> +statement pool at the same time, or zero for no limit. NOTE - Some
> +drivers have limits on the number of open statements, so make sure there
> +are some resources left for the other (non-prepared) statements. Default
> +value is 0.
> +
> +AccessToUnderlyingConnectionAllowed
> +
> +If true the raw physical connection to the database can be accessed
> +using the following construct: Connection conn =
> +ds.getConnection(); Connection rawConn = ((DelegatingConnection)
> +conn).getInnermostDelegate(); ... conn.close() Default is false,
> +because misbehaving programs can do harmfull things to the raw
> +connection shuch as closing the raw connection or continuing to use the
> +raw connection after it has been assigned to another logical
> +connection. Be carefull and only use when you need direct access to
> +driver specific extentions. NOTE: Do NOT close the underlying
> +connection, only the original logical connection wrapper. Default value
> +is false.
> +
> +ActiveMQResourceAdapter
> +
> +Declarable in tomee.xml via
> +
> +Declarable in properties via
> +
> +Foo = new://Resource?type=ActiveMQResourceAdapter
> +
> +Supports the following properties
> +
> +Property Name
> +
> +Description
> +
> +BrokerXmlConfig
> +
> +Broker configuration Default value is
> +broker:(tcp://localhost:61616)?useJmx=false.
> +
> +ServerUrl
> +
> +Broker address Default value is vm://localhost?async=true.
> +
> +DataSource
> +
> +DataSource for persistence messages Default value is Default Unmanaged
> +JDBC Database.
> +
> +javax.jms.ConnectionFactory
> +
> +Declarable in tomee.xml via
> +
> +Declarable in properties via
> +
> +Foo = new://Resource?type=javax.jms.ConnectionFactory
> +
> +Supports the following properties
> +
> +Property Name
> +
> +Description
> +
> +ResourceAdapter
> +
> +Default value is Default JMS Resource Adapter.
> +
> +TransactionSupport
> +
> +Specifies if the connection is enrolled in global transaction allowed
> +values: xa, local or none Default value is xa.
> +
> +PoolMaxSize
> +
> +Maximum number of physical connection to the ActiveMQ broker Default
> +value is 10.
> +
> +PoolMinSize
> +
> +Minimum number of physical connection to the ActiveMQ broker Default
> +value is 0.
> +
> +ConnectionMaxWaitMilliseconds
> +
> +Maximum amount of time to wait for a connection Default value is 5000.
> +
> +ConnectionMaxIdleMinutes
> +
> +Maximum amount of time a connection can be idle before being reclaimed
> +Default value is 15.
> +
> +javax.jms.Queue
> +
> +Declarable in tomee.xml via
> +
> +Declarable in properties via
> +
> +Foo = new://Resource?type=javax.jms.Queue
> +
> +Supports the following properties
> +
> +Property Name
> +
> +Description
> +
> +destination
> +
> +Specifies the name of the queue
> +
> +javax.jms.Topic
> +
> +Declarable in tomee.xml via
> +
> +Declarable in properties via
> +
> +Foo = new://Resource?type=javax.jms.Topic
> +
> +Supports the following properties
> +
> +Property Name
> +
> +Description
> +
> +destination
> +
> +Specifies the name of the topic
> +
> +org.omg.CORBA.ORB
> +
> +Declarable in tomee.xml via
> +
> +Declarable in properties via
> +
> +Foo = new://Resource?type=org.omg.CORBA.ORB
> +
> +No properties.
> +
> +javax.mail.Session
> +
> +Declarable in tomee.xml via
> +
> +Declarable in properties via
> +
> +Foo = new://Resource?type=javax.mail.Session
> +
> +No properties.
> diff --git a/docs/contrib/.DS_Store b/docs/contrib/.DS_Store
> new file mode 100644
> index 0000000..e6a912a
> Binary files /dev/null and b/docs/contrib/.DS_Store differ
> diff --git a/docs/contrib/debug/debug-intellij.adoc \
> b/docs/contrib/debug/debug-intellij.adoc new file mode 100644
> index 0000000..18d5335
> --- /dev/null
> +++ b/docs/contrib/debug/debug-intellij.adoc
> @@ -0,0 +1,182 @@
> +:index-group: IDE
> +:jbake-date: 2018-12-05
> +:jbake-type: page
> +:jbake-status: published
> +
> +
> += Debugging an Apache
> +TomEE App in Intellij IDEA
> +
> +Stepping through the http://tomee.apache.org/apache-tomee.html[TomEE]
> +source code is a must-to-follow step if you want to understand how TomEE
> +works and later contribute. This is a guide to quickly start your
> +debugging session with TomEE as a TomEE developer.
> +
> +This guide assumes that:
> +
> +* Linux is the OS
> +* IntelliJ IDEA 13.1.3 is the IDE
> +* Maven 3.0.5 or better is installed
> +
> +== Download the Source Code
> +
> +For beginners it is recommended not to start with the trunk, because it
> +is common to have some blockers or non-stable functionality which could
> +bring your learning to a halt. So first start with the latest stable
> +released source code. Move to trunk once you are ready to do some code
> +modification on TomEE.
> +
> +http://www.apache.org/dyn/closer.cgi/tomee/tomee-1.7.1/openejb-4.7.1-source-release.zip[Click
> +here to download TomEE 1.7.1 Source code]
> +
> +== Build the Source Code
> +
> +First extract the zip file named *openejb-4.7.1-source-release.zip* to
> +any location. Lets assume it is your home folder.
> +
> +_______________________________________
> +unzip openejb-4.7.1-source-release -d ~
> +_______________________________________
> +
> +The above command will create the *openejb-4.7.1* directory in your home
> +directory.
> +
> +Even though you can do a full build, We will run the following command
> +to do a quick build so that you can have your meal before your hunger
> +kills you.
> +
> +_________________________________________________________________________________________________________________________________________________
> +mvn -Pquick -Dsurefire.useFile=false -DdisableXmlReport=true
> +-DuniqueVersion=false -ff -Dassemble -DskipTests -DfailIfNoTests=false
> +clean install
> +_________________________________________________________________________________________________________________________________________________
> +
> +More details about building the product from the source can be found
> +http://tomee.apache.org/dev/source-code.html[here].
> +
> +== Deploy TomEE
> +
> +The TomEE build builds several distributions (zip & war files) to cater
> +the different needs of different users. Here we discuss about the tomee
> +plus distribution & TomEE war distribution only. TomEE+ is the full
> +feature packed distribution from TomEE.
> +
> +TomEE+ zip location:
> +
> +_____________________________________________________________________
> +~/openejb-4.7.1/tomee/apache-tomee/target/apache-tomee-plus-1.7.1.zip
> +_____________________________________________________________________
> +
> +Unzip the zip into your home directory (or any other location)
> +
> +________________________________________________________________________________
> +unzip
> +~/openejb-4.7.1/tomee/apache-tomee/target/apache-tomee-plus-1.7.1.zip -d
> +~
> +________________________________________________________________________________
> +
> +You will find the directory *apache-tomee-plus-1.7.1* in your home
> +folder. Lets run the TomEE.
> +
> +__________________________________________________
> +cd ~/apache-tomee-plus-1.7.1/bin ./catalina.sh run
> +__________________________________________________
> +
> +"INFO: Server startup in xxxx ms" is the Green light!
> +
> +== Prepare your IDE
> +
> +Lets prepare our IntelliJ IDEA for the debugging session.
> +
> +Start IntelliJ IDEA and Click the Import Project link
> +
> +image:idea1.png[image]
> +
> +Select the ~/openejb-4.7.1 directory and press OK
> +
> +Select import project from external model & Maven as the external model.
> +
> +image:idea3.png[image]
> +
> +Press Next on this screen.
> +
> +image:idea4.png[image]
> +
> +Select the main profile.
> +
> +image:idea6.png[image]
> +
> +Select the org.apache.openejb:openejb:4.7.1
> +
> +image:idea7.png[image]
> +
> +Select the JDK you want to use with.
> +
> +image:idea8.png[image]
> +
> +Give the project a name and press Finish.
> +
> +image:idea9.png[image]
> +
> +Now your IDE will load the project.
> +
> +== First Breakpoint
> +
> +Next step is to put a breakpoint at the place where the code is
> +triggered. Lets understand how the code is triggered.
> +
> +TomEE+ is created on top of Tomcat. TomEE registers a Tomcat Lifecycle
> +Listener *"org.apache.tomee.catalina.ServerListener"* on *server.xml*
> +file.
> +
> +All the Tomcat lifecycle events i.e. before_init, after_init, start,
> +before_stop etc... are received by the *lifecycleEvent* method of the
> +ServerListener.
> +
> +The execution of TomEE code starts in this lifecycleEvent method. So the
> +first breakpoint should be on the lifecycleEvent method.
> +
> +== Run TomEE+ in debug mode
> +
> +If you simply run *catalina.sh jpda run* in the bin folder of tomee
> +deployment, the server starts in the debug mode but it will quckly pass
> +your breakpoint before you attach your IDE to the server process.
> +
> +So we set** JPDA_SUSPEND="y"** before we start our debugging. This will
> +tell the server "Do not proceed until the Debugger tool is attached to
> +the process"
> +
> +The convenient way of doing this is adding this line to catalina.sh file
> +right after the #!/bin/sh line.
> +
> +________________________________________
> += !/bin/sh JPDA_SUSPEND="y"
> +
> +Now to time to run TomEE+ on debug mode.
> +________________________________________
> +
> +__________________________________________________
> +~/apache-tomee-plus-1.7.1/bin/catalina.sh jpda run
> +__________________________________________________
> +
> +The terminal should hang with the message *"Listening for transport
> +dt_socket at address: 8000"*
> +
> +== Attach IntelliJ IDEA debugger
> +
> +* Menu Bar > Run > Edit Configurations
> +* Press the "*+*" button on the top left corner to get the Add new
> +configuration menu
> +* Select "Remote" from the Add new configuration menu
> +* Give a name (I gave "TomEE DEBUG") to this new configuration and set
> +the Port to 8000
> +* Click OK.
> +
> +image:idea10.png[image]
> +
> +To start debugging your TomEE+
> +
> +Main Menu > Run > Debug TomEE DEBUG
> +
> +Congratulations! You hit the break point you put at the startup of the
> +TomEE code. Carry on with your debugging session to learn more.
> diff --git a/docs/contrib/debug/idea1.png b/docs/contrib/debug/idea1.png
> new file mode 100644
> index 0000000..fb08bce
> Binary files /dev/null and b/docs/contrib/debug/idea1.png differ
> diff --git a/docs/contrib/debug/idea10.png b/docs/contrib/debug/idea10.png
> new file mode 100644
> index 0000000..e69f3b8
> Binary files /dev/null and b/docs/contrib/debug/idea10.png differ
> diff --git a/docs/contrib/debug/idea2.png b/docs/contrib/debug/idea2.png
> new file mode 100644
> index 0000000..32cc8c3
> Binary files /dev/null and b/docs/contrib/debug/idea2.png differ
> diff --git a/docs/contrib/debug/idea3.png b/docs/contrib/debug/idea3.png
> new file mode 100644
> index 0000000..def1687
> Binary files /dev/null and b/docs/contrib/debug/idea3.png differ
> diff --git a/docs/contrib/debug/idea4.png b/docs/contrib/debug/idea4.png
> new file mode 100644
> index 0000000..5c46256
> Binary files /dev/null and b/docs/contrib/debug/idea4.png differ
> diff --git a/docs/contrib/debug/idea6.png b/docs/contrib/debug/idea6.png
> new file mode 100644
> index 0000000..87dff02
> Binary files /dev/null and b/docs/contrib/debug/idea6.png differ
> diff --git a/docs/contrib/debug/idea7.png b/docs/contrib/debug/idea7.png
> new file mode 100644
> index 0000000..1fb877a
> Binary files /dev/null and b/docs/contrib/debug/idea7.png differ
> diff --git a/docs/contrib/debug/idea8.png b/docs/contrib/debug/idea8.png
> new file mode 100644
> index 0000000..1b9d64c
> Binary files /dev/null and b/docs/contrib/debug/idea8.png differ
> diff --git a/docs/contrib/debug/idea9.png b/docs/contrib/debug/idea9.png
> new file mode 100644
> index 0000000..a7e6cd5
> Binary files /dev/null and b/docs/contrib/debug/idea9.png differ
> diff --git a/docs/custom-injection.adoc b/docs/custom-injection.adoc
> new file mode 100644
> index 0000000..e6ff92f
> --- /dev/null
> +++ b/docs/custom-injection.adoc
> @@ -0,0 +1,209 @@
> += Custom Injection
> +:index-group: Unrevised
> +:jbake-date: 2018-12-05
> +:jbake-type: page
> +:jbake-status: published
> +
> += Overview
> +
> +As noted in the link:injection-of-env-entry-example.html[Injection of
> +env-entry Example] , the EJB 3.0 supported env-entry types are fairly
> +limited. Also the use of several tags in an ejb-jar.xml can get a bit
> +verbose.
> +
> +OpenEJB does not restrict you to just these data types or require you to
> +use an ejb-jar.xml to declare them.
> +
> +* `@Resource` can be used on any type for which there is
> +`java.beans.PropertyEditor`
> +* You may `install your own` PropertyEditors and package them with your
> +app.
> +* Java Generics are supported (e.g. List myURIs)
> +* You may use a `META-INF/env-entries.properties` file as an alternative
> +to an ejb-jar.xml
> +
> +See link:built-in-type-converters.html[Built-in Type Converters] for a
> +full list of supported env-entry types.
> +
> +The source for this example is the "custom-injection" directory located
> +in the link:downloads.html[openejb-examples.zip] available on the
> +http://tomee.apache.org/downloads.html[download page].
> +
> +# The Code
> +
> +== Bean Class
> +
> +[source,java]
> +----
> +@Stateless
> +public class Stratocaster {
> +
> + @Resource(name = "pickups")
> + private List<Pickup> pickups;
> +
> + @Resource(name = "style")
> + private Style style;
> +
> + @Resource(name = "dateCreated")
> + private Date dateCreated;
> +
> + @Resource(name = "guitarStringGuages")
> + private Map<String, Float> guitarStringGuages;
> +
> + @Resource(name = "certificateOfAuthenticity")
> + private File certificateOfAuthenticity;
> +
> + public Date getDateCreated() {
> + return dateCreated;
> + }
> +
> + /**
> + * Gets the guage of the electric guitar strings
> + * used in this guitar.
> + *
> + * @param string
> + * @return
> + */
> + public float getStringGuage(String string) {
> + return guitarStringGuages.get(string);
> + }
> +
> + public List<Pickup> getPickups() {
> + return pickups;
> + }
> +
> + public Style getStyle() {
> + return style;
> + }
> +
> + public File getCertificateOfAuthenticity() {
> + return certificateOfAuthenticity;
> + }
> +}
> +----
> +
> +== The META-INF/env-entries.properties file
> +
> +[source,properties]
> +----
> +guitarStringGuages=E1=0.052\nA=0.042\nD=0.030\nG=0.017\nB=0.013\nE=0.010
> +certificateOfAuthenticity=/tmp/strat-certificate.txt
> +dateCreated=1962-03-01
> +pickups=S,S,S
> +style=VINTAGE
> +----
> +
> +== The Custom Type and Editor
> +
> +Support for java.lang.Enum types is already built-in, but we've decided
> +we'd like to allow abbreviated versions of the enum constants to be
> +usable. We do this by creating a custom PropertyEditor for our Pickup
> +enum like so:
> +
> +[source,java]
> +----
> +public class PickupEditor extends java.beans.PropertyEditorSupport {
> + public void setAsText(String text) throws IllegalArgumentException {
> + text = text.trim();
> +
> + if (text.equalsIgnoreCase("H")) setValue(Pickup.HUMBUCKER);
> + else if (text.equalsIgnoreCase("S")) setValue(Pickup.SINGLE_COIL);
> + else throw new IllegalStateException("H and S are the only supported \
> Pickup aliases"); + }
> +}
> +----
> +
> +We cleverly install this PropertyEditor in a static block in the Pickup
> +class that will be executed should someone actually reference the Pickup
> +type.
> +
> +[source,java]
> +----
> +public enum Pickup {
> +
> + HUMBUCKER,
> + SINGLE_COIL;
> +
> + // Here's the little magic where we register the PickupEditor
> + // which knows how to create this object from a string.
> + // You can add any of your own Property Editors in the same way.
> + static {
> + PropertyEditorManager.registerEditor(Pickup.class, PickupEditor.class);
> + }
> +}
> +----
> +
> +# Test Case
> +
> +[source,java]
> +----
> +public class StratocasterTest extends TestCase {
> +
> + @EJB
> + private Stratocaster strat;
> +
> + public void test() throws Exception {
> + EJBContainer.createEJBContainer().getContext().bind("inject", this);
> +
> + Date date = DateFormat.getDateInstance(DateFormat.MEDIUM, \
> Locale.US).parse("Mar 1, 1962"); + assertEquals("Strat.getDateCreated()", \
> date, strat.getDateCreated()); +
> + List<Pickup> pickups = asList(Pickup.SINGLE_COIL, Pickup.SINGLE_COIL, \
> Pickup.SINGLE_COIL); + assertEquals("Strat.getPickups()", pickups, \
> strat.getPickups()); +
> + assertEquals("Strat.getStyle()", Style.VINTAGE, strat.getStyle());
> +
> + assertEquals("Strat.getStringGuage(\"E1\")", 0.052F, \
> strat.getStringGuage("E1")); + assertEquals("Strat.getStringGuage(\"A\")", \
> 0.042F, strat.getStringGuage("A")); + \
> assertEquals("Strat.getStringGuage(\"D\")", 0.030F, strat.getStringGuage("D")); + \
> assertEquals("Strat.getStringGuage(\"G\")", 0.017F, strat.getStringGuage("G")); + \
> assertEquals("Strat.getStringGuage(\"B\")", 0.013F, strat.getStringGuage("B")); + \
> assertEquals("Strat.getStringGuage(\"E\")", 0.010F, strat.getStringGuage("E")); +
> + File file = new File("/tmp/strat-certificate.txt");
> + assertEquals("Strat.getCertificateOfAuthenticity()", \
> file,strat.getCertificateOfAuthenticity()); +
> +
> + }
> +}
> +----
> +
> +# Running it
> +
> +Running the example is fairly simple. In the "custom-injection"
> +directory of the openejb:download.html[examples zip], just run:
> +
> +___________________
> +$ mvn clean install
> +___________________
> +
> +Which should create output like the following.
> +
> +[source,java]
> +----
> +-------------------------------------------------------
> + T E S T S
> +-------------------------------------------------------
> +Running org.superbiz.enventries.StratocasterTest
> +Apache OpenEJB 3.1-SNAPSHOT build: 20080409-12:05
> +http://tomee.apache.org/
> +INFO - openejb.home = /Users/dblevins/work/openejb3/examples/custom-injection
> +INFO - openejb.base = /Users/dblevins/work/openejb3/examples/custom-injection
> +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: \
> /Users/dblevins/work/openejb3/examples/custom-injection/target/classes +INFO - \
> Configuring app: /Users/dblevins/work/openejb3/examples/custom-injection/target/classes
> +INFO - Configuring Service(id=Default Stateless Container, type=Container, \
> provider-id=Default Stateless Container) +INFO - Auto-creating a container for bean \
> StratocasterImpl: Container(type=STATELESS, id=Default Stateless Container) +INFO - \
> Loaded Module: /Users/dblevins/work/openejb3/examples/custom-injection/target/classes
> +INFO - Assembling app: \
> /Users/dblevins/work/openejb3/examples/custom-injection/target/classes +INFO - \
> Jndi(name=StratocasterImplLocal) --> Ejb(deployment-id=StratocasterImpl) +INFO - \
> Created Ejb(deployment-id=StratocasterImpl, ejb-name=StratocasterImpl, \
> container=Default Stateless Container) +INFO - Deployed \
> Application(path=/Users/dblevins/work/openejb3/examples/custom-injection/target/classes)
> +Tests run: 1, Failures: 0, Errors: 0, Skipped: 0, Time elapsed: 0.705 sec
> +
> +Results :
> +
> +Tests run: 1, Failures: 0, Errors: 0, Skipped: 0
> +----
> diff --git a/docs/datasource-configuration-by-creator.adoc \
> b/docs/datasource-configuration-by-creator.adoc new file mode 100644
> index 0000000..9cd1577
> --- /dev/null
> +++ b/docs/datasource-configuration-by-creator.adoc
> @@ -0,0 +1,160 @@
> += DataSource Creator
> +:index-group: Datasource
> +:jbake-date: 2018-12-05
> +:jbake-type: page
> +:jbake-status: published
> +
> +TomEE uses `creator` to create the connection pool factory. In other
> +terms it means you can use any pool you want for DataSource in TomEE.
> +
> +Default provided pools are DBCP (default in embedded mode) and Tomcat
> +JDBC (default in TomEE to be aligned on Tomcat).
> +
> +Depending which one you use the accept configuration are not 100% the
> +same even if we try to align the most common entries to the historical
> +configuration (ie DBCP).
> +
> +Here are a more detailled list of accepted properties by creator.
> +
> +== DBCP2 (TomEE 7.x and 8.x)
> +
> +Note: details are at
> +http://tomee.apache.org/containers-and-resources.html (note:
> +http://commons.apache.org/proper/commons-dbcp/configuration.html uses
> +the latest version of DBCP but TomEE 1.7.x is not using this version).
> +
> +* AccessToUnderlyingConnectionAllowed
> +* ConnectionInitSqls
> +* ConnectionProperties
> +* DefaultAutoCommit
> +* DefaultCatalog
> +* DefaultReadOnly
> +* DefaultTransactionIsolation
> +* Delegate
> +* InitialSize
> +* JdbcDriver
> +* JdbcUrl
> +* LogAbandoned
> +* LogWriter
> +* LoginTimeout
> +* MaxActive
> +* MaxIdle
> +* MaxOpenPreparedStatements
> +* MaxWait
> +* MinEvictableIdleTimeMillis
> +* MinIdle
> +* Name
> +* NumTestsPerEvictionRun
> +* Password
> +* PasswordCipher
> +* PoolPreparedStatements
> +* RemoveAbandoned
> +* RemoveAbandonedTimeout
> +* TestOnBorrow
> +* TestOnReturn
> +* TestWhileIdle
> +* TimeBetweenEvictionRunsMillis
> +* UserName
> +* ValidationQuery
> +* ValidationQueryTimeout
> +
> +== Tomcat JDBC
> +
> +Note: details are at
> +https://tomcat.apache.org/tomcat-7.0-doc/jdbc-pool.html
> +
> +* AbandonWhenPercentageFull
> +* AccessToUnderlyingConnectionAllowed
> +* AlternateUsernameAllowed
> +* CommitOnReturn
> +* ConnectionProperties
> +* DataSource
> +* DataSourceJNDI
> +* DbProperties
> +* DefaultAutoCommit
> +* DefaultCatalog
> +* DefaultReadOnly
> +* DefaultTransactionIsolation
> +* DriverClassName
> +* FairQueue
> +* IgnoreExceptionOnPreLoad
> +* InitSQL
> +* InitialSize
> +* JdbcInterceptors
> +* JmxEnabled
> +* LogAbandoned
> +* LogValidationErrors
> +* LogWriter
> +* LoginTimeout
> +* MaxActive
> +* MaxAge
> +* MaxIdle
> +* MaxWait
> +* MinEvictableIdleTimeMillis
> +* MinIdle
> +* Name
> +* NumTestsPerEvictionRun
> +* Password
> +* PasswordCipher
> +* PoolProperties
> +* PropagateInterruptState
> +* RemoveAbandoned
> +* RemoveAbandonedTimeout
> +* RollbackOnReturn
> +* SuspectTimeout
> +* TestOnBorrow
> +* TestOnConnect
> +* TestOnReturn
> +* TestWhileIdle
> +* TimeBetweenEvictionRunsMillis
> +* Url
> +* UseDisposableConnectionFacade
> +* UseEquals
> +* UseLock
> +* Username
> +* ValidationInterval
> +* ValidationQuery
> +* ValidationQueryTimeout
> +* Validator
> +* ValidatorClassName
> +
> +== DBCP2 (TomEE 7.x)
> +
> +Note: details are at
> +http://commons.apache.org/proper/commons-dbcp/configuration.html
> +
> +* AccessToUnderlyingConnectionAllowed
> +* ConnectionInitSqls
> +* ConnectionProperties
> +* DefaultAutoCommit
> +* DefaultCatalog
> +* DefaultReadOnly
> +* DefaultTransactionIsolation
> +* Delegate
> +* InitialSize
> +* JdbcDriver
> +* JdbcUrl
> +* LogAbandoned
> +* LogWriter
> +* LoginTimeout
> +* MaxTotal
> +* MaxIdle
> +* MaxOpenPreparedStatements
> +* MaxWait
> +* MinEvictableIdleTimeMillis
> +* MinIdle
> +* Name
> +* NumTestsPerEvictionRun
> +* Password
> +* PasswordCipher
> +* PoolPreparedStatements
> +* RemoveAbandonedOnBorrow
> +* RemoveAbandonedOnMaintenance
> +* RemoveAbandonedTimeout
> +* TestOnBorrow
> +* TestOnReturn
> +* TestWhileIdle
> +* TimeBetweenEvictionRunsMillis
> +* UserName
> +* ValidationQuery
> +* ValidationQueryTimeout
> diff --git a/docs/datasource-password-encryption.adoc \
> b/docs/datasource-password-encryption.adoc new file mode 100644
> index 0000000..4052004
> --- /dev/null
> +++ b/docs/datasource-password-encryption.adoc
> @@ -0,0 +1,168 @@
> += DataSource Password Encryption
> +:index-group: Datasource
> +:jbake-date: 2018-12-05
> +:jbake-type: page
> +:jbake-status: published
> +
> +_Apache OpenEJB 3.1.2 or later required_
> +
> +_TomEE 1.5.0 switched from Apache Commons-DBCP to Tomcat-pool. On that
> +specific version, password encryption is not available. You can still
> +switch back to Apache Commons DBCP buy adding the following property:
> +DataSourceCreator dbcp. On all following versions, the database
> +encryption will be ported and hence available on Tomcat-pool as well._
> +
> += Ciphering passwords Apache OpenEJB now provides an easy and extensible
> +way to cipher databases passwords. Not that by default, this feature is
> +not activated so plain passwords are used.
> +
> +== Usage
> +
> +Default Plain text password example:
> +
> +[source,xml]
> +----
> +<Resource id="MySQL Database" type="DataSource">
> + # MySQL example
> + #
> + # This connector will not work until you download the driver at:
> + # http://www.mysql.com/downloads/api-jdbc-stable.html
> +
> + JdbcDriver com.mysql.jdbc.Driver
> + JdbcUrl jdbc:mysql://localhost/test
> + UserName test
> + Password Passw0rd
> +</Resource>
> +----
> +
> +3DES ciphered password example.
> +
> +Note that the built in 3DES implementation uses _a static key_ to
> +encode/decode your password. _It's only meant to be a sample on how to
> +implement a Codec. On a real enterprise life, you should implement your
> +how relying on an HSM for example._ The easiest way to do it is to
> +implement the _org.apache.openejb.resource.jdbc.cipher.PasswordCipher_
> +interface.
> +
> +[source,xml]
> +----
> +<Resource id="MySQL Database" type="DataSource">
> + # MySQL example
> + #
> + # This connector will not work until you download the driver at:
> + # http://www.mysql.com/downloads/api-jdbc-stable.html
> +
> + JdbcDriver com.mysql.jdbc.Driver
> + JdbcUrl jdbc:mysql://localhost/test
> + UserName test
> +
> + # ciphered value for Passw0rd using Static3DES codec is
> + xMH5uM1V9vQzVUv5LG7YLA==
> + Password xMH5uM1V9vQzVUv5LG7YLA==
> + PasswordCipher Static3DES
> +</Resource>
> +----
> +
> +== Hint
> +
> +You can plug your own algorithm to extend Apache OpenEJB built in ones.
> +To do such, you just need to implement the
> +
> +=== Command line tool
> +
> +Apache OpenEJB also provides a command line tool allowing password
> +cipher algorithm. Actually, it's useful to get the ciphered value of a
> +plain text value using a given algorithm.
> +
> +==== NAME
> +
> +openejb cipher - OpenEJB Cypher Tool
> +
> +==== SYNOPSIS
> +
> +[source,properties]
> +----
> +openejb cipher [#options]
> +----
> +
> +==== DESCRIPTION
> +
> +The OpenEJB Cipher tool is an OPTIONAL tool that allows you to use
> +`PasswordCipher` algorithm to encode/decode values.
> +
> +_This tool isn't package by default on TomEE 1.5.0. It's only available
> +on the standalone distribution. After 1.5.0, it's in TomEE as well._
> +
> +The OpenEJB Cipher tool can be executed from any directory as long as
> +`<OPENEJB_HOME>/bin` is in the system PATH. Before running this tool you
> +need to set the environment variable OPENEJB_HOME to the path of the
> +directory where you unpacked the OpenEJB installation. For for the
> +remainder of this document we will assume you unpacked OpenEJB into the
> +directory C:-3.1.2.
> +
> +In Windows, the cipher tool can be executed as follows:
> +
> +[source,java]
> +----
> +`C:\openejb-3.1.2> bin\openejb cipher --help`
> +----
> +
> +In UNIX, Linux, or Mac OS X, the cipher tool can be executed as follows:
> +
> +[source,java]
> +----
> +`\[user@host openejb-3.1.2]# bin/openejb cipher --help`
> +----
> +
> +Depending on your OpenEJB version, you may need to change execution bits
> +to make the scripts executable. You can do this with the following
> +command.
> +
> +[source,java]
> +----
> +`\[user@host openejb-3.1.2]# chmod 755 bin/openejb`
> +----
> +
> +From here on out, it will be assumed that you know how to execute the
> +right openejb script for your operating system and commands will appear
> +in shorthand as show below.
> +
> +[source,java]
> +----
> +`openejb cipher --help`
> +----
> +
> +==== OPTIONS
> +
> +-h, --_help_
> +
> +Lists these options and exit.
> +
> +-c, --_cipher_
> +
> +Specifies the password cipher implementation to use (default is
> +Static3DES).
> +
> +-d, --_decrypt_
> +
> +Switches command line tool to decrypt.
> +
> +-e, --_encrypt_
> +
> +Switches command line tool to encrypt (default).
> +
> +==== EXAMPLES
> +
> +Encrypt a plain password using the default algorithm.
> +
> +[source,java]
> +----
> +`openejb cipher Passw0rd`
> +----
> +
> +Output
> +
> +[source,properties]
> +----
> +xMH5uM1V9vQzVUv5LG7YLA==
> +----
> diff --git a/docs/deamon/lin-service.adoc b/docs/deamon/lin-service.adoc
> new file mode 100644
> index 0000000..20df48b
> --- /dev/null
> +++ b/docs/deamon/lin-service.adoc
> @@ -0,0 +1,44 @@
> +:index-group: Installation
> +:jbake-date: 2018-12-05
> +:jbake-type: page
> +:jbake-status: published
> +
> +
> += Linux Service
> +
> +Depending on your flavour of Linux, there are likely a few different ways you can \
> run TomEE as a service. +This page demonstrates running as a service with systemd, \
> and has been tested with RedHat Enterprise Linux. +
> +Create a file `/etc/systemd/system/tomee.service` with the following content:
> +
> +```
> +[Unit]
> +Description=Apache TomEE
> +After=network.target
> +
> +[Service]
> +User=<user to run as>
> +Type=forking
> +Environment=JAVA_HOME=/usr/lib/jvm/jre
> +Environment=CATALINA_PID=/opt/tomee/temp/tomee.pid
> +Environment=CATALINA_HOME=/opt/tomee
> +Environment=CATALINA_BASE=/opt/tomee
> +Environment=CATALINA_OPTS='-server'
> +Environment=JAVA_OPTS='-Djava.awt.headless=true'
> +ExecStart=/opt/tomee/bin/startup.sh
> +ExecStop=/opt/tomee/bin/shutdown.sh
> +KillSignal=SIGCONT
> +
> +[Install]
> +WantedBy=multi-user.target
> +```
> +
> +The file above assumes TomEE is extracted to `/opt/tomee`, and that `JAVA_HOME` is \
> at `/usr/lib/jvm/jre` - adjust these to match your installation. +
> +Once done, run `sudo systemctl daemon-reload` so systemd is aware of the new \
> service. +
> +You should now be able to use the following commands to control the TomEE service:
> +
> +* `sudo systemctl start tomee` (to start TomEE)
> +* `sudo systemctl stop tomee` (to stop TomEE)
> +* `sudo systemctl status tomee` (to check the status of the TomEE service)
> diff --git a/docs/deamon/win-service.adoc b/docs/deamon/win-service.adoc
> new file mode 100644
> index 0000000..0aa046b
> --- /dev/null
> +++ b/docs/deamon/win-service.adoc
> @@ -0,0 +1,140 @@
> +:index-group: Installation
> +:jbake-date: 2018-12-05
> +:jbake-type: page
> +:jbake-status: published
> +
> +
> += Windows Service
> +== TomEE as a Windows ® Service
> +
> +It is possible to configure TomEE to run as Windows service, and batch
> +files are provided in the bin folder to accomplish this. The key batch
> +file is `service.bat`, and this provides commands to install and
> +remove the service. Additionally two helper files are provided to
> +simplify the installation and create a basic service setup.
> +
> +* service.install.as.admin.bat
> +* service.remove.as.admin.bat
> +
> +== Installation
> +
> +These instructions assume you have already downloaded a TomEE zip file
> +and extracted it to the desired location on the file system, and that
> +you have a suitable Java installation on your machine.
> +
> +Start by opening a Command Prompt as an Administrator user.
> +
> +
> +Ensure you have JAVA_HOME set to the JDK you wish to use for the
> +service. You can check this by running `set JAVA_HOME`.
> +
> +Run `service install`. Optionally you can pass a service name, and
> +credentials for a service user.
> +
> +`service install [/service-user <user>] [/service-password <password>] [service \
> name]` +
> +For example:
> +
> +```
> + C:\Java\apache-tomee-plus-8.0.0-SNAPSHOT\bin>service install TomEE-DEV
> + Installing the service 'TomEE-DEV' ...
> + Using CATALINA_HOME: "C:\Java\apache-tomee-plus-8.0.0-SNAPSHOT"
> + Using CATALINA_BASE: "C:\Java\apache-tomee-plus-8.0.0-SNAPSHOT"
> + Using JAVA_HOME: "C:\Java\jdk-11.0.4+11
> + Using JRE_HOME: "C:\Java\jdk-11.0.4+11"
> + Using JVM: "C:\Java\jdk-11.0.4+11"\bin\server\jvm.dll"
> + Using Service User: ""
> + Installed, will now configure TomEE
> + The service 'TomEE-DEV' has been installed.
> +
> + C:\Java\apache-tomee-plus-8.0.0-SNAPSHOT\bin>
> +```
> +
> +== Removal
> +
> +Removal is similar to installation. First, ensure the service is stopped.
> + In an administrator Command Prompt, run:
> +
> +`service remove [service name]`
> +
> +For example:
> +
> +```
> + C:\Java\apache-tomee-plus-8.0.0-SNAPSHOT\bin>service remove TomEE-DEV
> + The service 'TomEE-DEV' has been removed
> +
> + C:\Java\apache-tomee-plus-8.0.0-SNAPSHOT\bin>
> +```
> +
> +== Service Accounts
> +
> +Ny default, the service is installed to run at the user `NT-Authority\Local \
> Service`, +which is a very restricted account. If you wish to use `LocalSystem`, \
> which +has more privileges, use:
> +
> +`service install /service-user LocalSystem [service name]`
> +
> +For example:
> +
> +```
> +C:\Java\apache-tomee-plus-8.0.0-SNAPSHOT\bin>service install /service-user \
> LocalSystem TomEE-DEV +Installing the service 'TomEE-DEV' ...
> +Using CATALINA_HOME: "C:\Java\apache-tomee-plus-8.0.0-SNAPSHOT"
> +Using CATALINA_BASE: "C:\Java\apache-tomee-plus-8.0.0-SNAPSHOT"
> +Using JAVA_HOME: "C:\Java\jdk-11.0.4+11"
> +Using JRE_HOME: "C:\Java\jdk-11.0.4+11"
> +Using JVM: "C:\Java\jdk-11.0.4+11"\bin\server\jvm.dll"
> +Using Service User: "LocalSystem"
> +Installed, will now configure TomEE
> +The service 'TomEE-DEV' has been installed.
> +
> +C:\Java\apache-tomee-plus-8.0.0-SNAPSHOT\bin>
> +```
> +
> +Alternatively, you may have a specific local or domain user you wish to use
> +to run the service. You can specify the username and password for
> +the service user with the `/service-user` and `/service-password`
> +parameters.
> +
> +== Making Changes
> +
> +Once the service is installed, it is possible to make changes either
> +using the Windows Service Control Manager (start, stop, change user)
> +or by running the TomEE.exe executable in the bin directory which
> +will allow you change more settings, such as the JVM the service
> +uses.
> +
> +NOTE: if you use a custom name for your service, rename (or copy) TomEE.exe to
> +match it - e.g. TomEE-DEV.exe to match the examples above.
> +
> +== Using a 32 bit JVM on 64 bit Windows
> +
> +The service script will install either TomEE.x86.exe or TomEE.amd64.exe as the
> +service. The script uses the `PROCESSOR_ARCHITECTURE=AMD64` environment
> +variable to determine which to use. The TomEE executable used needs to
> +match the architecture of the JVM you wish to use.
> +
> +If you wish to use a 32 bit JVM on 64 bit Windows, run
> +
> +`set PROCESSOR_ARCHITECTURE=X86` prior to installing the service.
> +
> +== Setting environment variables for the service
> +
> +Setting custom environment variables for TomEE to use is a little tricky
> +as it can't be done through the UI, but can be accomplished via the
> +command line.
> +
> +After the service as been installed, at the Command Prompt, use the
> +following syntax (use the right TomEE exe for your platform)
> +
> +`TomEE.amd64.exe //US//TomEE ++Environment "variable=value"`
> +
> +Replace `TomEE` after `//US//` with your service name if you are using
> +a custom service name.
> +
> +== Further information
> +
> +The TomEE exe files are from the Apache Commons Daemon project.
> +Full documentation for commons-daemon can be found here:
> +
> +http://commons.apache.org/proper/commons-daemon/procrun.html
> diff --git a/docs/declaring-references.adoc b/docs/declaring-references.adoc
> new file mode 100644
> index 0000000..1b48249
> --- /dev/null
> +++ b/docs/declaring-references.adoc
> @@ -0,0 +1,5 @@
> += Declaring References
> +:index-group: Unrevised
> +:jbake-date: 2018-12-05
> +:jbake-type: page
> +:jbake-status: published
> diff --git a/docs/deploy-tool.adoc b/docs/deploy-tool.adoc
> new file mode 100644
> index 0000000..ed17d1d
> --- /dev/null
> +++ b/docs/deploy-tool.adoc
> @@ -0,0 +1,167 @@
> += Deploy Tool
> +:index-group: OpenEJB Standalone Server
> +:jbake-date: 2018-12-05
> +:jbake-type: page
> +:jbake-status: published
> +
> +
> += NAME
> +
> +openejb deploy - OpenEJB Deploy Tool
> +
> += SYNOPSIS
> +
> +____________________________________________________________________
> +openejb deploy link:#DeployTool-OPTIONS[options] <file> [<file> ...]
> +____________________________________________________________________
> +
> += NOTE
> +
> +The OpenEJB Deploy tool is an OPTIONAL tool that allows you to deploy
> +into a running server and get feedback as if the app was deployed and
> +how it was deployed (deploymentIds, jndi names, etc.).
> +
> +It can be used to deploy into an offline server, however in this
> +scenario it simply copies the archive into the deployment directory (by
> +default `openejb.base/apps`) which is something that can be done
> +manually with a simple copy command or drag and drop.
> +
> +The OpenEJB Deploy tool can be executed from any directory as long as
> +`openejb.home/bin` is in the system PATH. `openejb.home` is the
> +directory where OpenEJB was installed or unpacked. For for the remainder
> +of this document we will assume you unpacked OpenEJB into the directory
> +`C:\openejb-3.0` under Windows.
> +
> +In Windows, the deploy tool can be executed as follows:
> +
> +________________________
> +C:-3.0> bindeploy --help
> +________________________
> +
> +In UNIX, Linux, or Mac OS X, the deploy tool can be executed as follows:
> +
> +____________________________________
> +user@host# bin/openejb deploy --help
> +____________________________________
> +
> +Depending on your OpenEJB version, you may need to change execution bits
> +to make the scripts executable. You can do this with the following
> +command.
> +
> +_______________________________
> +user@host# chmod +x bin/openejb
> +_______________________________
> +
> +From here on out, it will be assumed that you know how to execute the
> +right openejb script for your operating system and commands will appear
> +in shorthand as show below.
> +
> +_____________________
> +openejb deploy --help
> +_____________________
> +
> += DESCRIPTION
> +
> +The files passed to the Deploy Tool can be any combination of the
> +following:
> +
> +* EJB 1.1, 2.0, 2.1, 3.0 or 3.1 jar
> +* application client jar
> +* EAR file containing only libraries, EJBs and application clients --
> +everything else will be ignored.
> +
> +The type of the files passed is determined as follows:
> +
> +* Archives ending in `.ear` or containing a `META-INF/application.xml`
> +are assumed to be EAR files.
> +* Archives containing a `META-INF/ejb-jar.xml` file or any classes
> +annotated with `@Stateless`, `@Stateful` or `@MessageDriven`, are
> +assumed to be _EJB_ applications. EJB applications older that EJB 3.0
> +should contain a complete `META-INF/ejb-jar.xml` inside the jar, however
> +we do not strictly enforce that -- the act of it being incomplete makes
> +it an EJB 3.0 application by nature.
> +* Archives containing a `META-INF/application-client.xml` or with a
> +`META-INF/MANIFEST.MF` containing the `Main-Class` attribute, are
> +assumed to be _Application Client_ archives.
> +
> += OPTIONS
> +
> +-d, --debug
> +
> +Increases the level of detail on validation errors and deployment
> +summary.
> +
> +--dir
> +
> +Sets the destination directory where the app will be deployed. The
> +default is /apps/ directory. Note when changing this setting make sure
> +the directory is listed in the openejb.xml via a tag or the app will not
> +be picked up again on restart.
> +
> +-conf file
> +
> +Sets the OpenEJB configuration to the specified file.
> +
> +-h, --help
> +
> +Lists these options and exit.
> +
> +-o, --offline
> +
> +Deploys the app to an offline server by copying the archive into the
> +server's apps/ directory. The app will be deployed when the server is
> +started. The default is online.
> +
> +-q, --quiet
> +
> +Decreases the level of detail on validation and skips the deployment
> +summary.
> +
> +-s, --server-url <url>
> +
> +Sets the url of the OpenEJB server to which the app will be deployed.
> +The value should be the same as the JNDI Provider URL used to lookup
> +EJBs. The default is 'ejbd://localhost:4201'.
> +
> +-v, --version
> +
> +Prints the OpenEJB version and exits.
> +
> += EXAMPLES
> +
> +== Deploying multiple jar files
> +
> +__________________________________
> +openejb deploy myapp.jar myapp.jar
> +__________________________________
> +
> +Deploys the beans in the fooEjbs.jar first, then deploys the beans in
> +the barEjbs.jar. Wildcards can be used as well.
> +
> +_________________________
> +openejb deploy myapp*.jar
> +_________________________
> +
> += OUTPUT
> +
> +On running the deploy tool with a valid EJB jar the following output is
> +printed on the console
> +
> +[source,properties]
> +----
> +Application deployed successfully at {0}
> +App(id=C:\samples\Calculator-new\hello-addservice.jar)
> + EjbJar(id=hello-addservice.jar, \
> path=C:\samples\Calculator-new\hello-addservice.jar) + Ejb(ejb-name=HelloBean, \
> id=HelloBean) + Jndi(name=HelloBean)
> + Jndi(name=HelloBeanLocal)
> +
> + Ejb(ejb-name=AddServiceBean, id=AddServiceBean)
> + Jndi(name=AddServiceBean)
> + Jndi(name=AddServiceBeanLocal)
> +----
> +
> +Note: In the above case the command used is: > openejb deploy
> +hello-addservice.jar
> +
> +The JAR file contains two EJBs: AddServiceBean and HelloBean.
> diff --git a/docs/deploying-in-tomee.adoc b/docs/deploying-in-tomee.adoc
> new file mode 100644
> index 0000000..f138f83
> --- /dev/null
> +++ b/docs/deploying-in-tomee.adoc
> @@ -0,0 +1,73 @@
> +:index-group: General Information
> +:jbake-date: 2018-12-05
> +:jbake-type: page
> +:jbake-status: published
> +
> +
> +NOTE: Licensed to the Apache Software Foundation (ASF) under
> +one or more contributor license agreements. See the NOTICE file
> +distributed with this work for additional information regarding
> +copyright ownership. The ASF licenses this file to you under the Apache
> +License, Version 2.0 (the "License"); you may not use this file except
> +in compliance with the License. You may obtain a copy of the License at
> +. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by
> +applicable law or agreed to in writing, software distributed under the
> +License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR
> +CONDITIONS OF ANY KIND, either express or implied. See the License for
> +the specific language governing permissions and limitations under the
> +License.
> +
> += Deploying in TomEE
> +
> +Deploying applications in TomEE is as simple as deploying them in
> +Tomcat.
> +
> +You could deploy your application in Eclipse just like how you would
> +deploy with Tomcat. For an example,
> +link:tomee-and-eclipse.html[tomee-and-eclipse] shows how to use TomEE
> +with Eclipse.
> +
> +Or you can simply package your application as a standard *WAR* file and
> +copy it to the *[TomEE]/webapps* folder, or as an *EAR* file and copy it
> +to the *[TomEE]/apps* folder.
> +
> +Read on to learn more about packaging EJBs in a WAR file.
> +
> +== Packaging
> +
> +=== One archive
> +
> +The basic idea of this approach is that your Servlets and EJBs are
> +together in your WAR file as one application.
> +
> +* No classloader boundaries between Servlets and EJBs
> +* EJBs and Servlets can share all third-party libraries (like Spring!)
> +* No EAR required.
> +* Can put the web.xml and ejb-jar.xml in the same archive (the WAR file)
> +* EJBs can see Servlet classes and vice versa
> +
> +=== Not quite J2EE (But it is Java EE 6)
> +
> +This is very different than J2EE or Java EE 5 as there are not several
> +levels of separation and classloader hierarchy any more. +
> +This may take some getting used to and it is important to understand
> +that this style of packaging is *not* J2EE compliant. +
> +You should not worry though, as it is an accepted feature of Java EE 6.
> +
> +=== J2EE classloading rules:
> +
> +* You cannot ever have EJBs and Servlets in the same classloader.
> +* Three classloader minimum; a classloader for the ear, one for each
> +ejb-jar, and one for each WAR file.
> +* Servlets can see EJBs, but EJBs cannot see Servlets.
> +
> +To pull that off, J2EE has to kill you on packaging: - You cannot have
> +EJB classes and Servlet classes in the same archive.
> +
> +* You need at least three archives to combine Servlets and EJBs; 1 EAR
> +containing 1 EJB jar and 1 Servlet WAR.
> +* Shared libraries must go in the EAR and be included in a specially
> +formatted 'Class-Path' entry in the EAR's MANIFEST file.
> +
> +Critically speaking, forcing more than one classloader on an application
> +is where J2EE "jumps the shark" for a large majority of people's needs.
> diff --git a/docs/deployment-id.adoc b/docs/deployment-id.adoc
> new file mode 100644
> index 0000000..1a3b0fb
> --- /dev/null
> +++ b/docs/deployment-id.adoc
> @@ -0,0 +1,236 @@
> += Deployment ID
> +:index-group: Unrevised
> +:jbake-date: 2018-12-05
> +:jbake-type: page
> +:jbake-status: published
> +
> +
> += What is a Deployment ID?
> +
> +Every bean deployed in OpenEJB has a unique deployment-id that
> +identifies it within the scope of the entire container system. The
> +server and container system refer beans at run-time using the bean's
> +deployment id.
> +
> +== Like ejb-name
> +
> +This deployment id is much like the element of the ejb-jar.xml , with
> +one very important difference. The is only required to be unique within
> +the scope of the ejb-jar.xml in the bean's jar. The deployment id is
> +required to be unique across all beans and jars in OpenEJB. This is a
> +subtle, but important, distinction.
> +
> +Remember that the EJB specification was designed so that enterprise
> +beans could be create, packaged, and sold by vendors (EJB Providers).
> +Furthermore, users should be able to buy a packaged set of beans (a jar
> +with an ejb-jar.xml in it) and deploy it into an EJB Container without
> +modification.
> +
> +== The ejb-name is not unique
> +
> +Let's consider this, what happens if two vendors each sell a package
> +(jar) that contains a bean with the PurchaseOrder? Both are completely
> +different in terms functionality and are different beans in every other
> +respect. The EJB spec says, this is fine, ejb-names only have to unique
> +within the jar and that jar's ejb-jar.xml file. It's ridiculous to
> +expect EJB Providers to call each other up and ask, "Are you already
> +using the name 'PurchaseOrder' in your jar?" Remember that the EJB
> +specification was designed so that enterprise beans could be create,
> +packaged, and sold by vendors (EJB Providers). Furthermore, users should
> +be able to buy a packaged set of beans (a jar with an ejb-jar.xml in it)
> +and deploy it into an EJB Container without modification. This is all
> +fine and dandy, but it still leaves it up to the EJB Container/Server
> +providers to settle the difference.
> +
> +== The deployment-id is unique
> +
> +OpenEJB solves this with the OpenEJB-specific deployment id. By
> +requiring that each bean deployed into OpenEJB has a unique name, we can
> +guarantee that we are always referring to the right bean at all times.
> +Furthermore, it allows you to deploy different versions of the same
> +package several times in the same container system, each time giving the
> +beans new deployment ids.
> +
> +== Using ejb-name as deployment-id anyway
> +
> +If you're lazy -- as any truly great programmer should be -- and don't
> +want to type a deployment id for each bean every time you deploy a jar,
> +you can use the -D option of the Deploy Tool. This will throw caution to
> +the wind, and automatically assign the bean's ejb-name as the value of
> +the bean's OpenEJB deployment id. This leaves up to you to guarantee
> +that bean's ejb-name will be unique across all beans and jars in the
> +container system. In other words, be very careful with the -D option!
> +
> += How is it used?
> +
> +== In the container system
> +
> +In the container system, the deployment id is used to index the bean in
> +a system-wide registry. This registry is refereed to on every call made
> +in the container system. Being able to safely hash and cache bean
> +information by id is a must. This stresses the importance of unique ids
> +for every bean deployed in OpenEJB.
> +
> +== In the Local Server
> +
> +The Local (IntraVM) Server is an integral part of the container system
> +and the two are, in many ways, inseparable. The Local Server takes care
> +of all bean to bean and client to bean invocations made inside the
> +virtual machine. For this reason, it often refered to as the IntraVM
> +Server.
> +
> +For bean to bean communications, the Local Server must create a JNDI
> +namespace (JNDI ENC) for each bean as defined by the bean's , , and
> +elements of the bean's ejb-jar.xml file. Every bean literally gets its
> +very own JNDI namespace. When a bean makes a JNDI call, the Local Server
> +intercepts this call and uses the deployment id of the calling bean to
> +retrieve that bean's private JNDI namespace from the container system's
> +index. The Local Server then carries out the lookup on that bean's
> +namespace.
> +
> +All non-bean clients share one big global namespace. Since non-bean
> +clients are not deployed and do not have a deployment descriptor like an
> +ejb-jar.xml, the Local Server is unable to taylor a namespace for each
> +non-bean client as it can for bean clients. The Local server cannot
> +identify non-bean clients as they have no deployment id. All JNDI calls
> +made by clients that the Local Server cannot identify go to the public,
> +global namespace. The public, global JNDI namespace contains all beans
> +and resources in the container system. name.
> +
> +Each bean is added to the public, global namespace using it's deployment
> +id as its JNDI lookup. For example, if a bean had a deployment-id of
> +"/my/bean/foo", a non-bean client could lookup that bean as follows.
> +
> +[source,java]
> +----
> +...
> +Object bean = initialContext.lookup("/my/bean/Foo");
> +...
> +----
> +
> +If a bean in the container system made the above JNDI call, the Local
> +Server would see the bean's identity (deployment id) hidden in the
> +Thread, go get the bean's private JNDI namespace and finish the lookup
> +on that. Since all names in bean's JNDI namespace are required start
> +with "java:comp/env", the lookup would fail and the bean would receive a
> +javax.naming.NameNotFoundException.
> +
> +In short...
> +
> +For beans: - Each bean has it's own private, personalized JNDI namespace
> +- The names in it are the same names it uses in its ejb-jar.xml - Beans
> +can only access their private namespace, period
> +
> +For non-beans (everyone else): - Non-bean clients share the public,
> +global JNDI namespace - The names in it are the deployment ids of all
> +the beans - Non-bean clients can only access the one global namespace
> +
> +== In the Remote Server
> +
> +The Remote Server has a public, global namespace just as the Local
> +Server does. The difference being that the Remote Server only serves
> +clients outside the container system and outside the virtual machine.
> +So, all clients from the perspective of the Remote Server are non-bean
> +clients. As a result, the Remote Server only has the one public, global
> +JNDI namespace. Just as in the Local Server, the names in this namespace
> +consist of the deployment ids of the beans in the container system.
> +
> +Just as before, clients can lookup beans from the Remote Server using
> +the bean's deployment id. For example, if a bean had a deployment-id of
> +"/my/bean/foo", a client could lookup that bean as follows.
> +
> +[source,java]
> +----
> +...
> +Object bean = initialContext.lookup("/my/bean/Foo");
> +...
> +----
> +
> +== In the CORBA Adapter
> +
> +The CORBA Adapter is separate than the Remote Server. It adapts the
> +OpenEJB Container System and the Local Server into OpenORB as an
> +embedded library. It provides users of OpenORB the ability to lookup and
> +execute beans (EJBs) via the RMI-IIOP protocol. All the EJBHome and
> +EJBObject interfaces of beans in OpenEJB are implemented by OpenORB as
> +CORBA stubs and ties.
> +
> +The beans are exported into OpenORB's naming service by deployment id.
> +So, just as with the Local Server and Remote Server, clients can lookup
> +beans using the bean's deployment id. OpenORB has a JNDI implementation
> +of their naming service, so lookups can be done just as before.
> +
> +[source,java]
> +----
> +...
> +String[] args = ...
> +
> +// The ORB and Object
> +org.omg.CORBA.ORB orb = null;
> +org.omg.CORBA.Object bean = null.
> +
> +// The Naming Service and Object Name
> +org.omg.CosNaming.NamingContext context = null;
> +org.omg.CosNaming.NameComponent[] name = null;
> +
> +// Get the ORB
> +orb = org.omg.CORBA.ORB.init( args, null );
> +
> +// Get the Naming Service
> +org.omg.CORBA.Object ref = null;
> +ref = orb.resolve_initial_references("NameService");
> +context = org.omg.CosNaming.NamingContextHelper.narrow( ref );
> +
> +// Get the Name as a component
> +// Note: the string is the bean's deployment id
> +name = new org.omg.CosNaming.NameComponent[ 1 ];
> +name[0] = new org.omg.CosNaming.NameComponent("/my/bean/foo","");
> +
> +// Finally, get the bean as a CORBA object
> +// Equvalent to an InitialContext.lookup("/my/bean/foo");
> +bean = context.resolve( name );
> +...
> +----
> +
> += What happens if there is a duplicate deployment ID?
> +
> +The deployment ID uniquely identifies the bean in the OpenEJB container
> +system. Therefore, no two beans can share the same deployment ID.
> +
> +If a bean attempts to use a deployment ID that is already in use by
> +another bean, the second bean and all beans in it's jar will not be
> +loaded. In addition, the system will log a warning like the following
> +one asking you to redeploy the jar and choose an different deployment ID
> +for the bean.
> +
> +[source,properties]
> +----
> +WARN : Jar C:\openejb\beans\fooEjbs.jar cannot be loaded. The Deployment ID \
> "/my/bean/foo" is already in use. Please redeploy this jar and assign a different \
> deployment ID to the bean with the ejb-name "FooBean". +----
> +
> +For example, the acmeEjbs.jar contains a bean with the ejb-name
> +"DaffyDuckBean". The disneyEjbs.jar contains contains a bean with the
> +ejb-name "DonaldDuckBean".
> +
> +We deploy the acmeEjbs.jar and give the "DaffyDuckBean" the deployment
> +ID of "/my/favorite/duck". Sometime afterwards, we deploy the
> +disneyEjbs.jar and assign the "DonaldDuckBean" the deployment ID
> +"/my/favorite/duck", having forgotten that we already gave that unique
> +ID to the "DaffyDuckBean" in the acmeEjbs.jar.
> +
> +When the container system is started, the system will begin loading all
> +the beans one jar at a time. It will first load the acmeEjbs.jar and
> +index each bean by deployment ID. But, when the system reaches the
> +disneyEjbs.jar, it will discover that it cannot index the
> +"DonaldDuckBean" using the deployment ID "/my/favorite/duck" because
> +that index is already taken.
> +
> +The system cannot load the "DonaldDuckBean" and must also ignore the
> +rest of the beans in the disneyEjbs.jar as they may need the
> +"DonaldDuckBean" bean to function properly. The disneyEjbs.jar is
> +skipped and the following warning is logged.
> +
> +[source,properties]
> +----
> +WARN : Jar C:\openejb\beans\disneyEjbs.jar cannot be loaded. The Deployment ID \
> "/my/favorite/duck" is already in use. Please redeploy this jar and assign a \
> different deployment ID to the bean with the ejb-name "DonaldDuckBean". +----
> diff --git a/docs/deployments.adoc b/docs/deployments.adoc
> new file mode 100644
> index 0000000..a6bc11c
> --- /dev/null
> +++ b/docs/deployments.adoc
> @@ -0,0 +1,153 @@
> += Deployments
> +:index-group: Configuration
> +:jbake-date: 2018-12-05
> +:jbake-type: page
> +:jbake-status: published
> +
> +
> += The 'Deployments' element in tomee.xml
> +
> +== A single jar
> +
> +To include a single jar by name, just declare a 'Deployments' element
> +with a 'jar' attribute pointing to the jar file on the file system.
> +
> +[source,xml]
> +----
> +<tomee>
> +...
> +<Deployments jar="c:\my\app\superEjbs.jar" />
> +<Deployments jar="c:\someplace\purchasing.jar" />
> +<Deployments jar="timeTrack.jar" />
> +</tomee>
> +----
> +
> +The last element in the example uses a relative path to point to the ejb
> +jar. This path will be resolved relative to the catalina.base property.
> +So, for example, of the value of catalina.base was 'c:' then TomEE
> +would look for the jar 'c:.jar'. See the [OPENEJB:Configuration] guide
> +for more details.
> +
> +== A directory of jars
> +
> +To point to a directory that contains several jar files that TomEE
> +should load, simply declare a 'Deployments' element with a 'dir'
> +attribute pointing to the directory containing the jar files.
> +
> +[source,xml]
> +----
> +<tomee>
> +...
> +
> +<Deployments dir="c:\my\app\beans\" />
> +<Deployments dir="c:\crimestopper\lib" />
> +<Deployments dir="ejbs" />
> +<Deployments dir="beans" />
> +</tomee>
> +----
> +
> +The directories listed will be searched for jars containing
> +'META-INF/ejb-jar.xml' files and will be added to the list of jars to
> +load if they do. Better said, it's completely safe to point to a
> +directory containing a mix of ejbs and regular jar files. TomEE will
> +simply skip over jars that do contain the required
> +'META-INF/ejb-jar.xml' file.
> +
> +The last Deployments element declares a 'beans' directory relative to
> +catalina.base for holding ejb jars. This declaration is simply convention
> +and not required.
> +
> +== An unpacked jar
> +
> +As of 1.0 beta1, TomEE supports unpacked ejb jars. Simply meaning that
> +you don't need to pack your ejb's into a jar file in order to use them
> +in TomEE. You still need to follow the ejb jar layout and include an
> +"META-INF/ejb-jar.xml" in the directory that contains your ejbs.
> +
> +For example, if you have a directory structure like this:
> +
> +[source,java]
> +----
> +> C:\myapp\
> +> C:\myapp\acmeEjbs\
> +> C:\myapp\acmeEjbs\META-INF\ejb-jar.xml
> +> C:\myapp\acmeEjbs\org\acme\Foo.class
> +> C:\myapp\acmeEjbs\org\acme\FooBean.class
> +> C:\myapp\acmeEjbs\org\acme\FooHome.class
> +> C:\myapp\acmeEjbs\org\acme\Bar.class
> +> C:\myapp\acmeEjbs\org\acme\BarBean.class
> +> C:\myapp\acmeEjbs\org\acme\BarHome.class
> +----
> +
> +Then you would delcare a 'Deployments' element with the 'dir' attribute
> +set to 'C:' as shown below.
> +
> +[source,xml]
> +----
> +<tomee>
> +...
> +
> +<Deployments dir="c:\myapp\acmeEjbs" />
> +</tomee>
> +----
> +
> +Note that this syntax is the same as the directory syntax above. If
> +TomEE finds a META-INF directory with an 'ejb-jar.xml' fine inside,
> +then TomEE will treat the directory as an unpacked ejb jar. Otherwise
> +TomEE will look for ejb jar files to load as detailed in the above
> +section.
> +
> +== Log file
> +
> +When trying to figure out if your ejbs were loaded, the openejb.log file
> +is an incredible asset.
> +
> +If your ejbs were loaded successfully you should see entries like the
> +following (1.x and higher only):
> +
> +[source,properties]
> +----
> +INFO : Loaded EJBs from
> +/usr/local/openejb-1.0-beta1/beans/openejb-itests-beans.jar
> +INFO : Loaded EJBs from
> +/usr/local/openejb-1.0-beta1/beans/openejb-webadmin-clienttools.jar
> +----
> +
> +If your ejbs failed to load, you will see an entry similar to the
> +following.
> +
> +[source,properties]
> +----
> +WARN : Jar not loaded. /usr/local/openejb-1.0-beta1/beans/helloworld.jar.
> +Jar failed validation. Use the validation tool for more details
> +----
> +
> +Additionally, all the successfully loaded ejbs are individually listed
> +in the log file at startup. The Deployment ID listed is the JNDI name
> +used to lookup the ejb from a client of the Local or Remote Servers. The
> +beans listed below are from our test suite.
> +
> +[source,properties]
> +----
> +DEBUG: Deployments : 19
> +DEBUG: Type Deployment ID
> +DEBUG: CMP_ENTITY client/tests/entity/cmp/RMI-over-IIOP/EJBHome
> +DEBUG: STATEFUL client/tests/stateful/EncBean
> +DEBUG: STATELESS client/tests/stateless/BeanManagedBasicStatelessHome
> +DEBUG: STATEFUL client/tests/stateful/BasicStatefulHome
> +DEBUG: STATELESS client/tests/stateless/EncBean
> +DEBUG: STATEFUL client/tests/stateful/BeanManagedTransactionTests/EJBHome
> +DEBUG: BMP_ENTITY client/tests/entity/bmp/RMI-over-IIOP/EJBHome
> +DEBUG: STATEFUL client/tests/stateful/RMI-over-IIOP/EJBHome
> +DEBUG: STATELESS client/tests/stateless/BeanManagedTransactionTests/EJBHome
> +DEBUG: BMP_ENTITY client/tests/entity/bmp/allowed_operations/EntityHome
> +DEBUG: CMP_ENTITY client/tests/entity/cmp/EncBean
> +DEBUG: STATEFUL client/tests/stateful/BeanManagedBasicStatefulHome
> +DEBUG: BMP_ENTITY client/tests/entity/bmp/BasicBmpHome
> +DEBUG: STATELESS client/tests/stateless/BasicStatelessHome
> +DEBUG: CMP_ENTITY client/tests/entity/cmp/BasicCmpHome
> +DEBUG: STATELESS client/tools/DatabaseHome
> +DEBUG: CMP_ENTITY client/tests/entity/cmp/allowed_operations/EntityHome
> +DEBUG: BMP_ENTITY client/tests/entity/bmp/EncBean
> +DEBUG: STATELESS client/tests/stateless/RMI-over-IIOP/EJBHome
> +----
> diff --git a/docs/details-on-openejb-jar.adoc b/docs/details-on-openejb-jar.adoc
> new file mode 100644
> index 0000000..cb996d3
> --- /dev/null
> +++ b/docs/details-on-openejb-jar.adoc
> @@ -0,0 +1,156 @@
> += Details on openejb-jar
> +:index-group: EJB
> +:jbake-date: 2018-12-05
> +:jbake-type: page
> +:jbake-status: published
> +
> +
> += What is an openejb-jar.xml?
> +
> +This is the file created by the Deploy Tool that maps your bean's
> +deployment descriptor (ejb-jar.xml) to actual containers and resources
> +declared in your OpenEJB configuration (openejb.conf). In fact, the
> +Deploy tool really does nothing more than create this file and put it in
> +your jar, that's it.
> +
> += When is the openejb-jar.xml used?
> +
> +At startup, any jar containing a openejb-jar.xml is loaded by the
> +container system. The configuration tools will go looking in all the
> +directories and jars you have declared in your openejb.conf with the
> +element. For every jar file it finds, it will look inside for an
> +openejb-jar.xml. If it finds one, it will attempt to load and deploy it
> +into the container system.
> +
> += Do I even need the deploy tool then?
> +
> +Nope. Typically you would only use the deploy tool to create your
> +openejb-jar.xml, then just keep your openejb-jar.xml in your CVS (or
> +other repository). If you learn how to maintain this openejb-jar.xml
> +file, you'll never need the deploy tool again! You can do all your
> +builds and deploys automatically.
> +
> += Where do I put the openejb-jar.xml in my jar?
> +
> +The openejb-jar.xml file just goes in the META-INF directory of your jar
> +next to the ejb-jar.xml file.
> +
> += Is the file format easy?
> +
> +If you can understand the ejb-jar.xml, the openejb-jar.xml should be a
> +breeze.
> +
> +This is the openejb-jar.xml that is created by the Deploy tool in the
> +Hello World example. As you can see, the file format is extremely
> +simple.
> +
> +[source,xml]
> +----
> +<?xml version="1.0"?>
> +<openejb-jar xmlns="http://www.openejb.org/openejb-jar/1.1">
> + <ejb-deployment ejb-name="Hello"
> + deployment-id="Hello"
> + container-id="Default Stateless Container"/>
> +</openejb-jar>
> +----
> +
> +The _ejb-name_ attribute is the name you gave the bean in your
> +ejb-jar.xml. The _deployment-id_ is the name you want to use to lookup
> +the bean in your client's JNDI namespace. The _container-id_ is the name
> +of the container in your openejb.conf file that you would like the bean
> +to run in. There MUST be one _ejb-deployment_ element for each EJB in
> +your jar.
> +
> +== What if my bean uses a JDBC datasource?
> +
> +Then you simply add a element to your element like this
> +
> +[source,xml]
> +----
> +<?xml version="1.0"?>
> +<openejb-jar xmlns="http://www.openejb.org/openejb-jar/1.1">
> +
> + <ejb-deployment ejb-name="Hello"
> + deployment-id="Hello"
> + container-id="Default Stateless Container" >
> +
> + <resource-link res-ref-name="jdbc/basic/entityDatabase"
> + res-id="Default JDBC Database"/>
> +
> + </ejb-deployment>
> +
> +</openejb-jar>
> +----
> +
> +The _res-ref-name_ attribute refers to the element of the bean's
> +declaration in the ejb-jar.xml. The _res-id_ attribute refers to the id
> +of the declared in your openejb.conf that will handle the connections
> +and provide access to the desired resource.
> +
> += How many resource-link elements will I need?
> +
> +You will need one element for every element in your ejb-jar.xml. So if
> +you had an ejb-jar.xml like the following
> +
> +[source,xml]
> +----
> +<?xml version="1.0"?>
> +<ejb-jar>
> + <enterprise-beans>
> + <session>
> + <ejb-name>MyExampleBean</ejb-name>
> + <home>com.widget.ExampleHome</home>
> + <remote>com.widget.ExampleObject</remote>
> + <ejb-class>com.widget.ExampleBean</ejb-class>
> + <session-type>Stateless</session-type>
> + <transaction-type>Container</transaction-type>
> +
> + <resource-ref>
> + <description>
> + This is a reference to a JDBC database.
> + </description>
> + <res-ref-name>jdbc/myFirstDatabase</res-ref-name>
> + <res-type>javax.sql.DataSource</res-type>
> + <res-auth>Container</res-auth>
> + </resource-ref>
> +
> + <resource-ref>
> + <description>
> + This is another reference to a JDBC database.
> + </description>
> + <res-ref-name>jdbc/anotherDatabase</res-ref-name>
> + <res-type>javax.sql.DataSource</res-type>
> + <res-auth>Container</res-auth>
> + </resource-ref>
> +
> + </session>
> + </enterprise-beans>
> +</ejb-jar>
> +----
> +
> +Then you would need two elements for that bean in your openejb-jar.xml
> +file as such.
> +
> +[source,xml]
> +----
> +<?xml version="1.0"?>
> +<openejb-jar xmlns="http://www.openejb.org/openejb-jar/1.1">
> +
> + <ejb-deployment ejb-name="MyExampleBean"
> + deployment-id="MyExampleBean"
> + container-id="Default Stateless Container" >
> +
> + <resource-link res-ref-name="jdbc/myFirstDatabase"
> + res-id="My Oracle JDBC Database"/>
> +
> + <resource-link res-ref-name="jdbc/anotherDatabase"
> + res-id="My PostgreSQL JDBC Database"/>
> +
> + </ejb-deployment>
> +
> +</openejb-jar>
> +----
> +
> +This would require two declarations in your openejb.conf, one with the
> +_id_ attribute set to _"My Oracle JDBC Database"_ , and another with
> +it's _id_ attribute set to _"My PostgreSQL JDBC Database"_
> diff --git a/docs/developer/.DS_Store b/docs/developer/.DS_Store
> new file mode 100644
> index 0000000..23b46d8
> Binary files /dev/null and b/docs/developer/.DS_Store differ
> diff --git a/docs/developer/classloading/index.adoc \
> b/docs/developer/classloading/index.adoc new file mode 100644
> index 0000000..46a64d5
> --- /dev/null
> +++ b/docs/developer/classloading/index.adoc
> @@ -0,0 +1,58 @@
> += The TomEE ClassLoader
> +:jbake-date: 2016-03-16
> +:jbake-type: page
> +:jbake-status: published
> +:jbake-tomeepdf:
> +
> +TomEE ClassLoading is directly mapped to Tomcat one.
> +
> +ifndef::backend-pdf[]
> +
> +[#filetree.col-md-3]
> +[
> + {
> + label: 'JVM',
> + description: 'The JVM classloader launching tomcat main(String[])',
> + children: [
> + {
> + label:'common.loader',
> + description:'Customizable in conf/catalina.properties, the common \
> loader is the Tomcat classloader', + children: [
> + {
> + label:'shared.loader',
> + description:'Optional layer where you can add libraries \
> for the web applications not seen by Tomcat. It is generally not used and not \
> encouraged since Tomcat 6', + children: [
> + {
> + label:'webapp1',
> + description:'loader of one of your wars, it \
> container WEB-INF/classes, WEB-INF/lib/*.jar' + },
> + {
> + label:'webapp2',
> + description:'loader of another one of your wars, \
> it container WEB-INF/classes, WEB-INF/lib/*.jar' + },
> + {
> + label:'application1',
> + description:'loader of another application, it can \
> be an ear, it contains lib and ejbmodules of the ear', + \
> children: [ + {
> + label:'earwebapp1',
> + description:'loader of one of the wars of \
> the ear' + },
> + {
> + label:'earwebapp2',
> + description:'loader of the other webapp of \
> the ear' + }
> + ]
> + }
> + ]
> + }
> + ]
> + }
> + ]
> + }
> +]
> +
> +[#filetreedetail.col-md-8.bs-callout.bs-callout-primary]
> +Click on the tree (JVM) on the left to see the detail there.
> +
> +endif::[]
> diff --git a/docs/developer/configuration/cxf.adoc \
> b/docs/developer/configuration/cxf.adoc new file mode 100644
> index 0000000..997fc82
> --- /dev/null
> +++ b/docs/developer/configuration/cxf.adoc
> @@ -0,0 +1,93 @@
> += CXF Configuration - JAX-RS (RESTful Services) and JAX-WS (Web Services)
> +:jbake-date: 2016-03-16
> +:jbake-type: page
> +:jbake-status: published
> +:jbake-tomeepdf:
> +
> +TomEE relies on Apache CXF for JAX-RS (RESTful Services) and JAX-WS (Web \
> Services). It does not provide all CXF modules, but the most common ones for both \
> specifications (JAX-RS is part of all distributions but JAX-WS is only part of plus \
> one). +
> +== Configuration
> +
> +CXF API is reusable but you can also configure the interceptors through \
> `openejb-jar.xml` (located in WEB-INF). +
> +If you want to configure JAX-RS you will use the prefix `cxf.jaxrs` and if you \
> configure JAX-WS you use `cxf.jaxws` prefix. +
> +TIP: to configure directly the bus use `org.apache.openejb.cxf.bus.` prefix and \
> configure it in `conf/system.properties`. +
> +To configure JAX-RS you need to add in `openejb-jar.xml` a `pojo-deployment`:
> +
> +[source,xml]
> +----
> +<?xml version="1.0" encoding="UTF-8"?>
> +<openejb-jar>
> + <pojo-deployment class-name="jaxrs-application">
> + <properties>
> + # here will go the config
> + </properties>
> + </pojo-deployment>
> +</openejb-jar>
> +----
> +
> +For JAX-WS you will use a `pojo-deployment` matching the webservice class name for \
> POJO webservices +or an `ejb-deployment` instead of a `pojo-deployment` for EJB \
> webservices: +
> +
> +[source,xml]
> +----
> +<?xml version="1.0" encoding="UTF-8"?>
> +<openejb-jar>
> + <ejb-deployment ejb-name="MyEJBWebService">
> + <properties>
> + # here will go the config
> + </properties>
> + </ejb-deployment>
> +</openejb-jar>
> +----
> +
> +Then once you selected your prefix and know where to write the config just use the \
> following entries: +
> +- properties: server factory properties
> +- features: CXF features
> +- in-interceptors: CXF in interceptors
> +- out-interceptors: CXF out interceptors
> +- in-fault-interceptors: CXF in interceptors for fault handling
> +- out-fault-interceptors: CXF out interceptors for fault handling
> +- databinding: server databinding
> +- providers (only for JAX-RS endpoint): list of JAX-RS providers
> +- skip-provider-scanning (only for JAX-RS): is provider scanning on or not \
> (default true) +
> +For features and interceptors the rule is the same: value is a list comma \
> separated. Each value of the list is either a qualified class name or an id of a \
> service in resources.xml. +
> +Databinding is simply either a qualified name or a service id in resources.xml \
> (located in WEB-INF). +
> +== Sample for JAX-WS
> +
> +To configure WSS4J on the EJB `CalculatorBean` for instance add in \
> openejb-jar.xml: +
> +[source,xml]
> +----
> +<openejb-jar xmlns="http://www.openejb.org/openejb-jar/1.1">
> + <ejb-deployment ejb-name="CalculatorBean">
> + <properties>
> + cxf.jaxws.in-interceptors = wss4j
> + </properties>
> + </ejb-deployment>
> +</openejb-jar>
> +----
> +
> +With associated resources.xml which will define precisely the `wss4j` \
> configuration: +
> +[source,xml]
> +----
> +<resources>
> + <Service id="wss4j" \
> class-name="org.apache.openejb.server.cxf.config.WSS4JInInterceptorFactory" \
> factory-name="create"> + action = UsernameToken
> + passwordType = PasswordText
> + passwordCallbackClass = org.superbiz.ws.security.PasswordCallbackHandler
> + </Service>
> +</resources>
> +----
> +
> +== Sample for JAX-RS
> +
> +link:../json/index.html[JAX-RS JSON] page shows a sample dedicated to JAX-RS.
> diff --git a/docs/developer/ide/index.adoc b/docs/developer/ide/index.adoc
> new file mode 100644
> index 0000000..c2539c4
> --- /dev/null
> +++ b/docs/developer/ide/index.adoc
> @@ -0,0 +1,23 @@
> += Integrated Development Environments (IDEs)
> +:jbake-date: 2016-03-16
> +:jbake-type: page
> +:jbake-status: published
> +:jbake-tomeepdf:
> +
> +TomEE is supported by the main IDEs in the market:
> +
> +- https://eclipse.org/downloads/[Eclipse]
> +- https://www.jetbrains.com/idea/download/[Intellij Idea]
> +- https://netbeans.org/downloads/[Netbeans]
> +
> +== Eclipse
> +
> +Eclipse is an integrated development environment used in computer programming, and \
> is the most widely used Java IDE. It contains a base workspace and an extensible \
> plug-in system for customizing the environment. \
> link:https://en.wikipedia.org/wiki/Eclipse_(software)[Wikipedia] +
> +== IntelliJ IDEA
> +
> +IntelliJ IDEA is a Java integrated development environment for developing computer \
> software. It is developed by JetBrains, and is available as an Apache 2 Licensed \
> community edition, and in a proprietary commercial edition. Both can be used for \
> commercial development. link:https://en.wikipedia.org/wiki/IntelliJ_IDEA[Wikipedia] \
> + +== Netbeans
> +
> +NetBeans is an integrated development environment for Java. NetBeans allows \
> applications to be developed from a set of modular software components called \
> modules. NetBeans runs on Microsoft Windows, macOS, Linux and Solaris. \
> link:https://en.wikipedia.org/wiki/NetBeans[Wikipedia]
> diff --git a/docs/developer/index.adoc b/docs/developer/index.adoc
> new file mode 100644
> index 0000000..65ec610
> --- /dev/null
> +++ b/docs/developer/index.adoc
> @@ -0,0 +1,7 @@
> += Developer
> +:jbake-date: 2016-03-16
> +:jbake-type: page
> +:jbake-status: published
> +:jbake-tomeepdf:
> +
> +Click link:../docs.html[here] to find documentation for developers.
> diff --git a/docs/developer/json/index.adoc b/docs/developer/json/index.adoc
> new file mode 100644
> index 0000000..4d0cbbf
> --- /dev/null
> +++ b/docs/developer/json/index.adoc
> @@ -0,0 +1,205 @@
> += TomEE and Apache Johnzon - JAX-RS JSON Provider
> +:jbake-date: 2016-03-16
> +:jbake-type: page
> +:jbake-status: published
> +:jbake-tomeepdf:
> +
> +Since TomEE 7.0, TomEE comes with Apache Johnzon.
> +It means you can use JSON-P out of the box but also Johnzon Mapper
> +which is the default JAX-RS provider for JSON.
> +
> +*IMPORTANT* - this is a breaking change with 1.x which was using jettison.
> +This last one was relying on JAXB model to generate JSON which often led
> +to unexpected JSON tree and some unexpected escaping too.
> +
> +== Getting started with Johnzon Mapper
> +
> +http://johnzon.apache.org/ will get more informations than this quick
> +getting started but here are the basics of the mapping with Johnzon.
> +
> +The mapper uses a direct java to json representation.
> +
> +For instance this java bean:
> +
> +[source,java]
> +----
> +public class MyModel {
> + private int id;
> + private String name;
> +
> + // getters/setters
> +}
> +----
> +
> +will be mapped to:
> +
> +[source,json]
> +----
> +{
> + "id": 1234,
> + "name": "Johnzon doc"
> +}
> +----
> +
> +Note that Johnzon supports several customization either directly on the \
> MapperBuilder of through annotations. +
> +=== @JohnzonIgnore
> +
> +@JohnzonIgnore is used to ignore a field. You can optionally say you ignore the \
> field until some version +if the mapper has a version:
> +
> +[source,java]
> +----
> +public class MyModel {
> + @JohnzonIgnore
> + private String name;
> +
> + // getters/setters
> +}
> +----
> +
> +Or to support name for version 3, 4, ... but ignore it for 1 and 2:
> +
> +
> +[source,java]
> +----
> +public class MyModel {
> + @JohnzonIgnore(minVersion = 3)
> + private String name;
> +
> + // getters/setters
> +}
> +----
> +
> +=== @JohnzonConverter
> +
> +Converters are used for advanced mapping between java and json.
> +
> +There are several converter types:
> +
> +1. Converter: map java to json and the opposite based on the string representation
> +2. Adapter: a converter not limited to String
> +3. ObjectConverter.Reader: to converter from json to java at low level
> +4. ObjectConverter.Writer: to converter from java to json at low level
> +4. ObjectConverter.Codec: a Reader and Writer
> +
> +The most common is to customize date format but they all take. For that simple \
> case we often use a Converter: +
> +[source,java]
> +----
> +public class LocalDateConverter implements Converter<LocalDate> {
> + @Override
> + public String toString(final LocalDate instance) {
> + return instance.toString();
> + }
> +
> + @Override
> + public LocalDate fromString(final String text) {
> + return LocalDate.parse(text);
> + }
> +}
> +----
> +
> +If you need a more advanced use case and modify the structure of the json \
> (wrapping the value for instance) +you will likely need Reader/Writer or a Codec.
> +
> +Then once your converter developed you can either register globally on the \
> MapperBuilder or simply decorate +the field you want to convert with \
> `@JohnzonConverter`: +
> +[source,java]
> +----
> +public class MyModel {
> + @JohnzonConverter(LocalDateConverter.class)
> + private LocalDate date;
> +
> + // getters/setters
> +}
> +----
> +
> +=== @JohnzonProperty
> +
> +Sometimes the json name is not java friendly (_foo or foo-bar or even 200 for \
> instance). For that cases +@JohnzonProperty allows to customize the name used:
> +
> +[source,java]
> +----
> +public class MyModel {
> + @JohnzonProperty("__date")
> + private LocalDate date;
> +
> + // getters/setters
> +}
> +----
> +
> +=== AccessMode
> +
> +On MapperBuilder you have several AccessMode available by default but you can also \
> create your own one. +
> +The default available names are:
> +
> +* field: to use fields model and ignore getters/setters
> +* method: use getters/setters (means if you have a getter but no setter you will \
> serialize the property but not read it) +* strict-method (default based on Pojo \
> convention): same as method but getters for collections are not used to write +
> +You can use these names with setAccessModeName().
> +
> +=== Your own mapper
> +
> +Since johnzon is in tomee libraries you can use it yourself (if you use \
> maven/gradle set johnzon-mapper as provided): +
> +[source,java]
> +----
> +final MySuperObject object = createObject();
> +
> +final Mapper mapper = new MapperBuilder().build();
> +mapper.writeObject(object, outputStream);
> +
> +final MySuperObject otherObject = mapper.readObject(inputStream, \
> MySuperObject.class); +----
> +
> +== Johnzon and JAX-RS
> +
> +TomEE uses by default Johnzon as JAX-RS provider for versions 7.x. If you want \
> however to customize it you need to follow this procedure: +
> +1. Create a WEB-INF/openejb-jar.xml:
> +
> +[source,xml]
> +----
> +<?xml version="1.0" encoding="UTF-8"?>
> +<openejb-jar>
> + <pojo-deployment class-name="jaxrs-application">
> + <properties>
> + # optional but requires to skip scanned providers if set to true
> + cxf.jaxrs.skip-provider-scanning = true
> + # list of providers we want
> + cxf.jaxrs.providers = \
> johnzon,org.apache.openejb.server.cxf.rs.EJBAccessExceptionMapper + </properties>
> + </pojo-deployment>
> +</openejb-jar>
> +----
> +
> +2. Create a WEB-INF/resources.xml to define johnzon service which will be use to \
> instantiate the provider +
> +[source,xml]
> +----
> +<?xml version="1.0" encoding="UTF-8"?>
> +<resources>
> + <Service id="johnzon" \
> class-name="org.apache.johnzon.jaxrs.ConfigurableJohnzonProvider"> + # 1M
> + maxSize = 1048576
> + bufferSize = 1048576
> +
> + # ordered attributes
> + attributeOrder = $order
> +
> + # Additional types to ignore
> + ignores = org.apache.cxf.jaxrs.ext.multipart.MultipartBody
> + </Service>
> +
> + <Service id="order" class-name="com.company.MyAttributeSorter" />
> +
> +</resources>
> +----
> +
> +Note: as you can see you mainly just need to define a service with the id johnzon \
> (same as in openejb-jar.xml) +and you can reference other instances using $id for \
> services and `@id` for resources.
> diff --git a/docs/developer/migration/tomee-1-to-7.adoc \
> b/docs/developer/migration/tomee-1-to-7.adoc new file mode 100644
> index 0000000..5bf7153
> --- /dev/null
> +++ b/docs/developer/migration/tomee-1-to-7.adoc
> @@ -0,0 +1,33 @@
> += Migrate from TomEE 1 to TomEE 7
> +:jbake-date: 2017-06-17
> +:jbake-type: page
> +:jbake-status: published
> +:jbake-tomeepdf:
> +
> +== Breaking changes
> +
> +- Artifact coordinates changes
> +
> +GroupId changed from `org.apache.openejb` to `org.apache.tomee`.
> +It includes maven plugins which use now `org.apache.tomee.maven` and the \
> `javaee-api`. +
> +Versions of openejb and tomee are now aligned on 7.x and you don't need to use
> +4.x and 1.x (or any variant) for openejb and tomee.
> +
> +- JAX-RS 2 specification refined the sorting of providers. It can have side \
> effects for message body +readers/writers which don't define their target mediatype \
> properly like Jackson which uses wildcard instead of +a json related mediatype. To \
> solve it register a custom provider redefining the media type. +
> +Can be as easy as:
> +
> +[source,java]
> +----
> +@Provider
> +@Consumes("application/json")
> +@Produces("application/json")
> +public class MyAppJsonProvider extends JacksonJsonProvider {
> +}
> +----
> +
> +- JPA and CDI are linked now, enabling JPA to use CDI for its components but CDI \
> can use JPA too... +to solve issues with hibernate you need to add either as system \
> property or persistence unit `tomee.jpa.factory.lazy = true`.
> diff --git a/docs/developer/testing/applicationcomposer/index.adoc \
> b/docs/developer/testing/applicationcomposer/index.adoc new file mode 100644
> index 0000000..5a49960
> --- /dev/null
> +++ b/docs/developer/testing/applicationcomposer/index.adoc
> @@ -0,0 +1,335 @@
> += ApplicationComposer: The TomEE Swiss Knife
> +:jbake-date: 2016-03-16
> +:jbake-type: page
> +:jbake-status: published
> +:jbake-tomeepdf:
> +
> +ApplicationComposer API is mainly contained in org.apache.openejb.testing package \
> (historically, today we would have called the package \
> org.apache.tomee.applicationcomposer). +
> +== Dependencies
> +
> +To start using ApplicationComposer you need to add some dependencies.
> +
> +The minimum required one is openejb-core:
> +
> +[source,xml]
> +----
> +<dependency>
> + <groupId>org.apache.tomee</groupId>
> + <artifactId>openejb-core</artifactId>
> + <version>${openejb.version></version>
> +</dependency>
> +----
> +
> +If you need JAXRS services you'll add (or replace thanks to transitivity of maven) \
> openejb-cxf-rs: +
> +[source,xml]
> +----
> +<dependency>
> + <groupId>org.apache.tomee</groupId>
> + <artifactId>openejb-cxf-rs</artifactId>
> + <version>${openejb.version></version>
> +</dependency>
> +----
> +
> +If you need JAXWS services you'll add (or replace thanks to transitivity of maven) \
> openejb-cxf: +
> +[source,xml]
> +----
> +<dependency>
> + <groupId>org.apache.tomee</groupId>
> + <artifactId>openejb-cxf</artifactId>
> + <version>${openejb.version></version>
> +</dependency>
> +----
> +
> +== ApplicationComposer Components
> +
> +=== @Module
> +An ApplicationComposer needs at minimum a module (the application you need to \
> deploy). +
> +To do so you have two cases:
> +
> +before TomEE 7.x: you can only write method(s) decorated with `@Module`
> +since TomEE 7.x: you can skip it and use `@Classes` directly on the \
> ApplicationComposer class as a shortcut for: +
> +[source,java]
> +----
> +@Module public WebApp app() { return new WebApp(); }
> +----
> +
> +The expected returned type of these methods are in org.apache.openejb.jee package:
> +
> +- Application: entry point to create an ear
> +- WebApp: a web application
> +- EjbJar: an ejb module
> +- EnterpriseBean children: a simple EJB
> +- Persistence: a persistence module with multiple units
> +- PersistenceUnit: a simple unit (automatically wrapped in a Persistence)
> +- Connector: a JCA connector module
> +- Beans: a CDI module,
> +- Class[] or Class: a set of classes scanned to discover annotations
> +
> +Note that for easiness `@Classes` was added to be able to describe a module and \
> some scanned classes. For instance the following snippet will create a web \
> application with classes C1, C2 as CDI beans and E1 as an EJB automatically: +
> +[source,java]
> +----
> +@Module
> +@Classes(cdi = true, value = { C1.class, C2.class, E1.class })
> +public WebApp app() {
> + return new WebApp();
> +}
> +----
> +
> +=== @Configuration
> +Often you need to customize a bit the container or at least create some resources \
> like test databases. To do so you can create a method returning Properties which \
> will be the container properties. +
> +Note: to simplify writing properties you can use PropertiesBuilder util class \
> which is just a fluent API to write properties. +
> +In these properties you can reuse OpenEJB/TomEE property syntax for resources.
> +
> +Here is a sample:
> +
> +[source,java]
> +----
> +@Configuration
> +public Properties configuration() {
> + return new PropertiesBuilder()
> + .p("db", "new://Resource?type=DataSource")
> + .p("db.JdbcUrld", "jdbc:hsqldb:mem:test")
> + .build();
> +}
> +----
> +
> +Since TomEE 7.x you can also put properties on ApplicationComposer class using \
> `@ContainerProperties` API: +
> +[source,java]
> +----
> +@ContainerProperties({
> + @ContainerProperties.Property(name = "db", value = \
> "new://Resource?type=DataSource"), + @ContainerProperties.Property(name = \
> "db.JdbcUrl", value = "jdbc:hsqldb:mem:test") +})
> +public class MyAppComposer() {
> + // ...
> +}
> +----
> +
> +=== @Component
> +Sometimes you need to customize a container component. The most common use case is \
> the security service to mock a little bit authorization if you don't care in your \
> test. +
> +To do so just write a method decorated with `@Component` returning the instance \
> you desire. +
> +Components in TomEE are stored in a container Map and the key needs to be a Class. \
> This one is deduced from the returned type of the `@Component` method: +
> +[source,java]
> +----
> +@Component
> +public SecurityService mockSecurity() {
> + return new MySecurityService();
> +}
> +----
> +
> +=== @Descriptors
> +You can reuse existing file descriptors using `@Descriptors`. The name is the file \
> name and the path either a classpath path or a file path: +
> +[source,java]
> +----
> +// runner if needed etc...
> +@Descriptors(@Descriptor(name = "persistence.xml", path = \
> "META-INF/persistence.xml")) +public class MyTest {
> + //...
> +}
> +----
> +
> +Note: this can be put in a `@Module` method as well.
> +
> +=== Services
> +If you want to test a JAXRS or JAXWS service you need to activate these services.
> +
> +To do so just add the needed dependency and use `@EnableServices`:
> +
> +[source,java]
> +----
> +// runner if needed etc...
> +@EnableService("jaxrs") // jaxws supported as well
> +public class MyTest {
> + //...
> +}
> +----
> +
> +=== Random port
> +Services like JAXRS and JAXWS relies on HTTP. Often it is nice to have a random \
> port to be able to deploy multiple tests/projects on the same CI platform at the \
> same time. +
> +To shortcut all the needed logic you can use `@RandomPort`. It is simply an \
> injection giving you either the port (int) or the root context (URL): +
> +[source,java]
> +----
> +// runner, services if needed etc...
> +public class MyTest {
> + @RandomPort("http")
> + private int port;
> +}
> +----
> +
> +Note: you can generate this way multiple ports. The value is the name of the \
> service it will apply on (being said http is an alias for httpejbd which is our \
> embedded http layer). +
> +=== Nice logs
> +@SimpleLog annotation allows you to have one liner logs
> +
> +=== @JaxrsProvider
> +@JaxrsProvider allows you to specify on a `@Module` method the list of JAXRS \
> provider you want to use. +
> +=== Dependencies without hacky code
> +@Jars allows you to add dependencies (scanned) to your application automatically \
> (like CDI libraries): +
> +[source,java]
> +----
> +@Module
> +@Classes(cdi = true, value = { C1.class, C2.class, E1.class })
> +@Jars("deltaspike-")
> +public WebApp app() {
> + return new WebApp();
> +}
> +----
> +
> +=== @Default
> +@Default (openejb one not CDI one) automatically adds in the application \
> target/classes as binaries and src/main/webapp as resources for maven projects. +
> +=== @CdiExtensions
> +This annotation allows you to control which extensions are activated during the \
> test. +
> +=== @AppResource
> +This annotation allows injection of few particular test resources like:
> +
> +the test AppModule (application meta)
> +the test Context (JNDI)
> +the test ApplicationComposers (underlying runner)
> +ContextProvider: allow to mock JAXRS contexts
> +
> +=== @MockInjector
> +Allows to mock EJB injections. It decorates a dedicated method returning an \
> instance (or Class) implementing FallbackPropertyInjector. +
> +=== @WebResource
> +Allow for web application to add folders containing web resources.
> +
> +
> +== How to run it?
> +=== JUnit
> +If you use JUnit you have mainly 2 solutions to run you "model" using the \
> ApplicationComposer: +
> +using ApplicationComposer runner:
> +
> +[source,java]
> +----
> +@RunWith(ApplicationComposer.class) public class MyTest { // ... }
> +----
> +
> +using ApplicationComposerRule rule:
> +public class MyTest { `@Rule` // or `@ClassRule` if you want the \
> container/application lifecycle be bound to the class and not test methods public \
> final ApplicationComposerRule rule = new ApplicationComposerRule(this); } +
> +Tip: since TomEE 7.x ApplicationComposerRule is decomposed in 2 rules if you need: \
> ContainerRule and DeployApplication. Using JUnit RuleChain you can chain them to \
> get the samebehavior as ApplicationComposerRule or better deploy multiple \
> ApplicationComposer models and controlling their deployment ordering (to mock a \
> remote service for instance). +
> +Finally just write `@Test` method using test class injections as if the test class \
> was a managed bean! +
> +=== TestNG
> +TestNG integration is quite simple today and mainly ApplicationComposerListener \
> class you can configure as a listener to get ApplicationComposer features. +
> +Finally just write TestNG `@Test` method using test class injections as if the \
> test class was a managed bean! +
> +=== Standalone
> +Since TomEE 7.x you can also use ApplicationComposers to directly run you \
> ApplicationComposer model as a standalone application: +
> ... 26295 lines suppressed ...
>
[prev in list] [next in list] [prev in thread] [next in thread]
Configure |
About |
News |
Add a list |
Sponsored by KoreLogic