NAME
Java::SJ::Config - SJ Configuration File
DESCRIPTION
This module represents SJ configurations. It uses XML::XPath to parse configuration files and generates objects to represent the directives.
Unless you're working on the module what you really want to know is what directives are allowed and their meaning. You're in luck, its below.
CONFIGURATION
All the tags defined below may appear in either the system or application configuration files. Some of course make more sense in one than the other. It may appear that some (class for example) have no business being in the system configuratino at all.
This is allowed for two reasons. Firstly it makes parsing and overriding configuration easier. Secondly it allows you to do things such as print nice error message for people when classes are not defined in app config files.
Name
<name/>
Name to use for this application. If this is not set then the configuration script filename is used without extension. So a script called 'hello.sj' would be run as a program named 'hello'.
It doesn't make much sense to place this in the system configuration but you could do so if you felt kinky.
Class
<class/>
Full name of the class whose main method you wish to run for this application.
It makes no sense to place this in the system configuration unless you want to do something really perverted.
Var
<var name="" value=""/>
Specify variables that can be used within configuration files. The names of the variables may be used as values in the configuration file.
Property
<property name="" value=""/>
Specify properties to define for the VM that is eventually used to run the application. These get turned into -D options to the VM
Environment
<environment name="" value=""/>
Specify environment settings to define for the interpreter and VM. This can be useful to set things such as TimeZones, Locales etc.
Param
<param name="" value="" sep=""/>
Specify a command line argument. This may simply be a name for option switches or can include a value. The sep attribute defines what to seperate the argument name and value by, the default is a single space.
Params can be defined for VMs and for applications generally. Params for VMs will be passed to the VM whilst params defined in the application configuration main section will be passed to the application after the class name
Dir
<dir path=""/>
Specify a directory path. These are used in multiple places but primarily in specifying where to look for classes.
Jar
<jar name="" version="" file=""/>
Specify the location of a JAR file.
If only a name is provided then the highest version JAR available in the SJ library directory will be used. Otherwise SJ will look for a specific version number and attempt to use that.
If file is given then that exact JAR file is used.
Pid
<pid dir="${dir.pid}" file="${app.name}.pid"/>
Specify whether or not to keep a PID file for this application.
Additionally this tag allows you to change where the PID file is kept and what it is called. These default to the ${dir.pid} directory and ${app.name}.pid for filename.
This tag when specified in the application configuration means that a PID file should be written, otherwise one will not be created. You should only wish to create PID files for programs that require control over time using the other SJ admin scripts.
Programs that run interactively or that can have multiple instances running concurrently should not use the PID tag in their application config file since the PID file will be overwritten for any currently running instances.
Bootclasspath
<bootclasspath> <dir/>* <jar/>* </bootclasspath>
Specify the boot classpath to use for the VM in full.
Prepend_bootclasspath
<prepend_bootclasspath>
<dir/>*
<jar/>*
</prepend_bootclasspath>Specify elements to prepend to the boot classpath.
Append_bootclasspath
<append_bootclasspath>
<dir/>*
<jar/>*
</append_bootclasspath>Specify elements to append to the boot classpath.
Classpath
<classpath>
<dir/>*
<jar/>*
</classpath>Specify elements to add to the classpath.
VM
<vm name="" vendor="" version="" language="" home="" default="true|false">
<property/>*
<param/>*
<environment/>*
</vm>
<vm ref="">
<property/>*
<param/>*
<environment/>*
</vm>The VM tag is used to define or refer to an existing VM description.
In the first instance a VM definition includes;
- name
-
A unique name to refer to this VM description
- vendor
-
The vendor name
- version
-
The version number
- language
-
The Java language version this VM supports
- home
-
The JAVA_HOME location for this VM
- default
-
Whether or not to use this VM if one is not explicitly specified by an application.
The VM marked 'default' in the system config will be used unless the application config specifically mentions another VM.
Only a single VM should be marked as 'default'.
When used with a ref attribute it refers to a previously defined VM by name and possible adds/overrides some of the proeprties and environment settings.
The VM tag allows you to specify properties to set on a per-vm bases and also allows you to specify arbitrary command line arguments to pass to the VM. It also allows you to specify environment settings to apply to the VM.
Debug
<debug level=""/>
Set the debug level
VARIABLES
The following variables and their relevant defaults are used by the system. These defaults have been chosen to make it as easy as possible to install SJ on a fairly standard UNIX system and have logs, and directories in places that you would expect to find them.
The full paths that will be used if every default is in effect is also shown below.
dir.base - default /usr/local - full /usr/local
The base directory for the system. This directory is used in conjunction with defaults to find directories if they have not been defined elsewhere.
dir.lib - default ${dir.base}/lib/sj - full /usr/local/lib/sj
The directory to find jar files in.
dir.pid - default ${dir.base}/var/run - full /usr/local/var/run
The directory to store PID files in.
dir.log - default ${dir.base}/var/log/sj - full /usr/local/var/log/sj
The directory to store log files in
dir.script - default ${dir.base}/var/sj/script - full /usr/local/var/sj/script
The directory to store generated script files in.
dir.tmp - default &File::Spec::Functions::tmpdir - full N/A (depends on system)
The directory to store temporary files in.
app.name - no default
The name of the application
app.class - no default
The class file for the application
vm.default - Defined by whichever VM has default=true attribute
The default VM tag to use if none supplied by the application
TODO
Test, test, test.
BUGS
None known so far. Please report any and all to Nigel Rantor <wiggly@wiggly.org>
SUPPORT / WARRANTY
This module is free software. IT COMES WITHOUT WARRANTY OF ANY KIND.
LICENSE
The Java::SJ::Config module is Copyright (c) 2003 Nigel Rantor. England. All rights reserved.
You may distribute under the terms of either the GNU General Public License or the Artistic License, as specified in the Perl README file.
AUTHORS
Nigel Rantor <wiggly@wiggly.org>