com.jniwrapper.win32.service
Class Service

java.lang.Object
  extended bycom.jniwrapper.Parameter
      extended bycom.jniwrapper.Pointer.Void
          extended bycom.jniwrapper.win32.Handle
              extended bycom.jniwrapper.win32.service.ScHandle
                  extended bycom.jniwrapper.win32.service.Service
All Implemented Interfaces:
com.jniwrapper.IntegerParameter, com.jniwrapper.PointerParameter

public class Service
extends com.jniwrapper.win32.service.ScHandle

This class represents Windows service application, which is either started automatically at system startup, or by a user through Services application, or programmatically.

Note: Available for Windows NT, Windows 2000, Windows XP, Windows Server 2003.

See Also:
Platform SDK: DLLs, Processes, and Threads

Nested Class Summary
static class Service.AccessRights
          This class represents access rights to a service.
static class Service.CurrentState
          This class represents the current state of the service.
static class Service.ErrorControl
           
static class Service.StartupType
          This class represents startup type of service.
static class Service.Status
          This class represents the service status.
static interface Service.StatusListener
           
static class Service.Type
          This class represents type of the service.
 
Field Summary
static java.lang.String ACCOUNT_LOCAL_SYSTEM
           
 
Fields inherited from class com.jniwrapper.win32.Handle
INFINITE_TIMEOUT, INVALID_HANDLE_VALUE, STATUS_ABANDONED_WAIT_0, STATUS_TIMEOUT, STATUS_WAIT_0
 
Fields inherited from class com.jniwrapper.Parameter
LICENSE_TYPE, V
 
Constructor Summary
protected Service(java.lang.String name)
          Creates a service in open state.
protected Service(java.lang.String name, Service.AccessRights accessRights)
          Creates a service in open state.
 
Method Summary
protected  void checkOpened()
           
protected  void checkResult(java.lang.String msg, com.jniwrapper.Bool result)
          A utility method for checking an operation result.
 boolean close()
          Closes the handle to a service-related object.
 RegistryKey createParametersKey()
          Creates parameters subkey in registry.
 void delete()
          Marks the service as deleted.
 Service.AccessRights getAccessRights()
          Returns access rights for the service.
 java.lang.String getBinaryPath()
          Returns the absolute path to the executable file for the service.
 Service.CurrentState getCurrentState()
          Returns the current state of the service.
 java.lang.String[] getDependencies()
          Returns names of the services that the system must start before starting this service.
 java.lang.String getDescription()
          Returns description for the service.
 java.lang.String getDisplayName()
          Returns the display name of the service.
 Service.ErrorControl getErrorControl()
          Returns severity of the error that describes the action performed if the service failed to start:
ErrorControl.IGNORE Logs error and continues startup ErrorControl.NORMAL Logs error, shows message box with error message and continues startup ErrorControl.SEVERE Logs error.
 java.lang.String getName()
          Returns the service name used for openning the service.
 java.lang.String getPassword()
           
 Service.Type getServiceType()
          Returns a type of the service.
 java.lang.String getStartAccount()
          Returns the account under which the service starts in the form: domainName\\userName or LocalSystem for LocalSystem account.
 Service.StartupType getStartupType()
          Returns startup type of the service.
 Service.Status getStatus()
          Returns the service status.
 boolean isInteractive()
          Returns true, if the service can interact with desktop.
protected  boolean isLocked()
           
protected  boolean isOpened()
           
 void loadConfiguration()
          Loads the configuration of the service.
protected  void lock()
          Locks the handle for closing.
 void pause()
          Pauses the service.
 void resume()
          Resumes the paused service.
 void saveConfiguration()
          Saves configuration of the service.
 void setAccessRights(Service.AccessRights accessRights)
          Sets access rights to the service.
 void setBinaryPath(java.lang.String binaryPath)
          Sets the absolute path to the executable file for the service.
 void setDependencies(java.lang.String[] dependencies)
          Sets dependencies for the service.
 void setDisplayName(java.lang.String displayName)
          Sets the display name.
 void setErrorControl(Service.ErrorControl errorControl)
          Sets severity of the error that describes the action performed if the service failed to start:
ErrorControl.IGNORE Logs error and continues startup ErrorControl.NORMAL Logs error, shows message box with error message and continues startup ErrorControl.SEVERE Logs error.
 void setInteractive(boolean isInteractive)
          Allows / disallows interaction of the service with desktop.
 void setName(java.lang.String name)
          Sets service name.
protected  void setOpened(boolean isOpened)
           
 void setPassword(java.lang.String password)
          Sets password for the start account.
 void setServiceType(Service.Type serviceType)
          Sets a type of the service.
 void setStartAccount(java.lang.String startAccount)
          Sets the account under which the service starts.
 void setStartupType(Service.StartupType startupType)
          Sets startup type of the service.
 void setValue(long value)
          Sets handle value of this pointer to service.
 void start()
          Starts the service.
 void start(java.lang.String[] parameters)
          Starts the service.
 void stop()
          Stops the service.
