jade.core
Class BaseService

java.lang.Object
  |
  +--jade.core.BaseService
All Implemented Interfaces:
Service

public abstract class BaseService
extends java.lang.Object
implements Service

The BaseService abstract class partially implements the Service interface, providing a simple and uniform mechanism for slice management and service discovery. Developers interested in creating JADE kernel level services should extend BaseService instead of directly implementing the Service interface

Author:
Giovanni Rimassa - FRAMeTech s.r.l.

Nested Class Summary
 
Nested classes inherited from class jade.core.Service
Service.Slice
 
Field Summary
static java.lang.String MAIN_SLICE
           
protected  ServiceFinder myFinder
           
protected  Logger myLogger
           
static java.lang.String THIS_SLICE
           
 
Fields inherited from interface jade.core.Service
DEAD_NODE, DEAD_PLATFORM_MANAGER, DEAD_REPLICA, DEAD_SLICE, NEW_NODE, NEW_REPLICA, NEW_SLICE, REATTACHED
 
Constructor Summary
BaseService()
           
 
Method Summary
protected  void addAlias(java.lang.String alias, java.lang.String name)
          This protected method allows subclasses to define their own naming schemes, by adding aliases for existing slice names.
 void boot(Profile p)
          Performs the active initialization step of a kernel-level service.
protected  void clearCachedSlice(java.lang.String name)
           
protected  CallbackInvokator createInvokator()
           
 Service.Slice[] getAllSlices()
          The getAllSlices() implementation of this class directly retrieves the current list of slices from the Service Manager.
 Behaviour getAMSBehaviour()
          This should be properly implemented by the services that require a service specific Behaviour running in the AMS.
 Filter getCommandFilter(boolean direction)
          This should be properly implemented by the services that have filters.
 Sink getCommandSink(boolean direction)
          This should be properly implemented by the services that have sinks.
protected  Service.Slice getFreshSlice(java.lang.String name)
           
 ServiceHelper getHelper(Agent a)
          This should be properly implemented by the services that have helpers.
 java.lang.Class getHorizontalInterface()
          This should be properly implemented by the services that have non-empty slices.
 Node getLocalNode()
           
 Service.Slice getLocalSlice()
          This should be properly implemented by the services that have non-empty slices.
 int getNumberOfSlices()
          This method returns the current number of slices known to this service on this node.
 java.lang.String[] getOwnedCommands()
          This should be properly implemented by the services that owns vertival commands.
 Service.Slice getSlice(java.lang.String name)
          The getSlice() implementation of this class works as follows: First, the name alias table is used to convert the given slice name into another name, if any Then, the new name (which may or may not be different from the original one) is used to look up an internal table keeping the service slices If no slice was found, the ServiceFinder is asked to provide the slice, which is then put into the local table.
 void init(AgentContainer ac, Profile p)
          Performs the passive initialization step of the service.
protected  java.lang.String lookupAlias(java.lang.String alias)
          This protected method is used by getSlice() to dereference aliases for slice names.
 void shutdown()
          Performs the shutdown step of a kernel-level service.
 java.lang.Object submit(VerticalCommand cmd)
          Allows submitting a vertical command for processing.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 
Methods inherited from interface jade.core.Service
getName
 

Field Detail

MAIN_SLICE

public static final java.lang.String MAIN_SLICE
See Also:
Constant Field Values

THIS_SLICE

public static final java.lang.String THIS_SLICE
See Also:
Constant Field Values

myFinder

protected ServiceFinder myFinder

myLogger

protected Logger myLogger
Constructor Detail

BaseService

public BaseService()
Method Detail

init

public void init(AgentContainer ac,
                 Profile p)
          throws ProfileException
Description copied from interface: Service
Performs the passive initialization step of the service. This method is called before activating the service. Its role should be simply the one of a constructor, setting up the internal data as needed. Service implementations should not use the Service Manager and Service Finder facilities from within this method. A distributed initialization protocol, if needed, should be exectuted within the boot() method.

Specified by:
init in interface Service
Parameters:
ac - The agent container this service is activated on.
p - The configuration profile for this service.
Throws:
ProfileException - If the given profile is not valid.

getSlice

public Service.Slice getSlice(java.lang.String name)
                       throws ServiceException
The getSlice() implementation of this class works as follows:
  1. First, the name alias table is used to convert the given slice name into another name, if any
  2. Then, the new name (which may or may not be different from the original one) is used to look up an internal table keeping the service slices
  3. If no slice was found, the ServiceFinder is asked to provide the slice, which is then put into the local table.

Specified by:
getSlice in interface Service
Parameters:
name - A name for the requested slice. The name must be unique within this service.
Returns:
The Slice object that is a part of this service and is identified by the given name, or null if no such slice exists.
Throws:
ServiceException - If some underlying error (e.g. a network problem) occurs, that does not allow to decide whether the requested slice exists or not.

getNumberOfSlices

public int getNumberOfSlices()
This method returns the current number of slices known to this service on this node. Due to the distributed nature of many JADE services, there is no guaranteed that calling this method for the same service on different nodes will actually result on the same number.

Specified by:
getNumberOfSlices in interface Service
Returns:
The number of slices of this service that are known to this node.

getLocalNode

public Node getLocalNode()
                  throws IMTPException
IMTPException

