An Application Service can be deployed as a Windows NT/XP/2003 Service. This option has the several advantages:
- The service can be configured to automatically start when the server computer is started.
- The service can be manually started, stopped, and paused using the standard Windows Service Management Console.
- The service is monitored using a heartbeat to ensure it is still processing. If it fails to respond, the service is automatically restarted. This functionality can be used to increase availability.
The Java Service Wrapper is used to ‘wrap’ the Application Service so that it can be managed using Windows. This tool can be downloaded from http://wrapper.tanukisoftware.org and is available for free use under an unrestricted license. This tool is Copyright (c) 1999, 2005 Tanuki Software Inc.
8.1. Installation
Ensure the following files are available in the application distribution and lib directories:
| Application | Java Service Wrapper Files |
|---|---|
| <Application home>/dist/wrapper.exe | <Wrapper home>/bin/wrapper.exe |
| <Application home>/lib/wrapper/wrapper.dll | <Wrapper home>/lib/wrapper.dll |
| <Application home>/lib/wrapper/wrapper.jar | <Wrapper home>/lib/wrapper.jar |
| <Application home>/dist/wrapper.conf | <Wrapper home>/conf/wrapper.conf.in |
Note: For convenience, the Java Service Wrapper files are included in <Framework home>/lib/wrapper. When Framework is built, the wrapper.exe is copied to the dist directory and the wrapper.dll and wrapper.jar files are copied to dist/list/wrapper directory. When an application is built, these files are copied in an identical manner to the application’s dist directory.
8.2. Configuration
Edit the wrapper configuration file (<Application home>\dist\wrapper.conf) and define:
- wrapper.java.command=java
- wrapper.java.classpath.1=lib/wrapper/wrapper.jar
- wrapper.java.classpath.2=<App>.jar
- wrapper.java.classpath.3=fbs.jar
- wrapper.java.classpath.4=foundation.jar
- wrapper.java.classpath.5=lib/*.jar
- wrapper.java.classpath.6=lib/oracle/*.jar
- wrapper.java.library.path.1=lib/wrapper
- wrapper.java.additional.1=-server
- wrapper.java.additional.2=-Djava.security.policy=policy
- wrapper.java.additional.3=–Dcom.sun.management.jmxremote.port=<port>
- wrapper.java.additional.4=–Dcom.sun.management.jmxremote.ssl=false
- wrapper.java.additional.5=–Dcom.sun.management.jmxremote.authenticate=false
- wrapper.java.maxmemory=256
- wrapper.app.parameter.1=com.<App>.client.Application
- wrapper.app.parameter.2=-server
- wrapper.console.title=<App>Server
- wrapper.ntservice.name=<App>Server
- wrapper.ntservice.displayname=<App>Server
- wrapper.ntservice.description=<description>
8.3. Configuring the Java Virtual Machine
This wrapper.java.command property determines the command to use when launching a JVM. If the full path to the java executable is not specified, then the Wrapper will attempt to locate a java executable on the system path. It is advised that the value does not contain an extension. Specifying a value like java.exe would mean that the same configuration file could not be used on Linux or UNIX systems.
Example using system path:
- wrapper.java.command=java
Example using JAVA_HOME environment variable:
- wrapper.java.command=%JAVA_HOME%/bin/java
Example using full path (not platform independent):
- wrapper.java.command=c:/j2sdk1.4.0/bin/java
8.4. Testing the Wrapper in a Console
From a command window, in the \dist directory, execute:
- wrapper.exe -c wrapper.conf
8.5. Installing the Windows Service
From a command window, in the <Application home>\dist directory, execute:
- wrapper.exe -i wrapper.conf
The service is now added to the list of services in the Microsoft Service Management Console and can be managed (started, stopped, and paused) using this tool.
Note: the service is NOT started at this point. See Starting the Service before attempting to connect a client.
Note: before the service can be run, the database must be defined. If the database does not yet exist, it must be created. From a command window, in the <Application home>\dist directory, execute:
- run –define
8.6. Starting the Windows Service
From a command window, execute:
- net start <App>Server
Note: enclose <App>Server in quotes if spaces were used.
By default, the service is configured to log all output to the wrapper.log. This log is cumulative in that restarts of the service do NOT erase the previous log information.
8.7. Testing the Windows Service using a Client
From a command window, in the <Application home>\dist directory, execute:
- run –client
Log in and test the application.
8.8. Stopping the Windows Service
From a command window, execute:
- net stop <App>Server
Note: enclose <App>Server in quotes if spaces were used.
8.9. Removing the Windows Service
From a command window, in the <Application home>\dist directory, execute:
- wrapper.exe -r wrapper.conf
The service is removed from the list of services in the Microsoft Service Management Console and can no longer be managed.