Howto: Execute JOnAS as a WIN32 Service

This document describes the procedures necessary to run JOnAS as a system service on Microsoft Windows platforms. This applies starting from JOnAS 3.3.2.

Instructions

This procedure uses ANT targets that are introduced in JOnAS 3.3.2. The procedure also uses the Java Service Wrapper open source project which must be downloaded and installed separately.

Download and install Java Service Wrapper

  1. Download Java Service Wrapper version 3.0.5 or later, and unzip the package to a directory in the local filesystem.
  2. Set WRAPPER_HOME environment variable to the root directory for Java Service Wrapper.

    For example, if the package for Wrapper version 3.0.5 is unzipped into c:\jsw, then SET WRAPPER_HOME=c:\jsw\wrapper_win32_3.0.5

create_win32service

Before JOnAS can be run as a WIN32 service, it is necessary to copy Java Service Wrapper executable files to the %JONAS_BASE% directory and create a Java Service Wrapper configuration file. Prior to executing the steps in this section, it is necessary to create a JONAS_BASE directory as described in the JOnAS Configuration Guide.

  1. Verify that JONAS_BASE and WRAPPER_HOME environment variables are set.
  2. Set %JONAS_ROOT% as the current directory.
  3. Execute ant [-Djonas.name=<server_name>] create_win32service.

The -Djonas.name=<server_name> parameter is optional. If not specified, the default server name is 'jonas'.

NOTE: it is necessary to execute create_win32service to regenerate wrapper configuration files whenever the JOnAS configuration is modified. Refer to the Modify JOnAS Configuration section for more information.

install_win32service

After the %JONAS_BASE% directory has been updated for use with Java Service Wrapper, JOnAS can be installed as a WIN32 service using the install_win32service ant target. Prior to installing the configuration as a WIN32 service, the configuration can be tested as a standard console application. Refer to the Testing configuration section for more information. The following steps will install the service.

  1. Verify that JONAS_BASE and WRAPPER_HOME environment variables are set.
  2. Set %JONAS_ROOT% as the current directory.
  3. Execute ant install_win32service.

By default, the service is configured to start automatically each time Windows starts. If the administrator would prefer to start the service manually, modify the wrapper.ntservice.starttype parameter in the %JONAS_BASE%\conf\wrapper.conf file. Set the value as described in the comments found in the wrapper.conf file.

uninstall_win32service

When it is no longer desirable to run JOnAS as a Windows service, the service can be uninstalled using the uninstall_win32service ant target.

  1. Verify that JONAS_BASE and WRAPPER_HOME environment variables are set.
  2. Set %JONAS_ROOT% as the current directory.
  3. Verify that the service has been stopped.
  4. Execute ant uninstall_win32service.

start JOnAS service

To start the JOnAS service, open the Service Control Manager (Control Panel Services) window, select the JOnAS service and start the service.

By default, JOnAS will be started automatically each time Windows is started. After installing the service, it can be started manually to avoid the need to reboot Windows.

stop JOnAS service

To stop the JOnAS service, open the Service Control Manager window, select the JOnAS service and stop the service.

Files managed by create_win32service

The create_win32service ant target copies executable files from the Java Service Wrapper installation directory and generates a configuration file in the %JONAS_BASE% directory. The following files are managed by the create_win32service ant target.

NOTE: wrapper_ext.conf contains Java Service Wrapper configuration properties specific to the JOnAS service. This file is generated by the create_win32service ant target. Any changes made to this file will be lost when the create_win32service target is executed.

Modify JOnAS Configuration

Most of the JOnAS configuration is specified using property and XML files in the %JONAS_BASE%\conf directory. Changes to the files located in the %JONAS_BASE%\conf directory take effect the next time the service is started. It is only necessary to stop the service and restart the service for the changes to take effect.

In addition to the files located in the conf directory, JOnAS configuration is affected by the contents of %JONAS_ROOT%\bin\nt\config_env.bat, and by the CLASSPATH and JAVA_OPTS environment variables. If changes are made to config_env.bat, or to the CLASSPATH or JAVA_OPTS environment variables, it is necessary to update the Java Service Wrapper configuration files.

  1. Using the Windows Service Control Manager, stop the JOnAS service.
  2. Update the Java Service Wrapper configuration. Refer to the create_win32service section for details.
  3. Test the updated configuration. Refer to the Testing configuration section for more information.
  4. Using the Windows Service Control Manager, start the JOnAS service.

Testing configuration

After the Java Service Wrapper configuration files have been generated, it is possible to test the configuration in a console window before installing the configuration as a WIN32 service.

  1. Verify that JONAS_BASE environment variable is set.
  2. Execute %JONAS_BASE%\bin\server.

The Java Service Wrapper will start as a console application and load JOnAS using the configuration generated by the create_win32service ant target.

Enter CTRL-C to terminate JOnAS. After pressing Ctrl-C, the Java Service Wrapper displays the following messages to the execution report, and/or log file.

wrapper  | CTRL-C trapped.  Shutting down.
jvm 1    | 2003-12-02 15:25:20,578 : AbsJWebContainerServiceImpl.unRegisterWar 
                                   : War /G:/w32svc/webapps/autoload/ctxroot.war no longer available
jvm 1    | Stopping service Tomcat-JOnAS.
wrapper  | JVM exited unexpectedly while stopping the application.
wrapper  | <-- Wrapper Stopped.