JavaService - Description
 

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:

  1. 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.

  2. Copy the JavaService.exe file to a directory appropriate for your application, and optionally rename JavaService.exe to something more relevant.

  3. Start a command prompt and change to the directory where the JavaService.exe is located.

  4. 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_service (optional) - Another NT service that must be running before this particular java service can start. Will cause the named service to be started automatically if required when starting the java service. Will also stop the java service if the named 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.

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

  1. Start a command prompt and change to the directory where the JavaService.exe is located.
  2. 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:

  1. Start a command prompt and change to the directory where the JavaService.exe is located.
  2. Type 'JavaService.exe -version' and the program will display version and copyright information.

Alternatively:

  1. Locate and select the file JavaService.exe in Windows Explorer.
  2. 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.
  3. 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.

  1. Copy the JavaService.exe file into the {TOMCAT_HOME}\bin directory as tomcat.exe.
  2. Start a command prompt and change to the directory {TOMCAT_HOME}\bin.
  3. 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'.

  1. Copy the JavaService.exe file into the {ORION_HOME} directory as OrionServer.exe.
  2. Start a command prompt and change to the directory {ORION_HOME}.
  3. 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
  4. 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'.

  1. Copy the JavaService.exe file into the {JBOSS_BIN} directory as JBossService.exe.
  2. Start a command prompt and change to the directory {JBOSS_BIN}.
  3. 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
  4. 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