
ERChangeNotificationJMS framework 
Tatsuya Kawano <tatsuyak@mac.com>


What is the ERChangeNotificationJMS framework?
----------------------------------------------
This framework synchronizes states of cached enterprise objects between application instances running on different Java Virtual Machines. Inspired by David Neumann's ChangeNotification framework for WebObjects 4.5 ....
...
Uses OpenJMS, an open source implementation of Sun Microsystems's Java Message Service API 1.0.2 Specification, which comes with a standalone JMS server with embedded JNDI service and RMI registry. 

OpenJMS Project 
http://openjms.sourceforge.net/

Sun - JMS: Java Message Service (API Specification)
http://java.sun.com/products/jms/


Benefits/Advantages
-------------------
- Synchronizes states of enterprise objects between multiple application instances. 
- Easy to set up; Uses the standalone JMS server with embedded JNDI service and RMI registry. 
- Works transparently; No need to modify your application codes. 
- Scaleable/Reliable; Should reliably works with any number of applications, no matter how high the traffic is. 
- Multi-thread safe; Works with WOF concurrent request handling feature.
- Optional: Supports variety of JMS connections; RMI to default, but can use TCP, HTML and SSL connections. 


Configuration (Mac OS X 10.x) 
-----------------------------
Download OpenJMS

1. Download the latest distribution of OpenJMS (openjms-0.7.3.1.tgz) from:  
http://openjms.sourceforge.net/download.html

2. From Terminal, type: 
gzip -cd ~/Desktop/openjms-0.7.3.1.tgz | tar xvf -

3. From Finder, choose Go -> Go to Folder (Command + Shift + G); type /usr/local and press the Enter key. 
4. Create "openjms" folder under /usr/local
5. Move the contents of openjms-0.7.3.1 folder into /usr/local/openjms folder. 


Setup Environment Variables

6. From Terminal, type:
setenv OPENJMS_HOME /usr/local/openjms

Note: you can include this into ~/.cshrc so that you don't have to type this every time you open a Terminal window. 

7. Check if JAVA_HOME is already set (type "printenv JAVA_HOME".  /Library/Java/Home is the default)


Preparatory Work for the UNIX Environment

8. If you are running OpenJMS on a UNIX platform then you need to do some preparatory work before building the product. Firstly, you must ensure that the build.sh script is executable. To make the script executable enter the following command in the console. 

cd $OPENJMS_HOME
chmod +x build.sh

9. Secondly, you need to execute the following shell command to prime all the other scripts for the UNIX environment. 

./build.sh convert


Copy OpenJMS configuration files

10. On Finder, open ERChangeNotificationJMS framework's Support folder, copy the following files into /usr/local/openjms/config folder: 

rmi_jms_jdbm.xml
rmi_jms_mysql.xml


Starting the OpenJMS Server

11. To start the server, type:  

cd $OPENJMS_HOME/bin
startjms.sh -config ../config/rmi_jms_jdbm.xml & 

For more information about setting up OpenJMS, 
see: http://openjms.sourceforge.net/quickstart.html


Shutting down the OpenJMS Server

12. To stop the server, type: 

cd $OPENJMS_HOME/bin
admin.sh -config ../config/rmi_jms_jdbm.xml -stopServer 


Optional: Startup and Shutdown the OpenJMS Server Automatically
----------------------------------------------------------------
Put OpenJMS folder under Support/StartupItemsMacOSX folder into /Library/StartupItems folder. Now OpenJMS server will be automatically started when Mac OS X system starts up, and will be stopped when the system shuts down. 

Also, now you can manually start, stop, restart the OpenJMS server by the following way:

sudo SystemStarter start OpenJMS
sudo SystemStarter stop OpenJMS
sudo SystemStarter restart OpenJMS


Optional: Improving Performance with MySQL, PostgreSQL, FrontBase, Oracle, etc.
--------------------------------------------------------
OpenJMS supports the following databases for persistent message store. They are faster databases than the embedded JDBM database, and using them should be able to improve performance. 

MySQL
PostgreSQL
Oracle
Sybase / Sybase Anywhere
MS SQL Server
Interbase
DB2
JDS
HSQL

To use MySQL: 

1. Create "openjms" MySQL database. 
2. Edit $OPENJMS_HOME/config/rmi_jms_mysql.xml and set your MySQL user name and password. 

    <!-- MySQL -->
    <RdbmsDatabaseConfiguration
      driver="org.gjt.mm.mysql.Driver" 
      url="jdbc:mysql://localhost/openjms"
      user="[user]" 
      password="[password]" />

3. From Terminal, type: 

cd $OPENJMS_HOME/bin
dbtool.sh -create -config ../config/rmi_jms_mysql.xml
 
4. Start the OpenJMS Server with the following commands: 

cd $OPENJMS_HOME/bin
startjms.sh -config ../config/rmi_jms_mysql.xml & 

5. If you have installed the OpenJMS StartupItem (Mac OS X), update the script with the configuration file you use. 

With a text editor, open OpenJMS file inside /Library/StartupItems/OpenJMS folder. Update the following statement with the configuration file you use. 

  # Replace this with the one that you actually use. 
  CONFIG_FILE="rmi_jms_jdbm.xml"


Configure your WebObjects Application
-------------------------------------
1. Build ERChangeNotificationJMS framework. (Note: don't perform Deployment build. It will not copy NSPricipalClass setting which is necessary to initialize the framework.)
2. Add the framework under the Frameworks group of your application project. 
3. Create an empty file called "Properties" (no file extension) under the Resource group of your application project. 
4. Copy the contents of Documentation/SampleProperties.txt into the Properties file. 
5. Add ERJars and ERExtensions framework to the application project. These frameworks are required just because ERChangeNotificationJMS framework uses ERXLogger for logging. If you don't want to include these frameworks, you can delete ERXLogger, log.info and log.debug statements from the framework source files (there are only three Java classes who use ERXLogger).

Note: There is no need to modify your application code. The framework works transparently. 


This is it!  Enjoy the benefits!

For requests and bug reports, please contact Project WONDER at: 
wonder-disc@sourceforge.net 

-_-_-_-_

September 7, 2002 (Draft) - Tatsuya Kawano <tatsuyak@mac.com>
December 11, 2002 (Draft) - Added PostgreSQL description. by Tatsuya Kawano 
December 29, 2002 (Draft) - Added StartupItems description. by Tatsuya Kawano

