 |
Practical Deployment on JBoss Application Server
In this section you will see how the previous steps can be applied to a real world application server. You will learn how to deploy and run your openMDX EJBs in practice. To do this the JBoss Application Server was chosen because it is an open source yet production quality application server that is available to everyone for free.
Prerequisites
The lab has been deployed and verified on JBoss Application Server 3.2.2 and 3.2.3. However this does not mean that it does not run on newer or older versions of JBoss Application Server.
In the following sections we will use the default configuration of JBoss Application Server to deploy and run the lab example. Simply adapt the described steps to deploy and run using the minimal, all or any other configuration if required.
For convenience we have used the open source JBoss IDE plugin for EclipseT to start/stop JBoss Application Server and to deploy Enterprise JavaBeans applications on it. However this is no requirement at all.
For more information on JBoss Application Server and JBoss IDE plugin for Eclipse please refer to http://www.jboss.org.
The following sections use the expressions $JBOSS_HOME to specify the JBoss installation directory and $OPENMDX_LAB_HOME to specify the openMDX lab installation directory.
What needs to be done to run my openMDX EJBs on JBoss?
This sections gives a brief overview what needs to be done to deploy and run openMDX EJBs on JBoss Application Server .
Modify the JBoss installation to enable the execution of openMDX EJBs
Deploy the EAR that contains your gateways and provider EJBs
Write an openMDX client
Create a deployment configuration for your openMDX client to access the deployed gateways and provider EJBs
How to modify the JBoss installation to enable the execution of openMDX EJBs?
Copy the current version of the libraries openmdx-kernel.jar and openmdx-base.jar to the directory $JBOSS_HOME/server/default/lib
Modify the JBoss startup script ($JBOSS_HOME/bin/run.bat, $JBOSS_HOME/bin/run.sh or wherever you start JBoss) to include the following system properties:
Example 7-3. Modify JBoss startup script to include the following Java system properties
-Dorg.openmdx.compatibility.kernel.application.j2ee.domain=apps -Dorg.openmdx.compatibility.kernel.application.j2ee.server=server1 -Dorg.openmdx.compatibility.kernel.application.cci.Application.register=org.openmdx.compatibility.kernel.application.j2ee.ApplicationServerManager_1 -Djava.protocol.handler.pkgs=org.openmdx.kernel.url.protocol -Dorg.openmdx.log.config.filename=$OPENMDX_LAB_HOME\build\server.log.properties -Dorg.openmdx.log.path=$OPENMDX_LAB_HOME\build
The following table explains the meaning of the different system properties:
Table 7-3. Explanation of additional JBoss system properties needed to run openMDX applications
Java System Property
Value
org.openmdx.compatibility.kernel.application.j2ee.domain
J2EE domain name, e.g. apps (system property can be omitted in future versions)
org.openmdx.compatibility.kernel.application.j2ee.server
J2EE server name, e.g. server1, within the J2EE domain (system property can be omitted in future versions)
org.openmdx.compatibility.kernel.application.cci.Application.register
tells openMDX which openMDX application startup class to use, must be set to org.openmdx.compatibility.kernel.application.j2ee.ApplicationServerManager_1 (configuration will no longer be needed in future versions)
java.protocol.handler.pkgs
specifies Java custom protocol handlers that will be loaded from the system classpath (please refer to java.net.URLStreamHandler for more information), must include org.openmdx.kernel.url.protocol for openMDX
org.openmdx.log.config.filename
name of log file that configures the log properties
org.openmdx.log.path
output path for the openMDX gateway and provider logs
Do not forget to copy the current version of the libraries openmdx-kernel.jar and openmdx-base.jar to the directory $JBOSS_JOME/server/default/lib every time you upgrade to a new version of openMDX!
How to deploy your EAR that contains the gateways and provider EJBs?
First make sure that the Enterprise Application Archive (EAR) that contains your openMDX gateways and provider Enterprise JavaBeans conforms to the recommended EAR structure. Please refer to EAR layout for more details on this topic.
Specify JNDI names for all EJBs. Declaring JNDI names for EJBs is different for each type of of application server that you choose to deploy to. To deploy on JBoss Application Server separate XML files jboss.xml have to be created which identify the EJBs and supply JNDI names for it.
The following example file jboss.xml (in directory META-INF of gateways.jar) assigns JNDI names to the configured gateway EJBs:
Example 7-4. jboss.xml for gateway EJBs
<?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE jboss PUBLIC "-//JBoss//DTD JBOSS 3.0//EN" "http://www.jboss.org/j2ee/dtd/jboss_3_0.dtd"> <jboss> <enterprise-beans> <session> <ejb-name>gateway_NoOrNew</ejb-name> <jndi-name>org/openmdx/example/lab/gateway/NoOrNew</jndi-name> </session> <session> <ejb-name>gateway_Never</ejb-name> <jndi-name>org/openmdx/example/lab/gateway/Never</jndi-name> </session> <session> <ejb-name>gateway_Mandatory</ejb-name> <jndi-name>org/openmdx/example/lab/gateway/Mandatory</jndi-name> </session> </enterprise-beans> </jboss>The following example file jboss.xml (in directory META-INF of gateways.jar) assigns a JNDI name to the configured provider EJB (here a single provider with transaction attribute Never):
Example 7-5. jboss.xml for provider EJB
<?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE jboss PUBLIC "-//JBoss//DTD JBOSS 3.0//EN" "http://www.jboss.org/j2ee/dtd/jboss_3_0.dtd"> <jboss> <enterprise-beans> <session> <ejb-name>lab_Never</ejb-name> <jndi-name>org/openmdx/example/lab/lab/Never</jndi-name> </session> </enterprise-beans> </jboss>In essence, the code in the files shown above tells the JBoss Application Server to take a specified EJB and to register it with the JBoss JNDI directory under the specified name. After JBoss has performed this task, any client with access to the JBoss JNDI directory can lookup, retrieve and access a desired EJB.
To create the EAR, go to the openmdx-example-lab directory and execute ant all. This will create an EAR named openmdx-example-lab.ear in the openmdx-example-lab/dist directory.
To deploy the created EAR simply copy it from the openmdx-example-lab/dist directory to the JBoss directory $JBOSS_HOME/server/default/deploy.
How to write an openMDX client?
Simply use an existing client for the same model, e.g. use a client from a previous lab example. You do not have to change a single line of code in your existing in-memory client to use it as an EJB client! The only thing that needs to be done is to change the deployment configuration. This is shown in the next section.
How to create a deployment configuration for your openMDX client to access the deployed gateways and provider EJBs?
Basically you need to define how to access the initial JNDI context factory (protocol, host and port) and the JNDI name of the initial gateway gateway_NoOrNew. This can be done by specifying a DataproviderConnector as ResourceAdapter which uses a Dataprovider_1RemoteConnectionFactory to connect to a remote provider. By specifying the URI jnp://localhost:1099/org/openmdx/example/lab/gateway/NoOrNew you tell JBoss where to find the initial JNDI context factory (host localhost and port 1099), which protocol to use (jnp) and which JNDI entry has to be resolved (org/openmdx/example/lab/gateway/NoOrNew) to access gateway_NoOrNew. This entry name has to match the JNDI name that was specified in jboss.xml for gateway_NoOrNew (please refer to How to deploy your EAR that contains the gateways and provider EJBs? for more details).
You do not access the desired provider directly! As you have seen in General Overview, clients always access the desired provider via the initial gateway gateway_NoOrNew.
This DataproviderConnector has references to three different ResourceAdapterStringProperty instances. They configure the values for the container-specific initial JNDI context factory class (JNDI:InitialContextFactory), the user name (BasicPassword:UserName) and the password (BasicPassword:Password) to access the context factory. JBoss uses the class org.jnp.interfaces.NamingContextFactory as initial JNDI context factory. User name and password do not have to be provided at all.
Example 7-6. deployment.configuration.xml
<?xml version="1.0" encoding="ISO-8859-1"?>
<org.openmdx.base.Authority name="org:openmdx:deployment1"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:noNamespaceSchemaLocation="resource:org/openmdx/deployment1/xmi/deployment1_edit.xsd">
<_object/>
<_content>
<provider>
<org.openmdx.base.Provider qualifiedName="org:openmdx">
<_object/>
<_content>
<segment>
<org.openmdx.deployment1.Segment qualifiedName="org:openmdx:example:lab">
<_object/>
<_content>
<configuration>
<org.openmdx.deployment1.Configuration name="memory">
<_object/>
<_content>
<domain>
<org.openmdx.deployment1.Domain name="apps">
<_object/>
<_content>
<deploymentUnit>
<org.openmdx.deployment1.DeploymentUnit name="connectors">
<_object/>
<_content>
<module>
<org.openmdx.deployment1.Module name="labmodel">
<_object/>
<_content>
<resourceAdapter>
<org.openmdx.deployment1.DataproviderConnector name="connector">
<_object>
<connectionFactoryImplementation>
org.openmdx.compatibility.application.dataprovider.transport.ejb.cci.Dataprovider_1RemoteConnectionFactory
</connectionFactoryImplementation>
<uri>
<!-- define protocol, host, port and jndi name (take jndi name from jboss.xml of gateway_NoOrNew) -->
<_item>jnp://localhost:1099/org/openmdx/example/lab/gateway/NoOrNew</_item>
</uri>
<registrationId>org/openmdx/example/lab/noornew/labmodel</registrationId>
</_object>
<_content>
<property>
<org.openmdx.deployment1.ResourceAdapterStringProperty qualifiedName="JNDI:InitialContextFactory">
<_object>
<value>
<!-- class name of InitialContextFactory -->
<_item>org.jnp.interfaces.NamingContextFactory</_item>
</value>
</_object>
<_content/>
</org.openmdx.deployment1.ResourceAdapterStringProperty>
<!-- this InitialContextFactory ignores SECURITY.Principal and SECURITY.Credentials -->
<org.openmdx.deployment1.ResourceAdapterStringProperty qualifiedName="BasicPassword:UserName">
<_object>
<value>
<_item>anonymous</_item>
</value>
</_object>
<_content/>
</org.openmdx.deployment1.ResourceAdapterStringProperty>
<org.openmdx.deployment1.ResourceAdapterStringProperty qualifiedName="BasicPassword:Password">
<_object>
<value>
<_item>anonymous</_item>
</value>
</_object>
<_content/>
</org.openmdx.deployment1.ResourceAdapterStringProperty>
</property>
</_content>
</org.openmdx.deployment1.DataproviderConnector>
</resourceAdapter>
</_content>
</org.openmdx.deployment1.Module>
</module>
</_content>
</org.openmdx.deployment1.DeploymentUnit>
</deploymentUnit>
</_content>
</org.openmdx.deployment1.Domain>
</domain>
</_content>
</org.openmdx.deployment1.Configuration>
</configuration>
</_content>
</org.openmdx.deployment1.Segment>
</segment>
</_content>
</org.openmdx.base.Provider>
</provider>
</_content>
</org.openmdx.base.Authority>You can find this deployment.configuration.xml in the openmdx-example-lab/etc/org.openmdx.example.lab1.appserver.jboss/ directory.
How to run the openMDX client?
To run the openMDX/JBoss client using the provided ant file run.xml, follow these steps:
Go to the openmdx-example-lab directory.
Execute ant -f run.xml clientJBoss
If you want to start an openMDX/JBoss client somewhere else, please make sure that you include the following JBoss jar files on the classpath:
$JBOSS_HOME/client/jboss-client.jar
$JBOSS_HOME/client/jbosssx-client.jar
$JBOSS_HOME/client/jboss-common-client.jar
$JBOSS_HOME/client/jboss-system-client.jar
$JBOSS_HOME/client/jboss-transaction-client.jar
$JBOSS_HOME/client/jnp-client.jar
How to troubleshoot openMDX EJBs?
In case you have problems running your EJB, you have the following possibilities to gather information to help you:
Have a look at the console output of JBoss. In addition to the console, the output can be found in file $JBOSS_HOME/server/default/log/server.log.
Have a look at the openMDX server log output written by the EJB. You can find the server log output in the openmdx-example-lab/build directory. To change the log level detail of this log output, you have to configure the openmdx-example-lab/build/server.log.properties file (by means of setting the entry LogLevel to the value trace, you will produce as many log output entries as possible). For more information about openMDX Logging and Tracing please refer to the appropriate document.
Have a look at the openMDX client log output written by the openMDX client. You can find the client log output in the openmdx-example-lab/build directory. To change the log level detail of this log output, you have to configure the openmdx-example-lab/build/client.log.properties file (by means of setting the entry LogLevel to the value trace, you will produce as many log output entries as possible). For more information about openMDX Logging and Tracing please refer to the appropriate document.