Class Service

public abstract class Service
{
  // Fields
  public static final int ACCEPT_PAUSE_CONTINUE;
  public static final int ACCEPT_SHUTDOWN;
  public static final int ACCEPT_STOP;
  public static final int CONTINUE_PENDING;
  protected static boolean disableassassin;
  public PrintStream err;
  protected static final int ERROR_SERVICE_SPECIFIC_ERROR;
  protected static final int NO_ERROR;
  public PrintStream out;
  public static final int PAUSE_PENDING;
  public static final int PAUSED;
  public static final int RUNNING;
  public static final int START_PENDING;
  public static final int STOP_PENDING;
  public static final int STOPPED;

  // Constructors
  protected Service( );

  // Methods
  public synchronized boolean canPause( );
  public synchronized boolean canShutdown( );
  public synchronized boolean canStop( );
  protected synchronized void CheckPoint( );
  protected synchronized void CheckPoint( int waithint );
  protected static void disableAllAssassins ();
  protected void disableAssassin( );
  protected static void enableAllAssassins ();
  protected void enableAssassin( );
  protected void getAssassinTimeout( long ms );
  public synchronized int getCheckPoint( );
  public synchronized int getControlsAccepted( );
  public synchronized int getCurrentState( );
  public synchronized final ServiceStatus getServiceStatus( );
  public final ServiceStatus getServiceStatusDirect( );
  public synchronized int getWaitHint( );
  protected boolean handleContinue( );
  protected boolean handleInterrogate( );
  protected boolean handlePause( );
  protected boolean handleShutdown( );
  protected boolean handleStop( );
  protected boolean handleUnrecognizedEvent (int event);
  protected boolean isAssassinActive( );
  protected static void preventAssassins ();
  protected void setAssassinTimeout( long ms );
  public static boolean setAutoDumpErr( boolean autodump );
  public static boolean setAutoDumpOut( boolean autodump );
  protected synchronized void setContinuing( int waithint );
  protected synchronized void setPaused( );
  protected synchronized void setPausing( int waithint );
  protected synchronized void setRunning( int controls );
  protected synchronized void setRunning( );
  public boolean setServiceAutoDumpErr( boolean autodump );
  public boolean setServiceAutoDumpOut( boolean autodump );
  protected synchronized final boolean setServiceStatus (
        ServiceStatus newstatus);
  protected final boolean setServiceStatusDirect(
        ServiceStatus newstatus );
  protected synchronized void setStopped( );
  protected synchronized void setStopping( int waithint );
  protected void StopServiceEventHandler (int waithint);
}

This class is a base class for creating Microsoft® Windows NT® system services in Java.

Caution By default, the service assassin is turned on for services. It must be turned off by using the disableAssassin method. For more information, see the enableAssassin method.

Constructors

Service

protected Service( );

Constructs a new service.

Caution The service being created must send a status update within 30 seconds or disable the assassin; otherwise, the assassin will kill the service.

Methods

canPause

public synchronized boolean canPause( );

Indicates whether the service can be paused.

Return Value:

Returns true if the service can be paused (that is, if getControlsAccepted returns ACCEPT_PAUSE_CONTINUE); otherwise, returns false.

canShutdown

public synchronized boolean canShutdown( );

Indicates whether the service should be notified when the system shuts down.

Return Value:

Returns true if the service can accept shutdown requests (that is, if getControlsAccepted returns ACCEPT_SHUTDOWN); otherwise, returns false.

canStop

public synchronized boolean canStop( );

Indicates whether the service can be stopped.

Return Value:

Returns true if the service can be stopped (that is, if getControlsAccepted returns ACCEPT_STOP); otherwise, returns false.

CheckPoint

protected synchronized void CheckPoint( );

Increments the current checkpoint value.

Return Value:

No return value.

Remarks:

During a pending operation, the service should call the CheckPoint method to indicate that the service has progressed toward changing the state from pending to start, stop, continue, or pause.

CheckPoint

protected synchronized void CheckPoint( int waithint );

Sets the checkpoint to a specified value.

Return Value:

No return value.

Parameter	Description
waithint	The estimated number of milliseconds until the next state.

disableAllAssassins

protected static void disableAllAssassins ();

