All of OpenEFM's business objects have been implemented as entity EJBs, using "local" interfaces, if you're familiar with J2EE. Remote access to these beans is provided by dint of corresponding "session facade" beans, which are stateless session beans. The entity beans themselves are container-managed (CMP) and are backed by a relational database, which must be configured in the J2EE server (not in OpenEFM).
To run OpenEFM as a J2EE application, you must build and deploy a J2EE EAR archive, which requires that both Java and Apache Ant be installed on your system. (Note that, because OpenEFM is written entirely in Java, it need not be built on the very server where it is to be deployed. You can build the EAR file on a workstation and then deploy it elsewhere.)
Running the command "ant ear-me-roar" from within the ./build directory of the source distribution should produce the file "./out/dist/web/openefm.ear". This default archive is configured for Jboss version 3.2 and should be ready for deployment on that application server. For any other J2EE container, such as Sun Microsystem's reference implementation or IBM's Websphere, some proprietary descriptor files will have to be added to the archive:
Before going any further, you will need to edit OpenEFM's main configuration file, which is ./web/admin/WEB-INF/config.xml. Look in this file for two XML elements, <model> and <id-factory>. For each of these, there is an Ozone-based implementation (for standalone mode) and an EJB mode (you'll notice the characters "EJB" appearing in the names of these elements). Uncomment the two EJB elements, and comment out the two they replace. There are also a number of ports appearing within URI values in that file, and some of those may need to be changed according to your environment.
For J2EE applications of any complexity, certain configuration files (normally XML) must be present in the EAR file, which are proprietary to the specific J2EE server being used. (This seems to run counter to J2EE's goal of portability, but it is the reality at present.) Additionally, some server-specific configuration may need to be done outside of the EAR file, among the J2EE server's own installation files. I cannot speak for every J2EE application server, so I will describe what I had to do for JBoss, and hopefully you can extrapolate from that according to your own server products.
To add your proprietary descriptor files to the OpenEFM EAR, you will need to rebuild it, using the Ant build files under ./build. Place your descriptor files in ./build/j2ee/, then modify build-j2ee.xml (in that same directory) to include them. At this point you should be able to cd to ./build and there invoke the command "ant ear-me-roar", which will rebuild the EAR and place it in an output directory ("./out/dist/web/"). See this site for information on using Ant.
Your J2EE container will need access to an RDBMS, for container-managed entity persistence. JBoss comes with an embedded system, which should work. No advanced database features are required. I used a separate installation of MySQL, for which I had to configure JBoss. Whatever database you use, you will need to expose a JNDI data source named "java/efm-db", since OpenEFM will reference that name to procure its database connections. This is where you may need to configure your J2EE server directly.
You will probably need to create OpenEFM's database manually and then add a user to it, granting more or less complete access to that database. (This user's login information should be specified where the JNDI datasource is defined. In my case, this was in an XML file, "msql-ds.xml", which I copied into JBoss's deployment directory.) With MySQL, this was accomplished by running the command:
mysqladmin create efm
to create a database called "efm", and then executing "mysql efm" in order to create the user:
GRANT ALL PRIVILEGES ON efm.* TO 'username'@'localhost.localdomain' IDENTIFIED BY 'password' WITH GRANT OPTION ;
(Be sure to replace "username" and "password" with sensible values.)
Typically, a J2EE container will create tables automatically for any EJBs deployed to it. There is just a bit more to be done, however. Namely, a table named 'Global' must be created, and one record must be inserted. (This record is used to generate new internal ID values.) Your database's DDL syntax may differ, but here is what I used against MySQL:
CREATE TABLE Global
(
name varchar(15) NOT NULL,
intValue int NULL,
stringValue varchar(255) NULL,
PRIMARY KEY (name)
) TYPE = INNODB
;
INSERT INTO Global VALUES ('nextID', 0, NULL)
;
The steps I took in deploying OpenEFM on JBoss and MySQL are as follows:
I Installed JBoss 3.2.3 and MySQL 4.0.18, configuring as described above.
I copied mysql.jar from the MySQL installation into JBoss's main libraries directory ("/var/lib/jboss/default/lib").
I included "jaws.xml" and "jbosscmp-jdbc.xml" in the EJB JAR file. These I copied from JBoss's installation and example configuration files, with some slight modifications. Basically, they provide mappings between Java types and data types in the RBDMS.
I copied a file "./examples/jca/mysql-ds.xml", from the JBoss installation, into its "deploy directory", which on my system is "/var/lib/jboss/default/deploy", and I modified it according my particular database. This file actually creates OpenEFM's data source and makes it accessible via the JNDI name "efm-db".
I copied my updated EAR file into that "deploy directory", after which JBoss detects the file automatically and attempts to deploy the entire application. Initial errors in my configuration appeared in JBoss main log file, "/var/log/jboss/server.log".
After all, however, working with J2EE is not straightforward, so it is difficult to foresee the all the blocks over which you may stumble. Perusing your log files is probably the best way to solve problems in a J2EE deployment. Please let us know your experiences, so that we can improve this document in the future.
Original Author: Jason Van Cleve
Version: 2004.06.16