http://git-wip-us.apache.org/repos/asf/tomee/blob/b45a3d00/docs/deployment-id.md ---------------------------------------------------------------------- diff --git a/docs/deployment-id.md b/docs/deployment-id.md deleted file mode 100644 index 533a16d..0000000 --- a/docs/deployment-id.md +++ /dev/null @@ -1,231 +0,0 @@ -index-group=Unrevised -type=page -status=published -title=Deployment ID -~~~~~~ - -<a name="DeploymentID-WhatisaDeploymentID?"></a> -# What is a Deployment ID? - -Every bean deployed in OpenEJB has a unique deployment-id that identifies -it within the scope of the entire container system. The server and -container system refer beans at run-time using the bean's deployment id. - -<a name="DeploymentID-Likeejb-name"></a> -## Like ejb-name - -This deployment id is much like the <ejb-name> element of the ejb-jar.xml , -with one very important difference. The <ejb-name> is only required to be -unique within the scope of the ejb-jar.xml in the bean's jar. The -deployment id is required to be unique across all beans and jars in -OpenEJB. This is a subtle, but important, distinction. - -Remember that the EJB specification was designed so that enterprise beans -could be create, packaged, and sold by vendors (EJB Providers). -Furthermore, users should be able to buy a packaged set of beans (a jar -with an ejb-jar.xml in it) and deploy it into an EJB Container without -modification. - -<a name="DeploymentID-Theejb-nameisnotunique"></a> -## The ejb-name is not unique - -Let's consider this, what happens if two vendors each sell a package (jar) -that contains a bean with the <ejb-name> PurchaseOrder? Both are completely -different in terms functionality and are different beans in every other -respect. The EJB spec says, this is fine, ejb-names only have to unique -within the jar and that jar's ejb-jar.xml file. It's ridiculous to expect -EJB Providers to call each other up and ask, "Are you already using the -name 'PurchaseOrder' in your jar?" Remember that the EJB specification was -designed so that enterprise beans could be create, packaged, and sold by -vendors (EJB Providers). Furthermore, users should be able to buy a -packaged set of beans (a jar with an ejb-jar.xml in it) and deploy it into -an EJB Container without modification. This is all fine and dandy, but it -still leaves it up to the EJB Container/Server providers to settle the -difference. - -<a name="DeploymentID-Thedeployment-idisunique"></a> -## The deployment-id is unique - -OpenEJB solves this with the OpenEJB-specific deployment id. By requiring -that each bean deployed into OpenEJB has a unique name, we can guarantee -that we are always referring to the right bean at all times. Furthermore, it -allows you to deploy different versions of the same package several times -in the same container system, each time giving the beans new deployment -ids. - -<a name="DeploymentID-Usingejb-nameasdeployment-idanyway"></a> -## Using ejb-name as deployment-id anyway - -If you're lazy -- as any truly great programmer should be -- and don't want -to type a deployment id for each bean every time you deploy a jar, you can -use the -D option of the Deploy Tool. This will throw caution to the wind, -and automatically assign the bean's ejb-name as the value of the bean's -OpenEJB deployment id. This leaves up to you to guarantee that bean's -ejb-name will be unique across all beans and jars in the container system. -In other words, be very careful with the -D option! - -<a name="DeploymentID-Howisitused?"></a> -# How is it used? - -<a name="DeploymentID-Inthecontainersystem"></a> -## In the container system - -In the container system, the deployment id is used to index the bean in a -system-wide registry. This registry is refereed to on every call made in the -container system. Being able to safely hash and cache bean information by -id is a must. This stresses the importance of unique ids for every bean -deployed in OpenEJB. - -<a name="DeploymentID-IntheLocalServer"></a> -## In the Local Server - -The Local (IntraVM) Server is an integral part of the container system and -the two are, in many ways, inseparable. The Local Server takes care of all -bean to bean and client to bean invocations made inside the virtual -machine. For this reason, it often refered to as the IntraVM Server. - -For bean to bean communications, the Local Server must create a JNDI -namespace (JNDI ENC) for each bean as defined by the bean's <env-entry>, -<ejb-ref>, and <resource-ref> elements of the bean's ejb-jar.xml file. -Every bean literally gets its very own JNDI namespace. When a bean makes a -JNDI call, the Local Server intercepts this call and uses the deployment id -of the calling bean to retrieve that bean's private JNDI namespace from the -container system's index. The Local Server then carries out the lookup on -that bean's namespace. - -All non-bean clients share one big global namespace. Since non-bean clients -are not deployed and do not have a deployment descriptor like an -ejb-jar.xml, the Local Server is unable to taylor a namespace for each -non-bean client as it can for bean clients. The Local server cannot -identify non-bean clients as they have no deployment id. All JNDI calls -made by clients that the Local Server cannot identify go to the public, -global namespace. The public, global JNDI namespace contains all beans and -resources in the container system. name. - -Each bean is added to the public, global namespace using it's deployment id -as its JNDI lookup. For example, if a bean had a deployment-id of -"/my/bean/foo", a non-bean client could lookup that bean as follows. - - ... - Object bean = initialContext.lookup("/my/bean/Foo"); - ... - - -If a bean in the container system made the above JNDI call, the Local -Server would see the bean's identity (deployment id) hidden in the Thread, -go get the bean's private JNDI namespace and finish the lookup on that. -Since all names in bean's JNDI namespace are required start with -"java:comp/env", the lookup would fail and the bean would receive a -javax.naming.NameNotFoundException. - -In short... - -For beans: - - Each bean has it's own private, personalized JNDI namespace - - The names in it are the same names it uses in its ejb-jar.xml - - Beans can only access their private namespace, period - -For non-beans (everyone else): - - Non-bean clients share the public, global JNDI namespace - - The names in it are the deployment ids of all the beans - - Non-bean clients can only access the one global namespace - -<a name="DeploymentID-IntheRemoteServer"></a> -## In the Remote Server - -The Remote Server has a public, global namespace just as the Local Server -does. The difference being that the Remote Server only serves clients -outside the container system and outside the virtual machine. So, all -clients from the perspective of the Remote Server are non-bean clients. As -a result, the Remote Server only has the one public, global JNDI namespace. -Just as in the Local Server, the names in this namespace consist of the -deployment ids of the beans in the container system. - -Just as before, clients can lookup beans from the Remote Server using the -bean's deployment id. For example, if a bean had a deployment-id of -"/my/bean/foo", a client could lookup that bean as follows. - - ... - Object bean = initialContext.lookup("/my/bean/Foo"); - ... - - -<a name="DeploymentID-IntheCORBAAdapter"></a> -## In the CORBA Adapter - -The CORBA Adapter is separate than the Remote Server. It adapts the OpenEJB -Container System and the Local Server into OpenORB as an embedded library. -It provides users of OpenORB the ability to lookup and execute beans (EJBs) -via the RMI-IIOP protocol. All the EJBHome and EJBObject interfaces of -beans in OpenEJB are implemented by OpenORB as CORBA stubs and ties. - -The beans are exported into OpenORB's naming service by deployment id. So, -just as with the Local Server and Remote Server, clients can lookup beans -using the bean's deployment id. OpenORB has a JNDI implementation of their -naming service, so lookups can be done just as before. - - ... - String[] args = ... - - // The ORB and Object - org.omg.CORBA.ORB orb = null; - org.omg.CORBA.Object bean = null. - - // The Naming Service and Object Name - org.omg.CosNaming.NamingContext context = null; - org.omg.CosNaming.NameComponent[] name = null; - - // Get the ORB - orb = org.omg.CORBA.ORB.init( args, null ); - - // Get the Naming Service - org.omg.CORBA.Object ref = null; - ref = orb.resolve_initial_references("NameService"); - context = org.omg.CosNaming.NamingContextHelper.narrow( ref ); - - // Get the Name as a component - // Note: the string is the bean's deployment id - name = new org.omg.CosNaming.NameComponent[ 1 ]; - name[0] = new org.omg.CosNaming.NameComponent("/my/bean/foo",""); - - // Finally, get the bean as a CORBA object - // Equvalent to an InitialContext.lookup("/my/bean/foo"); - bean = context.resolve( name ); - ... - - -<a name="DeploymentID-WhathappensifthereisaduplicatedeploymentID?"></a> -# What happens if there is a duplicate deployment ID? - -The deployment ID uniquely identifies the bean in the OpenEJB container -system. Therefore, no two beans can share the same deployment ID. - -If a bean attempts to use a deployment ID that is already in use by another -bean, the second bean and all beans in it's jar will not be loaded. In -addition, the system will log a warning like the following one asking you -to redeploy the jar and choose an different deployment ID for the bean. - - WARN : Jar C:\openejb\beans\fooEjbs.jar cannot be loaded. The Deployment ID "/my/bean/foo" is already in use. Please redeploy this jar and assign a different deployment ID to the bean with the ejb-name "FooBean". - -For example, the acmeEjbs.jar contains a bean with the ejb-name -"DaffyDuckBean". The disneyEjbs.jar contains contains a bean with the -ejb-name "DonaldDuckBean". - -We deploy the acmeEjbs.jar and give the "DaffyDuckBean" the deployment ID -of "/my/favorite/duck". Sometime afterwards, we deploy the disneyEjbs.jar -and assign the "DonaldDuckBean" the deployment ID "/my/favorite/duck", -having forgotten that we already gave that unique ID to the "DaffyDuckBean" -in the acmeEjbs.jar. - -When the container system is started, the system will begin loading all the -beans one jar at a time. It will first load the acmeEjbs.jar and index each -bean by deployment ID. But, when the system reaches the disneyEjbs.jar, it -will discover that it cannot index the "DonaldDuckBean" using the -deployment ID "/my/favorite/duck" because that index is already taken. - -The system cannot load the "DonaldDuckBean" and must also ignore the rest -of the beans in the disneyEjbs.jar as they may need the "DonaldDuckBean" -bean to function properly. The disneyEjbs.jar is skipped and the following -warning is logged. - - WARN : Jar C:\openejb\beans\disneyEjbs.jar cannot be loaded. The Deployment ID "/my/favorite/duck" is already in use. Please redeploy this jar and assign a different deployment ID to the bean with the ejb-name "DonaldDuckBean".
http://git-wip-us.apache.org/repos/asf/tomee/blob/b45a3d00/docs/deployments.adoc ---------------------------------------------------------------------- diff --git a/docs/deployments.adoc b/docs/deployments.adoc new file mode 100644 index 0000000..dc31d32 --- /dev/null +++ b/docs/deployments.adoc @@ -0,0 +1,146 @@ +# Deployments +:index-group: Configuration +:jbake-date: 2018-12-05 +:jbake-type: page +:jbake-status: published + + +# The 'Deployments' element in openejb.xml + +== A single jar + +To include a single jar by name, just declare a 'Deployments' element +with a 'jar' attribute pointing to the jar file on the file system. + +.... +<openejb> +... +<Deployments jar="c:\my\app\superEjbs.jar" /> +<Deployments jar="c:\someplace\purchasing.jar" /> +<Deployments jar="timeTrack.jar" /> +</openejb> +.... + +The last element in the example uses a relative path to point to the ejb +jar. This path will be resolved relative to the openejb.base property. +So, for example, of the value of openejb.base was 'c:' then OpenEJB +would look for the jar 'c:.jar'. See the [OPENEJB:Configuration] guide +for more details. + +== A directory of jars + +To point to a directory that contains several jar files that OpenEJB +should load, simply declare a 'Deployments' element with a 'dir' +attribute pointing to the directory containing the jar files. + +.... +<openejb> +... + +<Deployments dir="c:\my\app\beans\" /> +<Deployments dir="c:\crimestopper\lib" /> +<Deployments dir="ejbs" /> +<Deployments dir="beans" /> +</openejb> +.... + +The directories listed will be searched for jars containing +'META-INF/ejb-jar.xml' files and will be added to the list of jars to +load if they do. Better said, it's completely safe to point to a +directory containing a mix of ejbs and regular jar files. OpenEJB will +simply skip over jars that do contain the required +'META-INF/ejb-jar.xml' file. + +The last Deployments element declares a 'beans' directory relative to +openejb.base for holding ejb jars. This declaration is simply convention +and not required. + +== An unpacked jar + +As of 1.0 beta1, OpenEJB supports unpacked ejb jars. Simply meaning that +you don't need to pack your ejb's into a jar file in order to use them +in OpenEJB. You still need to follow the ejb jar layout and include an +"META-INF/ejb-jar.xml" in the directory that contains your ejbs. + +For example, if you have a directory structure like this: + +.... +> C:\myapp\ +> C:\myapp\acmeEjbs\ +> C:\myapp\acmeEjbs\META-INF\ejb-jar.xml +> C:\myapp\acmeEjbs\org\acme\Foo.class +> C:\myapp\acmeEjbs\org\acme\FooBean.class +> C:\myapp\acmeEjbs\org\acme\FooHome.class +> C:\myapp\acmeEjbs\org\acme\Bar.class +> C:\myapp\acmeEjbs\org\acme\BarBean.class +> C:\myapp\acmeEjbs\org\acme\BarHome.class +.... + +Then you would delcare a 'Deployments' element with the 'dir' attribute +set to 'C:' as shown below. + +.... +<openejb> +... + +<Deployments dir="c:\myapp\acmeEjbs" /> +</openejb> +.... + +Note that this syntax is the same as the directory syntax above. If +OpenEJB finds a META-INF directory with an 'ejb-jar.xml' fine inside, +then OpenEJB will treat the directory as an unpacked ejb jar. Otherwise +OpenEJB will look for ejb jar files to load as detailed in the above +section. + +== Log file + +When trying to figure out if your ejbs were loaded, the openejb.log file +is an incredible asset. + +If your ejbs were loaded successfully you should see entries like the +following (1.x and higher only): + +.... +INFO : Loaded EJBs from +/usr/local/openejb-1.0-beta1/beans/openejb-itests-beans.jar +INFO : Loaded EJBs from +/usr/local/openejb-1.0-beta1/beans/openejb-webadmin-clienttools.jar +.... + +If your ejbs failed to load, you will see an entry similar to the +following. + +.... +WARN : Jar not loaded. /usr/local/openejb-1.0-beta1/beans/helloworld.jar. +Jar failed validation. Use the validation tool for more details +.... + +Additionally, all the successfully loaded ejbs are individually listed +in the log file at startup. The Deployment ID listed is the JNDI name +used to lookup the ejb from a client of the Local or Remote Servers. The +beans listed below are from our test suite. + +.... +DEBUG: Deployments : 19 +DEBUG: Type Deployment ID +DEBUG: CMP_ENTITY client/tests/entity/cmp/RMI-over-IIOP/EJBHome +DEBUG: STATEFUL client/tests/stateful/EncBean +DEBUG: STATELESS client/tests/stateless/BeanManagedBasicStatelessHome +DEBUG: STATEFUL client/tests/stateful/BasicStatefulHome +DEBUG: STATELESS client/tests/stateless/EncBean +DEBUG: STATEFUL client/tests/stateful/BeanManagedTransactionTests/EJBHome +DEBUG: BMP_ENTITY client/tests/entity/bmp/RMI-over-IIOP/EJBHome +DEBUG: STATEFUL client/tests/stateful/RMI-over-IIOP/EJBHome +DEBUG: STATELESS client/tests/stateless/BeanManagedTransactionTests/EJBHome +DEBUG: BMP_ENTITY client/tests/entity/bmp/allowed_operations/EntityHome +DEBUG: CMP_ENTITY client/tests/entity/cmp/EncBean +DEBUG: STATEFUL client/tests/stateful/BeanManagedBasicStatefulHome +DEBUG: BMP_ENTITY client/tests/entity/bmp/BasicBmpHome +DEBUG: STATELESS client/tests/stateless/BasicStatelessHome +DEBUG: CMP_ENTITY client/tests/entity/cmp/BasicCmpHome +DEBUG: STATELESS client/tools/DatabaseHome +DEBUG: CMP_ENTITY client/tests/entity/cmp/allowed_operations/EntityHome +DEBUG: BMP_ENTITY client/tests/entity/bmp/EncBean +DEBUG: STATELESS client/tests/stateless/RMI-over-IIOP/EJBHome +.... http://git-wip-us.apache.org/repos/asf/tomee/blob/b45a3d00/docs/deployments.md ---------------------------------------------------------------------- diff --git a/docs/deployments.md b/docs/deployments.md deleted file mode 100644 index a6d9be1..0000000 --- a/docs/deployments.md +++ /dev/null @@ -1,135 +0,0 @@ -index-group=Configuration -type=page -status=published -title=Deployments -~~~~~~ - -<a name="Deployments-The'Deployments'elementinopenejb.xml"></a> -# The 'Deployments' element in openejb.xml - -<a name="Deployments-Asinglejar"></a> -## A single jar - -To include a single jar by name, just declare a 'Deployments' element with -a 'jar' attribute pointing to the jar file on the file system. - - <openejb> - ... - <Deployments jar="c:\my\app\superEjbs.jar" /> - <Deployments jar="c:\someplace\purchasing.jar" /> - <Deployments jar="timeTrack.jar" /> - </openejb> - - -The last element in the example uses a relative path to point to the ejb -jar. This path will be resolved relative to the openejb.base property. -So, for example, of the value of openejb.base was 'c:\timeapp\' then -OpenEJB would look for the jar 'c:\timeapp\timeTrack.jar'. See the [OPENEJB:Configuration] - guide for more details. - -## A directory of jars - -To point to a directory that contains several jar files that OpenEJB should -load, simply declare a 'Deployments' element with a 'dir' attribute -pointing to the directory containing the jar files. - - <openejb> - ... - - <Deployments dir="c:\my\app\beans\" /> - <Deployments dir="c:\crimestopper\lib" /> - <Deployments dir="ejbs" /> - <Deployments dir="beans" /> - </openejb> - - -The directories listed will be searched for jars containing -'META-INF/ejb-jar.xml' files and will be added to the list of jars to load -if they do. Better said, it's completely safe to point to a directory -containing a mix of ejbs and regular jar files. OpenEJB will simply skip -over jars that do contain the required 'META-INF/ejb-jar.xml' file. - -The last Deployments element declares a 'beans' directory relative to -openejb.base for holding ejb jars. This declaration is simply convention -and not required. - -<a name="Deployments-Anunpackedjar"></a> -## An unpacked jar - -As of 1.0 beta1, OpenEJB supports unpacked ejb jars. Simply meaning that -you don't need to pack your ejb's into a jar file in order to use them in -OpenEJB. You still need to follow the ejb jar layout and include an -"META-INF/ejb-jar.xml" in the directory that contains your ejbs. - -For example, if you have a directory structure like this: - - > C:\myapp\ - > C:\myapp\acmeEjbs\ - > C:\myapp\acmeEjbs\META-INF\ejb-jar.xml - > C:\myapp\acmeEjbs\org\acme\Foo.class - > C:\myapp\acmeEjbs\org\acme\FooBean.class - > C:\myapp\acmeEjbs\org\acme\FooHome.class - > C:\myapp\acmeEjbs\org\acme\Bar.class - > C:\myapp\acmeEjbs\org\acme\BarBean.class - > C:\myapp\acmeEjbs\org\acme\BarHome.class - -Then you would delcare a 'Deployments' element with the 'dir' attribute set -to 'C:\myapp\acmeEjbs' as shown below. - - <openejb> - ... - - <Deployments dir="c:\myapp\acmeEjbs" /> - </openejb> - - -Note that this syntax is the same as the directory syntax above. If -OpenEJB finds a META-INF directory with an 'ejb-jar.xml' fine inside, then -OpenEJB will treat the directory as an unpacked ejb jar. Otherwise OpenEJB -will look for ejb jar files to load as detailed in the above section. - -# Log file - -When trying to figure out if your ejbs were loaded, the openejb.log file is -an incredible asset. - -If your ejbs were loaded successfully you should see entries like the -following (1.x and higher only): - - INFO : Loaded EJBs from - /usr/local/openejb-1.0-beta1/beans/openejb-itests-beans.jar - INFO : Loaded EJBs from - /usr/local/openejb-1.0-beta1/beans/openejb-webadmin-clienttools.jar - -If your ejbs failed to load, you will see an entry similar to the -following. - - WARN : Jar not loaded. /usr/local/openejb-1.0-beta1/beans/helloworld.jar. - Jar failed validation. Use the validation tool for more details - -Additionally, all the successfully loaded ejbs are individually listed in -the log file at startup. The Deployment ID listed is the JNDI name used to -lookup the ejb from a client of the Local or Remote Servers. The beans -listed below are from our test suite. - - DEBUG: Deployments : 19 - DEBUG: Type Deployment ID - DEBUG: CMP_ENTITY client/tests/entity/cmp/RMI-over-IIOP/EJBHome - DEBUG: STATEFUL client/tests/stateful/EncBean - DEBUG: STATELESS client/tests/stateless/BeanManagedBasicStatelessHome - DEBUG: STATEFUL client/tests/stateful/BasicStatefulHome - DEBUG: STATELESS client/tests/stateless/EncBean - DEBUG: STATEFUL client/tests/stateful/BeanManagedTransactionTests/EJBHome - DEBUG: BMP_ENTITY client/tests/entity/bmp/RMI-over-IIOP/EJBHome - DEBUG: STATEFUL client/tests/stateful/RMI-over-IIOP/EJBHome - DEBUG: STATELESS client/tests/stateless/BeanManagedTransactionTests/EJBHome - DEBUG: BMP_ENTITY client/tests/entity/bmp/allowed_operations/EntityHome - DEBUG: CMP_ENTITY client/tests/entity/cmp/EncBean - DEBUG: STATEFUL client/tests/stateful/BeanManagedBasicStatefulHome - DEBUG: BMP_ENTITY client/tests/entity/bmp/BasicBmpHome - DEBUG: STATELESS client/tests/stateless/BasicStatelessHome - DEBUG: CMP_ENTITY client/tests/entity/cmp/BasicCmpHome - DEBUG: STATELESS client/tools/DatabaseHome - DEBUG: CMP_ENTITY client/tests/entity/cmp/allowed_operations/EntityHome - DEBUG: BMP_ENTITY client/tests/entity/bmp/EncBean - DEBUG: STATELESS client/tests/stateless/RMI-over-IIOP/EJBHome http://git-wip-us.apache.org/repos/asf/tomee/blob/b45a3d00/docs/details-on-openejb-jar.adoc ---------------------------------------------------------------------- diff --git a/docs/details-on-openejb-jar.adoc b/docs/details-on-openejb-jar.adoc new file mode 100644 index 0000000..36ceb86 --- /dev/null +++ b/docs/details-on-openejb-jar.adoc @@ -0,0 +1,152 @@ +# Details on openejb-jar +:index-group: Unrevised +:jbake-date: 2018-12-05 +:jbake-type: page +:jbake-status: published + + +# What is an openejb-jar.xml? + +This is the file created by the Deploy Tool that maps your bean's +deployment descriptor (ejb-jar.xml) to actual containers and resources +declared in your OpenEJB configuration (openejb.conf). In fact, the +Deploy tool really does nothing more than create this file and put it in +your jar, that's it. + +# When is the openejb-jar.xml used? + +At startup, any jar containing a openejb-jar.xml is loaded by the +container system. The configuration tools will go looking in all the +directories and jars you have declared in your openejb.conf with the +element. For every jar file it finds, it will look inside for an +openejb-jar.xml. If it finds one, it will attempt to load and deploy it +into the container system. + +# Do I even need the deploy tool then? + +Nope. Typically you would only use the deploy tool to create your +openejb-jar.xml, then just keep your openejb-jar.xml in your CVS (or +other repository). If you learn how to maintain this openejb-jar.xml +file, you'll never need the deploy tool again! You can do all your +builds and deploys automatically. + +# Where do I put the openejb-jar.xml in my jar? + +The openejb-jar.xml file just goes in the META-INF directory of your jar +next to the ejb-jar.xml file. + +# Is the file format easy? + +If you can understand the ejb-jar.xml, the openejb-jar.xml should be a +breeze. + +This is the openejb-jar.xml that is created by the Deploy tool in the +Hello World example. As you can see, the file format is extremely +simple. + +.... +<?xml version="1.0"?> +<openejb-jar xmlns="http://www.openejb.org/openejb-jar/1.1";> + <ejb-deployment ejb-name="Hello" + deployment-id="Hello" + container-id="Default Stateless Container"/> +</openejb-jar> +.... + +The _ejb-name_ attribute is the name you gave the bean in your +ejb-jar.xml. The _deployment-id_ is the name you want to use to lookup +the bean in your client's JNDI namespace. The _container-id_ is the name +of the container in your openejb.conf file that you would like the bean +to run in. There MUST be one _ejb-deployment_ element for each EJB in +your jar. + +== What if my bean uses a JDBC datasource? + +Then you simply add a element to your element like this + +.... +<?xml version="1.0"?> +<openejb-jar xmlns="http://www.openejb.org/openejb-jar/1.1";> + + <ejb-deployment ejb-name="Hello" + deployment-id="Hello" + container-id="Default Stateless Container" > + + <resource-link res-ref-name="jdbc/basic/entityDatabase" + res-id="Default JDBC Database"/> + + </ejb-deployment> + +</openejb-jar> +.... + +The _res-ref-name_ attribute refers to the element of the bean's +declaration in the ejb-jar.xml. The _res-id_ attribute refers to the id +of the declared in your openejb.conf that will handle the connections +and provide access to the desired resource. + +# How many resource-link elements will I need? + +You will need one element for every element in your ejb-jar.xml. So if +you had an ejb-jar.xml like the following + +.... +<?xml version="1.0"?> +<ejb-jar> + <enterprise-beans> + <session> + <ejb-name>MyExampleBean</ejb-name> + <home>com.widget.ExampleHome</home> + <remote>com.widget.ExampleObject</remote> + <ejb-class>com.widget.ExampleBean</ejb-class> + <session-type>Stateless</session-type> + <transaction-type>Container</transaction-type> + + <resource-ref> + <description> + This is a reference to a JDBC database. + </description> + <res-ref-name>jdbc/myFirstDatabase</res-ref-name> + <res-type>javax.sql.DataSource</res-type> + <res-auth>Container</res-auth> + </resource-ref> + + <resource-ref> + <description> + This is another reference to a JDBC database. + </description> + <res-ref-name>jdbc/anotherDatabase</res-ref-name> + <res-type>javax.sql.DataSource</res-type> + <res-auth>Container</res-auth> + </resource-ref> + + </session> + </enterprise-beans> +</ejb-jar> +.... + +Then you would need two elements for that bean in your openejb-jar.xml +file as such. + +.... +<?xml version="1.0"?> +<openejb-jar xmlns="http://www.openejb.org/openejb-jar/1.1";> + + <ejb-deployment ejb-name="MyExampleBean" + deployment-id="MyExampleBean" + container-id="Default Stateless Container" > + + <resource-link res-ref-name="jdbc/myFirstDatabase" + res-id="My Oracle JDBC Database"/> + + <resource-link res-ref-name="jdbc/anotherDatabase" + res-id="My PostgreSQL JDBC Database"/> + + </ejb-deployment> + +</openejb-jar> +.... + +This would require two declarations in your openejb.conf, one with the +_id_ attribute set to _"My Oracle JDBC Database"_ , and another with +it's _id_ attribute set to _"My PostgreSQL JDBC Database"_ http://git-wip-us.apache.org/repos/asf/tomee/blob/b45a3d00/docs/details-on-openejb-jar.md ---------------------------------------------------------------------- diff --git a/docs/details-on-openejb-jar.md b/docs/details-on-openejb-jar.md deleted file mode 100644 index 8ab2848..0000000 --- a/docs/details-on-openejb-jar.md +++ /dev/null @@ -1,156 +0,0 @@ -index-group=Unrevised -type=page -status=published -title=Details on openejb-jar -~~~~~~ - -<a name="Detailsonopenejb-jar-Whatisanopenejb-jar.xml?"></a> -# What is an openejb-jar.xml? - -This is the file created by the Deploy Tool that maps your bean's -deployment descriptor (ejb-jar.xml) to actual containers and resources -declared in your OpenEJB configuration (openejb.conf). In fact, the Deploy -tool really does nothing more than create this file and put it in your jar, -that's it. - -<a name="Detailsonopenejb-jar-Whenistheopenejb-jar.xmlused?"></a> -# When is the openejb-jar.xml used? - -At startup, any jar containing a openejb-jar.xml is loaded by the container -system. The configuration tools will go looking in all the directories and -jars you have declared in your openejb.conf with the <Deployment> element. -For every jar file it finds, it will look inside for an openejb-jar.xml. If -it finds one, it will attempt to load and deploy it into the container -system. - -<a name="Detailsonopenejb-jar-DoIevenneedthedeploytoolthen?"></a> -# Do I even need the deploy tool then? - -Nope. Typically you would only use the deploy tool to create your -openejb-jar.xml, then just keep your openejb-jar.xml in your CVS (or other -repository). If you learn how to maintain this openejb-jar.xml file, you'll -never need the deploy tool again! You can do all your builds and deploys -automatically. - -<a name="Detailsonopenejb-jar-WheredoIputtheopenejb-jar.xmlinmyjar?"></a> -# Where do I put the openejb-jar.xml in my jar? - -The openejb-jar.xml file just goes in the META-INF directory of your jar -next to the ejb-jar.xml file. - -<a name="Detailsonopenejb-jar-Isthefileformateasy?"></a> -# Is the file format easy? - -If you can understand the ejb-jar.xml, the openejb-jar.xml should be a -breeze. - -This is the openejb-jar.xml that is created by the Deploy tool in the Hello -World example. As you can see, the file format is extremely simple. - - <?xml version="1.0"?> - <openejb-jar xmlns="http://www.openejb.org/openejb-jar/1.1";> - <ejb-deployment ejb-name="Hello" - deployment-id="Hello" - container-id="Default Stateless Container"/> - </openejb-jar> - - - -The *ejb-name* attribute is the name you gave the bean in your ejb-jar.xml. -The *deployment-id* is the name you want to use to lookup the bean in your -client's JNDI namespace. The *container-id* is the name of the container in -your openejb.conf file that you would like the bean to run in. There MUST -be one *ejb-deployment* element for each EJB in your jar. - -# What if my bean uses a JDBC datasource? - -Then you simply add a <resource-link> element to your <ejb-deployment> -element like this - - <?xml version="1.0"?> - <openejb-jar xmlns="http://www.openejb.org/openejb-jar/1.1";> - - <ejb-deployment ejb-name="Hello" - deployment-id="Hello" - container-id="Default Stateless Container" > - - <resource-link res-ref-name="jdbc/basic/entityDatabase" - res-id="Default JDBC Database"/> - - </ejb-deployment> - - </openejb-jar> - - - -The *res-ref-name* attribute refers to the <res-ref-name> element of the -bean's <resource-ref> declaration in the ejb-jar.xml. The *res-id* -attribute refers to the id of the <Connector> declared in your openejb.conf -that will handle the connections and provide access to the desired -resource. - -<a name="Detailsonopenejb-jar-Howmanyresource-linkelementswillIneed?"></a> -# How many resource-link elements will I need? - -You will need one <resource-link> element for every <resource-ref> element -in your ejb-jar.xml. So if you had an ejb-jar.xml like the following - - <?xml version="1.0"?> - <ejb-jar> - <enterprise-beans> - <session> - <ejb-name>MyExampleBean</ejb-name> - <home>com.widget.ExampleHome</home> - <remote>com.widget.ExampleObject</remote> - <ejb-class>com.widget.ExampleBean</ejb-class> - <session-type>Stateless</session-type> - <transaction-type>Container</transaction-type> - - <resource-ref> - <description> - This is a reference to a JDBC database. - </description> - <res-ref-name>jdbc/myFirstDatabase</res-ref-name> - <res-type>javax.sql.DataSource</res-type> - <res-auth>Container</res-auth> - </resource-ref> - - <resource-ref> - <description> - This is another reference to a JDBC database. - </description> - <res-ref-name>jdbc/anotherDatabase</res-ref-name> - <res-type>javax.sql.DataSource</res-type> - <res-auth>Container</res-auth> - </resource-ref> - - </session> - </enterprise-beans> - </ejb-jar> - - -Then you would need two <resource-link> elements for that bean in your -openejb-jar.xml file as such. - - <?xml version="1.0"?> - <openejb-jar xmlns="http://www.openejb.org/openejb-jar/1.1";> - - <ejb-deployment ejb-name="MyExampleBean" - deployment-id="MyExampleBean" - container-id="Default Stateless Container" > - - <resource-link res-ref-name="jdbc/myFirstDatabase" - res-id="My Oracle JDBC Database"/> - - <resource-link res-ref-name="jdbc/anotherDatabase" - res-id="My PostgreSQL JDBC Database"/> - - </ejb-deployment> - - </openejb-jar> - - - -This would require two <Connector> declarations in your openejb.conf, one -with the *id* attribute set to _"My Oracle JDBC Database"_ , and another -with it's *id* attribute set to _"My PostgreSQL JDBC Database"_ http://git-wip-us.apache.org/repos/asf/tomee/blob/b45a3d00/docs/documentation.adoc ---------------------------------------------------------------------- diff --git a/docs/documentation.adoc b/docs/documentation.adoc new file mode 100644 index 0000000..c3baa94 --- /dev/null +++ b/docs/documentation.adoc @@ -0,0 +1,103 @@ +# Documentation +:index-group: Unrevised +:jbake-date: 2018-12-05 +:jbake-type: page +:jbake-status: published + + +See also the link:examples-trunk/index.html[examples page] for +downloadable, executable and code-focused view of Java EE and TomEE. You +can also find us on IRC freenode.org #openejb and #tomee + +\{row + +\{span-one-third ###IDE link:tomee-and-intellij.html[Get started with +Intellij], link:contrib/debug/debug-intellij.html[Debugging in +Intellij] + +link:tomee-and-eclipse.html[Get started with Eclipse (WTP)] + +link:getting-started-with-eclipse-and-webby.html[Get started with +Eclipse (m2e-Webby)] + +link:tomee-and-netbeans.html[Get started with Netbeans] + +###General Informations link:comparison.html[Comparison: OpenEJB, TomEE, +TomEE+] + +link:tomee-directory-structure.html[TomEE Directory structure] + +link:deploying-in-tomee.html[Deploying in TomEE] + +link:tomee-webapp.html[The 'tomee' webapp] + +link:refcard/refcard.html[TomEE Reference Card] + +link:application-composer/index.html[ApplicationComposer] + +} \{span-one-third ###Configuration link:system-properties.html[System +Properties] + +link:deployments.html[Deployments] + +link:Configuring-in-tomee.html[Configuring Resources] + +link:configuring-datasources.html[Configuring DataSources] + +link:containers-and-resources.html[Containers and Resources] + +link:jms-resources-and-mdb-container.html[JMS Resources and MDB +Container] + +link:configuring-javamail.html[Configuring JavaMail] + +link:tomee-and-security.html[TomEE Security] + +link:security.html[Security How To] + +link:clients.html[EJB Clients] + +link:ejb-over-ssl.html[EJB over SSL] + +link:jndi-names.html[JNDI Names] + +link:changing-jms-implementations.html[Changing JMS implementations] + +link:tomee-and-hibernate.html[Changing JPA to Hibernate] + +} \{span-one-third ###Testing Techniques +link:application-discovery-via-the-classpath.html[Application discovery +via the classpath] + +link:embedded-configuration.html[Embedded Configuration] + +link:configuring-datasources-in-tests.html[Configuring DataSources in +Tests] + +link:configuring-persistenceunits-in-tests.html[Configuring +PersistenceUnits in Tests] + +link:configuring-containers-in-tests.html[Configuring Containers in +Tests] + +link:configuring-logging-in-tests.html[Configuring Logging in Tests] + +link:alternate-descriptors.html[Alternate Descriptors] + +link:unit-testing-transactions.html[Unit Testing Transactions] + +link:testcase-with-testbean-inner-class.html[TestCase with TestBean +inner-class] + +[TestCase Injection (@LocalClient)](local-client-injection.html) + +} } \{row + +\{span-one-third ###Discovery and Failover +link:ejb-failover.html[Overview] + +link:multicast-discovery.html[Multicast Discovery (UDP)] + +link:multipulse-discovery.html[Multipulse Discovery (UDP)] + +link:multipoint-discovery.html[Multipoint Discovery (TCP)] + +link:multipoint-considerations.html[Multipoint Considerations] + +link:multipoint-recommendations.html[Multipoint Recommendations] + +link:failover-logging.html[Logging Events] + +} \{span-one-third + +###OpenEJB Standalone Server +link:understanding-the-directory-layout.html[Understanding the Directory +Layout] + +link:startup.html[Startup] + +link:deploy-tool.html[Deploy Tool] + +link:properties-tool.html[Properties Tool] + +} \{span-one-third ###Spring link:spring-and-openejb-3.0.html[Spring and +OpenEJB 3.0] + +link:spring.html[Spring and OpenEJB 3.1 and later] + +link:spring-ejb-and-jpa.html[Spring, EJB and JPA example] + +} } \{row + +\{span-one-third ###Arquillian +link:arquillian-getting-started.html[Arquillian Primer - What you need +to know] + +link:arquillian-available-adapters.html[Using the TomEE Arquillian +adapters] + +} \{span-one-third ###TomEE Maven Plugin +link:tomee-mp-getting-started.html[Getting started] + +link:maven/index.html[tomee-maven-plugin reference documentation] + +link:tomee-embedded-maven-plugin.html[tomee-embedded-maven-plugin +reference documentation] + +link:tomee-mp-getting-started.html[TomEE simple webapp archetype +documentation] + +} \{span-one-third ###Tips and Tricks +link:installation-drop-in-war.html[Install TomEE using the drop-in +WAR] + +link:tip-concurrency.html[Global Concurrency Management] + +link:tip-weblogic.html[WebLogic Lookup] + +link:tip-jersey-client.html[Jersey Client] + +} } http://git-wip-us.apache.org/repos/asf/tomee/blob/b45a3d00/docs/documentation.md ---------------------------------------------------------------------- diff --git a/docs/documentation.md b/docs/documentation.md deleted file mode 100644 index 2310807..0000000 --- a/docs/documentation.md +++ /dev/null @@ -1,106 +0,0 @@ -index-group=Unrevised -type=page -status=published -title=Documentation -~~~~~~ - -See also the [examples page](examples-trunk/index.html) for downloadable, executable and code-focused view of Java EE and TomEE. -You can also find us on IRC freenode.org #openejb and #tomee - -{row - -{span-one-third -###IDE -[Get started with Intellij](tomee-and-intellij.html), [Debugging in Intellij](contrib/debug/debug-intellij.html) -[Get started with Eclipse (WTP)](tomee-and-eclipse.html) -[Get started with Eclipse (m2e-Webby)](getting-started-with-eclipse-and-webby.html) -[Get started with Netbeans](tomee-and-netbeans.html) - -###General Informations -[Comparison: OpenEJB, TomEE, TomEE+](comparison.html) -[TomEE Directory structure](tomee-directory-structure.html) -[Deploying in TomEE](deploying-in-tomee.html) -[The 'tomee' webapp](tomee-webapp.html) -[TomEE Reference Card](refcard/refcard.html) -[ApplicationComposer](application-composer/index.html) -} -{span-one-third -###Configuration -[System Properties](system-properties.html) -[Deployments](deployments.html) -[Configuring Resources](Configuring-in-tomee.html) -[Configuring DataSources](configuring-datasources.html) -[Containers and Resources](containers-and-resources.html) -[JMS Resources and MDB Container](jms-resources-and-mdb-container.html) -[Configuring JavaMail](configuring-javamail.html) -[TomEE Security](tomee-and-security.html) -[Security How To](security.html) -[EJB Clients](clients.html) -[EJB over SSL](ejb-over-ssl.html) -[JNDI Names](jndi-names.html) -[Changing JMS implementations](changing-jms-implementations.html) -[Changing JPA to Hibernate](tomee-and-hibernate.html) -} -{span-one-third -###Testing Techniques -[Application discovery via the classpath](application-discovery-via-the-classpath.html) -[Embedded Configuration](embedded-configuration.html) -[Configuring DataSources in Tests](configuring-datasources-in-tests.html) -[Configuring PersistenceUnits in Tests](configuring-persistenceunits-in-tests.html) -[Configuring Containers in Tests](configuring-containers-in-tests.html) -[Configuring Logging in Tests](configuring-logging-in-tests.html) -[Alternate Descriptors](alternate-descriptors.html) -[Unit Testing Transactions](unit-testing-transactions.html) -[TestCase with TestBean inner-class](testcase-with-testbean-inner-class.html) -[TestCase Injection (@LocalClient)](local-client-injection.html) -} -} -{row - -{span-one-third -###Discovery and Failover -[Overview](ejb-failover.html) -[Multicast Discovery (UDP)](multicast-discovery.html) -[Multipulse Discovery (UDP)](multipulse-discovery.html) -[Multipoint Discovery (TCP)](multipoint-discovery.html) -[Multipoint Considerations](multipoint-considerations.html) -[Multipoint Recommendations](multipoint-recommendations.html) -[Logging Events](failover-logging.html) -} -{span-one-third - -###OpenEJB Standalone Server -[Understanding the Directory Layout](understanding-the-directory-layout.html) -[Startup](startup.html) -[Deploy Tool](deploy-tool.html) -[Properties Tool](properties-tool.html) -} -{span-one-third -###Spring -[Spring and OpenEJB 3.0](spring-and-openejb-3.0.html) -[Spring and OpenEJB 3.1 and later](spring.html) -[Spring, EJB and JPA example](spring-ejb-and-jpa.html) -} -} -{row - -{span-one-third -###Arquillian -[Arquillian Primer - What you need to know](arquillian-getting-started.html) -[Using the TomEE Arquillian adapters](arquillian-available-adapters.html) -} -{span-one-third -###TomEE Maven Plugin -[Getting started](tomee-mp-getting-started.html) -[tomee-maven-plugin reference documentation](maven/index.html) -[tomee-embedded-maven-plugin reference documentation](tomee-embedded-maven-plugin.html) -[TomEE simple webapp archetype documentation](tomee-mp-getting-started.html) -} -{span-one-third -###Tips and Tricks -[Install TomEE using the drop-in WAR](installation-drop-in-war.html) -[Global Concurrency Management](tip-concurrency.html) -[WebLogic Lookup](tip-weblogic.html) -[Jersey Client](tip-jersey-client.html) -} -} http://git-wip-us.apache.org/repos/asf/tomee/blob/b45a3d00/docs/documentation.old.adoc ---------------------------------------------------------------------- diff --git a/docs/documentation.old.adoc b/docs/documentation.old.adoc new file mode 100644 index 0000000..c7fe243 --- /dev/null +++ b/docs/documentation.old.adoc @@ -0,0 +1,98 @@ +Title: Documentation + +See also the link:examples-trunk/index.html[examples page] for +downloadable, executable and code-focused view of Java EE and TomEE. You +can also find us on IRC freenode.org #openejb and #tomee + +\{row + +\{span-one-third ###IDE link:tomee-and-intellij.html[Get started with +Intellij], link:contrib/debug/debug-intellij.html[Debugging in +Intellij] + +link:tomee-and-eclipse.html[Get started with Eclipse (WTP)] + +link:getting-started-with-eclipse-and-webby.html[Get started with +Eclipse (m2e-Webby)] + +link:tomee-and-netbeans.html[Get started with Netbeans] + +###General Informations link:comparison.html[Comparison: OpenEJB, TomEE, +TomEE+] + +link:tomee-directory-structure.html[TomEE Directory structure] + +link:deploying-in-tomee.html[Deploying in TomEE] + +link:tomee-webapp.html[The 'tomee' webapp] + +link:refcard/refcard.html[TomEE Reference Card] + +link:application-composer/index.html[ApplicationComposer] + +} \{span-one-third ###Configuration link:system-properties.html[System +Properties] + +link:deployments.html[Deployments] + +link:Configuring-in-tomee.html[Configuring Resources] + +link:configuring-datasources.html[Configuring DataSources] + +link:containers-and-resources.html[Containers and Resources] + +link:jms-resources-and-mdb-container.html[JMS Resources and MDB +Container] + +link:configuring-javamail.html[Configuring JavaMail] + +link:tomee-and-security.html[TomEE Security] + +link:security.html[Security How To] + +link:clients.html[EJB Clients] + +link:ejb-over-ssl.html[EJB over SSL] + +link:jndi-names.html[JNDI Names] + +link:changing-jms-implementations.html[Changing JMS implementations] + +link:tomee-and-hibernate.html[Changing JPA to Hibernate] + +} \{span-one-third ###Testing Techniques +link:application-discovery-via-the-classpath.html[Application discovery +via the classpath] + +link:embedded-configuration.html[Embedded Configuration] + +link:configuring-datasources-in-tests.html[Configuring DataSources in +Tests] + +link:configuring-persistenceunits-in-tests.html[Configuring +PersistenceUnits in Tests] + +link:configuring-containers-in-tests.html[Configuring Containers in +Tests] + +link:configuring-logging-in-tests.html[Configuring Logging in Tests] + +link:alternate-descriptors.html[Alternate Descriptors] + +link:unit-testing-transactions.html[Unit Testing Transactions] + +link:testcase-with-testbean-inner-class.html[TestCase with TestBean +inner-class] + +[TestCase Injection (@LocalClient)](local-client-injection.html) + +} } \{row + +\{span-one-third ###Discovery and Failover +link:ejb-failover.html[Overview] + +link:multicast-discovery.html[Multicast Discovery (UDP)] + +link:multipulse-discovery.html[Multipulse Discovery (UDP)] + +link:multipoint-discovery.html[Multipoint Discovery (TCP)] + +link:multipoint-considerations.html[Multipoint Considerations] + +link:multipoint-recommendations.html[Multipoint Recommendations] + +link:failover-logging.html[Logging Events] + +} \{span-one-third + +###OpenEJB Standalone Server +link:understanding-the-directory-layout.html[Understanding the Directory +Layout] + +link:startup.html[Startup] + +link:deploy-tool.html[Deploy Tool] + +link:properties-tool.html[Properties Tool] + +} \{span-one-third ###Spring link:spring-and-openejb-3.0.html[Spring and +OpenEJB 3.0] + +link:spring.html[Spring and OpenEJB 3.1 and later] + +link:spring-ejb-and-jpa.html[Spring, EJB and JPA example] + +} } \{row + +\{span-one-third ###Arquillian +link:arquillian-getting-started.html[Arquillian Primer - What you need +to know] + +link:arquillian-available-adapters.html[Using the TomEE Arquillian +adapters] + +} \{span-one-third ###TomEE Maven Plugin +link:tomee-mp-getting-started.html[Getting started] + +link:maven/index.html[tomee-maven-plugin reference documentation] + +link:tomee-embedded-maven-plugin.html[tomee-embedded-maven-plugin +reference documentation] + +link:tomee-mp-getting-started.html[TomEE simple webapp archetype +documentation] + +} \{span-one-third ###Tips and Tricks +link:installation-drop-in-war.html[Install TomEE using the drop-in +WAR] + +link:tip-concurrency.html[Global Concurrency Management] + +link:tip-weblogic.html[WebLogic Lookup] + +link:tip-jersey-client.html[Jersey Client] + +} } http://git-wip-us.apache.org/repos/asf/tomee/blob/b45a3d00/docs/documentation.old.md ---------------------------------------------------------------------- diff --git a/docs/documentation.old.md b/docs/documentation.old.md deleted file mode 100644 index b0f4238..0000000 --- a/docs/documentation.old.md +++ /dev/null @@ -1,102 +0,0 @@ -Title: Documentation - -See also the [examples page](examples-trunk/index.html) for downloadable, executable and code-focused view of Java EE and TomEE. -You can also find us on IRC freenode.org #openejb and #tomee - -{row - -{span-one-third -###IDE -[Get started with Intellij](tomee-and-intellij.html), [Debugging in Intellij](contrib/debug/debug-intellij.html) -[Get started with Eclipse (WTP)](tomee-and-eclipse.html) -[Get started with Eclipse (m2e-Webby)](getting-started-with-eclipse-and-webby.html) -[Get started with Netbeans](tomee-and-netbeans.html) - -###General Informations -[Comparison: OpenEJB, TomEE, TomEE+](comparison.html) -[TomEE Directory structure](tomee-directory-structure.html) -[Deploying in TomEE](deploying-in-tomee.html) -[The 'tomee' webapp](tomee-webapp.html) -[TomEE Reference Card](refcard/refcard.html) -[ApplicationComposer](application-composer/index.html) -} -{span-one-third -###Configuration -[System Properties](system-properties.html) -[Deployments](deployments.html) -[Configuring Resources](Configuring-in-tomee.html) -[Configuring DataSources](configuring-datasources.html) -[Containers and Resources](containers-and-resources.html) -[JMS Resources and MDB Container](jms-resources-and-mdb-container.html) -[Configuring JavaMail](configuring-javamail.html) -[TomEE Security](tomee-and-security.html) -[Security How To](security.html) -[EJB Clients](clients.html) -[EJB over SSL](ejb-over-ssl.html) -[JNDI Names](jndi-names.html) -[Changing JMS implementations](changing-jms-implementations.html) -[Changing JPA to Hibernate](tomee-and-hibernate.html) -} -{span-one-third -###Testing Techniques -[Application discovery via the classpath](application-discovery-via-the-classpath.html) -[Embedded Configuration](embedded-configuration.html) -[Configuring DataSources in Tests](configuring-datasources-in-tests.html) -[Configuring PersistenceUnits in Tests](configuring-persistenceunits-in-tests.html) -[Configuring Containers in Tests](configuring-containers-in-tests.html) -[Configuring Logging in Tests](configuring-logging-in-tests.html) -[Alternate Descriptors](alternate-descriptors.html) -[Unit Testing Transactions](unit-testing-transactions.html) -[TestCase with TestBean inner-class](testcase-with-testbean-inner-class.html) -[TestCase Injection (@LocalClient)](local-client-injection.html) -} -} -{row - -{span-one-third -###Discovery and Failover -[Overview](ejb-failover.html) -[Multicast Discovery (UDP)](multicast-discovery.html) -[Multipulse Discovery (UDP)](multipulse-discovery.html) -[Multipoint Discovery (TCP)](multipoint-discovery.html) -[Multipoint Considerations](multipoint-considerations.html) -[Multipoint Recommendations](multipoint-recommendations.html) -[Logging Events](failover-logging.html) -} -{span-one-third - -###OpenEJB Standalone Server -[Understanding the Directory Layout](understanding-the-directory-layout.html) -[Startup](startup.html) -[Deploy Tool](deploy-tool.html) -[Properties Tool](properties-tool.html) -} -{span-one-third -###Spring -[Spring and OpenEJB 3.0](spring-and-openejb-3.0.html) -[Spring and OpenEJB 3.1 and later](spring.html) -[Spring, EJB and JPA example](spring-ejb-and-jpa.html) -} -} -{row - -{span-one-third -###Arquillian -[Arquillian Primer - What you need to know](arquillian-getting-started.html) -[Using the TomEE Arquillian adapters](arquillian-available-adapters.html) -} -{span-one-third -###TomEE Maven Plugin -[Getting started](tomee-mp-getting-started.html) -[tomee-maven-plugin reference documentation](maven/index.html) -[tomee-embedded-maven-plugin reference documentation](tomee-embedded-maven-plugin.html) -[TomEE simple webapp archetype documentation](tomee-mp-getting-started.html) -} -{span-one-third -###Tips and Tricks -[Install TomEE using the drop-in WAR](installation-drop-in-war.html) -[Global Concurrency Management](tip-concurrency.html) -[WebLogic Lookup](tip-weblogic.html) -[Jersey Client](tip-jersey-client.html) -} -} http://git-wip-us.apache.org/repos/asf/tomee/blob/b45a3d00/docs/dynamic-datasource.adoc ---------------------------------------------------------------------- diff --git a/docs/dynamic-datasource.adoc b/docs/dynamic-datasource.adoc new file mode 100644 index 0000000..95bf338 --- /dev/null +++ b/docs/dynamic-datasource.adoc @@ -0,0 +1,219 @@ +# Dynamic Datasource +:index-group: Unrevised +:jbake-date: 2018-12-05 +:jbake-type: page +:jbake-status: published + +# OpenEJB dynamic datasource + +== Goal + +The openejb dynamic datasource api aims to allow to use multiple data +sources as one. + +It can be useful for technical reasons (load balancing for example) or +functionnal reasons (filtering, aggregation, enriching...). + +== The API + +The interface Router (_org.apache.openejb.resource.jdbc.Router_) have +only one method to get the datasource to use: + +.... +Router.getDataSource() +.... + +The _org.apache.openejb.resource.jdbc.RoutedDataSource_ wraps a +classical data source. It has to be used to declare your datasource. + +You can implement all the policy you want in your Router implementation. + +A class called _org.apache.openejb.resource.jdbc.AbstractRouter_ is +available to ease router development. + +== Known limitation(s) + +You have to use the same kind of databases (same version, same +configuration...). + +All database have to be created when you use the router. The way to do +it automatically can depend of your JPA provider. + +=== OpenJPA + +OpenJPA initializes its database when the entitymanager is called for +the first time so you need to initialize all your proxied datasource +before using the other one. It can be done using an Init EJB doing a +find() on each proxied datasource. + +=== Hibernate + +Hibernate initializes the database when it starts so if you declare a +persistence unit by database all databases will be initialized at the +start up. + +== Example + +=== The story (the unit test example) + +You want to use only one datasource in the code but you have a criteria +to set to choose the real database to use between three. + +So in your code you want something like: + +.... +public class RoutedEJBBean { + @PersistenceContext(unitName = "router") + private EntityManager em; + + // this router is not automatic, we + // need it to select the database to use + @Resource(name = "My Router") + private DeterminedRouter router; + + public void persist(int id, String name, String clientDatasource) { + router.setDataSource(clientDatasource); + em.persist(new Person(id, name)); + } +} +.... + +== The router implementation + +The router will simply manage a map to store proxied datasources and a +field to store the datasource used in the current thread (ThreadLocal). + +.... +public class DeterminedRouter implements Router { + private String dataSourceNames; // used to store configuration (openejb.xml) + private String defaultDataSourceName; // defautl data source name + private Map<String, DataSource> dataSources = null; // proxied data sources + private ThreadLocal<DataSource> currentDataSource = new ThreadLocal<DataSource>(); // the datasource to use or null + + /** + * @param datasourceList datasource resource name, separator is a space + */ + public void setDataSourceNames(String datasourceList) { + dataSourceNames = datasourceList; + } + + /** + * lookup datasource in openejb resources + */ + private void init() { // looking up datasources declared as proxied + dataSources = new ConcurrentHashMap<String, DataSource>(); + for (String ds : dataSourceNames.split(" ")) { + ContainerSystem containerSystem = SystemInstance.get().getComponent(ContainerSystem.class); + + Object o = null; + Context ctx = containerSystem.getJNDIContext(); + try { + o = ctx.lookup("openejb:Resource/" + ds); + if (o instanceof DataSource) { + dataSources.put(ds, (DataSource) o); + } + } catch (NamingException ignore) { + } + } + } + + /** + * @return the user selected data source if it is set + * or the default one + * @throws IllegalArgumentException if the data source is not found + */ + public DataSource getDataSource() { + // lazy init of routed datasources + if (dataSources == null) { + init(); + } + + // if no datasource is selected use the default one + if (currentDataSource.get() == null) { + if (dataSources.containsKey(defaultDataSourceName)) { + return dataSources.get(defaultDataSourceName); + + } else { + throw new IllegalArgumentException("you have to specify at least one datasource"); + } + } + + // the developper set the datasource to use + return currentDataSource.get(); + } + + /** + * + * @param datasourceName data source name + */ + public void setDataSource(String datasourceName) { + if (dataSources == null) { + init(); + } + if (!dataSources.containsKey(datasourceName)) { + throw new IllegalArgumentException("data source called " + datasourceName + " can't be found."); + } + DataSource ds = dataSources.get(datasourceName); + currentDataSource.set(ds); + } + + public void setDefaultDataSourceName(String name) { + this.defaultDataSourceName = name; + } +} +.... + +== Creation of the service provider for the router + +To be able to use your router add a file called service-jar.xml under +META-INF/. For example META-INF/org.router. + +This file will contain something like: + +.... +<ServiceJar> + <ServiceProvider id="DeterminedRouter" service="Resource" + type="org.apache.openejb.resource.jdbc.Router" class-name="implementation class"> + Param defaultValue + ParamWithNoDefaultValue + </ServiceProvider> +</ServiceJar> +.... + +== openejb.xml + +In the openejb.xml file, you have to declare your dynamic database and +in our example it needs the proxied datasources too: + +.... +<Resource id="router" type="<your implementation>" provider="<your provider>"> + Param value +</Resource> + +<Resource id="route db" type="DataSource" provider="RoutedDataSource"> + Router router +</Resource> + +<!â- real databases â for our example --> +<Resource id="db1" type="DataSource"> + JdbcDriver org.hsqldb.jdbcDriver + JdbcUrl jdbc:hsqldb:mem:db1 + UserName sa + Password + JtaManaged true +</Resource> +<Resource id="db2" type="DataSource"> + JdbcDriver org.hsqldb.jdbcDriver + JdbcUrl jdbc:hsqldb:mem:db2 + UserName sa + Password + JtaManaged true +</Resource> +<Resource id="db3" type="DataSource"> + JdbcDriver org.hsqldb.jdbcDriver + JdbcUrl jdbc:hsqldb:mem:db3 + UserName sa + Password + JtaManaged true +</Resource> +.... http://git-wip-us.apache.org/repos/asf/tomee/blob/b45a3d00/docs/dynamic-datasource.md ---------------------------------------------------------------------- diff --git a/docs/dynamic-datasource.md b/docs/dynamic-datasource.md deleted file mode 100644 index 5f7ca11..0000000 --- a/docs/dynamic-datasource.md +++ /dev/null @@ -1,220 +0,0 @@ -index-group=Unrevised -type=page -status=published -title=Dynamic Datasource -~~~~~~ -<a name="DynamicDatasource-OpenEJBdynamicdatasource"></a> -# OpenEJB dynamic datasource - -<a name="DynamicDatasource-Goal"></a> -## Goal - -The openejb dynamic datasource api aims to allow to use multiple data -sources as one. - -It can be useful for technical reasons (load balancing for example) or -functionnal reasons (filtering, aggregation, enriching...). - -<a name="DynamicDatasource-TheAPI"></a> -## The API - -The interface Router (*org.apache.openejb.resource.jdbc.Router*) have -only one method to get the datasource to use: - - Router.getDataSource() - -The *org.apache.openejb.resource.jdbc.RoutedDataSource* wraps a classical -data source. It has to be used to declare your datasource. - -You can implement all the policy you want in your Router implementation. - -A class called *org.apache.openejb.resource.jdbc.AbstractRouter* is -available to ease router development. - -<a name="DynamicDatasource-Knownlimitation(s)"></a> -## Known limitation(s) - -You have to use the same kind of databases (same version, same -configuration...). - -All database have to be created when you use the router. The way to do it -automatically can depend of your JPA provider. - -<a name="DynamicDatasource-OpenJPA"></a> -### OpenJPA - -OpenJPA initializes its database when the entitymanager is called for the -first time so you need to initialize all your proxied datasource before -using the other one. It can be done using an Init EJB doing a find() on -each proxied datasource. - -<a name="DynamicDatasource-Hibernate"></a> -### Hibernate - -Hibernate initializes the database when it starts so if you declare a -persistence unit by database all databases will be initialized at the start -up. - -<a name="DynamicDatasource-Example"></a> -## Example - -<a name="DynamicDatasource-Thestory(theunittestexample)"></a> -### The story (the unit test example) - -You want to use only one datasource in the code but you have a criteria to -set to choose the real database to use between three. - -So in your code you want something like: - - public class RoutedEJBBean { - @PersistenceContext(unitName = "router") - private EntityManager em; - - // this router is not automatic, we - // need it to select the database to use - @Resource(name = "My Router") - private DeterminedRouter router; - - public void persist(int id, String name, String clientDatasource) { - router.setDataSource(clientDatasource); - em.persist(new Person(id, name)); - } - } - - -<a name="DynamicDatasource-Therouterimplementation"></a> -## The router implementation - -The router will simply manage a map to store proxied datasources and a -field to store the datasource used in the current thread (ThreadLocal). - - public class DeterminedRouter implements Router { - private String dataSourceNames; // used to store configuration (openejb.xml) - private String defaultDataSourceName; // defautl data source name - private Map<String, DataSource> dataSources = null; // proxied data sources - private ThreadLocal<DataSource> currentDataSource = new ThreadLocal<DataSource>(); // the datasource to use or null - - /** - * @param datasourceList datasource resource name, separator is a space - */ - public void setDataSourceNames(String datasourceList) { - dataSourceNames = datasourceList; - } - - /** - * lookup datasource in openejb resources - */ - private void init() { // looking up datasources declared as proxied - dataSources = new ConcurrentHashMap<String, DataSource>(); - for (String ds : dataSourceNames.split(" ")) { - ContainerSystem containerSystem = SystemInstance.get().getComponent(ContainerSystem.class); - - Object o = null; - Context ctx = containerSystem.getJNDIContext(); - try { - o = ctx.lookup("openejb:Resource/" + ds); - if (o instanceof DataSource) { - dataSources.put(ds, (DataSource) o); - } - } catch (NamingException ignore) { - } - } - } - - /** - * @return the user selected data source if it is set - * or the default one - * @throws IllegalArgumentException if the data source is not found - */ - public DataSource getDataSource() { - // lazy init of routed datasources - if (dataSources == null) { - init(); - } - - // if no datasource is selected use the default one - if (currentDataSource.get() == null) { - if (dataSources.containsKey(defaultDataSourceName)) { - return dataSources.get(defaultDataSourceName); - - } else { - throw new IllegalArgumentException("you have to specify at least one datasource"); - } - } - - // the developper set the datasource to use - return currentDataSource.get(); - } - - /** - * - * @param datasourceName data source name - */ - public void setDataSource(String datasourceName) { - if (dataSources == null) { - init(); - } - if (!dataSources.containsKey(datasourceName)) { - throw new IllegalArgumentException("data source called " + datasourceName + " can't be found."); - } - DataSource ds = dataSources.get(datasourceName); - currentDataSource.set(ds); - } - - public void setDefaultDataSourceName(String name) { - this.defaultDataSourceName = name; - } - } - - -<a name="DynamicDatasource-Creationoftheserviceproviderfortherouter"></a> -## Creation of the service provider for the router - -To be able to use your router add a file called service-jar.xml under -META-INF/<package>. For example META-INF/org.router. - -This file will contain something like: - - <ServiceJar> - <ServiceProvider id="DeterminedRouter" service="Resource" - type="org.apache.openejb.resource.jdbc.Router" class-name="implementation class"> - Param defaultValue - ParamWithNoDefaultValue - </ServiceProvider> - </ServiceJar> - -## openejb.xml - -In the openejb.xml file, you have to declare your dynamic database and in -our example it needs the proxied datasources too: - - <Resource id="router" type="<your implementation>" provider="<your provider>"> - Param value - </Resource> - - <Resource id="route db" type="DataSource" provider="RoutedDataSource"> - Router router - </Resource> - - <!â- real databases â for our example --> - <Resource id="db1" type="DataSource"> - JdbcDriver org.hsqldb.jdbcDriver - JdbcUrl jdbc:hsqldb:mem:db1 - UserName sa - Password - JtaManaged true - </Resource> - <Resource id="db2" type="DataSource"> - JdbcDriver org.hsqldb.jdbcDriver - JdbcUrl jdbc:hsqldb:mem:db2 - UserName sa - Password - JtaManaged true - </Resource> - <Resource id="db3" type="DataSource"> - JdbcDriver org.hsqldb.jdbcDriver - JdbcUrl jdbc:hsqldb:mem:db3 - UserName sa - Password - JtaManaged true - </Resource>