Disables the assassins for each service in the process.

Return Value:

No return value.

disableAssassin

protected void disableAssassin( );

Disables the service assassin. If the assassin is disabled, the service must always be able to respond to stop and shutdown requests, because a service cannot be shut down through the task manager. If it is unknown whether the service will always be able to do so, it is best advised to leave the assassin enabled. If the assassin is killing the service too soon, use the setAssassinTimeout to set its default timeout.

Return Value:

No return value.

See Also: enableAssassin, isAssassinActive

enableAllAssassins

protected static void enableAllAssassins ();

Restores the assassins for each service in the process to their normal state. This method globally re-enables assassins, regardless of their individual settings.

Return Value:

No return value.

enableAssassin

protected void enableAssassin( );

Enables the assassin. The assassin will observe the state of the service and will terminate it in the following cases:

• A control request is received and the service does not respond within the default time-out.
• A call to setServiceStatus changes the state of the service to a state unrelated to a previous state change request. This means that if a stop request is received and the service proceeds to set the state to RUNNING, the service is terminated. However, if the service sets its state to STOPPED or STOP_PENDING, the service will terminate in the first case, or it will re-start its time-out in the second case.
• A setServiceStatus call changes the state of the service to any PENDING state and the service does not make a setServiceStatus call to the corresponding state within the WaitHint (or if WaitHint is not specified), within the assassin's default time-out.

See Also: disableAssassin, isAssassinActive, setAssassinTimeout, STOPPED, START_PENDING, STOP_PENDING, RUNNING, CONTINUE_PENDING, PAUSE_PENDING, PAUSED

getAssassinTimeout

protected void getAssassinTimeout( long ms );

Obtains the default time for which the assassin will wait for any state change before terminating a service. The time-out initially defaults to 30 seconds.

Return Value:

Returns the time, in milliseconds, that the assassin will wait for a state change before terminating the service.

getCheckPoint

public synchronized int getCheckPoint( );

Determines the service checkpoint.

Return Value:

Returns the current checkpoint value.

getControlsAccepted

public synchronized int getControlsAccepted( );

Indicates the control codes that the service will accept and process.

Return Value:

Returns flags that indicate which controls the service will accept.

getCurrentState

public synchronized int getCurrentState( );

Determines the service state.

Return Value:

Returns the system's current state.

getServiceStatus

public synchronized final ServiceStatus getServiceStatus( );

Determines the service status.

Return Value:

Returns a copy of the service status, which is a ServiceStatus object.

getServiceStatusDirect

public final ServiceStatus getServiceStatusDirect( );

Determines the service status. This operation is not synchronized with other status-changing operations.

Return Value:

Returns a copy of the service status, which is a ServiceStatus object.

getWaitHint

public synchronized int getWaitHint( );

Determines the wait hint.

Return Value:

Returns the service wait hint.

Remarks:

The wait hint value specifies the number of milliseconds the service is likely to remain in the current pending state. If the service exceeds this value, the service will be terminated if the assassin is enabled.

handleContinue

protected boolean handleContinue( );

Handles the continue request.

Return Value:

Returns false.

Remarks:

Override this method in your derived service class if you want your service to handle continue events.

handleInterrogate

protected boolean handleInterrogate( );

Handles the interrogate request.

Return Value:

Returns false.

Remarks:

Override this method in your derived service class if you want your service to handle interrogate events.

handlePause

protected boolean handlePause( );

Handles the pause request.

Return Value:

Returns false.

Remarks:

Override this method in your derived service class if you want your service to handle pause events.

handleShutdown

protected boolean handleShutdown( );

Handles the shutdown request.

Return Value:

Returns false.

Remarks:

Override this method in your derived service class if you want your service to handle shutdown events. By default, this method makes a call to handleStop.

handleStop

protected boolean handleStop( );

Handles the stop request.

Return Value:

Returns false.

Remarks:

Override this method in your derived service class if you want your service to handle stop events. By default, if stop control requests are accepted, it will call the setStopped method and return false.

handleUnrecognizedEvent

protected boolean handleUnrecognizedEvent (int event);

Handles an unrecognized event code from the service control manager. Future versions of Windows NT may define additional events; this method provides a way for services to respond to these events.

Return Value:

