Java Service Launcher (JSL 0.92)

What is the JSL?
Links
Current version
Changes and previous versions
Will you answer mail asking for support?
Can I contribute or improve JSL?
Requirements
How To start my java programm as a service
Examples
Troublehooting
For experts
License
Contact the author
 

What is the JSL?

Links

Current version

NT 4.0 and Win2000 are supported.
Supported JAVA versions are SUN JRE 1.2 (any version) and SUN JRE 1.3 beta
All varieties of the virtual maschine should work (classic, JIT, HOTSPOT). I will support future versions of the JDK as soon as they are released.
If you would like other JVM supported send me a working example how to start it using C/C++ code.

Changes and previous versions

Will you answer mail asking for support?

By the way: From May 1st I'm open to employment opportunities in the munich area.
Just in case you need an IT professional with 4 years experience in consulting, design and implementation of e-business applications, C++ and JAVA development.
See here for contact.

Can I contribute to or improve the JSL?

Which software is needed to run the JSL?

How To start my java programm as a service

• Copy JSL.EXE and JSL.INI somewhere on your disk.
• Modify the JSL.INI to reflect your desired settings. Ecspecially classpath and command line parameters.
• Run jsl.exe -install
• Start it in the NT service manager or by calling NET start "Telnet Echo"

Initialization file:
The initialization file is both necessary for setup and running the service. Don't remove it after you have installed the service.
It contains parameters for both service setup and java application.

[service]
This section is only applied during service installation and removal.
appname =
servicename =
displayname =
stopport = <ip port on which the service manager will signal the java application to shut down. Must be unique if several jsl services run on the machine.>

[java]
Changes to this section will take effect when the service is restarted.

params = <number of parameters for the java application. Count start with param00>
param00 = <java command line parameters>
param01 = ..

Command line options
Calling jsl.exe without parameters gives an overview of the available options.

-install

Install the service in the NT service manager. Service is not started immediately, though it will start automatically when NT is rebooted.
Start the service from command line with NET START <APPNAME>.

-remove

Remove an installed service. This may fail if the service is still running.
Stop the service from command line with NET STOP <APPNAME>.

-debug

Run the application from command line for debugging purposes. Service need no be installed.

Stopping a service
To allow for orderly shutdown of the java application the service sends a signal to the java application by opening a connection on the port specified as "stopport" in the service ini file.
The most simple way to take advantage of this feature is to use the ServiceStopper class and Stopable interface as presented in the TelnetEcho example. The ServiceStopper will only accept connections from the localhost, so your service cannot be shutdown remotely.
You can avoid implementing the Stopable interface by using the class SimpleStopper.

This is the most simple service which simple does nothing until stopped.

public static main (String[] argv)
{
    ServiceStopper.stop( new SimpleStopper()  );
}

If the functionality supplied by ServiceStopper is insufficient for your needs, you might want to implement your own handler code for stopping the service. The port is passed to the java application via a -Dservice.stop.port=<PORT> parameter which is prepended to the parameters given in the INI file. You can read it back by a call to System.getProperty( "service.stop.port" )
 

Example

• jsl.ini
• TelnetEcho.java
• Stopable.java
• ServiceStopper.java

The out put shoud look like this

JSL Java Service launcher by Michael Röschter (Michael@Roeschter.de)
Version 0.92 February 26th 2000
Command line options:
jsl -install          to install the service
jsl -remove           to remove the service
jsl -debug            to run as a console app for debugging

Initalization file: E:\Java\TEST\jsl_0_9_2\Debug\jsl.ini
appname=Telnet Echo
servicename=TelnetEcho
displayname=Telnet Echo
stopport=8465
param00=-cp
param01=e:\java\test\jsl_0_9_2
param02=TelnetEcho
Java command line:
java -Dservice.stop.port=8465 -Dservice.path=E:\Java\TEST\jsl_0_9_2\Debug\ -Dservice.name=TelnetEcho -cp e:\java\test\jsl_0_9_2 TelnetEcho 

StartServiceCtrlDispatcher being called.
This may take several seconds.  Please wait.

Run jsl.exe -debug after you unpacked the distribution package.
Telnet echo will run a primitive telnet server which will simple echo back any character you try.
Test ist by running your favorite telnet terminal against your localhost.

Now install the service with jsl -install.
Go to the NT service manager and start it up.
Test again and try to shut it down in the service manager.
Uninstall with jsl -remove.

Now nothing should go wrong with your own service.

Troublehooting

The service won't start and I can't see why.
Try to start it in debug mode first. Run it as a service only when you are sure that there are no serious bugs in it.

How can I see may standard output.
You can replace the System.out stream. But that's a hack anyway.
You should use one of the numerous free packages on the web that can do a comfortable logging to a file.

The program did run fine in debug mode but can't find files when run as a service
Don't rely on the standard path when locating files from the service. Always use absolute paths. The service will path it's start path through a java system property.

How can I find out from which directory the service was started and how it is named
The JVM is started with a command line similar to this one.

java -Dservice.stop.port=8465 -Dservice.path=E:\Java\TEST\jsl_0_9\Debug\ -Dservice.name=TelnetEcho -cp e:\java\test\jsl_0_9 TelnetEcho

The program did run fine in debug mode but still does not find the files it needs though I load them from an absolute path.
Drives mounted from a network device are not accessible from a service!
Access them through fully qualified network names.

\\myserver\myfiles\myservice\hello.data

The program did run fine in debug mode but is denied access to the network shares I need
In standard settings the service will run as a system user. Sytem user can't access the network. You need to change the security settings manually in the NT service manager.
There may be other more exotic errors which could result from this.

The service runs fine but I can't stop it. Service manager tells me the stop request failed and I can't stop it using the task manager.
Services can not be stopped forcedly. They must stop themselves. That's what the stopable interface is for.
To get rid of your service you must restart NT (after you set service starting mode to manually).
(If somebody knows a work around please tell me)

For experts

This section will explain the source code and give a step by step introduction on how to write a custom java service launcher.

License

This software is supplied as is. Sources are supplied for informational purposes for the experienced developer.

Please note that this means:

• There is not liability for any direct or indirect consequences of running JSL on your computer.
• I cannot guarantee that the sources are free of copyright from third parties. Specifically there are code portions supplied with Microsoft Visual Studio and SUN JDK 1.2.x included in this distributions. If you want to use jsl in a commercial package delete all C sources and simply use the executable.
• I cannot guarantee any support.

Contact the author