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.
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.
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.
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.
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.
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.
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.
|
protected static void disableAllAssassins ();
Disables the assassins for each service in the process.
Return Value:
No return value.
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
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.
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
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.
public synchronized int getCheckPoint( );
Determines the service checkpoint.
Return Value:
Returns the current checkpoint value.
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.
public synchronized int getCurrentState( );
Determines the service state.
Return Value:
Returns the system's current state.
public synchronized final ServiceStatus getServiceStatus( );
Determines the service status.
Return Value:
Returns a copy of the service status, which is a ServiceStatus object.
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.
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.
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.
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.
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.
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.
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.
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.
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
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.
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.
|
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.
|
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.
|
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.
|
protected synchronized void setPaused( );
Sets the service to the PAUSED state.
Return Value:
No return value.
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.
|
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
protected synchronized void setRunning( );
Sets the service to RUNNING.
Return Value:
No return value.
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.
|
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.
|
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.
|
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.
|
protected synchronized void setStopped( );
Sets the service to STOPPED.
Return Value:
No return value.
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.
|
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.
|
- 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.