Returns false.

isAssassinActive

protected boolean isAssassinActive( );

Indicates whether the assassin is currently active.

Return Value:

Returns true if the assassin is active; otherwise, returns false.

See Also: enableAssassin, disableAssassin

preventAssassins

protected static void preventAssassins ();

Prevents assassins from being created. For this method to be effective, each service should call this method from its static initializer.

Return Value:

No return value.

setAssassinTimeout

protected void setAssassinTimeout( long ms );

Sets the time for which the assassin will wait for any state change before terminating a service.

Return Value:

No return value.

Parameter	Description
ms	The time, in milliseconds, for the assassin to wait for a state change before terminating the service.

setAutoDumpErr

public static boolean setAutoDumpErr( boolean autodump );

Determines whether each line written to System.err is automatically written to the event log or whether the service will manually flush the stream to log events.

Note This method changes the state of System.err if it has not been changed since the first service was instantiated. The status of err, the output stream for each service, can be changed with setServiceAutoDumpErr.

Return Value:

Returns the previous auto-flush state.

Parameter	Description
autodump	Set to true to automatically flush to the Windows NT event log whenever a new line is written. Set to false to enable writing to the error log. In this case, the stream can be manually flushed by calling System.err.flush, which will write any text printed to the stream since the last flush to the event log as a single event.

setAutoDumpOut

public static boolean setAutoDumpOut( boolean autodump );

Determines whether each line written to System.out is automatically written to the event log or whether the service will manually flush the stream to log events.

Note This method changes the state of System.out if it has not been changed since the first service was instantiated. The status of out, the output stream for each service, can be changed by using setServiceAutoDumpOut.

Return Value:

Returns the previous auto-flush state.

Parameter	Description
autodump	Set to true to automatically flush to the Windows NT event log whenever a new line is written. Set to false to enable the writing of multiline error messages to the information log. In this case, the stream can be manually flushed by calling System.out.flush, which will write any text printed to the stream since the last flush to the event log as a single event.

setContinuing

protected synchronized void setContinuing( int waithint );

Sets the service to CONTINUE_PENDING.

Return Value:

No return value.

Parameter	Description
waithint	The estimated number of milliseconds it takes for the service to reach the RUNNING state.

setPaused

protected synchronized void setPaused( );

Sets the service to the PAUSED state.

Return Value:

No return value.

setPausing

protected synchronized void setPausing( int waithint );

Sets the service to PAUSE_PENDING and sets the wait hint to waithint.

Return Value:

No return value.

Parameter	Description
waithint	The estimated number of milliseconds it takes for the service to reach the PAUSED state.

setRunning

protected synchronized void setRunning( int controls );

Sets the service to RUNNING and sets the ControlsAccepted field in the ServiceStatus object to a specified value indicating the control capabilities of the service.

Return Value:

No return value.

Parameter	Description
controls	The control capabilities that ControlsAccepted is set to.

See Also: com.ms.service.ServiceStatus.ControlsAccepted

setRunning

protected synchronized void setRunning( );

Sets the service to RUNNING.

Return Value:

No return value.

setServiceAutoDumpErr

public boolean setServiceAutoDumpErr( boolean autodump );

Determines whether each line written to err is automatically written to the event log or whether the service will manually flush the stream to log events.

Return Value:

Returns the previous auto-flush state.

Parameter	Description
autodump	Set to true to automatically flush to the Windows NT event log whenever a new line is written. Set to false to enable the writing of multiline error messages. In this case, the stream can be manually flushed by calling err.flush, which will write any text printed to the stream since the last flush to the event log as a single event.

setServiceAutoDumpOut

public boolean setServiceAutoDumpOut( boolean autodump );

Determines whether each line written to out is automatically written to the event log or whether the service will manually flush the stream to log events.

Return Value:

Returns the previous auto-flush state.

Parameter	Description
autodump	Set to true to automatically flush to the Windows NT event log whenever a new line is written. Set to false to enable the writing of multiline error messages. In this case, the stream can be manually flushed by calling out.flush, which will write any text printed to the stream since the last flush to the event log as a single event.

setServiceStatus

protected synchronized final boolean setServiceStatus (
        ServiceStatus newstatus);

