|
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
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:
init(Server)
method.start()
method. The started service is ready to serve
and can be utilized by the end-user or by other parts of the application.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.shutdown()
method. A shut down service may not be
used any moreThe 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 |
public static final int INITIALIZED
init(Server)
,
Constant Field Valuespublic static final int STARTED
start()
,
Constant Field Valuespublic static final int STOPPED
stop()
,
Constant Field Valuespublic static final int SHUTDOWN
shutdown()
,
Constant Field Valuespublic static final LogLevel LOG_XFER
public static final LogLevel LOG_TRACE
public static final LogLevel LOG_DEBUG
public static final LogLevel LOG_INFO
public static final LogLevel LOG_WARN
public static final LogLevel LOG_ERROR
public static final LogLevel LOG_FATAL
Method Detail |
public java.lang.String getName()
public java.lang.String getFullName()
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 "/".
public boolean getState(int 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.
state
- the queried state
INITIALIZED
,
STARTED
,
STOPPED
,
SHUTDOWN
public Parameters getParameters()
Service parameters can be used to provide a set of parameters related to the service itself.
public void init(Server parent) throws ServiceException
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.
parent
- the container of this service or null
java.lang.IllegalStateException
- if a call to getState(INITIALIZED) returns true
ServiceException
- if an error occured during the initialization processpublic void start() throws ServiceException
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.
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 processpublic void stop() throws ServiceException
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.
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 processpublic void shutdown()
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.
java.lang.IllegalStateException
- if a call to getState(INITIALIZED) returns
falsepublic void log(LogLevel level, java.lang.String message)
level
- the logging levelmessage
- the messagepublic void log(LogLevel level, java.lang.String message, java.lang.Throwable error)
level
- the logging levelmessage
- the messageerror
- the errorpublic AuthId login(javax.security.auth.Subject subject, javax.security.auth.callback.CallbackHandler handler) throws javax.security.auth.login.LoginException
The AuthId
object relates the login and logout operations, thus enabling
multiple authentication of a single subject.
subject
- the subject to log inhandler
- the callback handler
javax.security.auth.login.LoginException
- if the login operation failspublic void logout(AuthId id, javax.security.auth.Subject subject) throws javax.security.auth.login.LoginException
The AuthId
object must reference the previous login operation used to authenticate
the given subject.
id
- the authentication identifiersubject
- the subject to log out
javax.security.auth.login.LoginException
- if the logout operation fails
|
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |