SK.gnome.dwarf
Class GenericService

java.lang.Object
  SK.gnome.dwarf.GenericService

All Implemented Interfaces:

Service

Direct Known Subclasses:

DNSService, GenericServer, JAASAuthenticator, ParametersService, SimplePool, ThreadService

public abstract class GenericService

extends java.lang.Object

implements Service

Provides a generic Service implementation.

This is the most basic implementation of the Service interface. All services of this framework extend this abstract class.

The following requirements related to the service lifecycle are imposed by this implementation, and must be fulfilled by the application code:

1. service attributes must be set before the service is initialized
2. the attributes must not be changed after the service has been initialized
3. service's functionality may not be used by any part of the application if it has not been started, or it is currently stopped, or it has been shut down

All derived classes as well as the whole application code must follow these simple rules to be runtime compatible with the core framework.

The following sample code illustrates a typical use of a service:

 // instatiate a new service
 PizzaService ps = new PizzaService("Pizza Service");

 // set the service attributes first
 ps.setGreeting("Hello, here's you pizza!");  // the greeting sentence
 ps.setType(ASAP);                            // the type of the delivery
 ps.setMultipleDelivery(true);                // enable multiple deliveries

 // initialize the service
 ps.init(null);             // null means that the service has no container

 // start the service
 ps.start();

 // now the service is ready to serve
 ps.deliver(new Pizza(HAM_AND_CHEESE), "Mr. Spock", "2nd NW Hoyt, Portland, OR"));
 ps.deliver(new Pizza(NAPOLITANA), "Mr. Spock Jr.", "2nd NW Hoyt, Portland, OR"));

 // shut down the service 
 ps.shutdown();
 

Thread-safety note:
The state transition methods are not synchronized, therefore they must be synchronized manually, if required.

Field Summary

protected StringProperties	initParameters The initial service parameters.
protected Server	parent The service container.

Fields inherited from interface SK.gnome.dwarf.Service

INITIALIZED, LOG_DEBUG, LOG_ERROR, LOG_FATAL, LOG_INFO, LOG_TRACE, LOG_WARN, LOG_XFER, SHUTDOWN, STARTED, STOPPED

Constructor Summary

GenericService(java.lang.String name)
Constructs a new GenericService.

Method Summary

protected Authenticator	getAuthenticator() Returns an authentication service for this object.
protected java.lang.String	getAuthFacility() Returns the authentication facility.
java.lang.String	getFullName() Returns the full service name.
java.lang.String	getInitParameter(java.lang.String name) Returns the initial parameter by the name.
java.util.Enumeration	getInitParameterNames() Returns the initial parameter names.
protected java.lang.String	getLogFacility() Returns the logging facility.
protected Logger	getLogger() Returns a logging service for this object.
java.lang.String	getName() Returns the service name.
Parameters	getParameters() Returns the service parameters.
java.security.Principal	getPrincipal() Returns a principal representing the service.
protected int	getShutdownTimeout() Returns the shutdown timeout.
boolean	getState(int state) Returns the current service state.
void	init(Server parent) Initializes the service.
void	log(LogLevel level, java.lang.String message) Logs the message with the given logging level.
void	log(LogLevel level, java.lang.String message, java.lang.Throwable error) Logs the message and the error with the given logging level.
AuthId	login(javax.security.auth.Subject subject, javax.security.auth.callback.CallbackHandler handler) Authenticates the subject.
void	logout(AuthId id, javax.security.auth.Subject subject) Logouts the subject.
void	setAuthFacility(java.lang.String facility) Sets the authentication facility.
void	setInitParameters(StringProperties parameters) Sets the initial parameters.
void	setLogFacility(java.lang.String facility) Sets the logging facility.
void	shutdown() Shuts down the service.
void	start() Starts the service.
void	stop() Stops the service.
java.lang.String	toString() Returns the string representation of the service.

Methods inherited from class java.lang.Object

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

Field Detail

parent

protected Server parent

The service container.

Contains a reference to the parent server, i.e. the server which contains this service. A null value means that the service is not contained by any server.

The field value is assigned in the init(Server) method during the initialization procedure.

initParameters

protected StringProperties initParameters

The initial service parameters.

The initial parameters are intended to provide a set of initial read-only string parameters, probably with no prior knowledge of their type or syntax.

