http://git-wip-us.apache.org/repos/asf/tomee/blob/f779264f/docs/multiple-business-interface-hazzards.mdtext ---------------------------------------------------------------------- diff --git a/docs/multiple-business-interface-hazzards.mdtext b/docs/multiple-business-interface-hazzards.mdtext new file mode 100644 index 0000000..34bb395 --- /dev/null +++ b/docs/multiple-business-interface-hazzards.mdtext @@ -0,0 +1,199 @@ +Title: Multiple Business Interface Hazzards +<a name="MultipleBusinessInterfaceHazzards-UndeclaredThrowableException"></a> +# UndeclaredThrowableException + +When two java interfaces are implemented by a proxy and those two +interfaces declare the *same method* but with *different throws clauses* +some very nasty side effects happen, namely you loose the ability to throw +any checked exceptions that are not in the throws clause of both methods. + + + import junit.framework.TestCase; + + import java.lang.reflect.InvocationHandler; + import java.lang.reflect.Method; + import java.lang.reflect.UndeclaredThrowableException; + + /** + * @version $Rev$ $Date$ + */ + public class ExceptionTest extends TestCase { + + public void test() throws Exception { + ClassLoader classLoader = this.getClass().getClassLoader(); + Class[] + interfaces = new Class[]{One.class, Two.class}; + + InvocationHandler h = new TestInvocationHandler(); + + Object proxy = +java.lang.reflect.Proxy.newProxyInstance(classLoader, interfaces, h); + + One one = (One) proxy; + + try { + one.run(new CommonException()); + } catch (CommonException e) { + // this will work + } catch(UndeclaredThrowableException u) { + Throwable t = u.getCause(); + fail("Undeclared: "+t); + } catch(Throwable t){ + fail("Caught: "+t); + } + + try { + one.run(new OneException()); + } catch (OneException e) { + } catch(UndeclaredThrowableException u) { + Throwable t = u.getCause(); + fail("Undeclared: "+t); // This will always be the code that +executes + } catch(Throwable t){ + fail("Caught: "+t); + } + + Two two = (Two) proxy; + try { + two.run(new CommonException()); + } catch (TwoException e) { + } catch(UndeclaredThrowableException u) { + Throwable t = u.getCause(); + fail("Undeclared: "+t); // This will always be the code that +executes + } catch(Throwable t){ + fail("Caught: "+t); + } + + } + + public static class CommonException extends Exception { + public CommonException() { + } + } + + public static interface One { + void run(Object o) throws OneException, CommonException; + } + + public static class OneException extends Exception { + public OneException() { + } + } + + public static interface Two { + void run(Object o) throws TwoException, CommonException; + } + + public static class TwoException extends Exception { + public TwoException() { + } + } + + private static class TestInvocationHandler implements InvocationHandler +{ + public Object invoke(Object proxy, Method method, Object[] + args) throws Throwable { + throw (Throwable)args[0] +; + } + } + } + + + +<a name="MultipleBusinessInterfaceHazzards-IllegalArgumentException"></a> +# IllegalArgumentException + +This one is less of a runtime problem as doing this will cause things to +fail up front. When two java interfaces are implemented by a proxy and +those two interfaces declare the *same method* but with *different return +types* the VM proxy code will refuse to create a proxy at all. Take this +code example: + + + + import junit.framework.TestCase; + + import java.lang.reflect.InvocationHandler; + import java.lang.reflect.Method; + + /** + * @version $Rev$ $Date$ + */ + public class ReturnTest extends TestCase { + + public void test() throws Exception { + ClassLoader classLoader = this.getClass().getClassLoader(); + Class[] + interfaces = new Class[]{ReturnTest.One.class, ReturnTest.Two.class}; + + InvocationHandler h = new ReturnTest.TestInvocationHandler(); + + Object proxy = +java.lang.reflect.Proxy.newProxyInstance(classLoader, interfaces, h); + + One one = (One) proxy; + try { + Object object = one.run(new ThingOne()); + } catch (Throwable t) { + fail("Caught: " + t); + } + + Two two = (Two) proxy; + try { + Object object = two.run(new ThingTwo()); + } catch (Throwable t) { + fail("Caught: " + t); + } + + } + + public static interface One { + ThingOne run(Object o); + } + + public static class ThingOne { + } + + public static interface Two { + ThingTwo run(Object o); + } + + public static class ThingTwo { + } + + private static class TestInvocationHandler implements InvocationHandler +{ + public Object invoke(Object proxy, Method method, Object[] + args) throws Throwable { + return args[0] +; + } + } + } + + +Running this code will result in the following exception: + + + java.lang.IllegalArgumentException: methods with same signature +run(java.lang.Object) but incompatible return types: [class ReturnTest$ThingOne, class ReturnTest$ThingTwo] + at +sun.misc.ProxyGenerator.checkReturnTypes(ProxyGenerator.java:669) + at +sun.misc.ProxyGenerator.generateClassFile(ProxyGenerator.java:420) + at +sun.misc.ProxyGenerator.generateProxyClass(ProxyGenerator.java:306) + at java.lang.reflect.Proxy.getProxyClass(Proxy.java:501) + at java.lang.reflect.Proxy.newProxyInstance(Proxy.java:581) + at ReturnTest.test(ReturnTest.java:36) + at sun.reflect.NativeMethodAccessorImpl.invoke0(Native Method) + at +sun.reflect.NativeMethodAccessorImpl.invoke(NativeMethodAccessorImpl.java:39) + at +sun.reflect.DelegatingMethodAccessorImpl.invoke(DelegatingMethodAccessorImpl.java:25) + at +com.intellij.rt.execution.junit2.JUnitStarter.main(JUnitStarter.java:32) + +
http://git-wip-us.apache.org/repos/asf/tomee/blob/f779264f/docs/multipoint-considerations.mdtext ---------------------------------------------------------------------- diff --git a/docs/multipoint-considerations.mdtext b/docs/multipoint-considerations.mdtext new file mode 100644 index 0000000..4a295cc --- /dev/null +++ b/docs/multipoint-considerations.mdtext @@ -0,0 +1,26 @@ +Title: Multipoint 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. http://git-wip-us.apache.org/repos/asf/tomee/blob/f779264f/docs/multipoint-discovery.mdtext ---------------------------------------------------------------------- diff --git a/docs/multipoint-discovery.mdtext b/docs/multipoint-discovery.mdtext new file mode 100644 index 0000000..e042537 --- /dev/null +++ b/docs/multipoint-discovery.mdtext @@ -0,0 +1,71 @@ +Title: Multipoint (TCP) Discovery + +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 situation of +each server having multiple point-to-point connections which create a fully +connected graph. + +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: + + 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. + + 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. + + 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. http://git-wip-us.apache.org/repos/asf/tomee/blob/f779264f/docs/multipoint-recommendations.mdtext ---------------------------------------------------------------------- diff --git a/docs/multipoint-recommendations.mdtext b/docs/multipoint-recommendations.mdtext new file mode 100644 index 0000000..a7c2847 --- /dev/null +++ b/docs/multipoint-recommendations.mdtext @@ -0,0 +1,139 @@ +Title: Multipoint Recommendations + +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. + +# Failed scenario <small>background</small> + +As an example of a failed scenario, imagine there are three servers; +`server1`, `server2`, `server3`. They are setup only to point to the server in +front of them making a chain: + +* server1; `initialServers = server2` +* server2; `initialServers = server3` +* server3; `initialServers = *<blank>*` + +Which is essentially `server1` -> `server2` -> `server3`. This scenario could +work, but they servers would have to be started in exactly the opposite +order: + +1. `server3` starts +1. `server2` starts + 1. *static:* connect to `server3` +1. `server1` starts + 1. *static:* connect to `server2` + 1. *dynamic:* connect to `server3` + +At this point all servers would be fully connected. But the above setup is +flawed and could easily fail. The first flaw is `server3` lists nothing in +its `initialServers` list, so if it were restarted it would leave the +multipoint network and not know how to get back in. + +The second flaw is if you started them in any other order, you would also +not get a fully connected multipoint network. Say the servers were started +in "front" order: + +1. `server1` starts + 1. *static:* connect to `server2` - failed, `server2` not started. +1. `server2` starts + 1. *static:* connect to `server3` - failed, `server3` not started. +1. `server3` starts + 1. no connection attempts, initialServers list is empty. + +After startup completes, all servers will be completely isolated and +failover will not work. The described setup is weaker than it needs to be. +Listing just one server means the listed server is a potential point of +weakness. As a matter of trivia, it is interesting to point out that you +could bring a fourth server online temporarily that lists all three +servers. Once it makes the introductions and all servers learn of each +other, you could shut it down again. + +The above setup is easily fixable via better configuration. If `server3` +listed both `server1` and `server2` in its initialServers list, rather than +listing nothing at all, then all servers would fully discover each other +regardless of startup order; assuming all three servers did eventually +start. + +# Bootstrapping Three Servers or Less + +In a three sever scenario, we recommend simply having all three servers +list all three servers. + +* server1/conf/multipoint.properties + * `initialServers = server1, server2, server3` +* server2/conf/multipoint.properties + * `initialServers = server1, server2, server3` +* server3/conf/multipoint.properties + * `initialServers = server1, server2, server3` + +There's no harm to a server listing itself. It gives you one clean list to +maintain and it will work even if you decide not to start one of the three +servers. + +# Bootstrapping Four Servers or More + +In a scenario of four or more, we recommend picking at least to servers and +focus on always keeping at least one of them running. Lets refer to them +as "root" servers for simplicity sake. + +* server1/conf/multipoint.properties + * `initialServers = server2` +* server2/conf/multipoint.properties + * `initialServers = server1` + +Root `server1` would list root `server2` so they would always be linked to each +other regardless of start order or if one of them went down. `Server1` could +be shutdown and reconnect on startup to the full multipoint network through +`server2`, and vice versa. + +All other servers would simply list the root servers (`server1`, `server2`) in +their initialServers list. + +* server3/conf/multipoint.properties + * `initialServers = server1, server2` +* server4/conf/multipoint.properties + * `initialServers = server1, server2` +* serverN/conf/multipoint.properties + * `initialServers = server1, server2` + +As long as at least one root server (`server1` or `server2`) was running, you +can bring other servers on and offline at will and always have a fully +connected graph. + +Of course all servers once running and connected will have a full list of +all other servers in the network, so if at any time the "root" servers +weren't around to make initial introductions to new servers it would be no +trouble. It's possible to reconfigure new servers to point at any other +server in the network as all servers will have the full list. So these +"root" servers are no real point of failure in function, but only of +convenience. + +# Setting initialServers <small>overrides</small> + +Always remember that any property in a `conf/<server-service>.properties` +file can be overridden on the command line or via system properties. So it +is possible easily set the `initialServers` list in startup scripts. + +A bash example might look something like: + + !/bin/bash + + OPENEJB_HOME=/opt/openejb-3.1.3 + INITIAL_LIST=$(cat /some/shared/directory/our_initial_servers.txt) + + $OPENEJB_HOME/bin/openejb start -Dmultipoint.initialServers=$INITIAL_LIST + + http://git-wip-us.apache.org/repos/asf/tomee/blob/f779264f/docs/multipulse-discovery.mdtext ---------------------------------------------------------------------- diff --git a/docs/multipulse-discovery.mdtext b/docs/multipulse-discovery.mdtext new file mode 100644 index 0000000..2d279e6 --- /dev/null +++ b/docs/multipulse-discovery.mdtext @@ -0,0 +1,90 @@ +Title: MultiPulse (UDP) Discovery + +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: + + 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. + + 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: + + 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. + + 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. http://git-wip-us.apache.org/repos/asf/tomee/blob/f779264f/docs/new-in-openejb-3.0.mdtext ---------------------------------------------------------------------- diff --git a/docs/new-in-openejb-3.0.mdtext b/docs/new-in-openejb-3.0.mdtext new file mode 100644 index 0000000..7c593f7 --- /dev/null +++ b/docs/new-in-openejb-3.0.mdtext @@ -0,0 +1,175 @@ +Title: New in OpenEJB 3.0 +<a name="NewinOpenEJB3.0-EJB3.0"></a> +# EJB 3.0 + +OpenEJB 3.0 supports the EJB 3.0 specification as well as the prior EJB +2.1, EJB 2.0, and EJB 1.1. New features in EJB 3.0 include: + + - Annotations instead of xml + - No home interfaces + - Business Interfaces + - Dependency Injection + - Intercpetors + - Java Persistence API + - Service Locator (ala SessionContext.lookup) + - POJO-style beans + +EJB 2.x features since OpenEJB 1.0 also include: + - MessageDriven Beans + - Container-Managed Persistence (CMP) 2.0 + - Timers + +The two aspects of EJB that OpenEJB does not yet support are: + - Web Services (JAX-WS, JAX-RPC) + - CORBA + +JAX-WS and CORBA support will be added in future releases. Support for the +JAX-RPC API is not a planned feature. + +<a name="NewinOpenEJB3.0-ExtensionstoEJB3.0"></a> +# Extensions to EJB 3.0 + +<a name="NewinOpenEJB3.0-CMPviaJPA"></a> +## CMP via JPA + +Our CMP implementation is a thin layer over the new Java Persistence API +(JPA). This means when you deploy an old style CMP 1.1 or CMP 2.1 bean it +is internally converted and ran as a JPA bean. This makes it possible to +use both CMP and JPA in the same application without any coherence issues +that can come from using two competing persistence technologies against the +same data. Everything is ultimately JPA in the end. + +<a name="NewinOpenEJB3.0-ExtendedDependencyInjection"></a> +## Extended Dependency Injection + +Dependency Injection in EJB 3.0 via @Resource is largely limited to objects +provided by the container, such as DataSources, JMS Topics and Queues. It +is possible for you to supply your own configuration information for +injection, but standard rules allow for only data of type String, +Character, Boolean, Integer, Short, Long, Double, Float and Byte. If you +needed a URL, for example, you'd have to have it injected as a String then +convert it yourself to a URL. This is just plain silly as the conversion +of Strings to other basic data types has existed in JavaBeans long before +Enterprise JavaBeans existed. + +OpenEJB 3.0 supports injection of any data type for which you can supply a +JavaBeans PropertyEditor. We include several built-in PropertyEditors +already such as Date, InetAddress, Class, File, URL, URI, Map, List and +more. + + + import java.net.URI; + import java.io.File; + import java.util.Date; + + @Stateful + public class MyBean { + @Resource URI blog; + @Resource Date birthday; + @Resource File homeDirectory; + } + + +<a name="NewinOpenEJB3.0-TheMETA-INF/env-entries.properties"></a> +## The META-INF/env-entries.properties + +Along the lines of injection, one of the last remaining things in EJB 3 +that people need an ejb-jar.xml file for is to supply the value of +env-entries. Env Entries are the source of data for all user supplied data +injected into your bean; the afore mentioned String, Boolean, Integer, etc. + This is a very big burden as each env-entry is going to cost you 5 lines +of xml and the complication of having to figure out how to add you bean +declaration in xml as an override of an existing bean and not accidentally +as a new bean. All this can be very painful when all you want is to supply +the value of a few @Resource String fields in you bean class. + +To fix this, OpenEJB supports the idea of a META-INF/env-entries.properties +file where we will look for the value of things that need injection that +are not container controlled resources (i.e. datasources and things of that +nature). You can configure you ejbs via a properties file and skip the +need for an ejb-jar.xml and it's 5 lines per property madness. + + + blog = http://acme.org/myblog + birthday = locale=en_US style=MEDIUM Mar 1, 1954 + homeDirectory = /home/esmith/ + + +<a name="NewinOpenEJB3.0-SupportforGlassFishdescriptors"></a> +## Support for GlassFish descriptors + +Unit testing EJBs with OpenEJB is a major feature and draw for people, even +for people who may still use other app servers for final deployment such as +Geronimo or GlassFish. The descriptor format for Geronimo is natively +understood by OpenEJB as OpenEJB is the EJB Container provider for +Geronimo. However, OpenEJB also supports the GlassFish descriptors so +people using GlassFish as their final server can still use OpenEJB for +testing EJBs via plain JUnit tests in their build and only have one set of +vendor descriptors to maintain. + +<a name="NewinOpenEJB3.0-JavaEE5EARandApplicationClientsupport"></a> +## JavaEE 5 EAR and Application Client support + +JavaEE 5 EARs and Application Clients can be deployed in addition to ejb +jars. EAR support is limited to ejbs, application clients, and libraries; +WAR files and RAR files will be ignored. Per the JavaEE 5 spec, the +META-INF/application.xml and META-INF/application-client.xml files are +optional. + +<a name="NewinOpenEJB3.0-ApplicationValidationforEJB3.0"></a> +## Application Validation for EJB 3.0 + +Incorrect usage of various new aspects of EJB 3.0 are checked for and +reported during the deployment process preventing strange errors and +failures. + +As usual validation failures (non-compliant issues with your application) +are printed out in complier-style "all-at-once" output allowing you to see +and fix all your issues in one go. For example, if you have 10 +@PersistenceContext annotations that reference an invalid persistence unit, +you get all 10 errors on the *first* deploy rather than one failure on the +first deploy with 9 more failed deployments to go. + +Validation output comes in three levels. The most verbose level will tell +you in detail what you did wrong, what the options are, and what to do +next... even including valid code and annotation usage tailored to your app +that you can copy and paste into your application. Very ideal for +beginners and people using OpenEJB in a classroom setting. + +<a name="NewinOpenEJB3.0-MostconfigurableJNDInamesever"></a> +## Most configurable JNDI names ever + +<a name="NewinOpenEJB3.0-GeneralImprovements"></a> +# General Improvements + +<a name="NewinOpenEJB3.0-OnlineDeployment"></a> +## Online Deployment +<a name="NewinOpenEJB3.0-SecurityService"></a> +## Security Service +<a name="NewinOpenEJB3.0-ConnectionPooling"></a> +## Connection Pooling +<a name="NewinOpenEJB3.0-ConfigurationOverriding"></a> +## Configuration Overriding +<a name="NewinOpenEJB3.0-FlexibleJNDINameFormatting"></a> +## Flexible JNDI Name Formatting +<a name="NewinOpenEJB3.0-CleanerEmbedding"></a> +## Cleaner Embedding +<a name="NewinOpenEJB3.0-Tomcat6Support"></a> +## Tomcat 6 Support +<a name="NewinOpenEJB3.0-Businesslocalsremotable"></a> +## Business locals remotable + +If you want to make business local interfaces remotable, you can set this +property: + + openejb.remotable.businessLocals=true + +Then you can lookup your business local interfaces from remote clients. + +You'd still have to ensure that the you pass back and forth is +serializable. + + + + + http://git-wip-us.apache.org/repos/asf/tomee/blob/f779264f/docs/openejb-3.mdtext ---------------------------------------------------------------------- diff --git a/docs/openejb-3.mdtext b/docs/openejb-3.mdtext new file mode 100644 index 0000000..94dd083 --- /dev/null +++ b/docs/openejb-3.mdtext @@ -0,0 +1,68 @@ +Title: OpenEJB 3 + +<a name="OpenEJB3-Past,Present,andFuture"></a> +# Past, Present, and Future + +The goal of OpenEJB 3 is to merge our past, present, and future into one +codebase. OpenEJB 3 will take the excellent features in OpenEJB 1.0 +(tomcat integration, testability, embeddibility, ease of use, etc), move +towards an IoC architecture based on Gbean.org and Spring, bring in the +OpenEJB 2 code, and implement the EJB 3.0 specification. + +<a name="OpenEJB3-ThePlan"></a> +# The Plan + +We will start on OpenEJB 3 by taking the 1.0 code (pretty much the same as +0.9.2), merging in the 2.0 code, and ensuring that the entire time the code +we write is code you can use! We will never drop a feature, even +temporarily. We will start from code that users are now using and always +keep, maintain, and improve those features as we add new features. +Releasing early and often. + +<a name="OpenEJB3-Past"></a> +## Past + +OpenEJB 1.0 (from 0.9.2 lineage) has some great features and many people +that depend on them. Tomcat integration, Collapsed EARs, Container Driven +Testing, easy embedding, and other features make OpenEJB a unique EJB +implementation. We're going to take this code, kill all the static +old-school techniques, modernize it with and IoC architecture based on the +gbean.org kernel. The gbean kernel is an IoC kernel compatible with both +Spring and Geronimo. + +<a name="OpenEJB3-Present"></a> +## Present + +OpenEJB 2.0 is an awesome fast implementation of EJB 2.1 that runs in +Apache Geronimo. As the gbean.org kernel is both Spring and Geronimo +compatible, it provides a great way for us to take the Geronimo-compatible +EJB containers and deployers in OpenEJB 2 and start hammering them out and +releasing them to long-time OpenEJB users. It will also allow people using +OpenEJB to start experimenting with Spring's sophisticated IoC features. + +<a name="OpenEJB3-Future"></a> +## Future + +EJB 3.0 is a new direction for EJB and we're going to do it with style. A +focus on simplicity is where OpenEJB shines. Combining the EJB 3.0 +Simplified specification with our existing lightweight features, like +Container Driven Testing, is just the beginning. We plan to go way beyond +the planned additions and into areas the J2EE spec groups won't go such as +deployment descriptors with attributes, simpler packaging, more flexible +classloader setup, more powerful IoC support, simpler web services support +and more. + +<a name="OpenEJB3-ReleaseonDayOne"></a> +# Release on Day One + +Keep it working, keep it progressing, keep releasing. The 3.0 version +number won't be the finishing line, but the starting line. Our work will +start out as 3.0 on day one and keep incrementing the version number as we +get further along our feature list. The EJB 3.0 spec is not completed and +the OpenEJB 3.0 code line will be equally dynamic and best suited for +adventurous developers who enjoy reading release notes and participating on +user lists. There will be an incredible focus on keeping things stable +enough to use the entire time as we work towards feature completion. + +The effect of all this is that you get a fixed-up, far more extensible, +version of the code you are already using delivered to you right away. http://git-wip-us.apache.org/repos/asf/tomee/blob/f779264f/docs/openejb-binaries.mdtext ---------------------------------------------------------------------- diff --git a/docs/openejb-binaries.mdtext b/docs/openejb-binaries.mdtext new file mode 100644 index 0000000..0522ce7 --- /dev/null +++ b/docs/openejb-binaries.mdtext @@ -0,0 +1,24 @@ +Title: OpenEJB Binaries +Add this to your *$HOME/.m2/settings.xml* to enable publishing to the +Apache Nexus repo. This works for snapshots or staging final binaries. + + <settings> + <servers> + <server> + <id>apache.snapshots.https</id> + <username>yourapacheid</username> + <password>yourapachepass</password> + </server> + <server> + <id>apache.releases.https</id> + <username>yourapacheid</username> + <password>yourapachepass</password> + </server> + </servers> + </settings> + + +Then publish via: + + $ mvn clean deploy + http://git-wip-us.apache.org/repos/asf/tomee/blob/f779264f/docs/openejb-eclipse-plugin.mdtext ---------------------------------------------------------------------- diff --git a/docs/openejb-eclipse-plugin.mdtext b/docs/openejb-eclipse-plugin.mdtext new file mode 100644 index 0000000..68dc475 --- /dev/null +++ b/docs/openejb-eclipse-plugin.mdtext @@ -0,0 +1,19 @@ +Title: OpenEJB Eclipse Plugin +<a name="OpenEJBEclipsePlugin-OpenEJBEclipsePlugin"></a> +# OpenEJB Eclipse Plugin + +<a name="OpenEJBEclipsePlugin-Overview"></a> +### Overview + +The OpenEJB plugin for Eclipse provides the ability to run an OpenEJB +standalone server and deploy projects directly from within the IDE, using +functionality provided by the Eclipse Web Tools Project (WTP). +Additionally, the plugin also provides the capability to read a ejb-jar.xml +(and optionally a openejb-jar.xml) file and automatically add the +corresponding EJB 3 annotations to your code automatically. + +[Installation](installation.html) +[Building from source](building-from-source.html) +[Generating EJB 3 annotations](generating-ejb-3-annotations.html) +[Running a standalone OpenEJB server](running-a-standalone-openejb-server.html) + http://git-wip-us.apache.org/repos/asf/tomee/blob/f779264f/docs/openejb-jsr-107-integration.mdtext ---------------------------------------------------------------------- diff --git a/docs/openejb-jsr-107-integration.mdtext b/docs/openejb-jsr-107-integration.mdtext new file mode 100644 index 0000000..380b4a4 --- /dev/null +++ b/docs/openejb-jsr-107-integration.mdtext @@ -0,0 +1,21 @@ +Title: OpenEJB JSR-107 Integration + +<a name="OpenEJBJSR-107Integration-OpenEJBJSR-107(JCACHE)Integration"></a> +# OpenEJB JSR-107 (JCACHE) Integration + +This page is for the collaboration for those involved with the integration +of JSR-107 into OpenEJB. + +<a name="OpenEJBJSR-107Integration-Overview"></a> +### Overview + +The idea here is to add a caching layer to OpenEJB. The overall objective +is to improve performance in OpenEJB where applicable through caching EJBs. + +<a name="OpenEJBJSR-107Integration-Status"></a> +### Status + +Dain and myself (Jeremy) have deciphered the JSR-107 spec and how I am +working on the first crude integration of JCACHE into OpenEJB. Anyone +interested in helping or providing any feedback/suggestions, please contact +me via the developer mailing list. http://git-wip-us.apache.org/repos/asf/tomee/blob/f779264f/docs/openejb.xml.mdtext ---------------------------------------------------------------------- diff --git a/docs/openejb.xml.mdtext b/docs/openejb.xml.mdtext new file mode 100644 index 0000000..52a3104 --- /dev/null +++ b/docs/openejb.xml.mdtext @@ -0,0 +1,93 @@ +Title: openejb.xml + +<a name="openejb.xml-Overview"></a> +# Overview + +The openejb.xml is the main configuration file for the container system and +its services such as transaction, security, and data sources. + +The format is a mix of xml and properties inspired by the format of the +httpd configuration file. Basically: + + + <tag id=""> + ...properties... + </tag> + + +Such as: + + + <Resource id="MyDataSource" type="DataSource"> + username foo + password bar + </Resource> + + +*Note the space*. White space is a valid name/value pair separator in any +java properties file (along with semi-colon). So the above is equivalent +to: + + <Resource id="MyDataSource" type="DataSource"> + username = foo + password = bar + </Resource> + +You are free to use white space, ":", or "=" for your name/value pair +separator with no effect on OpenEJB. + +<a name="openejb.xml-PropertyDefaultsandOverriding"></a> +## Property Defaults and Overriding + +The openejb.xml file itself functions as an override, default values are +specified via other means (service-jar.xml files in the classpath), +therefore you only need to specify property values here for 2 reasons:<br/> +1. you wish to for documentation purposes<br/> +2. you need to change the default value + +The default openejb.xml file has most of the useful properties for each +component explicitly listed with default values for documentation purposes. + It is safe to delete them and be assured that no behavior will change if a +smaller config file is desired. + +Overriding can also be done via the command line or plain Java system +properties. See [System Properties](system-properties.html) + for details. + +<a name="openejb.xml-Whatpropertiesareavailable?"></a> +## What properties are available? + +To know what properties can be overriden the './bin/openejb properties' +command is very useful: see [Properties Tool](properties-tool.html) + +Its function is to connect to a running server and print a canonical list +of all properties OpenEJB can see via the various means of configuration. +When sending requests for help to the users list or jira, it is highly +encouraged to send the output of this tool with your message. + +<a name="openejb.xml-Notconfigurableviaopenejb.xml"></a> +## Not configurable via openejb.xml + +The only thing not yet configurable via this file are ServerServices due to +OpenEJB's embeddable nature and resulting long standing tradition of +keeping the container system separate from the server layer. This may +change someday, but untill then ServerServices are configurable via +conf/<service-id>.properties files such as conf/ejbd.properties to +configure the main protocol that services EJB client requests. + +The format of those properties files is greatly adapted from the xinet.d style +of configuration and even shares similar functionality and properties such +as host-based authorization (HBA) via the 'only_from' property. + +<a name="openejb.xml-Restoringopenejb.xmltothedefaults"></a> +## Restoring openejb.xml to the defaults + +To restore this file to its original default state, you can simply delete +it or rename it and OpenEJB will see it's missing and unpack another +openejb.xml into the conf/ directory when it starts. + +This is not only handy for recovering from a non-functional config, but +also for upgrading as OpenEJB will not overwrite your existing +configuration file should you choose to unpack an new distro over the top +of an old one -- this style of upgrade is safe provided you move your old +lib/ directory first. http://git-wip-us.apache.org/repos/asf/tomee/blob/f779264f/docs/openjpa.mdtext ---------------------------------------------------------------------- diff --git a/docs/openjpa.mdtext b/docs/openjpa.mdtext new file mode 100644 index 0000000..7e51d53 --- /dev/null +++ b/docs/openjpa.mdtext @@ -0,0 +1,111 @@ +Title: OpenJPA +OpenJPA is bundled with OpenEJB as the default persistence provider. + +An example of working `persistence.xml` for OpenJPA: + + <persistence xmlns="http://java.sun.com/xml/ns/persistence"; version="1.0"> + + <persistence-unit name="movie-unit"> + <jta-data-source>movieDatabase</jta-data-source> + <non-jta-data-source>movieDatabaseUnmanaged</non-jta-data-source> + <class>org.superbiz.injection.jpa.Movie</class> + + <properties> + <property name="openjpa.jdbc.SynchronizeMappings" value="buildSchema(ForeignKeys=true)"/> + </properties> + </persistence-unit> + </persistence> + + +Where the datasources above are configured in your openejb.xml as follows: + + <Resource id="movieDatabase" type="DataSource"> + JdbcDriver = org.hsqldb.jdbcDriver + JdbcUrl = jdbc:hsqldb:mem:moviedb + </Resource> + + <Resource id="movieDatabaseUnmanaged" type="DataSource"> + JdbcDriver = org.hsqldb.jdbcDriver + JdbcUrl = jdbc:hsqldb:mem:moviedb + JtaManaged = false + </Resource> + + +Or in properties as follows: + + p.put("movieDatabase", "new://Resource?type=DataSource"); + p.put("movieDatabase.JdbcDriver", "org.hsqldb.jdbcDriver"); + p.put("movieDatabase.JdbcUrl", "jdbc:hsqldb:mem:moviedb"); + + p.put("movieDatabaseUnmanaged", "new://Resource?type=DataSource"); + p.put("movieDatabaseUnmanaged.JdbcDriver", "org.hsqldb.jdbcDriver"); + p.put("movieDatabaseUnmanaged.JdbcUrl", "jdbc:hsqldb:mem:moviedb"); + p.put("movieDatabaseUnmanaged.JtaManaged", "false"); + + +# Common exceptions + +## Table not found in statement + +Or as derby will report it "Table 'abc.xyz' doesn't exist" + +Someone has to create the database structure for your persistent objects. +If you add the *openjpa.jdbc.SynchronizeMappings* property as shown below +OpenJPA will auto-create all your tables, all your primary keys and all +foreign keys exactly to match your objects. + + <persistence xmlns="http://java.sun.com/xml/ns/persistence"; version="1.0"> + + <persistence-unit name="movie-unit"> + <!-- your other stuff --> + + <properties> + <property name="openjpa.jdbc.SynchronizeMappings" value="buildSchema(ForeignKeys=true)"/> + </properties> + </persistence-unit> + </persistence> + + +<a name="OpenJPA-Auto-commitcannotbesetwhileenrolledinatransaction"></a> +## Auto-commit can not be set while enrolled in a transaction + +Pending + +<a name="OpenJPA-Thisbrokerisnotconfiguredtousemanagedtransactions."></a> +## This broker is not configured to use managed transactions. + +<a name="OpenJPA-Setup"></a> +### Setup + +Using a EXTENDED persistence context ... + + @PersistenceContext(unitName = "movie-unit", type = PersistenceContextType.EXTENDED) + EntityManager entityManager; + +on a persistence unit setup as RESOURCE_LOCAL ... + + <persistence-unit name="movie-unit" transaction-type="RESOURCE_LOCAL"> + ... + </persistence-unit> + + +inside of a transaction. + + @TransactionAttribute(TransactionAttributeType.REQUIRED) + public void addMovie(Movie movie) throws Exception { + entityManager.persist(movie); + } + + +Note the default transaction attribute for any ejb method is REQUIRED +unless explicitly set otherwise in the bean class or method in question. + +<a name="OpenJPA-Solutions"></a> +### Solutions + +You can either: + +1. Change your bean or it's method to use `TransactionAttributeType.NOT_REQUIRED` or `TransactionAttributeType.NEVER` which will guarantee it will not be invoked in a JTA transaction. +1. Change your persistence.xml so the persistence-unit uses `transaction-type="TRANSACTION"` making it capable of participating in a JTA transaction. + + http://git-wip-us.apache.org/repos/asf/tomee/blob/f779264f/docs/orb-config.mdtext ---------------------------------------------------------------------- diff --git a/docs/orb-config.mdtext b/docs/orb-config.mdtext new file mode 100644 index 0000000..0ec436f --- /dev/null +++ b/docs/orb-config.mdtext @@ -0,0 +1,24 @@ +Title: ORB Configuration + + +A ORB can be declared via xml in the `<tomee-home>/conf/tomee.xml` file or in a `WEB-INF/resources.xml` file using a declaration like the following. All properties in the element body are optional. + + <Resource id="myORB" type="org.omg.CORBA.ORB"> + </Resource> + +Alternatively, a ORB 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` + + myORB = new://Resource?type=org.omg.CORBA.ORB + +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 ORB a warning will be logged. If a ORB is needed by the application and one is not declared, TomEE will create one dynamically using default settings. Multiple ORB declarations are allowed. +# Supported Properties +<table> +<tr> +<th>Property</th> +<th>Type</th> +<th>Default</th> +<th>Description</th> +</tr> +</table> + + http://git-wip-us.apache.org/repos/asf/tomee/blob/f779264f/docs/persistence-context.mdtext ---------------------------------------------------------------------- diff --git a/docs/persistence-context.mdtext b/docs/persistence-context.mdtext new file mode 100644 index 0000000..cc14daa --- /dev/null +++ b/docs/persistence-context.mdtext @@ -0,0 +1,54 @@ +Title: persistence-context +<a name="persistence-context-Viaannotation"></a> +# Via annotation + +Both lookup and injection of an EntityManager can be configured via the +`@PersistenceContext` annotation. + + package org.superbiz; + + import javax.persistence.PersistenceContext; + import javax.persistence.EntityManager; + import javax.ejb.Stateless; + import javax.naming.InitialContext; + + @Stateless + @PersistenceContext(name = "myFooEntityManager", unitName = "foo-unit") + public class MyBean implements MyInterface { + + @PersistenceContext(unitName = "bar-unit") + private EntityManager myBarEntityManager; + + public void someBusinessMethod() throws Exception { + if (myBarEntityManager == null) throw new NullPointerException("myBarEntityManager not injected"); + + // Both can be looked up from JNDI as well + InitialContext context = new InitialContext(); + EntityManager fooEntityManager = (EntityManager) context.lookup("java:comp/env/myFooEntityManager"); + EntityManager barEntityManager = (EntityManager) context.lookup("java:comp/env/org.superbiz.MyBean/myBarEntityManager"); + } + } + + +<a name="persistence-context-Viaxml"></a> +# Via xml + +The above @PersistenceContext annotation usage is 100% equivalent to the +following xml. + + <persistence-context-ref> + <persistence-context-ref-name>myFooEntityManager</persistence-context-ref-name> + <persistence-unit-name>foo-unit</persistence-unit-name> + <persistence-context-type>Transaction</persistence-context-type> + </persistence-context-ref> + + <persistence-context-ref> + <persistence-context-ref-name>org.superbiz.calculator.MyBean/myBarEntityManager</persistence-context-ref-name> + <persistence-unit-name>bar-unit</persistence-unit-name> + <persistence-context-type>Transaction</persistence-context-type> + <injection-target> + <injection-target-class>org.superbiz.calculator.MyBean</injection-target-class> + <injection-target-name>myBarEntityManager</injection-target-name> + </injection-target> + </persistence-context-ref> + http://git-wip-us.apache.org/repos/asf/tomee/blob/f779264f/docs/persistence-unit-ref.mdtext ---------------------------------------------------------------------- diff --git a/docs/persistence-unit-ref.mdtext b/docs/persistence-unit-ref.mdtext new file mode 100644 index 0000000..4011699 --- /dev/null +++ b/docs/persistence-unit-ref.mdtext @@ -0,0 +1,87 @@ +Title: persistence-unit-ref +Both lookup and injection of an EntityManagerFactory can be configured via +the @PersistenceUnit annotation or <persistence-unit-ref> in xml. +Annotations and xml have equal function in both lookup and injection. + +<a name="persistence-unit-ref-InjectionandLookup"></a> +# Injection and Lookup + +<a name="persistence-unit-ref-Viaannotation"></a> +## Via annotation + + package org.superbiz; + + import javax.persistence.PersistenceUnit; + import javax.persistence.EntityManagerFactory; + import javax.ejb.Stateless; + import javax.naming.InitialUnit; + + @Stateless + public class MyBean implements MyInterface { + + @PersistenceUnit(unitName = "bar-unit") + private EntityManagerFactory myBarEntityManagerFactory; + + public void someBusinessMethod() throws Exception { + if (myBarEntityManagerFactory == null) throw new NullPointerException("myBarEntityManagerFactory not injected"); + + // Both can be looked up from JNDI as well + InitialContext unit = new InitialContext(); + EntityManagerFactory barEntityManagerFactory = (EntityManagerFactory) context.lookup("java:comp/env/org.superbiz.MyBean/myBarEntityManagerFactory"); + } + } + + +<a name="persistence-unit-ref-Viaxml"></a> +## Via xml + +The above @PersistenceUnit annotation usage is 100% equivalent to the +following xml. + + <persistence-unit-ref> + <persistence-unit-ref-name>org.superbiz.calculator.MyBean/myBarEntityManagerFactory</persistence-unit-ref-name> + <persistence-unit-name>bar-unit</persistence-unit-name> + <persistence-unit-type>Transaction</persistence-unit-type> + <injection-target> + <injection-target-class>org.superbiz.calculator.MyBean</injection-target-class> + <injection-target-name>myBarEntityManagerFactory</injection-target-name> + </injection-target> + </persistence-unit-ref> + + + +# Lookup only + +## Via annotation + + package org.superbiz; + + import javax.persistence.PersistenceUnit; + import javax.persistence.EntityManagerFactory; + import javax.ejb.Stateless; + import javax.naming.InitialUnit; + + @Stateless + @PersistenceUnit(name = "myFooEntityManagerFactory", unitName = "foo-unit") + public class MyBean implements MyInterface { + + public void someBusinessMethod() throws Exception { + InitialContext context = new InitialContext(); + EntityManagerFactory fooEntityManagerFactory = (EntityManagerFactory) context.lookup("java:comp/env/myFooEntityManagerFactory"); + } + } + + +<a name="persistence-unit-ref-Viaxml"></a> +# Via xml + +The above @PersistenceUnit annotation usage is 100% equivalent to the +following xml. + + <persistence-unit-ref> + <persistence-unit-ref-name>myFooEntityManagerFactory</persistence-unit-ref-name> + <persistence-unit-name>foo-unit</persistence-unit-name> + <persistence-unit-type>Transaction</persistence-unit-type> + </persistence-unit-ref> + + http://git-wip-us.apache.org/repos/asf/tomee/blob/f779264f/docs/properties-listing.mdtext ---------------------------------------------------------------------- diff --git a/docs/properties-listing.mdtext b/docs/properties-listing.mdtext new file mode 100644 index 0000000..43fe9ce --- /dev/null +++ b/docs/properties-listing.mdtext @@ -0,0 +1,90 @@ +Title: System Properties Listing + +# OpenEJB system properties +<table> +<tr><td><b>Name</b></td><td><b>Value</b></td><td><b>Description</b></td></tr> +<tr><td>openejb.embedded.remotable</td><td> bool </td><td> activate or not the remote services when available </td></tr> +<tr><td><service prefix>.bind, <service prefix>.port, <service prefix>.disabled, <service prefix>.threads</td><td> host or IP, port, bool</td><td> override the host. Available for ejbd and httpejbd services (used by jaxws and jaxrs), number of thread to maneg requests </td><tr> +<tr><td>openejb.embedded.initialcontext.close </td><td> LOGOUT or DESTROY </td><td> 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.</td></tr> +<tr><td>javax.persistence.provider </td><td> string </td><td> override the JPA provider value</td></tr> +<tr><td>javax.persistence.transactionType </td><td> string </td><td> override the transaction type for persistence contexts</td></tr> +<tr><td>javax.persistence.jtaDataSource </td><td> string </td><td> override the JTA datasource value for persistence contexts</td></tr> +<tr><td>javax.persistence.nonJtaDataSource </td><td> string </td><td> override the non JTA datasource value for persistence contexts</td></tr> +<tr><td>openejb.descriptors.output </td><td>bool</td><td> 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.</td></tr> +<tr><td>openejb.deployments.classpath.require.descriptor </td><td> CLIENT or EJB </td><td> can allow to filter what you want to scan (client modules or ejb modules)</td></tr> +<tr><td>openejb.descriptors.output.folder </td><td> path </td><td> where to dump deployement descriptors if activated. </td></tr> +<tr><td>openejb.strict.interface.declaration </td><td> bool </td><td> add some validations on session beans (spec validations in particular). false by default.</td></tr> +<tr><td>openejb.conf.file or openejb.configuration </td><td> string </td><td> OpenEJB configuration file path</td></tr> +<tr><td>openejb.debuggable-vm-hackery </td><td> bool </td><td> remove JMS informations from deployment</td></tr> +<tr><td>openejb.validation.skip </td><td> bool </td><td> skip the validations done when OpenEJB deploys beans</td></tr> +<tr><td>openejb.deployments.classpath.ear </td><td> bool </td><td> deploy the classpath as an ear</td></tr> +<tr><td>openejb.webservices.enabled </td><td> bool </td><td> activate or not webservices</td></tr> +<tr><td>openejb.validation.output.level </td><td> TERSE or MEDIUM or VERBOSE </td><td> level of the logs used to report validation errors</td></tr> +<tr><td>openejb.user.mbeans.list </td><td> * or a list of classes separated by , </td><td> list of mbeans to deploy automatically</td></tr> +<tr><td>openejb.deploymentId.format </td><td> composition (+string) of {ejbName} {ejbType} {ejbClass} and {ejbClass.simpleName} </td><td> default {ejbName}. The format to use to deploy ejbs.</td></tr> +<tr><td>openejb.deployments.classpath </td><td> bool </td><td> whether or not deploy from classpath</td></tr> +<tr><td>openejb.deployments.classpath.include and openejb.deployments.classpath.exclude </td><td> regex </td><td> regex to filter the scanned classpath (when you are in this case)</td></tr> +<tr><td>openejb.deployments.package.include and openejb.deployments.package.exclude </td><td> regex </td><td> regex to filter scanned packages</td></tr> +<tr><td>openejb.autocreate.jta-datasource-from-non-jta-one </td><td> bool </td><td> 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.</td></tr> +<tr><td>openejb.altdd.prefix </td><td> string </td><td> prefix use for altDD (example test to use a test.ejb-jar.xml).</td></tr> +<tr><td>org.apache.openejb.default.system.interceptors </td><td> list of interceptor (qualified names) separated by a comma or a space </td><td> add these interceptor on all beans</td></tr> +<tr><td>openejb.jndiname.strategy.class </td><td> class name </td><td> an implementation of org.apache.openejb.assembler.classic.JndiBuilder.JndiNameStrategy</td></tr> +<tr><td>openejb.jndiname.failoncollision </td><td> bool </td><td> if a NameAlreadyBoundException is thrown or not when 2 EJBs have the same name</td></tr> +<tr><td>openejb.jndiname.format </td><td> composition (+string) 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 </td><td> default {deploymentId}{interfaceType.annotationName}. Change the name used for the ejb.</td></tr> +<tr><td>openejb.org.quartz.threadPool.class </td><td> class qualified name which implements org.quartz.spi.ThreadPool </td><td> the thread pool used by quartz (used to manage ejb timers)</td></tr> +<tr><td>openejb.localcopy </td><td> bool </td><td> default true. whether or not copy EJB arguments[/method/interface] for remote invocations.</td></tr> +<tr><td>openejb.cxf.jax-rs.providers </td><td> 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.</td><td></td></tr> +<tr><td>openejb.wsAddress.format </td><td> composition (+string) of {ejbJarId}, ejbDeploymentId, ejbType, ejbClass, ejbClass.simpleName, ejbName, portComponentName, wsdlPort, wsdlService </td><td> default /{ejbDeploymentId}. The WS name format.</td></tr> +<tr><td>org.apache.openejb.server.webservices.saaj.provider </td><td> axis2, sun or null </td><td> specified the saaj configuration</td></tr> +<tr><td>[<uppercase service name>.]<service id>.<name> or [<uppercase service name>.]<service id></td><td> whatever is supported (generally string, int ...) </td><td> set this value to the corresponding service. example: [EnterpriseBean.]<ejb-name>.activation.<property>, [PERSISTENCEUNIT.]<persistence unit name>.<property>, [RESOURCE.]<name></td></tr> +<tr><td> log4j.category.OpenEJB.options </td><td> DEBUG, INFO, ... </td><td> active one OpenEJB log level. need log4j in the classpath</td></tr> +<tr><td> openejb.jmx.active </td><td> bool </td><td> activate (by default) or not the OpenEJB JMX MBeans </td></tr> +<tr><td> openejb.nobanner </td><td> bool </td><td> activate or not the OpenEJB banner (activated by default) +<tr><td> openejb.check.classloader </td><td> bool </td><td> if true print some information about duplicated classes </td><tr> +<tr><td> openejb.check.classloader.verbose </td><td> bool </td><td> if true print classes intersections </td><tr> +<tr><td> openejb.additional.exclude </td><td> string separated by comma </td><td> list of prefixes you want to exclude and are not in the default list of exclusion</td></tr> +<tr><td> openejb.additional.include </td><td> string separated by comma </td><td> list of prefixes you want to remove from thedefault list of exclusion</td></tr> +<tr><td> openejb.offline </td><td> bool </td><td> if true can create datasources and containers automatically </td></tr> +<tr><td> openejb.exclude-include.order </td><td> include-exclude or exclude-include </td><td> if the inclusion/exclusion should win on conflicts (intersection) </td><tr> +<tr><td>openejb.log.color</td><td> bool </td><td> activate or not the color in the console in embedded mode </td></tr> +<tr><td>openejb.log.color.<level in lowercase></td><td> color in uppercase </td><td> set a color +for a particular level. Color are BLACK, RED, GREEN, YELLOW, BLUE, MAGENTA, CYAN, WHITE, DEFAULT. </td></tr> +<tr><td>tomee.serialization.class.blacklist</td><td> string </td><td> default list of packages/classnames excluded for EJBd deserialization (needs to be set on server and client sides). Please see the description of <a href="http://tomee.apache.org/ejbd-transport.html";>Ejbd Transport</a> for details.</td></tr> +<tr><td>tomee.serialization.class.whitelist</td><td> string </td><td> 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 <a href="http://tomee.apache.org/ejbd-transport.html";>Ejbd Transport</a> for details.</td></tr> +<tr><td>tomee.remote.support</td><td> boolean </td><td> 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)</td></tr> +</table> + +Note: all resources can be configured by properties, see http://tomee.apache.org/embedded-configuration.html and http://tomee.apache.org/properties-tool.html + + +# OpenEJB client +<table> +<tr><td><b>Name</b></td><td><b>Value</b></td><td><b>Description</b></td></tr> +<tr><td>openejb.client.identityResolver </td><td> implementation of org.apache.openejb.client.IdentityResolver </td><td> default org.apache.openejb.client.JaasIdentityResolver. The class to get the client identity.</td></tr> +<tr><td>openejb.client.connection.pool.timeout or openejb.client.connectionpool.timeout </td><td> int (ms) </td><td> the timeout of the client</td></tr> +<tr><td>openejb.client.connection.pool.size or openejb.client.connectionpool.size </td><td> int </td><td> size of the socket pool</td></tr> +<tr><td>openejb.client.keepalive </td><td> int (ms) </td><td> the keepalive duration</td><tr> +<tr><td>openejb.client.protocol.version </td><td> string </td><td> 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</td><tr> +</table> + +# TomEE specific system properties +<table> +<tr><td><b>Name</b></td><td><b>Value</b></td><td><b>Description</b></td></tr> +<tr><td>openejb.crosscontext </td><td> bool </td><td> 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)</td></tr> +<tr><td>openejb.jsessionid-support </td><td> bool </td><td> remove URL from session tracking modes for this context (see javax.servlet.SessionTrackingMode)</td></tr> +<tr><td>openejb.myfaces.disable-default-values </td><td> bool </td><td> by default TomEE will initialize myfaces with some its default values to avoid useless logging</td></tr> +<tr><td>openejb.web.xml.major </td><td> int </td><td> 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</td></tr> +<tr><td>tomee.jaxws.subcontext </td><td> string </td><td> sub context used to bind jaxws web services, default is webservices</td></tr> +<tr><td>openejb.servicemanager.enabled</td><td> bool </td><td> run all services detected or only known available services (WS and RS</td></tr> +<tr><td>tomee.jaxws.oldsubcontext</td><td> bool </td><td> wether or not activate old way to bind jaxws webservices directly on root context</td><tr> +<tr><td>openejb.modulename.useHash</td><td> bool </td><td> 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.</td><tr> +<tr><td>openejb.session.manager</td><td> qualified name (string) </td><td> configure a session managaer to use for all contexts</td><tr> +</table> + +# TomEE Arquillian adaptor +<table> +<tr><td><b>Name</b></td><td><b>Value</b></td><td><b>Description</b></td></tr> +<tr><td>tomee.ejbcontainer.http.port </td><td> int </td><td> tomee port, -1 means random. When using a random port you can retreive it getting this property too.</td></tr> +<tr><td>tomee.arquillian.http </td><td> int </td><td> http port used by the embedded arquillian adaptor</td></tr> +<tr><td>tomee.arquillian.stop </td><td> int </td><td> shutdown port used by the embedded arquillian adaptor</td><tr> +</table> http://git-wip-us.apache.org/repos/asf/tomee/blob/f779264f/docs/properties-tool.mdtext ---------------------------------------------------------------------- diff --git a/docs/properties-tool.mdtext b/docs/properties-tool.mdtext new file mode 100644 index 0000000..6882d68 --- /dev/null +++ b/docs/properties-tool.mdtext @@ -0,0 +1,212 @@ +Title: Properties Tool +<a name="PropertiesTool-PropertiesCommandlineTool"></a> +# Properties Command line Tool + +To see all configurable properties in use by OpenEJB, using the following +tool against a running server: + +> ./bin/openejb properties + +The output of this tool takes all overrideable components OpenEJB sees and +outputs their properties along with the current value. This allows you to +easily see what is running in your system, what properties are available +for overriding, and what exact values are for each component. OpenEJB has +a number of flags that can be passed to it not associated with any +particular component, these are output as well. + +Content from this file can be safely copied as-is into the +conf/system.properties file or sent to the users list with bug reports. +These properties may also be applied back into the openejb.xml file by +pasting the properties without the "<id>." prefix into the respective +component declarations. The only warning is that any properties of type +"<id>.password" will have their values masked, so make sure you edit them +if you reapply them back into conf/openejb.xml or conf/system.properties. + +<a name="PropertiesTool-PropertyOverriding"></a> +# Property Overriding + +Any component configured in OpenEJB via the openejb.xml (and some that +aren't) can be overridden using system properties. The format is: + +`<id>.<property-name>=<property-value>` + +And this can be done on the command line as follows: + +`./bin/openejb -D<id>.<property-name>=<property-value> ...` + +Or by adding the property to the conf/system.properties file. Note that +command line overrides win over overrides in the +conf/system.properties file. + +In an embedded environment, the properties can be added to the Hashtable +passed into the javax.naming.InitialContext when using the +LocalInitialContextFactory or also to the System.getProperties() object +before OpenEJB is embedded (which will be when the first InitialContext is +created). + +At startup, OpenEJB will find the component with the given id and apply the +new property value before constructing the individual component. + +<a name="PropertiesTool-Exampleoutput"></a> +# Example output + + # Container(id=Default CMP Container) + # className: org.apache.openejb.core.cmp.CmpContainer + # + Default\ CMP\ Container.CmpEngineFactory=org.apache.openejb.core.cmp.jpa.JpaCmpEngineFactory + Default\ CMP\ Container.Engine=instantdb + Default\ CMP\ Container.ConnectorName=Default JDBC Database + + # Container(id=Default BMP Container) + # className: org.apache.openejb.core.entity.EntityContainer + # + Default\ BMP\ Container.PoolSize=10 + + # Container(id=Default Stateful Container) + # className: org.apache.openejb.core.stateful.StatefulContainer + # + Default\ Stateful\ Container.BulkPassivate=50 + Default\ Stateful\ Container.Passivator=org.apache.openejb.core.stateful.SimplePassivater + Default\ Stateful\ Container.TimeOut=20 + Default\ Stateful\ Container.PoolSize=500 + + # Container(id=Default Stateless Container) + # className: org.apache.openejb.core.stateless.StatelessContainer + # + Default\ Stateless\ Container.PoolSize=10 + Default\ Stateless\ Container.StrictPooling=true + Default\ Stateless\ Container.TimeOut=0 + + # Container(id=Default MDB Container) + # className: org.apache.openejb.core.mdb.MdbContainer + # + Default\ MDB\ Container.ResourceAdapter=Default JMS Resource Adapter + Default\ MDB\ Container.InstanceLimit=10 + Default\ MDB\ Container.MessageListenerInterface=javax.jms.MessageListener + Default\ MDB\ Container.ActivationSpecClass=org.apache.activemq.ra.ActiveMQActivationSpec + + # ConnectionManager(id=Default Local TX ConnectionManager) + # className: org.apache.openejb.resource.SharedLocalConnectionManager + # + + # Resource(id=Default JMS Resource Adapter) + # className: org.apache.activemq.ra.ActiveMQResourceAdapter + # + Default\ JMS\ Resource\ Adapter.ServerUrl=vm\://localhost?async\=true + Default\ JMS\ Resource\ Adapter.BrokerXmlConfig=broker\:(tcp\://localhost\:61616) + Default\ JMS\ Resource\ Adapter.ThreadPoolSize=30 + + # Resource(id=Default JDBC Database) + # className: org.apache.openejb.resource.jdbc.BasicManagedDataSource + # + Default\ JDBC\ Database.MinIdle=0 + Default\ JDBC\ Database.Password=xxxx + Default\ JDBC\ Database.JdbcUrl=jdbc\:hsqldb\:file\:hsqldb + Default\ JDBC\ Database.MaxIdle=20 + Default\ JDBC\ Database.ConnectionProperties= + Default\ JDBC\ Database.MaxWait=-1 + Default\ JDBC\ Database.TimeBetweenEvictionRunsMillis=-1 + Default\ JDBC\ Database.MaxActive=20 + Default\ JDBC\ Database.DefaultAutoCommit=true + Default\ JDBC\ Database.AccessToUnderlyingConnectionAllowed=false + Default\ JDBC\ Database.JdbcDriver=org.hsqldb.jdbcDriver + Default\ JDBC\ Database.TestWhileIdle=false + Default\ JDBC\ Database.UserName=sa + Default\ JDBC\ Database.MaxOpenPreparedStatements=0 + Default\ JDBC\ Database.TestOnBorrow=true + Default\ JDBC\ Database.PoolPreparedStatements=false + Default\ JDBC\ Database.ConnectionInterface=javax.sql.DataSource + Default\ JDBC\ Database.TestOnReturn=false + Default\ JDBC\ Database.MinEvictableIdleTimeMillis=1800000 + Default\ JDBC\ Database.NumTestsPerEvictionRun=3 + Default\ JDBC\ Database.InitialSize=0 + + # Resource(id=Default Unmanaged JDBC Database) + # className: org.apache.openejb.resource.jdbc.BasicDataSource + # + Default\ Unmanaged\ JDBC\ Database.MaxWait=-1 + Default\ Unmanaged\ JDBC\ Database.InitialSize=0 + Default\ Unmanaged\ JDBC\ Database.DefaultAutoCommit=true + Default\ Unmanaged\ JDBC\ Database.ConnectionProperties= + Default\ Unmanaged\ JDBC\ Database.MaxActive=10 + Default\ Unmanaged\ JDBC\ Database.TestOnBorrow=true + Default\ Unmanaged\ JDBC\ Database.JdbcUrl=jdbc\:hsqldb\:file\:hsqldb + Default\ Unmanaged\ JDBC\ Database.TestOnReturn=false + Default\ Unmanaged\ JDBC\ Database.AccessToUnderlyingConnectionAllowed=false + Default\ Unmanaged\ JDBC\ Database.Password=xxxx + Default\ Unmanaged\ JDBC\ Database.MinEvictableIdleTimeMillis=1800000 + Default\ Unmanaged\ JDBC\ Database.PoolPreparedStatements=false + Default\ Unmanaged\ JDBC\ Database.MaxOpenPreparedStatements=0 + Default\ Unmanaged\ JDBC\ Database.ConnectionInterface=javax.sql.DataSource + Default\ Unmanaged\ JDBC\ Database.MinIdle=0 + Default\ Unmanaged\ JDBC\ Database.NumTestsPerEvictionRun=3 + Default\ Unmanaged\ JDBC\ Database.TimeBetweenEvictionRunsMillis=-1 + Default\ Unmanaged\ JDBC\ Database.JdbcDriver=org.hsqldb.jdbcDriver + Default\ Unmanaged\ JDBC\ Database.UserName=sa + Default\ Unmanaged\ JDBC\ Database.MaxIdle=10 + Default\ Unmanaged\ JDBC\ Database.TestWhileIdle=false + + # Resource(id=Default JMS Connection Factory) + # className: org.apache.activemq.ra.ActiveMQManagedConnectionFactory + # + Default\ JMS\ Connection\ Factory.ConnectionInterface=javax.jms.ConnectionFactory, \ + javax.jms.QueueConnectionFactory, javax.jms.TopicConnectionFactory + Default\ JMS\ Connection\ Factory.ResourceAdapter=Default JMS Resource Adapter + + # SecurityService(id=Default Security Service) + # className: org.apache.openejb.core.security.SecurityServiceImpl + # + + # TransactionManager(id=Default Transaction Manager) + # className: org.apache.geronimo.transaction.manager.GeronimoTransactionManager + # + + # ServerService(id=httpejbd) + # className: org.apache.openejb.server.httpd.HttpEjbServer + # + httpejbd.port=4204 + httpejbd.name=httpejbd + httpejbd.disabled=false + httpejbd.server=org.apache.openejb.server.httpd.HttpEjbServer + httpejbd.threads=200 + httpejbd.bind=127.0.0.1 + + # ServerService(id=telnet) + # className: org.apache.openejb.server.telnet.TelnetServer + # + telnet.port=4202 + telnet.name=telnet + telnet.disabled=false + telnet.bind=127.0.0.1 + telnet.threads=5 + telnet.server=org.apache.openejb.server.telnet.TelnetServer + + # ServerService(id=ejbd) + # className: org.apache.openejb.server.ejbd.EjbServer + # + ejbd.disabled=false + ejbd.bind=127.0.0.1 + ejbd.server=org.apache.openejb.server.ejbd.EjbServer + ejbd.port=4201 + ejbd.name=ejbd + ejbd.threads=200 + + # ServerService(id=hsql) + # className: org.apache.openejb.server.hsql.HsqlService + # + hsql.port=9001 + hsql.name=hsql + hsql.disabled=false + hsql.server=org.apache.openejb.server.hsql.HsqlService + hsql.bind=127.0.0.1 + + # ServerService(id=admin) + # className: org.apache.openejb.server.admin.AdminDaemon + # + admin.disabled=false + admin.bind=127.0.0.1 + admin.only_from=localhost + admin.port=4200 + admin.threads=1 + admin.name=admin + admin.server=org.apache.openejb.server.admin.AdminDaemon http://git-wip-us.apache.org/repos/asf/tomee/blob/f779264f/docs/property-overriding.mdtext ---------------------------------------------------------------------- diff --git a/docs/property-overriding.mdtext b/docs/property-overriding.mdtext new file mode 100644 index 0000000..ddddb64 --- /dev/null +++ b/docs/property-overriding.mdtext @@ -0,0 +1,62 @@ +Title: Property Overriding +OpenEJB consists of several components (containers, resource adapters, +security services, etc.) all of which are pluggable and have their own +unique set of configurable properties. These components are required to +specify their default property values in their service-jar.xml file. This +means that at a minimum you as a user only need to specify what you'd like +to be different. You specify the property name and the new value and the +default value will be overwritten before the component is created. + +We call this overriding and there are several ways to do it. + +<a name="PropertyOverriding-Theopenejb.xml"></a> +# The openejb.xml + +The default openejb.xml file has most of the useful properties for each +component explicitly listed with default values for documentation purposes. + It is safe to delete them and be assured that no behavior will change if a +smaller config file is desired. + + +Overriding can also be done via the command line or plain Java system +properties. See [System Properties](system-properties.html) + for details. + +<a name="PropertyOverriding-Whatpropertiesareavailable?"></a> +## What properties are available? + +To know what properties can be overriden the './bin/openejb properties' +command is very useful: see [Properties Tool](properties-tool.html) + +It's function is to connect to a running server and print a canonical list +of all properties OpenEJB can see via the various means of configuration. +When sending requests for help to the users list or jira, it is highly +encouraged to send the output of this tool with your message. + +<a name="PropertyOverriding-Notconfigurableviaopenejb.xml"></a> +## Not configurable via openejb.xml + +The only thing not yet configurable via this file are ServerServices due to +OpenEJB's embeddable nature and resulting long standing tradition of +keeping the container system separate from the server layer. This may +change someday, but untill then ServerServices are configurable via +conf/<service-id>.properties files such as conf/ejbd.properties to +configure the main protocol that services EJB client requests. + +The format those properties files is greatly adapted from the xinet.d style +of configuration and even shares similar functionality and properties such +as host-based authorization (HBA) via the 'only_from' property. + +<a name="PropertyOverriding-Restoringopenejb.xmltothedefaults"></a> +## Restoring openejb.xml to the defaults + +To restore this file to its original default state, you can simply delete +it or rename it and OpenEJB will see it's missing and unpack another +openejb.xml into the conf/ directory when it starts. + +This is not only handy for recovering from a non-functional config, but +also for upgrading as OpenEJB will not overwrite your existing +configuration file should you choose to unpack an new distro over the top +of an old one -- this style of upgrade is safe provided you move your old +lib/ directory first. + http://git-wip-us.apache.org/repos/asf/tomee/blob/f779264f/docs/provisioning.mdtext ---------------------------------------------------------------------- diff --git a/docs/provisioning.mdtext b/docs/provisioning.mdtext new file mode 100644 index 0000000..e99fe91 --- /dev/null +++ b/docs/provisioning.mdtext @@ -0,0 +1,76 @@ +Title: TomEE/OpenEJB provisioning + +# Summary + +Provioning is about the way to get binaries or information. It is the answer to +how do i get my application, my webapp, my configuration. + +TomEE and OpenEJB brings some help about it allowing you to point out some +resources instead of providing it directly. + +This indirection is clearly very useful to industrialize your software +or simply to cloudify it. + +# A word about this page + +This page will not explain you how to deploy an application or +how to enhance your container. It will simply explain you how which +kind of urls are supported for such features. + +These feature are explained in other places. + +# Supported provionings +## file + +This is the default and well know provisioning. Simply give a +file path the container is able to access through its filesystem. + +Example: + + /MIDDLE/foo/bar/my-local-file.jar + +## Http/https + +Here you give an url to access the desired file. Proxies used are the JVM ones. + +Example: + + http://atos.net/foo/bar/my-http-file.jar + +## Maven +### Usage + +Probably the most fun but very useful for cloud deployments: maven. +Use maven informations to deploy your application. + +The location should follow: + + mvn:groupId/artifactId[/[version]/[type]] + +or + + mvn:groupId:artifactId[:[version]:[type]] + +Note: classifier are supported (through version field) + +For instance you can use: + + mvn:net.atos.xa/my-application/1.0.0/war + +### Installation + +The maven url parsing is not included by default in OpenEJB/TomEE bundle. It needs to be installed. + +If you are using an embedded application and maven simply add +org.apache.openejb:openejb-provisionning:VERSION dependency. + +If you are using TomEE you have to extract the org.apache.openejb:openejb-provisionning zip +in the same classloader than tomee (webapps/tomee/lib for instance, for other places please have +a look to other tip pages). + +Another way to install it with tomee is to edit or create the file <tomee>/conf/provisioning.properties +and add the line: + + zip=http://repo1.maven.org/maven2/org/apache/openejb/openejb-provisionning/<version>/openejb-provisionning-<version>.zip + + http://git-wip-us.apache.org/repos/asf/tomee/blob/f779264f/docs/proxyfactory-config.mdtext ---------------------------------------------------------------------- diff --git a/docs/proxyfactory-config.mdtext b/docs/proxyfactory-config.mdtext new file mode 100644 index 0000000..e73d983 --- /dev/null +++ b/docs/proxyfactory-config.mdtext @@ -0,0 +1,24 @@ +Title: ProxyFactory Configuration + + +A ProxyFactory 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. + + <ProxyFactory id="myProxyFactory" type="ProxyFactory"> + </ProxyFactory> + +Alternatively, a ProxyFactory 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` + + myProxyFactory = new://ProxyFactory?type=ProxyFactory + +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 ProxyFactory a warning will be logged. If a ProxyFactory is needed by the application and one is not declared, TomEE will create one dynamically using default settings. Multiple ProxyFactory declarations are allowed. +# Supported Properties +<table> +<tr> +<th>Property</th> +<th>Type</th> +<th>Default</th> +<th>Description</th> +</tr> +</table> + + http://git-wip-us.apache.org/repos/asf/tomee/blob/f779264f/docs/queue-config.mdtext ---------------------------------------------------------------------- diff --git a/docs/queue-config.mdtext b/docs/queue-config.mdtext new file mode 100644 index 0000000..ca8b354 --- /dev/null +++ b/docs/queue-config.mdtext @@ -0,0 +1,34 @@ +Title: Queue Configuration + + +A Queue can be declared via xml in the `<tomee-home>/conf/tomee.xml` file or in a `WEB-INF/resources.xml` file using a declaration like the following. All properties in the element body are optional. + + <Resource id="myQueue" type="javax.jms.Queue"> + destination = + </Resource> + +Alternatively, a Queue can be declared via properties in the `<tomee-home>/conf/system.properties` file or via Java VirtualMachine `-D` properties. The properties can also be used when embedding TomEE via the `javax.ejb.embeddable.EJBContainer` API or `InitialContext` + + myQueue = new://Resource?type=javax.jms.Queue + myQueue.destination = + +Properties and xml can be mixed. Properties will override the xml allowing for easy configuration change without the need for ${} style variable substitution. Properties are not case sensitive. If a property is specified that is not supported by the declared Queue a warning will be logged. If a Queue is needed by the application and one is not declared, TomEE will create one dynamically using default settings. Multiple Queue declarations are allowed. +# Supported Properties +<table> +<tr> +<th>Property</th> +<th>Type</th> +<th>Default</th> +<th>Description</th> +</tr> +<tr> + <td>destination</td> + <td>String</td> + <td></td> + <td> +Specifies the name of the queue +</td> +</tr> +</table> + + http://git-wip-us.apache.org/repos/asf/tomee/blob/f779264f/docs/quickstart.mdtext ---------------------------------------------------------------------- diff --git a/docs/quickstart.mdtext b/docs/quickstart.mdtext new file mode 100644 index 0000000..6c67f8f --- /dev/null +++ b/docs/quickstart.mdtext @@ -0,0 +1,67 @@ +Title: Quickstart +<a name="Quickstart-Installation"></a> +# Installation + + +To install OpenEJB, simply [download the latest binary](downloads.html) + and unpack your zip or tar.gz into the directory where you want OpenEJB to +live. + +Windows users can download the zip and unpack it with the WinZip program. + +Linux users can download the tar.gz and unpack it with the following +command: + +*tar xzvf openejb-3.0.tar.gz* + + +Congratulations, you've installed OpenEJB. + +If you've unpacked OpenEJB into the directory C:\openejb-3.0, for example, +then this directory is your OPENEJB_HOME directory. The OPENEJB_HOME +directory is referred to in various parts of the documentation, so it's +good to remember where it is. + +<a name="Quickstart-UsingOpenEJB"></a> +# Using OpenEJB + + +Now all you need to do is move to the bin directory in OPENEJB_HOME, the +directory where OpenEJB was unpacked, and type: + +*openejb* + +For Windows users, that looks like this: + +*C:\openejb-3.0> bin\openejb* + +For UNIX/Linux/Mac OS X users, that looks like this: + +`[user@host openejb-3.0](u...@host-openejb-3.0.html) +# ./bin/openejb` + +You really only need to know two commands to use OpenEJB, [deploy](openejbx30:deploy-tool.html) + and [start|OPENEJBx30:Startup] +. Both are completely documented and have examples. + +For help information and command options, try this: + +> openejb deploy --help +> openejb start --help + +For examples on using the start command and options, try this: + +> openejb start --examples + +That's it! + +If you don't have any EJBs or clients to run, try the ubiquitous [Hello World](openejbx30:hello-world.html) + example. + +<a name="Quickstart-Jointhemailinglist"></a> +# Join the mailing list + +The OpenEJB User list is where the general OpenEJB community goes to ask +questions, make suggestions, chat with other users, and keep a finger on +the pulse of the project. More information about the user list and dev list +can be found [here](mailing-lists.html) http://git-wip-us.apache.org/repos/asf/tomee/blob/f779264f/docs/refcard/.DS_Store ---------------------------------------------------------------------- diff --git a/docs/refcard/.DS_Store b/docs/refcard/.DS_Store new file mode 100644 index 0000000..c0893ad Binary files /dev/null and b/docs/refcard/.DS_Store differ
