http://git-wip-us.apache.org/repos/asf/tomee/blob/b93bd755/docs/callbacks.md ---------------------------------------------------------------------- diff --git a/docs/callbacks.md b/docs/callbacks.md new file mode 100644 index 0000000..d8016b1 --- /dev/null +++ b/docs/callbacks.md @@ -0,0 +1,167 @@ +index-group=Unrevised +type=page +status=published +title=Callbacks +~~~~~~ +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 + + +<a name="Callbacks-Stateless"></a> +## Stateless + + + 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(); + } + } + + +<a name="Callbacks-Stateful"></a> +## Stateful + + + 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(){ + + } + } + + +<a name="Callbacks-MessageDriven"></a> +## MessageDriven + + + 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(); + } + } + + +<a name="Callbacks-Interceptor"></a> +## Interceptor + + + 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){ + + } + }
http://git-wip-us.apache.org/repos/asf/tomee/blob/b93bd755/docs/changing-jms-implementations.md ---------------------------------------------------------------------- diff --git a/docs/changing-jms-implementations.md b/docs/changing-jms-implementations.md new file mode 100644 index 0000000..ca74f61 --- /dev/null +++ b/docs/changing-jms-implementations.md @@ -0,0 +1,136 @@ +index-group=Unrevised +type=page +status=published +title=Changing JMS Implementations +~~~~~~ +Notice: 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 [Generic Resource Adapter for JMS](http://genericjmsra.java.net/) 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` + + <?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: + + <Resource id="My Generic Adapter" type="GenericJMSRA" provider="org.superbiz:genericra"> + AdapterProperty1 PropertyValue1 + AdapterProperty2 PropertyValue2 + ... + </Resource> + +Or in properties like so: + + 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. http://git-wip-us.apache.org/repos/asf/tomee/blob/b93bd755/docs/client-server-transports.md ---------------------------------------------------------------------- diff --git a/docs/client-server-transports.md b/docs/client-server-transports.md new file mode 100644 index 0000000..d77c048 --- /dev/null +++ b/docs/client-server-transports.md @@ -0,0 +1,22 @@ +index-group=Unrevised +type=page +status=published +title=Client-Server Transports +~~~~~~ +<a name="Client-ServerTransports-Client/Servertransports"></a> +# Client/Server transports + +<table class="mdtable"> +<tr><th> jar </th><th> transport description </th></tr> +<tr><td> openejb-ejbd-3.0.jar </td><td> provides the 'ejbd' protocol. A binary protocol +traveling over a socket </td></tr> +<tr><td> openejb-http-3.0.jar </td><td> supports the ejbd protocol over http </td></tr> +<tr><td> openejb-derbynet-3.0.jar </td><td> allows for derby to accessed via it's network +driver </td></tr> +<tr><td> openejb-hsql-3.0.jar </td><td> allows for hsqldb to be accessed via it's network +driver </td></tr> +<tr><td> openejb-cxf-3.0.jar </td><td> turns on webservice ability, soap/http, via cxf </td></tr> +<tr><td> openejb-activemq-3.0.jar </td><td> supports remote jms clients via activemq </td></tr> +<tr><td> openejb-telnet-3.0.jar </td><td> allows for connecting to the server via telnet +for monitoring </td></tr> +</table> http://git-wip-us.apache.org/repos/asf/tomee/blob/b93bd755/docs/clients.md ---------------------------------------------------------------------- diff --git a/docs/clients.md b/docs/clients.md new file mode 100644 index 0000000..620c653 --- /dev/null +++ b/docs/clients.md @@ -0,0 +1,104 @@ +index-group=Unrevised +type=page +status=published +title=Clients +~~~~~~ + +<a name="Clients-LocalClient(embeddedcontainer)"></a> +### Local Client (embedded container) + + + 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"); + + +<a name="Clients-LocalClient(non-defaultrealmname)"></a> +### Local Client (non-default realm name) + +<a name="Clients-Loginconfigurationfile(conf/login.config)"></a> +### Login configuration file (conf/login.config) + + + 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=?"; + }; + + +<a name="Clients-Programcode"></a> +### Code + + + 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"); + + +<a name="Clients-RemoteClient(openejbstandalone)"></a> +### Remote Client (openejb standalone) + + + 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"); + + +<a name="Clients-RemoteClientwithHTTP(openejbstandalone)"></a> +### Remote Client with HTTP (openejb standalone) + + + 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"); + + + +<a name="Clients-RemoteClientwithHTTP(intomcat)"></a> +### Remote Client with HTTP (in TomEE) + + + 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"); + +<a name="RemoteClientUsingEjbInjection)"></a> +### Remote Client using @EJB Injection +see here: +<a href="http://tomee.apache.org/ejb-refs.html";>ejb-refs</a> http://git-wip-us.apache.org/repos/asf/tomee/blob/b93bd755/docs/cmpentitycontainer-config.md ---------------------------------------------------------------------- diff --git a/docs/cmpentitycontainer-config.md b/docs/cmpentitycontainer-config.md new file mode 100644 index 0000000..5a91989 --- /dev/null +++ b/docs/cmpentitycontainer-config.md @@ -0,0 +1,36 @@ +index-group=Unrevised +type=page +status=published +title=CmpEntityContainer Configuration +~~~~~~ + + +A CmpEntityContainer can be declared via xml in the `<tomee-home>/conf/tomee.xml` file or in a `WEB-INF/resources.xml` file using a declaration like the following. All properties in the element body are optional. + + <Container id="myCmpEntityContainer" type="CMP_ENTITY"> + cmpEngineFactory = org.apache.openejb.core.cmp.jpa.JpaCmpEngineFactory + </Container> + +Alternatively, a CmpEntityContainer can be declared via properties in the `<tomee-home>/conf/system.properties` file or via Java VirtualMachine `-D` properties. The properties can also be used when embedding TomEE via the `javax.ejb.embeddable.EJBContainer` API or `InitialContext` + + myCmpEntityContainer = new://Container?type=CMP_ENTITY + myCmpEntityContainer.cmpEngineFactory = org.apache.openejb.core.cmp.jpa.JpaCmpEngineFactory + +Properties and xml can be mixed. Properties will override the xml allowing for easy configuration change without the need for ${} style variable substitution. Properties are not case sensitive. If a property is specified that is not supported by the declared CmpEntityContainer a warning will be logged. If a CmpEntityContainer is needed by the application and one is not declared, TomEE will create one dynamically using default settings. Multiple CmpEntityContainer declarations are allowed. +# Supported Properties +<table class="mdtable"> +<tr> +<th>Property</th> +<th>Type</th> +<th>Default</th> +<th>Description</th> +</tr> +<tr> + <td>cmpEngineFactory</td> + <td>String</td> + <td>org.apache.openejb.core.cmp.jpa.JpaCmpEngineFactory</td> + <td> + +</td> +</tr> +</table> http://git-wip-us.apache.org/repos/asf/tomee/blob/b93bd755/docs/collapsed-ear.md ---------------------------------------------------------------------- diff --git a/docs/collapsed-ear.md b/docs/collapsed-ear.md new file mode 100644 index 0000000..a481a4c --- /dev/null +++ b/docs/collapsed-ear.md @@ -0,0 +1,46 @@ +index-group=Unrevised +type=page +status=published +title=Collapsed EAR +~~~~~~ +<a name="CollapsedEAR-Onearchive"></a> +# 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. + +<a name="CollapsedEAR-NotquiteJ2EE(itistrulyJava EE6)"></a> +# 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. + +<a name="CollapsedEAR-ExamplewithTomcat"></a> +# Example with Tomcat + +If you want to try to work with Servlets/JSP and OpenEJB using Tomcat, see +the [setup page](openejbx30:tomcat.html) + and the "/webapps/ejb-examples" section of the [openejb-examples.zip](downloads.html) + available on the [download page](http://tomee.apache.org/downloads.html). http://git-wip-us.apache.org/repos/asf/tomee/blob/b93bd755/docs/common-datasource-configurations.md ---------------------------------------------------------------------- diff --git a/docs/common-datasource-configurations.md b/docs/common-datasource-configurations.md new file mode 100644 index 0000000..0fa0777 --- /dev/null +++ b/docs/common-datasource-configurations.md @@ -0,0 +1,115 @@ +index-group=Unrevised +type=page +status=published +title=Common DataSource Configurations +~~~~~~ + +See the [DataSource Configuration](datasource-config.html) for details on all configuration options for DataSources. + +<a name="CommonDataSourceConfigurations-HSQLDB"></a> +## HSQLDB + +The drivers are included with OpenEJB 3.0 and HSQLDB is the default +database. + + <Resource id="HSQLDB Database" type="DataSource"> + JdbcDriver org.hsqldb.jdbcDriver + JdbcUrl jdbc:hsqldb:file:hsqldb + UserName sa + Password + </Resource> + + +<a name="CommonDataSourceConfigurations-Derby(Embedded)"></a> +## Derby (Embedded) + + + <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> + + +<a name="CommonDataSourceConfigurations-MySQL"></a> +## MySQL + + + <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> + + +<a name="CommonDataSourceConfigurations-Oracle"></a> +## Oracle + + + <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> + +<a name="CommonDataSourceConfigurations-OracleXA"></a> +## OracleXA + + + <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> + +<a name="CommonDataSourceConfigurations-PosgreSQL"></a> +## PosgreSQL + + + <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> + + +<a name="CommonDataSourceConfigurations-InstantDB"></a> +## InstantDB + + + <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 [Apache Commons DBCP configuration](http://commons.apache.org/dbcp/configuration.html). http://git-wip-us.apache.org/repos/asf/tomee/blob/b93bd755/docs/common-errors.md ---------------------------------------------------------------------- diff --git a/docs/common-errors.md b/docs/common-errors.md new file mode 100644 index 0000000..dbf992b --- /dev/null +++ b/docs/common-errors.md @@ -0,0 +1,30 @@ +index-group=Unrevised +type=page +status=published +title=Common Errors +~~~~~~ + +<a name="CommonErrors-Cannotfindcontainer"FOO"forbean"BAR""></a> +# 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"."></a> +# 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. http://git-wip-us.apache.org/repos/asf/tomee/blob/b93bd755/docs/common-persistenceprovider-properties.md ---------------------------------------------------------------------- diff --git a/docs/common-persistenceprovider-properties.md b/docs/common-persistenceprovider-properties.md new file mode 100644 index 0000000..4445c3b --- /dev/null +++ b/docs/common-persistenceprovider-properties.md @@ -0,0 +1,47 @@ +index-group=Unrevised +type=page +status=published +title=Common PersistenceProvider properties +~~~~~~ +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. + +<a name="CommonPersistenceProviderproperties-TopLink"></a> +# TopLink + + + <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> + + +<a name="CommonPersistenceProviderproperties-OpenJPA"></a> +# OpenJPA + + + <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> + + +<a name="CommonPersistenceProviderproperties-Hibernate"></a> +# Hibernate + + + <properties> + <property name="hibernate.hbm2ddl.auto" value="create-drop"/> + <property name="hibernate.transaction.manager_lookup_class" value="org.apache.openejb.hibernate.TransactionManagerLookup"/> + </properties> http://git-wip-us.apache.org/repos/asf/tomee/blob/b93bd755/docs/comparison.md ---------------------------------------------------------------------- diff --git a/docs/comparison.md b/docs/comparison.md new file mode 100644 index 0000000..4832ec5 --- /dev/null +++ b/docs/comparison.md @@ -0,0 +1,222 @@ +index-group=Unrevised +type=page +status=published +title=Comparison +~~~~~~ + +Apache OpenEJB and Apache TomEE are born from the same project and community. They differ in two major ways, only one of them technical: + + - TomEE incorporates two additional projects; Tomcat and MyFaces + - TomEE, as a name, more easily implies the breadth of technologies included + +Effectively, TomEE is a superset of OpenEJB. They share the same code and TomEE grew out of OpenEJB. + +Note: this table is for TomEE 1.x, TomEE 7 comments are under it. + +<table class="mdtable"> +<tr> +<th></th> +<th>Tomcat</th> +<th>TomEE</th> +<th>TomEE JAX-RS (~ Microprofile)</th> +<th>TomEE+</th> +<th>TomEE PluME</th> +<th>OpenEJB</th> +</tr> + +<tr> +<td>Java Servlets</td> +<td>(/)</td> +<td>(/)</td> +<td>(/)</td> +<td>(/)</td> +<td>(/)</td> +<td></td> +</tr> + +<tr> +<td>Java ServerPages (JSP)</td> +<td>(/)</td> +<td>(/)</td> +<td>(/)</td> +<td>(/)</td> +<td>(/)</td> +<td></td> +</tr> + +<tr> +<td>Java ServerFaces (JSF)</td> +<td></td> +<td>(/)</td> +<td>(/)</td> +<td>(/)</td> +<td>(/)</td> +<td></td> +</tr> + +<tr> +<td>Java Transaction API (JTA)</td> +<td></td> +<td>(/)</td> +<td>(/)</td> +<td>(/)</td> +<td>(/)</td> +<td>(/)</td> +</tr> + +<tr> +<td>Java Persistence API (JPA)</td> +<td></td> +<td>(/)</td> +<td>(/)</td> +<td>(/)</td> +<td>(/)</td> +<td>(/)</td> +</tr> + +<tr> +<td>Java Contexts and Dependency Injection (CDI)</td> +<td></td> +<td>(/)</td> +<td>(/)</td> +<td>(/)</td> +<td>(/)</td> +<td>(/)</td> +</tr> + +<tr> +<td>Java Authentication and Authorization Service (JAAS)</td> +<td></td> +<td>(/)</td> +<td>(/)</td> +<td>(/)</td> +<td>(/)</td> +<td>(/)</td> +</tr> + +<tr> +<td>Java Authorization Contract for Containers (JACC)</td> +<td></td> +<td>(/)</td> +<td>(/)</td> +<td>(/)</td> +<td>(/)</td> +<td>(/)</td> +</tr> + +<tr> +<td>JavaMail API</td> +<td></td> +<td>(/)</td> +<td>(/)</td> +<td>(/)</td> +<td>(/)</td> +<td>(/)</td> +</tr> + +<tr> +<td>Bean Validation</td> +<td></td> +<td>(/)</td> +<td>(/)</td> +<td>(/)</td> +<td>(/)</td> +<td>(/)</td> +</tr> + +<tr> +<td>Enterprise JavaBeans</td> +<td></td> +<td>(/)</td> +<td>(/)</td> +<td>(/)</td> +<td>(/)</td> +<td>(/)</td> +</tr> + +<tr> +<td>Java API for RESTful Web Services (JAX-RS)</td> +<td></td> +<td></td> +<td>(/)</td> +<td>(/)</td> +<td>(/)</td> +<td>(/)</td> +</tr> + +<tr> +<td>Java API for XML Web Services (JAX-WS)</td> +<td></td> +<td></td> +<td></td> +<td>(/)</td> +<td>(/)</td> +<td>(/)</td> +</tr> + +<tr> +<td>Java EE Connector Architecture</td> +<td></td> +<td></td> +<td></td> +<td>(/)</td> +<td>(/)</td> +<td>(/)</td> +</tr> + +<tr> +<td>Java Messaging Service (JMS)</td> +<td></td> +<td></td> +<td></td> +<td>(/)</td> +<td>(/)</td> +<td>(/)</td> +</tr> + +<tr> +<td>EclipseLink</td> +<td></td> +<td></td> +<td></td> +<td></td> +<td>(/)</td> +<td></td> +</tr> + +<tr> +<td>Mojarra</td> +<td></td> +<td></td> +<td></td> +<td></td> +<td>(/)</td> +<td></td> +</tr> + +</table> + + +TomEE 7 targets JavaEE 7 and implements these specifications (in parenthesis the distibution(s) containing it if not part of the basic packages): + +* WebSocket JSR 356 +* JSON-P JSR 353 +* Servlet 3.1 JSR 340 +* JSF 2.2 JSR 344 +* EL 3.0 JSR 341 +* JSP 2.3 JSR 245 +* JSTL 1.2 JSR 52 +* JBatch (plus) JSR 352 +* Concurrency utilities for EE JSR 236 +* CDI 1.2, DI, Interceptors 1.2, Common Annotations JSR 346 + JSR 330 + JSR 318 + JSR 250 +* Bean Validation 1.1 JSR 349 +* EJB 3.2 JSR 345 +* JavaEE Connector JSR 322 +* JPA 2.1 JSR 338 (WARNING: openjpa based distributions provide a JPA 2.0 runtime) +* JMS 2.0 JSR 343 (layer based on ActiveMQ 5 / JMS 1.1 for default distributions) +* JTA 1.2 JSR 907 +* Javamail 1.4 (NOTE: EE 7 requires 1.5) +* JAX-RS 2.0 JSR 339 +* JAX-WS 2.2 JSR 224 +* JAXB 2.2 JSR 222 +* and more inherited from TomEE 1/JavaEE 6 http://git-wip-us.apache.org/repos/asf/tomee/blob/b93bd755/docs/concepts.md ---------------------------------------------------------------------- diff --git a/docs/concepts.md b/docs/concepts.md new file mode 100644 index 0000000..370992d --- /dev/null +++ b/docs/concepts.md @@ -0,0 +1,79 @@ +index-group=Unrevised +type=page +status=published +title=Concepts +~~~~~~ +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. http://git-wip-us.apache.org/repos/asf/tomee/blob/b93bd755/docs/configuration.md ---------------------------------------------------------------------- diff --git a/docs/configuration.md b/docs/configuration.md new file mode 100644 index 0000000..ff78f5f --- /dev/null +++ b/docs/configuration.md @@ -0,0 +1,144 @@ +index-group=Unrevised +type=page +status=published +title=Configuration +~~~~~~ +<a name="Configuration-ShortOverview"></a> +# Short Overview + +<a name="Configuration-ConfigurationProperties"></a> +## 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. [Collapsed EAR](collapsed-ear.html) +** _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 + +<a name="Configuration-ConfigurationFile"></a> +## Configuration File + +Show a config file with the elements hyperlinked. + + <?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, <Deployment> +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: + + 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: + + /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: + + /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) http://git-wip-us.apache.org/repos/asf/tomee/blob/b93bd755/docs/configuring-containers-in-tests.md ---------------------------------------------------------------------- diff --git a/docs/configuring-containers-in-tests.md b/docs/configuring-containers-in-tests.md new file mode 100644 index 0000000..7bbe582 --- /dev/null +++ b/docs/configuring-containers-in-tests.md @@ -0,0 +1,27 @@ +index-group=Unrevised +type=page +status=published +title=Configuring Containers in Tests +~~~~~~ +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. + + + 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 [Containers and Resources](containers-and-resources.html) + for a full list of supported Resource types and their properties. http://git-wip-us.apache.org/repos/asf/tomee/blob/b93bd755/docs/configuring-datasources-in-tests.md ---------------------------------------------------------------------- diff --git a/docs/configuring-datasources-in-tests.md b/docs/configuring-datasources-in-tests.md new file mode 100644 index 0000000..665fac6 --- /dev/null +++ b/docs/configuring-datasources-in-tests.md @@ -0,0 +1,60 @@ +index-group=Unrevised +type=page +status=published +title=Configuring DataSources in Tests +~~~~~~ +<a name="ConfiguringDataSourcesinTests-InitialContextproperties"></a> +# InitialContext properties + +You can configure data sources from within your test case (avoiding the +need for an `openejb.xml` entirely) like so: + + + 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: + + 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"); + +This will allow an application to communicate through legacy drivers to the same JDBC provider. + +See [Embedded Configuration](embedded-configuration.html) + for further details on properties and overrides. + +See [Containers and Resources](containers-and-resources.html) + for a full list of supported Resource types and their properties. + +<a name="ConfiguringDataSourcesinTests-Noteon<jta-data-source>and<non-jta-data-source>"></a> +## 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. http://git-wip-us.apache.org/repos/asf/tomee/blob/b93bd755/docs/configuring-datasources.md ---------------------------------------------------------------------- diff --git a/docs/configuring-datasources.md b/docs/configuring-datasources.md new file mode 100644 index 0000000..cac0e56 --- /dev/null +++ b/docs/configuring-datasources.md @@ -0,0 +1,170 @@ +index-group=Unrevised +type=page +status=published +title=Configuring DataSources in tomee.xml +~~~~~~ + +<a name="ConfiguringDataSources-ConfiguringDataSourcesinopenejb.xml"></a> + + +The *<Resource>* 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 <Resource> to configure a DataSource. + +The <Resource> element is designed after @Resource annotation and has +similar attributes. + +For example, this annotation in your bean: + + @Resource(name = "myDerbyDatasource", type = javax.sql.DataSource.class) + + +Would map to a Resource declared in your openejb.xml as follows: + + <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: + + <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: + + <Resource id="myDerbyDatasource" type="DataSource" classpath="/path/to/driver.jar"> + . . . . + <Resource> + +...Or in a [Maven](http://maven.apache.org/) environment like so: + + <Resource id="myDerbyDatasource" type="DataSource" classpath="mvn:org.apache.derby:derby:10.10.1.1"> + . . . . + <Resource> + +See [Containers and Resources](containers-and-resources.html) + for a complete list of supported DataSource properties. + +See [DataSource Password Encryption](datasource-password-encryption.html) + for information on specifying non-plain-text database passwords in your openejb.xml file. + +See [Common DataSource Configurations](common-datasource-configurations.html) + for a list of the commonly used databases and their driver configurations. + +See [DataSource Configuration by Creator](datasource-configuration-by-creator.html) + 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 [Dynamic Datasource](dynamic-datasource.html) for more details. + +<a name="ConfiguringDataSources-JNDInamesforconfiguredDataSources"></a> +## JNDI names for configured DataSources + +<a name="ConfiguringDataSources-Example1"></a> +### Example 1 + + + <Resource id="Default JDBC Database" type="DataSource"> + . . . . . + </Resource> + +The global jndi name would be *java:openejb/Resource/Default JDBC Database* + +<a name="ConfiguringDataSources-Example2"></a> +### Example 2 + + + <Resource id="Derby Database" type="DataSource"> + . . . . . + </Resource> + +The global jndi name would be *java:openejb/Resource/Derby Database* + +<a name="ConfiguringDataSources-ObtainingaDataSource"></a> +## 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. + +1. Name Attribute Match - @Resource with a name attribute matching the +resource name gets that resource injected +1. Injected Name Match - variable name matching the resource name gets that +resource injected +1. 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: + + + <Resource id="myDerbyDatabase" type="DataSource"> + . . . . . + </Resource> + +There are several possible ways to refer to it, as follows. + + +*BY matching variable name to resource name* + + @Stateless + public class FooBean { + @Resource DataSource myDerbyDatabase; + } + + +*OR BY matching name* + + @Stateless + public class FooBean { + @Resource(name="myDerbyDatabase") + DataSource dataSource; + } + + +*OR BY JNDI lookup* + + @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* + + <resource-ref> + <res-ref-name>myDerbyDatabase</res-ref-name> + <res-type>javax.sql.DataSource</res-type> + </resource-ref> + +*OR* + + <resource-ref> + <res-ref-name>jdbc/myDerbyDatabase</res-ref-name> + <res-type>javax.sql.DataSource</res-type> + </resource-ref> + +*OR* + + <resource-ref> + <res-ref-name>someOtherName</res-ref-name> + <res-type>javax.sql.DataSource</res-type> + <mapped-name>myDerbyDatabase</mapped-name> + </resource-ref> http://git-wip-us.apache.org/repos/asf/tomee/blob/b93bd755/docs/configuring-durations.md ---------------------------------------------------------------------- diff --git a/docs/configuring-durations.md b/docs/configuring-durations.md new file mode 100644 index 0000000..8c93e66 --- /dev/null +++ b/docs/configuring-durations.md @@ -0,0 +1,67 @@ +index-group=Unrevised +type=page +status=published +title=Configuring Durations +~~~~~~ +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: + + + 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; http://git-wip-us.apache.org/repos/asf/tomee/blob/b93bd755/docs/configuring-javamail.md ---------------------------------------------------------------------- diff --git a/docs/configuring-javamail.md b/docs/configuring-javamail.md new file mode 100644 index 0000000..162c578 --- /dev/null +++ b/docs/configuring-javamail.md @@ -0,0 +1,41 @@ +index-group=Unrevised +type=page +status=published +title=Configuring JavaMail +~~~~~~ +<a name="ConfiguringJavaMail-DeclaringaJavaMailResource"></a> +# Declaring a JavaMail Resource + +The basics are that any properties listed in the <Resource> element are +given directly to the javamail provider via +javax.mail.Session.getDefaultInstance(Properties props). + +Here might be some example properties. + + <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 <Resource> 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: + + java ... -DSuperbizMail.mail.smtp.host=localhost + + http://git-wip-us.apache.org/repos/asf/tomee/blob/b93bd755/docs/configuring-logging-in-tests.md ---------------------------------------------------------------------- diff --git a/docs/configuring-logging-in-tests.md b/docs/configuring-logging-in-tests.md new file mode 100644 index 0000000..eb6be92 --- /dev/null +++ b/docs/configuring-logging-in-tests.md @@ -0,0 +1,118 @@ +index-group=Unrevised +type=page +status=published +title=Configuring Logging in Tests +~~~~~~ +<a name="ConfiguringLogginginTests-embedded.logging.properties"></a> +# 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. + +1. If you want to just change 5% of the logging settings, why take control +over the other 95% as well. +1. 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. + +<a name="ConfiguringLogginginTests-Overriding(recommended)"></a> +# Overriding (recommended) + +As mentioned in [Embedded Configuration](embedded-configuration.html) + 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: + + + 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. + +1. InitialContext properties +1. jndi.properties in classpath +1. system propertes +1. embedded.logging.properties in classpath + +By default there are no logging settings in 1-3, so #4 is the only source +of logging information. + +<a name="ConfiguringLogginginTests-Defaultembedded.logging.propertiescontents"></a> +# 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 + + + 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.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.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/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-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](http://svn.apache.org/repos/asf/openejb/tags/openejb-3.0-beta-1/container/openejb-core/src/main/resources/embedded.logging.properties) http://git-wip-us.apache.org/repos/asf/tomee/blob/b93bd755/docs/configuring-persistenceunits-in-tests.md ---------------------------------------------------------------------- diff --git a/docs/configuring-persistenceunits-in-tests.md b/docs/configuring-persistenceunits-in-tests.md new file mode 100644 index 0000000..ddd0d46 --- /dev/null +++ b/docs/configuring-persistenceunits-in-tests.md @@ -0,0 +1,144 @@ +index-group=Unrevised +type=page +status=published +title=Configuring PersistenceUnits in Tests +~~~~~~ +<a name="ConfiguringPersistenceUnitsinTests-Overridingthepersistence.xml"></a> +# 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. + +<a name="ConfiguringPersistenceUnitsinTests-Overridingthe<jta-data-source>and<non-jta-data-source>"></a> +## 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. + +<a name="ConfiguringPersistenceUnitsinTests-Overridingthepersistence-unit<properties>"></a> +## 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: + + <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). + + 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. + +1. InitialContext properties +1. jndi.properties from the classpath +1. System properties +1. 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: + + 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. http://git-wip-us.apache.org/repos/asf/tomee/blob/b93bd755/docs/constructor-injection.md ---------------------------------------------------------------------- diff --git a/docs/constructor-injection.md b/docs/constructor-injection.md new file mode 100644 index 0000000..c0a5b4c --- /dev/null +++ b/docs/constructor-injection.md @@ -0,0 +1,98 @@ +index-group=Unrevised +type=page +status=published +title=Constructor Injection +~~~~~~ +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. + + + @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: + + + @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 [[email protected]](mailto:[email protected]) + + +Not yet possible + + @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; + } + }
