Table of Contents
List of Tables
Table of Contents
If you notice any mistakes in this document, please email me at blaine.simpson@admc.com so that I can correct them. I've just converted this from Texinfo to Docbook, so there are most likely many mistakes in this revision. You can also email me if you have problems with the procedures explained herein, or if you have questions, comments, suggestions or complaints.
This document is available in several formats.
You may be reading this document right now at http://jamama.sourceforge.net/user, or in a distribution somewhere else. I hereby call the document distribution from which you are reading this, your current distro.
http://jamama.sourceforge.net/user hosts the latest versions of all available formats. If you want a different format of the same version of the document you are reading now, then you should try your current distro. If you want the latest version, you should try http://jamama.sourceforge.net/user.
Sometimes, distributions other than http://jamama.sourceforge.net/user do not host all available formats. So, if you can't access the format that you want in your current distro, you have no choice but to use the newest version at http://jamama.sourceforge.net/user.
Table 1. Alternate formats of this document
| format | your distro | at http://jamama.sourceforge.net/user |
|---|---|---|
| Chunked HTML | index.html | http://jamama.sourceforge.net/user/index.html |
| All-in-one HTML | user.html | http://jamama.sourceforge.net/user/user.html |
| user.pdf | http://jamama.sourceforge.net/user/user.pdf |
If you don't know what Jamama is, see the Jamama Design Document.
Obtain and install Java JRE 1.4.x.
Make sure that your path contains your Java 1.4.x java program
Downloading the binary zip at http://admc.com/jamama/dist/jamama.zip and unzip it.
The distribution will expand into a directory under your current directory named jamama. You may rename this directory if you wish. Jamama documentation refers to this directory on your computer as the JAMAMA_HOME .
If you don't want to set up your own runtime logging system, then copy the sample files in JAMAMA_HOME/localres to the same filenames without the .sample suffixes.
Copy the sample file in JAMAMA_HOME/config to the same filename without the .sample suffix.
Run Jamama. Set your classpath to contain all the jars in JAMAMA_HOME/lib, as well as JAMAMA_HOME/dist/jamama.jar and JAMAMA_HOME/localres. For example, if you are running a Bourne-compatible shell, you can set the shell variable JAMAMA_HOME to your JAMAMA_HOME directory path and run
$ java -version # To verify Java 1.4.x plus is in your search path
...
$ export CLASSPATH
$ CLASSPATH="${JAMAMA_HOME}/dist/jamama.jar:${JAMAMA_HOME}/localres"
$ for jarfile in $JAMAMA_HOME/lib/*.jar; do
CLASSPATH="${CLASSPATH}:$jarfile"
done
$ cd $JAMAMA_HOME # Just so Jamama can find config/config.xml
$ java com.admc.jamama.Jamama -i # Omit the -i to run without a console(Jamama does not need you to set the JAMAMA_HOME variable. I just had you do that to reduce the amount of typing you had to do above.) You can, of course, add anthing else that you want to your classpath. You may, for example, want to add the log4j jar file to the classpath.
Server instances that have <run> set to true in the config file will run. (If not, can tell them to run as instructed in the following steps).
Remember that if you want to make manual changes to the configuration file, you should make those changes while Jamama is shut down. The changes will be picked up during the next startup.
If you ran Jamama with the -i switch, for Interactive, you will have a console that you can type commands into. Type help and hit ENTER to get a list of valid commands.
Use the default JMX Interface, Sun's JDMK HTML Adaptor to view and modify your setup. Use a browser to connect to the hostname and port listed in a <jdmkHtmlAdaptor> element in the configuration file (the values default to any IP addr on your computer, and port 8082). Make sure that the <run> element is set to true on at least one jdmkHtmlAdaptor, of you will have no way to administer your setup other than with the console.
To stop Jamama, send EOD (typically Ctrl-Z or Ctrl-D) or "quit" or "exit" to the console; or use a JMX Interface to invoke the stop operation on the Jamama MBean.
The configuration file is JAMAMA_HOME/config/config.xml. The schema defining what kind of entries are allowed is at JAMAMA_HOME/dtd/jamama.dtd.
Do not put comments into config.xml, because Jamama dynamically updates the file if there are any run-time configuration changes. (Therefore, your comments will get lost).
Only edit config.xml when Jamama is not running. It wouldn't hurt anything to do so, but the changes won't get picked up until the next Jamama startup; and your changes will get lost if there is any run-time configurationchange (see previous item).
You can make run-time configuration changes by connecting to the HTML Adaptor which will be running on the port specified in the config.xml file (unless you have disabled it). You use a browser to connect to the Adaptor, and you can then view, modify, add/remove, start/stop, etc., all of the Jamama components.
Configuration changes to any of our components will be persisted (and restored the next time Jamama is started).
To create new component instances at run-time, use the supplied ConfigurableFactory object instead of the JMX management tool's constructor features. You can create objects with a JMX management tool, but JMX will not be able to link to the object from other Jamama components, and will not store configuration changes to it, or even know to re-create it when Jamama is restarted. N.b.: As of Fri Nov 28 17:07:14 EST 2003, ConfigurableFactory is not yet implemented.
If you set up logging according to the installation instructions and you just want to change logging level(s), then you don't need to read the rest of this chapter. To change the global logging level, just change the value of org.apache.commons.logging.simplelog.defaultlog in the file JAMAMA_HOME/localres/simplelog.properties. To change logging levels of particular components or areas, you do that in the same file. See the Commons Logging docs about the Simple Logger to find out how to make those settings.
Jamama users Apache Commons Logging. You can see the Commons Logging docs to learn anything you would want to know about how to configure it. In this chapter, I explain the default Jamama Commons Logging setup, and how to adjust Jamama to use log4j logging.
By default, you just rename the files in the localres directory according to the Jamama installation instructions. Commons Simple Logging will be used. At this time, I think that all you can do with Simple Logging is print to stderr (i.e., you can't log to files or anything, other than by OS shell redirection... and that's pretty inadequate for most purposes).
Java 1.4 Logging is supported by Commons Logging, but, in my opinion, it is just an inferior emulation of log4j.
There are other ways to set up log4j, I'm going to explain what I think is the most flexible and simple setup. There are three things you need to do.
The config file is named either log4j.xml or log4j.properties, and must reside directly in a classpath directory (i.e., not in a package directory or any other subdirectory).
Most users will just copy the file JAMAMA_HOME/localreslog4j.xml.sample file to log4j.xml and edit it. (localres will be in your classpath if you run Jamama as instructed in the User Guide).
Just put the path to it into your classpath. Developers using Ant to start Jamama will need to set the property local.runtimeclasspath in JAMAMA_HOME/build.properties like
local.runtimeclasspath: localres:/path/to/my/log4j-1.2.8.jarJust change the value of property org.apache.commons.logging.Log in the file JAMAMA_HOME/localres/commons-logging.properties according to the instructions in the sample file (JAMAMA_HOME/localres/commons-logging.properties).
If you use the supplied log4j config file, just create the directory JAMAMA_HOME/log.