SK.gnome.dwarf
Class ParametersService

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

All Implemented Interfaces:

Parameters, Reportable, Service

public abstract class ParametersService

extends GenericService

implements Parameters

Provides a generic Parameters implementation.

An instance of this class can be added to a GenericServer object, which makes it accessible to all nested services via their Service.getParameters() method.

Each parameter is represented by a protected member variable with pair of the traditional getter and setter public methods. If the server needs to provide an integer parameter named smtpTimeout, for example, the ParametersService may be subclassed as follows:

 public class SMTPParameters extends ParametersService
 { protected int smtpTimeout = 10;

   public int getSmtpTimeout()
   { return smtpTimeout;
   }

   public void setSmtpTimeout(int value)
   { readOnly(STARTED);
     smtpTimeout = value;
   }
 }
 

The following code illustrates a sample use of the SMTPParameters class:

 // instantiate the server
 SMTPServer server = new SMTPServer("SMTP Server");

 // instantiate the server parameters
 SMTPParameters params = new SMTPParameters("SMTP Parameters");

 // set the desired parameter value
 params.setSmtpTimeout(100);

 // add the parameters to the server
 server.addService(params);

 // instantiate a nested service
 SMTPQueue queue = new SMTPQueue("SMTP Queue");

 // add the nested service to the server
 server.addService(queue);

 // ... service configuration and composition would continue here ...  

 // initalize and start the server
 server.init(null);
 server.start();

 // get the parameter value
 int timeout = ((SMTPParameters)server.getParameters()).getSmtpTimeout();

 // get the same parameter value from the nested service
 timeout = ((SMTPParameters)queue.getParameters()).getSmtpTimeout();

 // set the parameter value - would throw an exception because server is in illegal state
 ((SMTPParameters)server.getParameters()).setSmtpTimeout(300);
 

The method readOnly(int) can be used to indicate that a parameter is read-only in the particular service state. Since the nested service's state always corresponds to the parent server's state, the smtpTimeout parameter from the example may be changed only if the parent server is not in the Service.STARTED state.

Note: This service is an exception to the rule that a service attributes may not be set after the service has been inititialized. However, the application integrity can be ensured by using the mentioned readOnly(int) method.

See Also:

Service.getParameters()

Field Summary

Fields inherited from class SK.gnome.dwarf.GenericService

initParameters, parent

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

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

Method Summary

protected void	readOnly(int state) Indicates a read-only parameter.
java.lang.String	report() Returns the service report.

Methods inherited from class SK.gnome.dwarf.GenericService

getAuthenticator, getAuthFacility, getFullName, getInitParameter, getInitParameterNames, getLogFacility, getLogger, getName, getParameters, getPrincipal, getShutdownTimeout, getState, init, log, log, login, logout, setAuthFacility, setInitParameters, setLogFacility, shutdown, start, stop, toString

Methods inherited from class java.lang.Object

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

Constructor Detail

ParametersService

public ParametersService(java.lang.String name)

Constructs a new ParametersService.

Method Detail

readOnly

protected void readOnly(int state)

Indicates a read-only parameter.

This method tests the service transition state by invoking the GenericService.getState(int) method and if the result is true, it throws an IllegalStateException. It can be used in the body of a setter method to indicate that the corresponding parameter is read-only in the given transition state:

 public void setLoginTimeout(int timeout)
 { 
   // do not allow to set the timeout if the service has been started already
   readOnly(STARTED);

   this.timeout = timeout;
 }
 

Parameters:

state - the service state

Throws:

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

report

public java.lang.String report()

Returns the service report.

It returns a list of parameter names and values. Parameters are displayed in the form of the "name=value" pairs, each on a separate line.

Specified by:

report in interface Reportable

Returns:

current service state in a human-readable format