protected  void unlock()
          Unlocks the handle for closing.
 void waitState(Service.CurrentState expectedState)
          Periodically checks the current state of the service and returns from the method when the current state is equal to the expected state.
 void waitState(Service.CurrentState[] expectedStates)
          Periodically checks the current state of the service and returns from the method when the current state is equal to one of the expected states.
 void waitState(Service.CurrentState[] expectedStates, Service.StatusListener listener)
          Periodically checks the current state of the service and returns from the method when the current state is equal to one of the expected states.
 void waitState(Service.CurrentState expectedState, Service.StatusListener listener)
          Periodically checks the current state of the service and returns from the method when the current state is equal to the expected state.
 
Methods inherited from class com.jniwrapper.win32.Handle
clone, closeHandle, equals, waitFor, waitFor
 
Methods inherited from class com.jniwrapper.Pointer.Void
asFunction, asFunction, asTypedPointer, castTo, getDebugInfo, getLength, getValue, hashCode, isNull, read, toString, write
 
Methods inherited from class com.jniwrapper.Parameter
, a, a, acceptIOPerformer, asReturnValue, b, dataBufferAssigned, getAlignedLength, getAlignmentRequirement, getDataBuffer, getDataBufferOffset, indent, pop, push, read, read, setDataBuffer, toByteArray, write
 
Methods inherited from class java.lang.Object
finalize, getClass, notify, notifyAll, wait, wait, wait
 

Field Detail

ACCOUNT_LOCAL_SYSTEM

public static final java.lang.String ACCOUNT_LOCAL_SYSTEM
See Also:
Constant Field Values
Constructor Detail

Service

protected Service(java.lang.String name,
                  Service.AccessRights accessRights)
Creates a service in open state.

Parameters:
name - service name used for opening.
accessRights - access rights to service.

Service

protected Service(java.lang.String name)
Creates a service in open state.

Parameters:
name - service name used for opening
Method Detail

setValue

public void setValue(long value)
Sets handle value of this pointer to service.


getName

public java.lang.String getName()
Returns the service name used for openning the service.

Returns:
the service name.

setName

public void setName(java.lang.String name)
Sets service name.

Parameters:
name - service name.

getDisplayName

public java.lang.String getDisplayName()
Returns the display name of the service.

Returns:
the display name.

setDisplayName

public void setDisplayName(java.lang.String displayName)
Sets the display name. The saveConfiguration() method must be called to apply the changes.

Parameters:
displayName - display name.

getServiceType

public Service.Type getServiceType()
Returns a type of the service.

Returns:
service type.

setServiceType

public void setServiceType(Service.Type serviceType)
Sets a type of the service. The saveConfiguration() method must be called to apply the changes.

Parameters:
serviceType - service type.

isInteractive

public boolean isInteractive()
Returns true, if the service can interact with desktop.

Returns:
true, if service is interactive; otherwise false.
See Also:
Platform SDK: DLLs, Processes, and Threads

setInteractive

public void setInteractive(boolean isInteractive)
Allows / disallows interaction of the service with desktop. The saveConfiguration() method must be called to apply the changes.

Parameters:
isInteractive - if true, the service can interact with desktop; otherwise the service can't interact with desktop.
See Also:
Platform SDK: DLLs, Processes, and Threads

getErrorControl

public Service.ErrorControl getErrorControl()
Returns severity of the error that describes the action performed if the service failed to start:
ErrorControl.IGNORE Logs error and continues startup
ErrorControl.NORMAL Logs error, shows message box with error message and continues startup
ErrorControl.SEVERE Logs error. If the last-known good configuration is started then continues startup else system is restarted with last-known good configuration
ErrorControl.CRITICAL Logs error if possible. If the last-known good configuration is started then startup is failed else system is restarted with last-known good configuration

Returns:
severity of the error.

setErrorControl

public void setErrorControl(Service.ErrorControl errorControl)
Sets severity of the error that describes the action performed if the service failed to start:
ErrorControl.IGNORE Logs error and continues startup
ErrorControl.NORMAL Logs error, shows message box with error message and continues startup
ErrorControl.SEVERE Logs error. If the last-known good configuration is started then continues startup else system is restarted with last-known good configuration
ErrorControl.CRITICAL Logs error if possible. If the last-known good configuration is started then startup is failed else system is restarted with last-known good configuration
The saveConfiguration() method must be called to apply the changes.

Parameters:
errorControl - severity of the error.

getStartupType

public Service.StartupType getStartupType()
Returns startup type of the service.

Returns:
service startup type.

setStartupType

public void setStartupType(Service.StartupType startupType)
Sets startup type of the service. The saveConfiguration() method must be called to apply the changes.

Parameters:
startupType - new startup type.

getBinaryPath

public java.lang.String getBinaryPath()
Returns the absolute path to the executable file for the service.

Note: The path is quoted when the path contains spaces. For example: "c:\Program files\myservice.exe".

Returns:
absolute path to the executable file for the service.

setBinaryPath

public void setBinaryPath(java.lang.String binaryPath)
Sets the absolute path to the executable file for the service.

Note: If the path contains spaces, it must be quoted (for example, "c:\Program files\myservice.exe").

Parameters:
binaryPath - the absolute path to the executable file for the service.

getAccessRights