Changes the value of the service, based on a ServiceStatus object.

Return Value:

Returns true if the status was updated; returns false if the newstatus parameter is not correct or the status could not be updated.

Parameter	Description
newstatus	The value that the service status is set to. The state in newstatus is copied to the current status.

setServiceStatusDirect

protected final boolean setServiceStatusDirect( ServiceStatus newstatus );

Changes the value of the service, based on a ServiceStatus object. This method should be externally synchronized with other status-changing operations, if necessary.

Caution This method is not synchronized with the other status get/set methods. This method provides the service with a direct way to internally update the assassin. It allows the assassin to identify deadlock conditions on internally-initiated state changes. External state changes through Service Control Manager events will always update the assassin. Use getServiceStatusDirect to obtain the status without synchronizing.

Return Value:

Returns true if the status was updated; returns false if the newstatus parameter is not correct or the status could not be updated.

Parameter	Description
newstatus	The value that the service status is set to. The state in newstatus is copied to the current status.

setStopped

protected synchronized void setStopped( );

Sets the service to STOPPED.

Return Value:

No return value.

setStopping

protected synchronized void setStopping( int waithint );

Sets the service to STOP_PENDING and the wait hint to waithint.

Return Value:

No return value.

Parameter	Description
waithint	The estimated number of milliseconds it takes for the service to reach the STOPPED state.

StopServiceEventHandler

protected void StopServiceEventHandler (int waithint);

Internally stops the service. Sets the service to STOPPED. No more control commands will be dispatched after this method is called.

Note This method is provided only for backward compatibility with services developed using SDK 1.5. The preferred way to indicate a stopped service is by using setStopped. Version 1.5 reported a STOP_PENDING status and activated the assassin with the given waithint; a STOPPED status would automatically be reported when all non-daemon threads terminated. Because multiple services are supported, this version simply reports a STOPPED status and does not activate the assassin.

Return Value:

No return value

Parameter	Description
waithint	This parameter is not used.

Fields

ACCEPT_PAUSE_CONTINUE

Indicates that the service accepts pause and continue requests.

ACCEPT_SHUTDOWN

Indicates that the service accepts shutdown requests.

ACCEPT_STOP

Indicates that the service accepts stop requests.

CONTINUE_PENDING

Indicates that the service is changing its state from pause to run.

disableassassin

When true, prevents the assassin from being activated. The assassin ensures that the service actually stops when instructed to do so. This deactivates the assassins for each service in the process.

Note Each service has its own assassin, which can be disabled by calling disableAssassin. All assassins can be globally disabled by calling disableAllAssassins.

err

An error output stream for the service. Data written to the stream is automatically redirected to the event log as error events using the event source specified to jntsvc. Each line printed to the stream results in a new event. Multiple lines can be written by synchronizing on this object and using setServiceAutoDumpErr to temporarily turn off auto-logging, as shown in the following example:

  synchronized (err)
  {
    boolean oldautodump = setServiceAutoDumpErr(false);
    err.println("Line 1");
    err.println("Line 2");
    setServiceAutoDumpErr(oldautodump);
    err.flush();
  }

ERROR_SERVICE_SPECIFIC_ERROR

Service-specific error reported. This is set in ServiceStatus.Win32ExitCode to indicate that an error has occurred.

NO_ERROR

No error reported. This is set in ServiceStatus.Win32ExitCode to indicate that the service terminated correctly.

out

A standard output stream for the service. Data written to the stream is automatically redirected to the event log using the event source specified to the jntsvc tool. Each line printed to the stream results in a new event. Multiple lines can be written by synchronizing on this object and using setServiceAutoDumpOut to temporarily turn off auto-logging, as shown in the following example.

  synchronized (out)
  {
    boolean oldautodump = setServiceAutoDumpOut(false);
    out.println("Line 1");
    out.println("Line 2");
    setServiceAutoDumpOut(oldautodump);
    out.flush();
  }

PAUSE_PENDING

Indicates that the service is changing its state from run to pause.

PAUSED

Indicates that the service is paused.

RUNNING

Indicates that the service is running.

START_PENDING

Indicates that the service is starting.

STOP_PENDING

Indicates that the service is stopping.

STOPPED

Indicates that the service has stopped.