getAllSlices

public Service.Slice[] getAllSlices()
                             throws ServiceException
The getAllSlices() implementation of this class directly retrieves the current list of slices from the Service Manager.

Specified by:
getAllSlices in interface Service
Returns:
An array of Service.Slice objects, whose elements are the slices of this service deployed at the different platform nodes.
Throws:
ServiceException - If some underlying error (e.g. a network problem) occurs, that does not allow to retrieve the full slice list.

addAlias

protected void addAlias(java.lang.String alias,
                        java.lang.String name)
This protected method allows subclasses to define their own naming schemes, by adding aliases for existing slice names.

Parameters:
alias - The new alias name.
name - The real name this alias must be mapped to.

lookupAlias

protected java.lang.String lookupAlias(java.lang.String alias)
This protected method is used by getSlice() to dereference aliases for slice names. Subclasses can override this method to build their own service-specific naming schema.

Parameters:
alias - The alias name to map to a real slice name.
Returns:
A mapped name, or the original one if no mapping was found.

getCommandFilter

public Filter getCommandFilter(boolean direction)
This should be properly implemented by the services that have filters. Note that when called multiple times with the same value of the direction parameter this method MUST always return the same object!

Specified by:
getCommandFilter in interface Service
Parameters:
direction - One of the two constants Filter.INCOMING and Filter.OUTGOING, distinguishing between the two filter chains managed by the command processor.
Returns:
A Filter object, used by this service to intercept and process kernel-level commands. If the service does not wish to install a command filter for one or both directions, it can just return null when appropriate.
See Also:
jade.core.CommandProcessor

getCommandSink

public Sink getCommandSink(boolean direction)
This should be properly implemented by the services that have sinks.

Specified by:
getCommandSink in interface Service
Parameters:
direction - One of the two constants Sink.COMMAND_SOURCE or Sink.COMMAND_TARGET, to state whether this sink will handle locally issued commands or commands incoming from remote nodes.
Returns:
Concrete services must return their own implementation of the Sink interface, that will be invoked by the kernel in order to consume any incoming vertical command owned by this service. If the service does not wish to install a command sink, it can just return null.
See Also:
Service.getOwnedCommands()

getOwnedCommands

public java.lang.String[] getOwnedCommands()
This should be properly implemented by the services that owns vertival commands.

Specified by:
getOwnedCommands in interface Service
Returns:
An array containing the names of all the vertical commands this service wants to own. If this service has no such commands (it acts purely as a command filter), it can return an empty array, or null as well.
See Also:
jade.core.Service#getCommandSink()

getHorizontalInterface

public java.lang.Class getHorizontalInterface()
This should be properly implemented by the services that have non-empty slices.

Specified by:
getHorizontalInterface in interface Service
Returns:
A Class object, representing the interface that is implemented by the slices of this service. Let s be the Class object corresponding to the Service.Slice interface, and let c be the returned Class object. Then, the two following conditions must hold:
  1. c.isInterface() == true
  2. s.isAssignableFrom(c) == true

getLocalSlice

public Service.Slice getLocalSlice()
This should be properly implemented by the services that have non-empty slices.

Specified by:
getLocalSlice in interface Service
Returns:
The slice of this service that resides on the local platform node, or null if no such slice exists.

getHelper

public ServiceHelper getHelper(Agent a)
                        throws ServiceException
This should be properly implemented by the services that have helpers.

Specified by:
getHelper in interface Service
Parameters:
a - The agent which the helper is requested for.
Returns:
The ServiceHelper to be used by the agent.
ServiceException
See Also:
AgentToolkit#getHelper, Agent.getHelper(java.lang.String)

getAMSBehaviour

public Behaviour getAMSBehaviour()
This should be properly implemented by the services that require a service specific Behaviour running in the AMS.

Specified by:
getAMSBehaviour in interface Service
Returns:
A Behaviour object associated with this service, or null if no such behaviour exists.

boot

public void boot(Profile p)
          throws ServiceException
Description copied from interface: Service
Performs the active initialization step of a kernel-level service. When JADE kernel calls this method, the service has already been already associated with its container and registered with the Service Manager.

Specified by:
boot in interface Service
Parameters:
p - The configuration profile for this service.
Throws:
ServiceException - If a problem occurs during service initialization.

shutdown

public void shutdown()
Description copied from interface: Service
Performs the shutdown step of a kernel-level service. The JADE kernel calls this method just before uninstalling this service

Specified by:
shutdown in interface Service

submit

public java.lang.Object submit(VerticalCommand cmd)
                        throws ServiceException
Description copied from interface: Service
Allows submitting a vertical command for processing. The given vertical command must be owned by this service (i.e. its name must be one of the constants contained in the array returned by getOwnedCommands(), or an exception is thrown

Specified by:
submit in interface Service
Parameters:
cmd - The command to submit to the service.
Returns:
The result of the command, or null if this command produced no result. If an exception was produced, it will not be thrown, but will be returned as well.
Throws:
ServiceException - If the passed command does not belong to this service.

getFreshSlice

protected Service.Slice getFreshSlice(java.lang.String name)
                               throws ServiceException
ServiceException

clearCachedSlice

protected void clearCachedSlice(java.lang.String name)

createInvokator

protected CallbackInvokator createInvokator()


JADE