You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@tomee.apache.org by David Jencks <da...@gmail.com> on 2020/02/14 06:21:39 UTC
Re: [tomee] branch tomee-7.1.x updated: Adding docs
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 <jo...@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 ...
>