public Service.AccessRights getAccessRights()
Returns access rights for the service.

Returns:
access to service.
See Also:
Platform SDK: DLLs, Processes, and Threads

setAccessRights

public void setAccessRights(Service.AccessRights accessRights)
Sets access rights to the service. The saveConfiguration() method must be called to apply the changes.

Parameters:
accessRights - new access rights.

getDependencies

public java.lang.String[] getDependencies()
Returns names of the services that the system must start before starting this service.

Returns:
names of services dependencies.

setDependencies

public void setDependencies(java.lang.String[] dependencies)
Sets dependencies for the service. The saveConfiguration() method must be called to apply the changes.

Parameters:
dependencies - names of services that the system must start before this service.

getStartAccount

public java.lang.String getStartAccount()
Returns the account under which the service starts in the form: domainName\\userName or LocalSystem for LocalSystem account.

Returns:
account under which the service starts.

setStartAccount

public void setStartAccount(java.lang.String startAccount)
Sets the account under which the service starts. The saveConfiguration() method must be called to apply the changes.

Parameters:
startAccount - start account for service in the form: domainName\\userName or LocalSystem for LocalSystem account.

getPassword

public java.lang.String getPassword()
Returns:
the password for the start account.

setPassword

public void setPassword(java.lang.String password)
Sets password for the start account. The saveConfiguration() method must be called to apply the changes.

Parameters:
password - account password.

start

public void start()
Starts the service.

Note: The service start can be still in progress after the method returns. You can use waitState(Service.CurrentState) after invoking this method for waiting until the service finishes the start up sequence.


start

public void start(java.lang.String[] parameters)
Starts the service.

Parameters:
parameters - startup parameters.

stop

public void stop()
Stops the service.

Note: The service stopping can be in progress after the method returns. You can use waitState(Service.CurrentState) after calling this method for waiting until the service is stopped.


pause

public void pause()
Pauses the service.


resume

public void resume()
Resumes the paused service.


getStatus

public Service.Status getStatus()
Returns the service status.

Returns:
service status.

getCurrentState

public Service.CurrentState getCurrentState()
Returns the current state of the service.

Returns:
service state.

loadConfiguration

public void loadConfiguration()
Loads the configuration of the service. Call this method to verify working with the up-to-date Service object.


getDescription

public java.lang.String getDescription()
Returns description for the service. This method returns the empty string when running under Windows NT as the corresponding OS function is not available.

Returns:
service description, "" when running under Windows NT.

saveConfiguration

public void saveConfiguration()
Saves configuration of the service. Call loadConfiguration() prior to invoking set of getters to update the configuration.


delete

public void delete()
Marks the service as deleted. The service is not deleted until all service handles have been closed by the close call.


waitState

public void waitState(Service.CurrentState expectedState)
               throws java.lang.InterruptedException
Periodically checks the current state of the service and returns from the method when the current state is equal to the expected state.

Parameters:
expectedState - expected states
Throws:
java.lang.InterruptedException

waitState

public void waitState(Service.CurrentState expectedState,
                      Service.StatusListener listener)
               throws java.lang.InterruptedException
Periodically checks the current state of the service and returns from the method when the current state is equal to the expected state.

Parameters:
expectedState - expected states
listener - listener that notified when is acquired current state of service
Throws:
java.lang.InterruptedException

waitState

public void waitState(Service.CurrentState[] expectedStates)
               throws java.lang.InterruptedException
Periodically checks the current state of the service and returns from the method when the current state is equal to one of the expected states.

Parameters:
expectedStates - expected states
Throws:
java.lang.InterruptedException

waitState

public void waitState(Service.CurrentState[] expectedStates,
                      Service.StatusListener listener)
               throws java.lang.InterruptedException
Periodically checks the current state of the service and returns from the method when the current state is equal to one of the expected states.

Parameters:
expectedStates - expected states
listener - listener that notified when is acquired current state of service
Throws:
java.lang.InterruptedException

createParametersKey

public RegistryKey createParametersKey()
Creates parameters subkey in registry. This key can be used for storing service settings:

     RegistryKey parametersKey = service.createParametersKey();
     parametersKey.values().put("logfile", "D:/tomcat/logs/error.error");
     parametersKey.close();
 

Location of created subkey:


     HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\service_name
 

Returns:
created parameters subkey in registry.

setOpened

protected void setOpened(boolean isOpened)

isOpened

protected boolean isOpened()

lock

protected void lock()
Locks the handle for closing.


unlock

protected void unlock()
Unlocks the handle for closing.


isLocked

protected boolean isLocked()
Returns:
true, if the handle is locked for closing.

checkOpened

protected void checkOpened()
                    throws java.lang.IllegalStateException
Throws:
java.lang.IllegalStateException - if the handle is closed.

close

public boolean close()
Closes the handle to a service-related object.

Returns:
true, if succeeds; otherwise false.

checkResult

protected void checkResult(java.lang.String msg,
                           com.jniwrapper.Bool result)
A utility method for checking an operation result.

Parameters:
msg - error message for the exception to be thrown.
result - boolean value to verify.
Throws:
ServiceException - if the result is false.