Running multiple application instances with Orion

[Kurt Hoyt]

I've put together a how-to on running the same J2EE application, but with
each instance using a different data source, using Orion. It would be nice
if there was a simpler way to do this (particularly in associating data
sources with applications, which causes the bulk of the work).

If the orionsupport.com folks are listening, you have my permission to add
this to your site (just be sure to give credit where due).

Kurt in Atlanta

Title: Running Multiple Application Instances with Orion

Running Multiple Application Instances with Orion

Kurt Hoyt ([EMAIL PROTECTED])

This document assumes you know how to create an EJB .jar file, a web application's .war file, and a J2EE application's .ear file. All this document does is describe the changes you need to make in order to run multiple instances of the same application within the same instance of Orion (one JVM running on one computer), with each instance using its own data source.

The data-sources.xml file

Create the data source entry in Orion’s config/data-sources.xml file. Here are the two data sources I created, one for SQL Server and one for Oracle:

   <data-source
      class="com.evermind.sql.DriverManagerDataSource"
      name="SQLServer"
      schema="database-schemas/ms-sql.xml"
      location="jdbc/SQLServerCoreDS"
      xa-location="jdbc/xa/SQLServerXADS"
      ejb-location="jdbc/SQLServerDS"
      connection-driver="com.inet.tds.TdsDriver"
      username="orion"
      password="orion"
      url="jdbc:inetdae7:SQLServerHost:1433?database=orion"
      inactivity-timeout="30"
   />
   <data-source
      class="com.evermind.sql.DriverManagerDataSource"
      name="Oracle"
      schema="database-schemas/oracle.xml"
      location="jdbc/OracleCoreDS"
      xa-location="jdbc/xa/OracleXADS"
      ejb-location="jdbc/OracleDS"
      connection-driver="oracle.jdbc.driver.OracleDriver"
      username="orion"
      password="orion"
      url="jdbc:oracle:thin:@OracleHost:1521:orionora"
      inactivity-timeout="30"
   />

Notice that the ejb-locations are different between the two data sources. Each data source will need a unique ejb-location (and the other locations). Notice the naming convention: jdbc/<some-name>DS for the ejb-location, jdbc/<some-name>CoreDS for the location, and jdbc/xa/<some-name>XADS for the xa-location (xa = transactional). There is also a pooled-location that can be used if the data source needs to be accessed from outside the EJB server (like inside a JSP).

It’s the ejb-location that you’ll need for the orion-ejb-jar.xml file. There will be a 1:1 relationship between each application instance and its data source.

The orion-ejb-jar.xml file


Once you have a data source set up, you have to tell Orion to use that data source
for the tables it creates for the entity beans in the EJB jar file (which I’ll
call “myapp-ejb.jar” for discussion purposes). You do that by editing the
orion/orion-ejb-jar.xml file that you’ll put inside the myapp-ejb.jar file.
This means that you will have a different myapp-ejb.jar file for each
application instance, with the only difference being the contents of the
orion-ejb-jar.xml file.


For each entity bean, you tell Orion which data source from the
config/data-sources.xml file to use:


   <entity-deployment name="Customer" table="Customer" data-source="jdbc/OracleDS">
   .
   .
   .
   </entity-deployment>



This is the skeleton for the Oracle version of the Content
entity bean deployment. The <entity-deployment> tag sits inside the
<enterprise-beans> tag inside the <orion-ejb-jar> tag inside the
orion-ejb-jar.xml file. Notice the data-source attribute in the
<entity-deployment> tag. That’s how the connection is made. The
data-source attribute must be set for each entity bean, so each entity bean
must represented with an <entity-deployment> tag inside the file. For SQL
Server, the same skeleton looks like this:


   <entity-deployment name="Customer" table="Customer" data-source="jdbc/SQLServerDS">
   .
   .
   .
   </entity-deployment>


You can see how each version uses a different data source.


I saved the Oracle version in a file called oracle-orion-ejb-jar.xml and the SQL
Server version in a file called sqlserver-orion-ejb-jar.xml. It should be
simple to create some kind of database-neutral skeletons that could be run
through some filter program that would assign the data source for you.


Build the myapp-ejb.jar file


