SK.gnome.dwarf
Interface Service

All Known Subinterfaces:

Server

All Known Implementing Classes:

GenericServer, GenericService

public interface Service

Provides core functionality of a service.

This interface provides a base atomic building unit of the Dwarf Server Framework. A Dwarf-based application typically consists of one or more classes derived from this interface.

The service lifecycle has several stages:

1. The service is instantiated via its constructor and its attributes are set via the corresponding setter methods.
2. It is initialized via its init(Server) method.
3. It is started via its start() method. The started service is ready to serve and can be utilized by the end-user or by other parts of the application.
4. If the service implements the Stoppable interface, it can be stopped temporarily by calling its stop() method. A stopped service is not usable until its start() method is called again.
5. It is shut down via the shutdown() method. A shut down service may not be used any more

Since the init, start, stop and shutdown methods are used to change the service internal state, they are called the state transition methods.

The following table ilustrates the relationships between the state transition methods and the associated service states. The service state can be tested at any time by calling the getState(int) method.

 method       getState(int)   INITIALIZED     STARTED     STOPPED     SHUTDOWN
 -----------------------------------------------------------------------------
 <constructor>    =>          false           false       false       false
 init(Service)    =>          true            false       false       false
 start()          =>          true            true        false       false
 stop()           =>          true            false       true        false
 shutdown()       =>          true            false       false       true
 

When overloading the transition methods in a subclass, the inherited method must be called first, typically as the first statement of the overloading method:

 public void init(Server parent) throws ServiceException
 { super.init(parent);

   // the subclass-specific initialization code
   ...
 }
 

This class provides also some constants and methods for logging and authentication. The authentication methods are based on the javax.security.auth package, but they do not imply any particular authentication mechanism to be used by default.

The getParameters() method may return an instance of the Parameters interface, which provides a set of runtime (and probably modifiable) parameters, which are specific to this service.

Field Summary

static int	INITIALIZED The initialized state.
static LogLevel	LOG_DEBUG Logging level of a debugging message.
static LogLevel	LOG_ERROR Logging level of a recoverable error message.
static LogLevel	LOG_FATAL Logging level of an unrecoverable error message.
static LogLevel	LOG_INFO Logging level of an informational message.
static LogLevel	LOG_TRACE Logging level of a tracing message.
static LogLevel	LOG_WARN Logging level of a warning message.
static LogLevel	LOG_XFER Logging level of a transfer message.
static int	SHUTDOWN The shutdown state.
static int	STARTED The started state.
static int	STOPPED The stopped state.

Method Summary

java.lang.String	getFullName() Returns the full service name.
java.lang.String	getName() Returns the service name.
Parameters	getParameters() Returns the service parameters.
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	shutdown() Shuts down the service.
void	start() Starts the service.
void	stop() Stops the service.

Field Detail

INITIALIZED

public static final int INITIALIZED

The initialized state.

See Also:

init(Server), Constant Field Values

STARTED

public static final int STARTED

The started state.

See Also:

start(), Constant Field Values

STOPPED

public static final int STOPPED

The stopped state.

See Also:

stop(), Constant Field Values

SHUTDOWN

public static final int SHUTDOWN

The shutdown state.

See Also:

shutdown(), Constant Field Values

LOG_XFER

public static final LogLevel LOG_XFER

Logging level of a transfer message.

LOG_TRACE

public static final LogLevel LOG_TRACE

Logging level of a tracing message.

LOG_DEBUG

public static final LogLevel LOG_DEBUG

Logging level of a debugging message.

LOG_INFO

public static final LogLevel LOG_INFO

Logging level of an informational message.

LOG_WARN

public static final LogLevel LOG_WARN

Logging level of a warning message.

LOG_ERROR

public static final LogLevel LOG_ERROR

Logging level of a recoverable error message.

LOG_FATAL

public static final LogLevel LOG_FATAL

Logging level of an unrecoverable error message.

Method Detail

getName

public java.lang.String getName()

Returns the service name.

Returns:

the service name

getFullName

public java.lang.String getFullName()

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 "/".

Returns:

the full service name

getState

public boolean getState(int state)

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.

Parameters:

state - the queried state

Returns:

true if the state argument corresponds to the current service state

See Also:

INITIALIZED, STARTED, STOPPED, SHUTDOWN

getParameters

public Parameters getParameters()

Returns the service parameters.

Service parameters can be used to provide a set of parameters related to the service itself.

Returns:

the parameters or null if no parameters are available

init

public void init(Server parent)
          throws ServiceException

Initializes the service.

This method changes the service state to 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 start() method, or it can be shut down by invoking the shutdown() method.

Parameters:

parent - the container of this service or null

Throws:

java.lang.IllegalStateException - if a call to getState(INITIALIZED) returns true

ServiceException - if an error occured during the initialization process

start

public void start()
           throws ServiceException

Starts the service.

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

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

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

Throws:

java.lang.IllegalStateException - if a call to getState(INITIALIZED) returns false or a call to getState(STARTED) returns true or a call to getState(SHUTDOWN) returns true

ServiceException - if an error occured during the starting process

stop

public void stop()
          throws ServiceException

Stops the service.

This method changes the service state to both the INITIALIZED and 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 start() method, or to shut down by invoking the shutdown() method on it.

Throws:

java.lang.IllegalStateException - if a call to getState(STARTED) returns false

java.lang.UnsupportedOperationException - if the service doesn't implement the Stoppable interface

ServiceException - if an error occured during the stopping process

shutdown

public void shutdown()

Shuts down the service.

This method changes the service state to both the INITIALIZED and 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.

Throws:

java.lang.IllegalStateException - if a call to getState(INITIALIZED) returns false

log

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

Logs the message with the given logging level.

Parameters:

level - the logging level

message - the message

log

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

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

Parameters:

level - the logging level

message - the message

error - the error

login

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

Authenticates the subject.

The AuthId object relates the login and logout operations, thus enabling multiple authentication of a single subject.

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 void logout(AuthId id,
                   javax.security.auth.Subject subject)
            throws javax.security.auth.login.LoginException

Logouts the subject.

The AuthId object must reference the previous login operation used to authenticate the given subject.

Parameters:

id - the authentication identifier

subject - the subject to log out

Throws:

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