Service (JADE v4.5.0 API)

All Known Implementing Classes:

BaseService, SAMService
```
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

Nested Classes
Modifier and Type	Interface and Description
`static interface`	`Service.Slice` The `Slice` nested interface represents that part of a service that is deployed at a given network node.

Field Summary

Fields
Modifier and Type	Field and Description
`static java.lang.String`	`ADOPTED_NODE` Service independent incoming vertical command issued on the Main container whenever a node that was monitored by a Main container replica is adopted (i.e. the local Main container starts monitoring it)
`static java.lang.String`	`DEAD_NODE` Service independent incoming vertical command issued on the Main container whenever a node is removed
`static java.lang.String`	`DEAD_PLATFORM_MANAGER` Service independent incoming vertical command issued on a peripheral container when a fault of the PlatformManager is detected
`static java.lang.String`	`DEAD_REPLICA` Service independent incoming vertical command issued on the Main container whenever a main replica is removed
`static java.lang.String`	`DEAD_SLICE` Service independent incoming vertical command issued on the Main container whenever a slice of a given service is removed
`static java.lang.String`	`NEW_NODE` Service independent incoming 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 incoming vertical command issued on the Main container whenever a new slice of a given service is added
`static java.lang.String`	`REATTACHED` Service independent incoming vertical command issued on a peripheral container when it re-attaches to a recovered Main Container (see the FaultRecoveryService)
`static java.lang.String`	`RECONNECTED` Service independent incoming vertical command issued on a peripheral container when it reconnects to a new master Main Container (see the MainReplicationService)

Method Summary

All Methods Instance Methods Abstract Methods
Modifier and Type	Method and Description
`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
```
static final java.lang.String NEW_NODE
```
    Service independent incoming vertical command issued on the Main container whenever a new node is added
    
    See Also:
    
    Constant Field Values
  - DEAD_NODE
```
static final java.lang.String DEAD_NODE
```
    Service independent incoming vertical command issued on the Main container whenever a node is removed
    
    See Also:
    
    Constant Field Values
  - ADOPTED_NODE
```
static final java.lang.String ADOPTED_NODE
```
    Service independent incoming vertical command issued on the Main container whenever a node that was monitored by a Main container replica is adopted (i.e. the local Main container starts monitoring it)
    
    See Also:
    
    Constant Field Values
  - NEW_SLICE
```
static final java.lang.String NEW_SLICE
```
    Service independent incoming vertical command issued on the Main container whenever a new slice of a given service is added
    
    See Also:
    
    Constant Field Values
  - DEAD_SLICE
```
static final java.lang.String DEAD_SLICE
```
    Service independent incoming vertical command issued on the Main container whenever a slice of a given service is removed
    
    See Also:
    
    Constant Field Values
  - NEW_REPLICA
```
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
```
static final java.lang.String DEAD_REPLICA
```
    Service independent incoming vertical command issued on the Main container whenever a main replica is removed
    
    See Also:
    
    Constant Field Values
  - DEAD_PLATFORM_MANAGER
```
static final java.lang.String DEAD_PLATFORM_MANAGER
```
    Service independent incoming vertical command issued on a peripheral container when a fault of the PlatformManager is detected
    
    See Also:
    
    Constant Field Values
  - REATTACHED
```
static final java.lang.String REATTACHED
```
    Service independent incoming vertical command issued on a peripheral container when it re-attaches to a recovered Main Container (see the FaultRecoveryService)
    
    See Also:
    
    Constant Field Values
  - RECONNECTED
```
static final java.lang.String RECONNECTED
```
    Service independent incoming vertical command issued on a peripheral container when it reconnects to a new master Main Container (see the MainReplicationService)
    
    See Also:
    
    Constant Field Values
- Method Detail
  - getName
```
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
```
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 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 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 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: c.isInterface() == true s.isAssignableFrom(c) == true getNumberOfSlices 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 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 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 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 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. Throws: ServiceException See Also: AgentToolkit.getHelper(jade.core.Agent, java.lang.String), Agent.getHelper(java.lang.String) getAMSBehaviour 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 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 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 void shutdown() Performs the shutdown step of a kernel-level service. The JADE kernel calls this method just before uninstalling this service submit 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.

Interface Service

Nested Class Summary

Field Summary

Method Summary

Field Detail

NEW_NODE

DEAD_NODE

ADOPTED_NODE

NEW_SLICE

DEAD_SLICE

NEW_REPLICA

DEAD_REPLICA

DEAD_PLATFORM_MANAGER

REATTACHED

RECONNECTED

Method Detail

getName

getSlice

getLocalSlice

getAllSlices

getHorizontalInterface

getNumberOfSlices

getCommandFilter

getCommandSink

getOwnedCommands

getHelper

getAMSBehaviour

init

boot

shutdown

submit