jade.core

Class BaseService

java.lang.Object

jade.core.BaseService

All Implemented Interfaces:

Service

Direct Known Subclasses:

SAMService

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/interfaces inherited from interface jade.core.Service

Service.Slice

Field Summary

Fields

Modifier and Type	Field and Description
static java.lang.String	ALL_DUMP_KEY
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

ADOPTED_NODE, DEAD_NODE, DEAD_PLATFORM_MANAGER, DEAD_REPLICA, DEAD_SLICE, NEW_NODE, NEW_REPLICA, NEW_SLICE, REATTACHED, RECONNECTED

Constructor Summary

Constructors

Constructor and Description
BaseService()

Method Summary

Modifier and Type	Method and Description
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.
void	broadcast(HorizontalCommand cmd, boolean includeMyself)
protected void	clearCachedSlice(java.lang.String name)
protected CallbackInvokator	createInvokator()
java.lang.String	dump(java.lang.String key) This method can be redefined to support service internal data inspection by means of the ContainerMonitorAgent included in the misc add-on.
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.
protected IMTPManager	getIMTPManager()
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.
boolean	isLocal()
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.
static java.lang.String	stringifySlice(Service.Slice s)
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

ALL_DUMP_KEY

public static final java.lang.String ALL_DUMP_KEY

See Also:

Constant Field Values

myFinder

protected ServiceFinder myFinder

myLogger

protected transient 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

Throws:

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. Note that slices are retrieved directly from the Main and not from the cache.

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.

broadcast

public void broadcast(HorizontalCommand cmd,
                      boolean includeMyself)
               throws IMTPException,
                      ServiceException

Throws:

IMTPException

ServiceException

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.

isLocal

public boolean isLocal()

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.

Throws:

ServiceException

See Also:

AgentToolkit.getHelper(jade.core.Agent, java.lang.String), 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

Throws:

ServiceException

getIMTPManager

protected IMTPManager getIMTPManager()

clearCachedSlice

protected void clearCachedSlice(java.lang.String name)

dump

public java.lang.String dump(java.lang.String key)

This method can be redefined to support service internal data inspection by means of the ContainerMonitorAgent included in the misc add-on. The default implementation just dumps the map of cached slices

Parameters:

key - A hint indicating which service data should be dumped

Returns:

A string representation of the service internal data

stringifySlice

public static final java.lang.String stringifySlice(Service.Slice s)

createInvokator

protected CallbackInvokator createInvokator()