|
Contents
Requirements
Overview
Installing
UnInstalling
Version Query
Registry Settings
Event Logging
Example (Tomcat)
Example (Orion)
Example (JBoss 3.0)
Requirements
JavaService requires a JNI 1.2 compliant
Java Virtual Machine. This includes the Sun Java 2 SDK versions 1.2, 1.3 and
1.4. It does not support the older JDK 1.1.x.
Overview
JavaService can be used to run any Java classes as
an NT Service. It can start the service using the standard
static void main(String[] args) method,
or any other static method that
takes a String[] as its only parameter.
In its simplest incarnation JavaService will simply terminate the JVM
to stop the service, but you can optionally have it call another static
method inside the JVM. If JavaService calls another method it will wait
either until both the start and the stop methods have returned or until
a 30 second timeout has expired before terminating the JVM. JavaService
can also optionally redirect the System.out and/or the System.err streams
into a file.
Installing
The JavaService executable has no dependencies on
any files or directories. This was intentional so that it could easily
be used with any Java software. Additionally, it does not have a dependency
on the name JavaService.exe. This means that you can, and probably should,
rename it to something more appropriate. This can be quite useful when
checking the Task Manager to see how much CPU time a particular service
is using, or how many threads it has created. Instead of seeing multiple
entries for JavaService.exe you see a unique entry for each renamed version
of the executable. Follow these instructions to use JavaService with your
Java application:
- Unzip the archive into a directory appropriate for your application.
The following files will be extracted:
- bin/JavaService.exe - The service executable.
- bin/installTomcat4.bat - A sample usage to install the service for
Tomcat 4.
- bin/installTomcat32.bat - A sample usage to install the service
for Tomcat 3.2.
- bin/installTomcat31.bat - A sample usage to install the service
for Tomcat 3.1.
- bin/installOrion.bat - A sample usage to install the service for Orion.
- bin/test_install_orion.bat - A test usage to invoke the Orion service installer.
- bin/test_uninstall_orion.bat - A test usage to remove the installed Orion service.
- bin/installJBoss.bat - A sample usage to install the service for JBoss 3.x.
- bin/test_install_jboss.bat - A test usage to invoke the JBoss service installer.
- bin/test_uninstall_jboss.bat - A test usage to remove the installed JBoss service.
- docs/documentation.html - This documentation.
- docs/license.html - The license for distributing this product.
- docs/overview.html - High-level introductory documentation.
- docs/history.html - Release notes and change history.
- docs/faq.html - Frequently-Asked Questions.
- docs/styles.css - Formatting stylesheet for HTML documentation.
- Copy the JavaService.exe file to a directory appropriate for your
application, and optionally rename JavaService.exe to something more
relevant.
- Start a command prompt and change to the directory where the JavaService.exe
is located.
- Type 'JavaService.exe -install' followed
by the proper parameters, as described below. Be sure to use quotation
marks around parameters with spaces (italics signify an application
dependent value):
- service_name (mandatory) - The name that you want to use
for this service. This is what the service will show up as in the
service control manager.
- jvm_library (mandatory) - The location of the jvm.dll file
that you want to use as your Java Virtual Machine. For Sun's Java
2 SDK, this is usually {JDK_HOME}\jre\bin\classic\jvm.dll or {JDK_HOME}\jre\bin\hotspot\jvm.dll.
- jvm_option* (optional) - Optionally specify any necessary
parameters to pass to the JVM upon invocation. These may include
thing such as "-Djava.class.path=" to specify a classpath
or "-Xmx128m" to specify a maximum heap size of 128MB.
Any parameters that you need to use when invoking the java.exe command
tool should be specified here. There is no limit to the number of
parameters specified.
- -start start_class (mandatory) - The name of the class
that you wish to use when starting the service. This must be the
fully qualified class name.
- -method start_method (optional) - The name of the static
method of the start_class that you wish to call to start
the service. The method must be static,
must return type void, and must take
a String[] as its only parameter.
If this parameter is not specified it defaults to main.
- -params start_parameter+ (optional) - Any parameters to
pass to the start_method when starting the service. These
will be passed in as the String[]
parameter.
- -stop stop_class (optional) - The name of the class that
you wish to use when stopping the service. This must be the fully
qualified class name. If no stop_class is specified, the
process containing the Virtual Machine is simply terminated when
the service is stopped.
- -method stop_method (optional, but only allowed if a stop_class
was specified) - The name of the static method of the stop_class
that you wish to call to stop the service. The method must be static,
must return type void, and must take
a String[] as its only parameter.
If this parameter is not specified it defaults to main.
- -params start_parameter+ (optional, but only allowed if
a stop_class was specified) - Any parameters to pass to the
stop_method when stopping the service. These will be passed
in as the String[] parameter.
- -out out_log_file (optional) - A file into which System.out
will be redirected. If this parameter is not specified, System.out
will not be redirected.
- -err err_log_file (optional) - A file into which System.err
will be redirected. If this parameter is not specified, System.err
will not be redirected.
- -current current_dir (optional) - A directory to use as
the current working directory for the service. If this parameter
is specified, all relative paths in the service will be relative
to relative to the specified directory.
- -path extra_path (optional) - An addition to the path for
the service. The specified path will be appended to the system path
before the service is started. This can be used to specify where
additional DLLs that native libraries are dependent upon can be
found.
- -depends other_services (optional) - Another NT service (or multiple services,
if specified as a comma-separated list) that
must be running before this particular java service can start. Will cause
the named service(s) to be started automatically if required when starting
the java service. Will also stop the java service if a specified service is stopped
(usually with user confirmation first being requested by Windows NT).
- -auto or -manual - Optional parameter indicating whether service
should be run automatically on system startup (default mode), or if it should
be started on demand using a manual command (i.e. net start service).
- -shutdown seconds (optional) - Specify the amount of time that
may be taken during processing of your shutdown/stop method. The value here
is used as a timeout, so if the method has not completed in this length of time,
the JVM process will be terminated to allow the service to shutdown completely.
- -user user_name (optional) - Specify the Windows domain username to be
used when running the service (also requires that the password parameter is specified).
Note that this should generally be specified in Windows 2000 Active Directory style (i.e. johndoe@foobar.com)
- -password password (optional) - Specify the Windows password associated with
the domain username specified for use when running the service (specify with user parameter).
- -append or -overwrite - Optional parameter indicating whether output
and error log files are to be appended to, or overwritten, on each service startup.
If not specified, the default is to append to existing log files.
A simple example might look like the following:
JavaService.exe -install "My Service" c:\jdk\jre\bin\classic\jvm.dll
-Djava.class.path=c:\app\classes.jar -start com.my.ExampleClass -err
c:\app\stderr.txt
This would create a service that, when started, would
create a JVM from the JDK in c:\jdk setting the classpath to be c:\app\classes.jar.
It would then call the main method of the com.my.ExampleClass class with
a String array of length 0 (no parameters). Anything written to System.err
would be redirected into the file c:\app\stderr.txt.
UnInstalling
- Start a command prompt and change to the directory where the JavaService.exe
is located.
- Type 'JavaService.exe -uninstall' followed
by the name of the service.
Version Query
There are two ways to determine the version number of this program.
First:
- Start a command prompt and change to the directory where the JavaService.exe
is located.
- Type 'JavaService.exe -version'
and the program will display version and copyright information.
Alternatively:
- Locate and select the file JavaService.exe in Windows Explorer.
- View the properties of this executable file by either pressing Alt+Enter
or by using the right-click menu and selecting Properties from the list.
- The version number and copyright information for the program can then be viewed from one of the property tabs
displayed by Windows.
Registry Settings
JavaService stores the configuration information for
installed services in the registry. The location is
HKEY_LOCAL_MACHINE\ SYSTEM\ CurrentControlSet\ Services\
{SERVICE_NAME}\ Parameters
The following keys are used and may be changed after
service installation to modify the behavior of the service.
Current Directory - The current working directory
for the service.
JVM Library - The location of the jvm.dll library
to use to create the Java Virtual Machine.
JVM Option Count - The number of option to pass
to the JVM when creating it.
JVM Option Number n - An option to pass to
the JVM. n ranges from 0 to "JVM Option Count" - 1.
Path - Extra path information that will be appended
to the system path before the service is started.
Start Class - The class to use to start the service.
Start Method - The static method to call on the
"Start Class" to start the service.
Start Param Count - The number of parameters to
pass to the "Start Method" to start the service.
Start Param Number n - A parameter to pass to the
"Start Method" to start the service. n ranges from 0 to "Start
Param Count" - 1.
Stop Class - The class to use to stop the service.
If this key is absent, the process containing the JVM will simply be
terminated when the service is stopped.
Stop Method - The static method to call on the "Stop
Class" to stop the service.
Stop Param Count - The number of parameters to pass
to the "Stop Method" to stop the service.
Stop Param Number n - A parameter to pass to the
"Stop Method" to stop the service. n ranges from 0 to "Stop
Param Count" - 1.
System.err File - A file into which System.err will
be redirected. If this key is absent, System.err will not be redirected.
System.out File - A file into which System.out will
be redirected. If this key is absent, System.out will not be redirected.
Shutdown Timeout - The number of milliseconds to allow for
the Java Stop method to complete, before timeout and JVM forced termination.
Event Logging
JavaService logs both informational events and errors
into the Application portion of the NT Event Log. Informational messages
include a message when the service is started and one when it is stopped.
Error messages may be logged because of a configuration problem or other
system error. If you are having trouble getting JavaService to run your
application, you should first check the Application portion of the Event
Log to see if any errors were reported. Additionally you can check the
redirected System.err file, as any Java exceptions will be written there
by the Virtual Machine.
Example (Tomcat)
Tomcat is
a JSP engine and was the primary reason that JavaService was created.
It is a pure Java application that is ideally used as a service, but comes
with no native ability to do so. The following example shows how JavaService
can be used to run Tomcat 3.1 as an NT service. The ideas shown here apply
to using JavaService with any Java application that needs to run as an
NT service. {JDK_HOME} is the location of your JDK and {TOMCAT_HOME} is
the location of your Tomcat installation.
- Copy the JavaService.exe file into the {TOMCAT_HOME}\bin directory as tomcat.exe.
- Start a command prompt and change to the directory {TOMCAT_HOME}\bin.
- Run the following command:
tomcat.exe -install Tomcat
{JDK_HOME}\jre\bin\{hotspot|server|classic}\jvm.dll
-Djava.class.path={TOMCAT_HOME}\bin\bootstrap.jar;{TOMCAT_HOME}\bin\servlet.jar;{JDK_HOME}\lib\tools.jar
-Dcatalina.home={TOMCAT_HOME}
-start org.apache.catalina.startup.Bootstrap
-params start
-stop org.apache.catalina.startup.Bootstrap
-params stop
-out {TOMCAT_HOME}\logs\stdout.log
-err {TOMCAT_HOME}\logs\stderr.log
Example (Orion)
The Orion Application Server
is a J2EE-compliant product that runs under the Java run-time environment. The JavaService
utility provides a convenient mechanism to run this program as an NT Service.
As the application server requires that an associated database server is already running, there
is a need to add a Windows NT Service dependency to the Orion Java Service. The example below
shows how this can be defined, with a dependency on the MySql database service in this case.
{JDK_HOME} is the location of your JDK and {ORION_HOME} is the location of your Orion
installation. The administrator username and password fields also need to be substituted in this command.
Please note that this has been used successfully against the V1.5.2 OrionServer release,
but is in any case provided 'as is'.
- Copy the JavaService.exe file into the {ORION_HOME} directory as OrionServer.exe.
- Start a command prompt and change to the directory {ORION_HOME}.
- Run the following command:
OrionServer.exe -install Orion
{JDK_HOME}\jre\bin\{hotspot|server|classic}\jvm.dll
-Djava.class.path={ORION_HOME}\orion.jar;{JDK_HOME}\lib\tools.jar -Xms64M -Xmx256M
-start com.evermind.server.ApplicationServer
-stop com.evermind.client.orion.OrionConsoleAdmin
-params "ormi://localhost admin_username admin_password -shutdown"
-out {ORION_HOME}\log\stdout.log
-err {ORION_HOME}\log\stderr.log
-current {ORION_HOME}
-depends mysql
-manual
-append
- To remove the registered service, run the following command from the same directory:
OrionServer.exe -uninstall Orion
The Orion service can then be started by issuing the following command,
which will also start the MySql service beforehand if it is not already running:
net start orion
The Orion service can then be stopped by issuing the following command:
net stop orion
The MySql database service may be stopped as normal by issuing the following command:
net start mysql
This will first stop the Orion service, if it is currently running, following user confirmation.
Example (JBoss 3.0)
The JBoss server software provides a Java
run-time environment that can be used for JSP and J2EE applications. In this use, it often needs to
be run as a Windows NT System Service, for which the JavaService utility is designed.
Depending on configuration, JBoss may require that an associated database server is already running, which
should be set up as a Windows NT Service dependency, with the example below set up against the MySql database.
{JDK_HOME} is the location of your JDK and {JBOSS_BIN} is the location of your JBoss binaries installation.
These instructions are based on information in the JBoss 3.0 quick-start guide,
but are in any case provided 'as is'.
- Copy the JavaService.exe file into the {JBOSS_BIN} directory as JBossService.exe.
- Start a command prompt and change to the directory {JBOSS_BIN}.
- Run the following command:
JBossService.exe -install JBoss
{JDK_HOME}\jre\bin\{hotspot|server|classic}\jvm.dll
-Djava.class.path={JDK_HOME}\lib\tools.jar;{JBOSS_BIN}\run.jar
-start org.jboss.Main
-stop org.jboss.Main -method systemExit
-out {JBOSS_BIN}\stdout.log
-err {JBOSS_BIN}\stderr.log
-current {JBOSS_BIN}
-depends mysql
-manual
-overwrite
- To remove the registered service, run the following command from the same directory:
JBossService.exe -uninstall JBoss
The JBoss service can then be started by issuing the following command,
which will also start the MySql service beforehand if it is not already running:
net start jboss
The service can then be stopped by issuing the following command:
net stop jboss
|