The purpose of the initial parameters is different than of those defined by the Parameters interface, which represents a set of parameters, dynamically shared by a tree of server and service instances. The initial parameters, on the contrary, represents a service-specific set of string arguments, accessible only to this service, and not to the outside world. They may be used by a subclass instance to pass an arbitrary initialization parameters to the service's initialization procedure, for example.

See Also:

getInitParameter(String), getInitParameterNames(), setInitParameters(StringProperties)

Constructor Detail

GenericService

public GenericService(java.lang.String name)

Constructs a new GenericService.

The string argument is trimmed before it is used for the service name. Since the slash "/" character is used as a separator in the full service names, it must not be included in the service name.

Parameters:

name - the service name

Throws:

java.lang.NullPointerException - if the name is null

java.lang.IllegalArgumentException - if either the name is empty string or it contains the slash character '/'

Method Detail

getName

public final java.lang.String getName()

Description copied from interface: Service

Returns the service name.

Specified by:

getName in interface Service

Returns:

the service name

getFullName

public java.lang.String getFullName()

Description copied from interface: Service

Returns the full service name.

The full name identifies the particular service instance in the whole service namespace. If there is a hierarchical tree of service instances, the full name must be a complete path from the top-level server down to the given nested service, like "Main Server/HTTP Server/Session Manager", for example.

The separation character used in the full name is always the slash "/".

Specified by:

getFullName in interface Service

Returns:

the full service name

getState

public final boolean getState(int state)

Description copied from interface: Service

Returns the current service state.

If a service has been initialized, for example, the getState(INITIALIZED) call returns true, but the getState(STARTED) call returns false if it has not been started yet.

Specified by:

getState in interface Service

Parameters:

state - the queried state

Returns:

true if the state argument corresponds to the current service state

See Also:

Service.INITIALIZED, Service.STARTED, Service.STOPPED, Service.SHUTDOWN

getParameters

public Parameters getParameters()

Returns the service parameters.

It returns the parent server's parameters as returned from its getParameters() method, or null if there is no parent server available.

Specified by:

getParameters in interface Service

Returns:

the parameters or null if no parameters are available

init

public void init(Server parent)
          throws ServiceException

Description copied from interface: Service

Initializes the service.

This method changes the service state to Service.INITIALIZED.

If the parent argument is not null, it means that the service is becomig a part of the server which the parent argument points to.

After a successful initialization the service can be started by invoking the Service.start() method, or it can be shut down by invoking the Service.shutdown() method.

Specified by:

init in interface Service

Parameters:

parent - the container of this service or null

Throws:

ServiceException - if an error occured during the initialization process

start

public void start()
           throws ServiceException

Description copied from interface: Service

Starts the service.

This method changes the service state to both the Service.INITIALIZED and Service.STARTED.

In order to be started the service must be initialized first by calling its Service.init(Server) method.

After the successful start the service can be stopped by invoking the Service.stop() method if it implements the Stoppable interface, or it can be shut down by invoking the Service.shutdown() method on it.

Specified by:

start in interface Service

Throws:

ServiceException - if an error occured during the starting process

stop

public void stop()
          throws ServiceException

Description copied from interface: Service

Stops the service.

This method changes the service state to both the Service.INITIALIZED and Service.STOPPED.

In order to allow this method to work properly, the service must implement the Stoppable interface.

After the service has been stopped, it must be able to start again by invoking the Service.start() method, or to shut down by invoking the Service.shutdown() method on it.

Specified by:

stop in interface Service

Throws:

ServiceException - if an error occured during the stopping process

shutdown

public void shutdown()

Description copied from interface: Service

Shuts down the service.

This method changes the service state to both the Service.INITIALIZED and Service.SHUTDOWN.

A service should be able to shut down if it has been initialized successfuly. If the shutdown process completes the service cannot be used more.

Specified by:

shutdown in interface Service

log

public final void log(LogLevel level,
                      java.lang.String message)

Logs the message with the given logging level.

The message is logged via logging service returned from the getLogger() method, or it is printed out to the standard system output, if that method returns null.

The facility argument value passed into the Logger is obtained via the getLogFacility() method.

Specified by:

log in interface Service

Parameters:

level - the logging level

message - the message

log

public final void log(LogLevel level,
                      java.lang.String message,
                      java.lang.Throwable error)

Logs the message and the error with the given logging level.

The message is logged via logging service returned from the getLogger() method, or it is printed out to the standard system output, if that method returns null.

The facility argument value passed into the Logger is obtained via the getLogFacility() method.

