com.excelsior.service
Class WinService

java.lang.Object
  |
  +--com.excelsior.service.WinService

public abstract class WinService

extends java.lang.Object

The WinService class is an abstract class representing Windows service.

To create your own service, you should subclass WinService class and override the run method to implement a service functionality. Optionally, you may override the init, shutdown, stop, pause, and resume methods as well. These methods are also referred to as Control Request Handlers (CRH).

The processing timeout can be set using the setInitTimeout, setPauseTimeout, setResumeTimeout, setStopTimeout methods. The default timeout value is 10 seconds. Note that timeout cannot be set for shutdown CRH method because it is defined by the operating system (as less than 20 seconds).

Upon service activation, its init CRH method is invoked. If it is not completed in time, a warning message is logged into the system event log and the run CRH method is invoked. The init method returns a boolean result indicating whether the service accepts the pause/resume control requests.

Each CRH method, including init, is run in a separate thread.

Any exceptions thrown during a CRH method execution are ignored, so you may wish to enclose the body of such a method into a try block to handle exceptions:

     try {
         ...
     } catch (Throwable exception) {
        logErrorEvent (exception.toString());
     }
 

You may not instantiate subclasses of the WinService class explicitly. The only instance of your service class is instantiated automatically for each service process at the moment of its activation. It is done using the method Class.newInstance(), so the default constructor with public access modifier must be present in the subclass of the WinService class.

Since:

JET 3.0

Constructor Summary

protected

WinService() Default constructor to create WinService instance.

Method Summary

protected static java.lang.String[]	getArgs() Retrieve the service command-line arguments.
protected boolean	init() Service initialization CRH.
protected void	logErrorEvent(java.lang.String message) Write an error message to the system event log.
protected void	logInfoEvent(java.lang.String message) Write an information message to the system event log.
protected void	logWarningEvent(java.lang.String message) Write a warning message to the system event log.
protected void	pause() Service pause CRH.
protected void	resume() Service resume CRH.
protected void	run() Main service routine.
protected void	setInitTimeout(int millis) Set initialization timeout.
protected void	setPauseTimeout(int millis) Set pause request completion timeout.
protected void	setResumeTimeout(int millis) Set resume request completion timeout.
protected void	setStopTimeout(int millis) Set stop request completion timeout.
protected void	shutdown() Service shutdown CRH.
protected void	stop() Service stop CRH.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

WinService

protected WinService()

Default constructor to create WinService instance. At most one instance of a WinService subclass can be created for each service process. Note that the instance is created automatically during service start-up. The subclass of the WinService class should declare the default constructor with public access modifier.

Method Detail

init

protected boolean init()

Service initialization CRH. Initalization time is limited to 10 seconds unless setInitTimeout is called.

Returns:

true if the service supports pause/resume control requests; false otherwise.

run

protected void run()

Main service routine. It is called after initialization is completed. However, if initialization is not completed in time, the run method is called anyway after timeout specified. The method is run in a separate thread. Upon exit of this method, the service stops executing.

pause

protected void pause()

Service pause CRH. The method is run in a separate thread. Timeout for completion of a pause request can be set using setPauseTimeout. Any exceptions thrown in this method are ignored.

resume

protected void resume()

Service resume CRH. The method is run in a separate thread. Timeout for completion of resume request can be set using setResumeTimeout. Any exceptions thrown in this method are ignored.

stop

protected void stop()

Service stop CRH. The method is run in a separate thread. Timeout for completion of stop request can be set using setStopTimeout. Any exceptions thrown in this method are ignored.

shutdown

protected void shutdown()

Service shutdown CRH. The method is run in a separate thread. Competion timeout cannot be set for the shutdown request and limited to less than 20 seconds. Any exceptions thrown in this method are ignored.

setInitTimeout

protected final void setInitTimeout(int millis)

Set initialization timeout. The default initialization timeout is 10 seconds.

setPauseTimeout

protected final void setPauseTimeout(int millis)

Set pause request completion timeout. The default pause completion timeout is 10 seconds.

setResumeTimeout

protected final void setResumeTimeout(int millis)

Set resume request completion timeout. The default resume completion timeout is 10 seconds

setStopTimeout

protected final void setStopTimeout(int millis)

Set stop request completion timeout. The default stop completion timeout is 10 seconds

getArgs

protected static java.lang.String[] getArgs()

Retrieve the service command-line arguments.

Since:

JET 3.5

logInfoEvent

protected final void logInfoEvent(java.lang.String message)

Write an information message to the system event log.

logWarningEvent

protected final void logWarningEvent(java.lang.String message)

Write a warning message to the system event log.

logErrorEvent

protected final void logErrorEvent(java.lang.String message)

Write an error message to the system event log.