To build the myapp-ejb.jar file, you need to have this directory structure
somewhere:

   mypackage/*.class (the EJB remote, home and bean classes)
   META-INF/ejb-jar.xml
   orion/orion-ejb-jar.xml


Once you have that structure, you can use the jar program to create the EJB jar file:

   jar cvf myapp-ejb.jar mypackage/*.class META-INF/ejb-jar.xml orion/orion-ejb-jar.xml


Copy the new myapp-ejb.jar file to the directory in which you will build the .ear file.


Build the myapp-web.war file


You need to go to the web application’s application.xml file and set the
<web-uri> entry for the myapp-web web module to myapp-web.war. That will
tell Orion to use a .war file to find all the web files (from .html and .jsp
pages to servlets and other helper classes) that are part of the application in
the .war file and not in the file system. The application.xml file should look
like this:

<?xml version="1.0"?>
<!DOCTYPE application PUBLIC "-//Sun Microsystems, Inc.//DTD J2EE Application 1.2//EN"
   "http://java.sun.com/j2ee/dtds/application_1_2.dtd">

<application>
   <display-name>My Application</display-name>
   <module>
      <ejb>counter.jar</ejb>
   </module>
   <module>
      <ejb>myapp-ejb.jar</ejb>
   </module>
   <module>
      <web>
         <web-uri>myapp-web.war</web-uri>
         <context-root>/</context-root>
      </web>
   </module>
</application>


All you have to do to build that .war file is go to the web application’s directory
(the one with the WEB-INF directory in it) and run the jar program:

   jar cvf ../myapp-web.war .


This will put the myapp-web.war file into the parent directory. Copy myapp-web.war
to the same directory you stored the counter.jar and myapp-ejb.jar files and META-INF
directory (containing the application.xml file). You are now ready to build the .ear
file for the client.


Build the client’s .ear file


Once you have the myapp-web.war file built, the build directory should contain at
least these items: counter.jar, myapp-ejb.jar, myapp-web.war and a META-INF
directory with an application.xml file in it. To build the .ear file, you use
the jar program again:

   jar cvf myapp1.ear counter.jar myapp-ejb.jar myapp-web.war META-INF/application.xml


You now have a .ear file (which I’ve called “myapp1.jar” for discussion) in your
build directory.


Deploy the .ear file


First, copy the .ear file to the /orion/applications directory. Then, you’ll need to
edit the config/server.xml file and config/default-web-site.xml file.


In the server.xml file, you would add a line inside the <application-server>
tags that looks like this:

   <application name="myapp1" path="../applications/myapp1.ear"/>


The name attribute is important. You’ll be using it in the next configuration file
to connect the J2EE application and the web application inside the file. The path
tells Orion where the .ear file is. By convention, they are put in the
/orion/applications directory. Since the server.xml file is in the /orion/config
directory, you can use the “..” to go up and over to the applications directory.


In the default-web-site.xml file, you and a web application entry to connect the
web application inside the .ear file to the web server’s virtual file system
tree:

   <web-app application="myapp1" name="myapp-web" root="/myapp1"/>


The application attribute is the application’s name from the server.xml file. The
name attribute is the name of the web application inside the .ear file. Orion
will look for a web module in the .ear file’s META-INF/application.xml file
named either “myapp-web” or “myapp-web.war”. The root attribute tells Orion the
virtual web root of the application. In this case, web pages (like the .html
and .jsp files) will be found under http://www.yourserver.com/myapp1. For
example, http://www.yourserver.com/myapp1/index.html would bring up the home
page.


Start Orion


You should be able to start Orion at this point and see the new application get
deployed. If Orion is running, you should be able to edit the default-web-site.xml
file followed by the server.xml file and Orion should notice that server.xml
has changed and automatically deploy it for you. It seems safer to me to bring
down Orion before making the configuration file changes.


You can repeat the process above for each deployment of the same application. Just
make sure the data sources are connected properly in the orion-ejb-jar.xml file
each time you build the myapp-ejb.jar file to include in the new .ear file you
build. And, make sure to use unique names in the server.xml and
default-web-site.xml files. I’ve successfully run multiple copies of the same
application, each talking to different data sources using these techniques.
Enjoy.