com.jniwrapper.win32.service

Class Service

java.lang.Object

com.jniwrapper.Parameter

com.jniwrapper.Pointer.Void

com.jniwrapper.win32.Handle

com.jniwrapper.win32.service.Service

All Implemented Interfaces:

com.jniwrapper.IntegerParameter, com.jniwrapper.PointerParameter

public class Service
extends Handle

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

Nested Classes

Modifier and Type	Class and Description
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

Fields

Modifier and Type	Field and Description
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

Constructors

Modifier	Constructor and Description
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

Modifier and Type	Method and Description
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: Error codes 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, castTo, getDebugInfo, getLength, getValue, hashCode, isNull, read, toString, write

Methods inherited from class com.jniwrapper.Parameter

acceptIOPerformer, asReturnValue, 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.

Specified by:

setValue in interface com.jniwrapper.IntegerParameter

Overrides:

setValue in class com.jniwrapper.Pointer.Void

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.

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.

getErrorControl

public Service.ErrorControl getErrorControl()

Returns severity of the error that describes the action performed if the service failed to start:

Error codes

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.

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.