jade.core
Interface Service

All Known Implementing Classes:
BaseService

public interface Service

The Service interface represents a centralized view of a JADE kernel-level service. Most JADE services are actually distributed, and each part of theirs, that is deployed at a given network node (container), is called service slice. The various slices of a service work together to carry out that service's task.

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

Nested Class Summary
static interface Service.Slice
          The Slice nested interface represents that part of a service that is deployed at a given network node.
 
Field Summary
static java.lang.String DEAD_NODE
          Service independent vertical command issued on the Main container whenever a node is removed
static java.lang.String DEAD_PLATFORM_MANAGER
          Service independent vertical command issued on a peripheral container when a fault of the PlatformManager is detected
static java.lang.String DEAD_REPLICA
          Service independent vertical command issued on the Main container whenever a main replica is removed
static java.lang.String DEAD_SLICE
          Service independent vertical command issued on the Main container whenever a slice of a given service is removed
static java.lang.String NEW_NODE
          Service independent vertical command issued on the Main container whenever a new node is added
static java.lang.String NEW_REPLICA
          Service independent vertical command issued on the Main container whenever a new main replica is added
static java.lang.String NEW_SLICE
          Service independent vertical command issued on the Main container whenever a new slice of a given service is added
static java.lang.String REATTACHED
          Service independent vertical command issued on a peripheral container when it re-attach to a recovered Main Container
 
Method Summary
 void boot(Profile p)
          Performs the active initialization step of a kernel-level service.
 Service.Slice[] getAllSlices()
          Retrieve the whole array of slices that compose this service.
 Behaviour getAMSBehaviour()
          Retrieve a behaviour that is associated with this service, and that will be deployed within the AMS.
 Filter getCommandFilter(boolean direction)
          Access the command filter this service needs to perform its tasks.
 Sink getCommandSink(boolean side)
          Access the command sink this service uses to handle its own vertical commands.
 ServiceHelper getHelper(Agent a)
          Get the helper for accessing this service.
 java.lang.Class getHorizontalInterface()
          Retrieve the interface through which the different service slices will communicate, that is, the service Horizontal Interface.
 Service.Slice getLocalSlice()
          Retrieve the locally installed slice of this service.
 java.lang.String getName()
          Retrieve the name of this service, that can be used to look up its slices in the Service Finder.
 int getNumberOfSlices()
          Query by how many slices this service is composed at present.
 java.lang.String[] getOwnedCommands()
          Access the names of the vertical commands this service wants to handle as their final destination.
 Service.Slice getSlice(java.lang.String name)
          Retrieve by name a slice of this service.
 void init(AgentContainer ac, Profile p)
          Performs the passive initialization step of the service.
 void shutdown()
          Performs the shutdown step of a kernel-level service.
 java.lang.Object submit(VerticalCommand cmd)
          Allows submitting a vertical command for processing.
 

Field Detail

NEW_NODE

public static final java.lang.String NEW_NODE
Service independent vertical command issued on the Main container whenever a new node is added

See Also:
Constant Field Values

DEAD_NODE

public static final java.lang.String DEAD_NODE
Service independent vertical command issued on the Main container whenever a node is removed

See Also:
Constant Field Values

NEW_SLICE

public static final java.lang.String NEW_SLICE
Service independent vertical command issued on the Main container whenever a new slice of a given service is added

See Also:
Constant Field Values

DEAD_SLICE

public static final java.lang.String DEAD_SLICE
Service independent vertical command issued on the Main container whenever a slice of a given service is removed

See Also:
Constant Field Values

NEW_REPLICA

public static final java.lang.String NEW_REPLICA
Service independent vertical command issued on the Main container whenever a new main replica is added

See Also:
Constant Field Values

DEAD_REPLICA

public static final java.lang.String DEAD_REPLICA
Service independent vertical command issued on the Main container whenever a main replica is removed

See Also:
Constant Field Values

DEAD_PLATFORM_MANAGER

public static final java.lang.String DEAD_PLATFORM_MANAGER
Service independent vertical command issued on a peripheral container when a fault of the PlatformManager is detected

See Also:
Constant Field Values

REATTACHED

public static final java.lang.String REATTACHED
Service independent vertical command issued on a peripheral container when it re-attach to a recovered Main Container

See Also:
Constant Field Values
Method Detail

getName

public java.lang.String getName()
Retrieve the name of this service, that can be used to look up its slices in the Service Finder.

Returns:
The name of this service.
See Also:
ServiceFinder

getSlice

public Service.Slice getSlice(java.lang.String name)
                       throws ServiceException
Retrieve by name a slice of this service. For distributed services, the returned slice will generally be some kind of proxy object to the real, remote slice. The actual proxy management policy (caching, reconnection, etc.) is decided by concrete services.

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.

getLocalSlice

public Service.Slice getLocalSlice()
Retrieve the locally installed slice of this service. A service without horizontal interfaces can safely return null from this method.

Returns:
The slice of this service that resides on the local platform node, or null if no such slice exists.

getAllSlices

public Service.Slice[] getAllSlices()
                             throws ServiceException
Retrieve the whole array of slices that compose this 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.

getHorizontalInterface

public java.lang.Class getHorizontalInterface()
Retrieve the interface through which the different service slices will communicate, that is, the service Horizontal Interface.

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

getNumberOfSlices

public int getNumberOfSlices()
Query by how many slices this service is composed at present.

Returns:
The number of slices belonging to this service. An active service must have at least one slice.

getCommandFilter

public Filter getCommandFilter(boolean direction)
Access the command filter this service needs to perform its tasks. This filter will be installed within the local command processing engine. Note that when called multiple times with the same value of the direction parameter this method MUST always return the same object!

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 side)
Access the command sink this service uses to handle its own vertical commands.

Parameters:
side - 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:
getOwnedCommands()

getOwnedCommands

public java.lang.String[] getOwnedCommands()
Access the names of the vertical commands this service wants to handle as their final destination. This set must not overlap with the owned commands set of any previously installed service, or an exception will be raised and service activation will fail.

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()

getHelper

public ServiceHelper getHelper(Agent a)
                        throws ServiceException
Get the helper for accessing this 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()
Retrieve a behaviour that is associated with this service, and that will be deployed within the AMS. Typical uses for this behaviour will be to handle a service-specific ontology and actions.

Returns:
A Behaviour object associated with this service, or null if no such behaviour exists.

init

public void init(AgentContainer ac,
                 Profile p)
          throws ProfileException
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.

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.

boot

public void boot(Profile p)
          throws ServiceException
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.

Parameters:
p - The configuration profile for this service.
Throws:
ServiceException - If a problem occurs during service initialization.

shutdown

public void shutdown()
Performs the shutdown step of a kernel-level service. The JADE kernel calls this method just before uninstalling this service


submit

public java.lang.Object submit(VerticalCommand cmd)
                        throws ServiceException
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

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.


JADE