Pointers to information on establishing a Windows Service
The following links supply information about running programs as a Windows Service. Based on emails read there are at least three programs that help establish a program as a Windows Service:
Java *Service* Launcher (JSL) or
Java *Service* Wrapper by Tanuki Software - there are probably others.
The usage of the standard windows programs (instsrv.EXE and srvany.exe) is described in the tutorial below.
- Tutorial on standard Windows service generation: http://www.vogella.de/articles/ApacheDerby/article.html#service
JSL and JSW are alternative ways of wrapping Java programs into a windows service.
- Information on JSL: http://sourceforge.net/projects/jslwin
- Information on JSW: http://wrapper.tanukisoftware.org/doc/english/index.html
Example Configuration Using Java Service Wrapper
Setting up Derby to run as a windows service is not terribly difficult using the Java Service Wrapper (JSW) by Tanuki Software. The steps below refer to Derby 10.2 and JSW version 3.2.3 configuring a service on Windows Server 2003.
Create Service User
It is typically a good idea to run services such as this one under a non-SYSTEM account. So first, create the user account that this service will run as.
The above command creates a local user "derby" with a password "derbypw". This user must now be granted access to log on as a windows service. Launch the "Local Security Settings" from the Control Panel's "Administrative Tools" folder. In this application:
- In the left tree pane, navigate to "Security Settings / Local Policies / User Rights Assignment"
- Find the "Log on as a service" policy in the right pane
- Add the "derby" user (in the local computer domain) to this policy
By default, this user will have read-only access to the files and directories on the disk. Grant this user full control access (or whatever is appropriate for your needs) to the directory where the databases are to be stored. To aid in troubleshooting, also ensure that this user has write access to any locations where log files are stored.
In sites concerned about security there are plenty of other steps to be taken to lock down this account but they go well beyond the scope of this page.
Configure the Wrapper
To configure the Java Service Wrapper (JSW), create a configuration file that describes the Derby launch and shutdown parameters. But before getting into the details of this file, it is important to know that the file will contain a lot of paths to various files. Java Service Wrapper sets the current working directory to the location of the wrapper executable. So any relative paths are relative to the location of "Wrapper.exe". Now, to configure JSW:
- Create a file (it doesn't really matter where) called
derby.conf. This file has a ".properties"-style format (key = value) to specify the configuration parameters.
- Add a property
wrapper.java.commandto specify the java runtime to launch:
- Derby works well with the Wrapper Start/Stop mechanism (option 2 of the JSW configuration reference). To enable this option add the property:
- Next provide properties to set the classpath. You need to specify the three derby JAR's and the wrapper JAR: be sure to change the paths to their actual location on your system.
- Set whatever Derby options are required using the
Nis a sequential index (starting with 1) for each option. Since JSW sets the current working directory to the location of its executable, you will at least want to set the
- Set the application parameters that will configure the wrapper to start and stop the application using the appropriate Derby class and options:
- Set the library search path so that JSW can find its Wrapper.dll. Set this parameter to the location of that DLL
- Set some standard Java runtime options (values are in MB - adjust as necessary)
- Set some general logging options:
- Finally, set the service options:
There are alternative options if you do not want to put the account password into a file. See the JSW docs for more information.
Set Java policy
To enable the derby network server and the wrapper to open connections the polycies for the wrapper and derby jar files have to be added in the policy-files of the execution JVM.
Add the following lines to
Start It Up
Before installing the service, run it from the console to ensure things are working properly.
You will have to supply the full path to the "derby.conf" file unless both Wrapper.exe and derby.conf are in the same directory. If things are configured correctly, this will start up in the current command window and await connections:
Use <CTRL-C> to stop the server. The JSW intercepts this and issues the proper shutdown sequence for Derby.
Once it works from the console, install the service. Just replace the "-c" option to Wrapper with "-i"
And that should be all. Start the service either by rebooting or through the service control manager:
At this point if you have trouble connecting to the database (and you had no problems when running in the console) it is typically a permissions problem with the "derby" user account. Error messages are logged in a variety of places:
- Windows Event Viewer
- The wrapper log file (configured in the
derby.conffile as the property
wrapper.logfilefor error messages.
- The Derby log file