Java Service Launcher (JSL 0.92)

download here or contact the author at  Michael@Roeschter.de

26.2.2000

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?

The Java Service Launcher is a small executable to start JAVA-programs under Windows NT 4.0. Is is NOT a Java virtual maschine.
It's just an utility like javap, javac or javah.
 

Links

Links to other sources for launching java applications as a service.
http://sw-technologies.com/java/ntsvc/
 

Current version

Current version is v0.92 (third public release/compatibility upgrade)
Release date: February 26th 2000
Author: Michael Röschter
Download URL http://141.40.115.121/jsl/index.html  or http://www.roeschter.de/index.html

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

Release 0.92 will now run with JRE 1.3 beta
Release 0.91 is now debugged against Win 2000. Microsoft subtly changed the StartServiceCtrlDispatcher API call. Null is no longer a valid parameter for a service name, while NT 4.0
API states that the service name will be ignored if service is of type SERVICE_WIN32_OWN_PROCESS.
Release 0.9 contained a serious bug. To be precise it would not run (I apologize to all who tried).
Release 0.5 First public release

Will you answer mail asking for support?

Any feedback is welcome. I will happily give e-mail support and feedback as long as you acknowledge that I'm a hard working member of society. I can't guarantee a 2 hour response time and won't care for requests like "help, my project is due tomorrow and I will get fired if I can't get the service running under WIN 2000". You may phone me, too. I'm always in for an improvement of my english conversation skills. My timezone is Central European. I'm at home after 8 o'clock in the evenings. That's well within US working hours, so you might give it a try. You might try on weekends, too.
From March 3rd to March 29th I'm on holiday far, far away where no phone or e-mail may reach me.

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?

In any way you like. I have no commercial interest in this. The only form of compensation I will give is an invitation to the Oktoberfest or some Biergarten if you happen to travel to munich.

Which software is needed to run the JSL?

NT 4.0 or Win2000. You need a JRE 1.2 or JRE 1.3 beta properly installed. That is, the JRE or JDK must be installed from the installation program, not just copied to the disk (which might suffice to run a java program from the command line). The JSL needs no setup and can simply be copied anywhere. Just note the limitations concerning a network as explained in the troubleshooting section.
 

How To start my java programm as a service

Quick start: Setup:
The jsl executable will look for an ini file with the same name in it's directory. Copy both to a location of your choice (posible where your java app is located).

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

For an example of a simple java service see the files: Run jsl without parameters to check if the initialization file is where it is expected.

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.
Now adjust the classpath setting in the initialization file.

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

Off course there is still a lot that may go wrong.

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 -D options can be accessed through the System Properties. Look in class java.lang.System for details.

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

Soon to come

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

License

There is no license aggrement and no copyright for version 0.9x of the JSL.

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

Please note that this means:

Contact the author

Mail to: Michael@Roeschter.de
Phone: (49)(or whatever is your escape for germany) 8161/44426