Home > Articles > Programming > Java

Java Reference Guide

Hosted by

Toggle Open Guide Table of ContentsGuide Contents

Close Table of ContentsGuide Contents

Close Table of Contents

Java Windows NT Services

Last updated Mar 14, 2003.

One limitation in using Java as your primary development environment is that, when you deploy to a Java Virtual Machine (JVM), you have limited access to the underlying operating system. This level of abstraction is powerful in allowing you to deploy to any operating system with a supported JVM, but you may have a set of tasks that you might want to accomplish that simply is not possible using Java. One such task is running your application as a Windows NT Service or as a Unix Daemon. A service running under Windows or a daemon running under Unix is a process that is started and managed by the operating system; furthermore, it has no graphical user interface associated with it.

This article focuses on running a Java application as a Windows NT Service.

NT Services

Windows NT Services are started and stopped by the operating system. You can access the NT Services installed on your computer through the "Control Panel," "Administrative Tools," "Computer Management." On the left side of this dialog box is a tree item named "Services and Applications;" when you expand that node and choose "Services," you will see all of the Services installed on your computer. Figure 1 shows an example of the services running on my notebook.

Figure xxxFigure 34. Services Screen Shot


You will notice that each service has the following information:

  • Name

  • Description

  • Status

  • Startup Type

  • Log on As

The name and description describe the service. The status displays whether or not the service is running by printing a "Started" label in this table column if the service has been started. The Startup Type can be either "Automatic," meaning that the operating system will start the service when it starts, or "Manual," meaning that you must manually start and stop the service; this can be accomplished by highlighting the service and pressing the play or stop icon or by right clicking on a service and choosing start or stop. Finally, the Log on As column says who the service will run as; some services may need special privileges and hence need to be run as a user with those privileges.

Windows NT Services are specified and configured in the Windows Registry in the following location:

HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\{SERVICE_NAME}

The configuration references a Windows executable that has been compiled as a Windows Service. So, to execute a Java application as a service, we are going to need a Windows executable to launch our Java process. There are several open source projects that exist for just this purpose, but in my research, the one with the most exposure is JavaService written by Alexandria Software Consulting.

JavaService

JavaService contains a Windows executable service that allows you to launch any Java application in a specified environment. Download either the binary or source (includes binary) from the following URL:

http://www.alexandriasc.com/software/JavaService/download.html

Copy JavaService.exe to your project and rename it to match whatever you want your service to be named (this is what you will see in the Windows Task Manager).

Next, you need to create a class to execute. JavaService can execute any application with a main() method, or you can specify a method to execute when the service starts. It must return void and accept as a parameter a String[].

Finally, you use the JavaService.exe file to install a Windows NT Service. This is accomplished by passing it a "-install" command line parameter followed by a set of additional parameters:

  • service_name (mandatory): The name 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 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 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 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 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. You can use this to specify where additional DLLs, upon which native libraries are dependent, can be found.

A common application that you might want to run as a service is a Web server. I have a small Web server that I have been developing, which I configured to run as a service using the following installation command:

WebServer.exe -install "JavaSRC Web Server" 
f:\j2sdk1.4.2_01\jre\bin\server\jvm.dll -
Djava.class.path=f:\projects\webserver\deploy\lib\webserver.jar;f: 
\projects\webserver\deploy\lib\jdom.jar;f:\projects\webserver\depl
oy\lib\xerces.jar; -start com.javasrc.webserver.WebServer -params 
f:\projects\webserver\deploy\config\webserver.xml -out 
f:\projects\webserver\deploy\logs\stdout.txt -err 
f:\projects\webserver\deploy\logs\stderr.txt -current 
f:\projects\webserver\deploy

Let's look at the parameters:

  • WebServer.exe: When the service is running, you'll see it in the task manager as "WebServer.exe"

  • "JavaSRC Web Server": This is the name of the service as it will appear in the Computer Manager Dialog box. Note that any parameter with spaces must be delimited by quotes.

  • jvm.dll: This is the fully qualified filename of the Java Virtual Machine dynamic link library (DLL); this is the path to the 1.4.2 JDK.

  • –Djava.class.path=...: This specifies all the JAR files that need to be in the CLASSPATH. Note that the Web Server itself has been packaged into the webserver.jar file. You can either package your classes into a JAR file or specify the current working directory using the "-current" parameter (later).

  • -start com...WebServer: This is the class to execute.

  • -params ...webserver.xml: This specifies the parameters to send to the start method (defaults to main) in a String[].

  • -out ...stdout.txt: This is the text file that System.out printouts will be sent to.

  • -err ...stderr.txt: This is the text file that System.err printouts will be sent to.

  • -current ...: This specifies the current working directory to start the WebServer class from.

This installation command yields the following registry values:

Windows Registry Editor Version 5.00

[HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\JavaSRC Web Server]
"Type"=dword:00000010
"Start"=dword:00000002
"ErrorControl"=dword:00000001
"ImagePath"=hex(2):46,00,3a,00,5c,00,70,00,72,00,6f,00,6a,00,65,00, 
63,00,74,00,\
 73,00,5c,00,77,00,65,00,62,00,73,00,65,00,72,00,76,00,65,00,72,00, 
5c,00,64,\
 00,65,00,70,00,6c,00,6f,00,79,00,5c,00,57,00,65,00,62,00,53,00, 
65,00,72,00,\
 76,00,65,00,72,00,2e,00,65,00,78,00,65,00,00,00
"DisplayName"="JavaSRC Web Server"
"ObjectName"="LocalSystem"

[HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\JavaSRC Web 
Server\Parameters]
"JVM Library"="f:\\j2sdk1.4.2_01\\jre\\bin\\server\\jvm.dll"
"JVM Option Count"=dword:00000001
"JVM Option Number 0"="-
Djava.class.path=f:\\projects\\webserver\\deploy\\lib\\webserver.jar; 
f:\\projects\\webserver\\deploy\\lib\\jdom.jar;f:\\projects\\webse
rver\\deploy\\lib\\xerces.jar;"
"Start Class"="com.javasrc.webserver.WebServer"
"Start Method"="main"
"Start Param Count"=dword:00000001
"Start Param Number 
0"="f:\\projects\\webserver\\deploy\\config\\webserver.xml"
"System.out File"="f:\\projects\\webserver\\deploy\\logs\\stdout.txt"
"System.err File"="f:\\projects\\webserver\\deploy\\logs\\stderr.txt"
"Current Directory"="f:\\projects\\webserver\\deploy"

[HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\JavaSRC Web 
Server\Security]
...

[HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\JavaSRC Web 
Server\Enum]
...

You can see all your configuration parameters under the "Parameters" subkey for the service. Any of these values can be modified to affect the behavior of the service.

Start the service from the "Computer Manager" dialog box and check the Windows Event Application Log (Control Panel, Administrative Tools, Event Viewer, Application Log node). If there were any errors on startup, you will find more information there.

Uninstallation is much easier:

WebServer.exe –uninstall "JavaSRC Web Server"

The only important thing to note during uninstallation is that the service name, "JavaSRC Web Server", must match the installation name.

Summary

Running your application as a service provides the benefit that when a machine is restarted, the operating system will automatically restart your service for you. The best candidates to become services are Web servers and application servers. You will find that with JavaService you will receive a batch file to install Tomcat as a service and you can find documentation on launching JBoss as a service.

If you are running in a Windows environment, services are a must for your highly available applications.

Official Documentation

JavaService Official Web Site

Online Resources

Sun's Web site