Specified by:

log in interface Service

Parameters:

level - the logging level

message - the message

error - the error

login

public final AuthId login(javax.security.auth.Subject subject,
                          javax.security.auth.callback.CallbackHandler handler)
                   throws javax.security.auth.login.LoginException

Authenticates the subject.

The subject is authenticated via authentication service returned from the getAuthenticator() method. A LoginException is thrown if that method returns null, i.e. there is no authentication service available.

After the successful login the principal returned by the getPrincipal() method is added to the given subject to represent this service, thus enabling the possibility to authenticate a single subject by more than one service.

The facility argument value passed into the Authenticator is obtained via the getAuthFacility() method.

Specified by:

login in interface Service

Parameters:

subject - the subject to log in

handler - the callback handler

Returns:

the authentication identifier

Throws:

javax.security.auth.login.LoginException - if the login operation fails

logout

public final void logout(AuthId id,
                         javax.security.auth.Subject subject)
                  throws javax.security.auth.login.LoginException

Logouts the subject.

The subject is authenticated via authentication service returned from the getAuthenticator() method. A LoginException is thrown if that method returns null, i.e. there is no authentication service available.

Before the logout the principal returned by the getPrincipal() method is removed from the given subject.

The facility argument value passed into the Authenticator is obtained via the getAuthFacility() method.

Specified by:

logout in interface Service

Parameters:

id - the authentication identifier

subject - the subject to log out

Throws:

javax.security.auth.login.LoginException - if the logout operation fails

setLogFacility

public void setLogFacility(java.lang.String facility)

Sets the logging facility.

Sets the logging facility of this service.

See Also:

getLogFacility()

setAuthFacility

public void setAuthFacility(java.lang.String facility)

Sets the authentication facility.

Sets the authentication facility of this service.

See Also:

getAuthFacility()

setInitParameters

public void setInitParameters(StringProperties parameters)

Sets the initial parameters.

It sets the value of the initParameters field.

Parameters:

parameters - the initial parameters

getInitParameter

public java.lang.String getInitParameter(java.lang.String name)

Returns the initial parameter by the name.

Returns the initial parameter corresponding to the given name or null if no such parameter exists.

Parameters:

name - the parameter name

Returns:

the parameter value

See Also:

initParameters

getInitParameterNames

public java.util.Enumeration getInitParameterNames()

Returns the initial parameter names.

Returns an enumeration of the parameter names or an empty enumeration if no parameters are available.

Returns:

the parameter names

See Also:

initParameters

getPrincipal

public java.security.Principal getPrincipal()

Returns a principal representing the service.

Returns an instance of the ServicePrincipal class with the name equal to the service's full name.

See Also:

getFullName()

getLogFacility

protected java.lang.String getLogFacility()

Returns the logging facility.

Logging facility is a unique string, which identifies the log messages generated by this service.

This method returns either the logging facility set via the setLogFacility(String) method, or the logging facility of the parent server. If there is no parent server available, it returns null.

Returns:

the logging facility

getAuthFacility

protected java.lang.String getAuthFacility()

Returns the authentication facility.

Authentication facility is a unique string identifying the particular authentication mechanism (e.g. a login module configuration), which will be used to authenticate subjects in the context of this service.

This method returns either the authentication facility set via the setAuthFacility(String) method, or the authentication facility of the parent server. If there is no parent server available, it returns null.

Returns:

the authentication facility

getLogger

protected Logger getLogger()

Returns a logging service for this object.

It returns logging service of the parent server or null if there is no parent server available.

This service is used by the logging methods to actually handle the logging requests.

Returns:

the logging service

getAuthenticator

protected Authenticator getAuthenticator()

Returns an authentication service for this object.

It returns authentication service of the parent server or null if there is no parent server available.

This service is used by the authentication methods to actually handle the authentication requests.

Returns:

the authentication service

getShutdownTimeout

protected int getShutdownTimeout()

Returns the shutdown timeout.

The shutdown timeout is a number of milliseconds the shutdown process should wait for finishing the current service's operation before returning from its shutdown() method.

This method returns a value of the Constants.DEFAULT_SHUTDOWN_TIMEOUT constant.

Returns:

shutdown timeout in milliseconds

toString

public java.lang.String toString()

Returns the string representation of the service. Returns the service name together with its full class name.

Returns:

the string service_name [class_name]

See Also:

getName()