AbstractLifecycleService (SARL Agent Oriented Programming Language 0.12.0 API)

java.lang.Object
- com.google.common.util.concurrent.AbstractService
- - io.sarl.sre.services.AbstractSreService
  - - io.sarl.sre.services.lifecycle.AbstractLifecycleService

All Implemented Interfaces:

com.google.common.util.concurrent.Service, LifecycleService
```
@Singleton
public abstract class AbstractLifecycleService
extends AbstractSreService
implements LifecycleService
```
Implementation of a spawning service that is based on the other services of the SRE platform.

Version:

io.janusproject.plugin 0.12.0 20210527-171007

Author:

Stéphane Galland

Maven Group Id:

io.janusproject.sre

Maven Artifact Id:

io.janusproject.plugin

Nested Class Summary

Nested Classes
Modifier and Type	Class and Description
`protected static class`	`AbstractLifecycleService.AgentCreationProcess` A class that is runnable into a thread and implements the creation of a single agent.
`protected static class`	`AbstractLifecycleService.AgentIdProvider` A dynamic provider of UUID for the newly created agents.
`protected static class`	`AbstractLifecycleService.ShutdownLookUp` A class that is looking for stopping the SRE kernel when o more agent is alive.
`protected static class`	`AbstractLifecycleService.SpawnQueries` A class enables to update the number of "spawn" queries and supporting the multiple spawning of agents within a single call to "spawn".

Nested classes/interfaces inherited from interface com.google.common.util.concurrent.Service
com.google.common.util.concurrent.Service.Listener, com.google.common.util.concurrent.Service.State

Nested classes/interfaces inherited from interface com.google.common.util.concurrent.Service
com.google.common.util.concurrent.Service.Listener, com.google.common.util.concurrent.Service.State

Constructor Summary

Constructors
Constructor and Description
AbstractLifecycleService(sarlSpecificationChecker : SarlSpecificationChecker, creator : AgentCreatorProvider, lifecycleListener : javax.inject.Provider<LifecycleServiceListener>, externalContextListener : javax.inject.Provider<ExternalContextMemberListener>, factories : javax.inject.Provider<Factories>, agentLevelInjector : javax.inject.Provider<ConfigurableAgentInjector>, skillProvider : DynamicSkillProvider, skillUninstaller : SkillUninstaller, executor : ExecutorService, loggingService : LoggingService, lifecycleConfig : LifecycleConfig) Constructs the service.

Method Summary

All Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`void`	`addDynamicSkillProvider(provider : DynamicSkillProvider)` Add a dynamic skill provider that must be used for the agents that are spawned after the call to this function.
`void`	`addKernelAgentLifecycleListener(listener : KernelAgentLifecycleListener)` Add a listener on the changes related to the kernel agent.
`void`	`addLifecycleServiceListener(agentLifecycleListener : LifecycleServiceListener)` Add a listener on the changes in the current state of an agent.
`boolean`	`canSpawnAgent()` Replies if the service can spawn.
`protected void`	`fireAgentDestroy(agent : Agent, outerContexts : ConcurrentCollection<ContextReference>, terminationCause : Object)` Notify the listeners outside the parent context.
`protected void`	`fireAgentDestructionEvents(agent : Agent, defaultContextBeforeKilled : ContextReference, leavedContexts : ConcurrentCollection<ContextReference>, terminationCause : Object)`
`protected void`	`fireAgentKillFailureEvent(agent : Agent, innerContext : ContextReference, cause : Object)` Fire the events related a failure of agent killing.
`protected void`	`fireAgentSpawned(spawningAgent : UUID, context : Context, agentClazz : Class<? extends Agent>, agent : Agent, initializationParameters : Object*)` Notify the listeners outside the parent context.
`protected void`	`fireAgentSpawnFailureEvent(spawningAgent : UUID, parent : Context, agentClazz : Class<? extends Agent>, cause : String)` Fire the events related a failure of agent spawn.
`protected void`	`fireAgentSpawningEvents(spawningAgent : UUID, parent : Context, agentClazz : Class<? extends Agent>, params : Object[], spawnedAgent : Agent)` Fire the events related to the agent spawn.
`protected void`	`fireKernelAgentDestroy()` Notifies the listeners about the kernel agent destruction.
`protected ExecutorService`	`getExecutor()`
`protected Logger`	`getLogger()` Replies the backend logger.
`boolean`	`getSpawnEnable()` Replies if the spawning of agents is enabled or disabled.
`boolean`	`isAlive(life : AgentLife)` Replies if the agent is alive.
`protected boolean`	`isEmptyRootContext(context : Context)` Replies if the given context is the root context and is empty.
`boolean`	`isKillableAgent(life : AgentLife, id : UUID)` Replies if the given agent could be kill according to the SARL specification.
`boolean`	`killAgent(agent : Agent, forceKillable : boolean, terminationCause : Object)` Kill the given agent.
`protected AbstractLifecycleService.AgentCreationProcess`	`newAgentCreatorProcess(spawnQueries : AbstractLifecycleService.SpawnQueries, spawningAgent : UUID, parentContext : Context, agentType : Class<? extends Agent>, initializationParameters : Object[], agentIds : (UUID)=>UUID, agentInstanceCreator : (UUID)=>Agent)` Invoked to create the function for launching an agent.
`protected void`	`onAgentCreated(agent : Agent)` This function is called each time an agent was created.
`protected void`	`onAgentFrameworkStop()` This function is called each time the agent framework should be stopped.
`protected void`	`onAgentKilled(agent : Agent)` This function is called each time an agent was killed.
`protected void`	`onStart()` Do something when starting the service.
`protected void`	`onStop()` Do something when stopping the service.
`void`	`removeDynamicSkillProvider(provider : DynamicSkillProvider)` Remove a dynamic skill provider that must be not be used any more for the agents that are spawned.
`void`	`removeKernelAgentLifecycleListener(listener : KernelAgentLifecycleListener)` Remove a listener on the changes related to the kernel agent.
`void`	`removeLifecycleServiceListener(agentLifecycleListener : LifecycleServiceListener)` Remove a listener on the changes in the current state of an agent.
`void`	`setSpawnEnable(enable : boolean)` Enable or disable the spawning of agents.
`protected void`	`spawnAgent(nbAgents : int, spawningAgent : UUID, parent : Context, agentClazz : Class<? extends Agent>, params : Object[], agentIds : (UUID)=>UUID)` Spawn agents of the given type, and pass the parameters to its initialization function.
`void`	`spawnAgent(nbAgents : int, spawningAgent : UUID, parent : Context, agentId : UUID, agentClazz : Class<? extends Agent>, params : Object[])` Spawn agents of the given type, and pass the parameters to its initialization function.

Methods inherited from class io.sarl.sre.services.AbstractSreService
doStart, doStop

Methods inherited from class com.google.common.util.concurrent.AbstractService
addListener, awaitRunning, awaitRunning, awaitTerminated, awaitTerminated, doCancelStart, failureCause, isRunning, notifyFailed, notifyStarted, notifyStopped, startAsync, state, stopAsync, toString

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Methods inherited from interface com.google.common.util.concurrent.Service
addListener, awaitRunning, awaitRunning, awaitTerminated, awaitTerminated, failureCause, isRunning, startAsync, state, stopAsync

- Constructor Detail
  - AbstractLifecycleService
```
public new(sarlSpecificationChecker : SarlSpecificationChecker,
           creator : AgentCreatorProvider,
           lifecycleListener : javax.inject.Provider<LifecycleServiceListener>,
           externalContextListener : javax.inject.Provider<ExternalContextMemberListener>,
           factories : javax.inject.Provider<Factories>,
           agentLevelInjector : javax.inject.Provider<ConfigurableAgentInjector>,
           skillProvider : DynamicSkillProvider,
           skillUninstaller : SkillUninstaller,
           executor : ExecutorService,
           loggingService : LoggingService,
           lifecycleConfig : LifecycleConfig)
```
    Constructs the service.
    
    Parameters:
    
    sarlSpecificationChecker - the tool for checking the validity of the SARL specification supported by the agents to launch.
    
    creator - the provider of agent creators that is used when spawning agents.
    
    lifecycleListener - the listener at the platform scale on life cycle events.
    
    externalContextListener - the listener at the platform scale on context membership events.
    
    factories - the provider of factories tool.
    
    skillProvider - the system-wide provider of agent skills.
    
    skillUninstaller - the object this is able to uninstall the skills.
    
    executor - the executor service.
    
    lifecycleConfig - the configuration of the lifecycle service.
    
    logger - the logging service.
- Method Detail
  - getSpawnEnable
```
@Pure
public def getSpawnEnable() : boolean 
```
    Description copied from interface: LifecycleService
    
    Replies if the spawning of agents is enabled or disabled.
    
    Specified by:
    
    getSpawnEnable in interface LifecycleService
    
    Returns:
    
    the flag that indicates if the spawning of agents is enable or disable.
  - setSpawnEnable
```
public def setSpawnEnable(enable : boolean) : void 
```
    Description copied from interface: LifecycleService
    
    Enable or disable the spawning of agents.
    
    Specified by:
    
    setSpawnEnable in interface LifecycleService
    
    Parameters:
    
    enable - indicates if the spawning of agents is enable or disable.
  - getLogger
```
@Pure
protected def getLogger() : Logger 
```
    Description copied from class: AbstractLifecycleService
    
    Replies the backend logger.
    
    Returns:
    
    the logger.
  - onStart
```
protected def onStart() : void 
```
    Description copied from class: AbstractSreService
    
    Do something when starting the service.
    This function is called from AbstractSreService.doStart()
    
    Overrides:
    
    onStart in class AbstractSreService
  - onStop
```
protected def onStop() : void 
```
    Description copied from class: AbstractSreService
    
    Do something when stopping the service.
    This function is called from AbstractSreService.doStop()
    
    Overrides:
    
    onStop in class AbstractSreService
  - addLifecycleServiceListener
```
public def addLifecycleServiceListener(agentLifecycleListener : LifecycleServiceListener) : void 
```
    Description copied from interface: LifecycleService
    
    Add a listener on the changes in the current state of an agent.
    
    Specified by:
    
    addLifecycleServiceListener in interface LifecycleService
    
    Parameters:
    
    agentLifecycleListener - the listener on the any change in the life-cycle of the agent.
  - removeLifecycleServiceListener
```
public def removeLifecycleServiceListener(agentLifecycleListener : LifecycleServiceListener) : void 
```
    Description copied from interface: LifecycleService
    
    Remove a listener on the changes in the current state of an agent.
    
    Specified by:
    
    removeLifecycleServiceListener in interface LifecycleService
    
    Parameters:
    
    agentLifecycleListener - the listener on the any change in the life-cycle of the agent.
  - addKernelAgentLifecycleListener
```
public def addKernelAgentLifecycleListener(listener : KernelAgentLifecycleListener) : void 
```
    Description copied from interface: LifecycleService
    
    Add a listener on the changes related to the kernel agent.
    
    Specified by:
    
    addKernelAgentLifecycleListener in interface LifecycleService
    
    Parameters:
    
    listener - listener on the spawning events in the local kernel.
  - removeKernelAgentLifecycleListener
```
public def removeKernelAgentLifecycleListener(listener : KernelAgentLifecycleListener) : void 
```
    Description copied from interface: LifecycleService
    
    Remove a listener on the changes related to the kernel agent.
    
    Specified by:
    
    removeKernelAgentLifecycleListener in interface LifecycleService
    
    Parameters:
    
    listener - listener on the spawning events in the local kernel.
  - fireAgentDestroy
```
protected def fireAgentDestroy(agent : Agent,
                               outerContexts : ConcurrentCollection<ContextReference>,
                               terminationCause : Object) : void 
```
    Description copied from class: AbstractLifecycleService
    
    Notify the listeners outside the parent context.
    
    Parameters:
    
    agents - the destroyed agent.
    
    outerContexts - the contexts in which the agent w destroyed.
    
    terminationCause - is the cause of the termination of the agent. If it is null, the agent does not provide a cause for its termination.
    
    Since:
    
    0.12
  - fireAgentSpawned
```
protected def fireAgentSpawned(spawningAgent : UUID,
                               context : Context,
                               agentClazz : Class<? extends Agent>,
                               agent : Agent,
                               initializationParameters : Object*) : void 
```
    Description copied from class: AbstractLifecycleService
    
    Notify the listeners outside the parent context.
    
    Parameters:
    
    spawningAgent - the spawning agent.
    
    context - the context in which the agents were spawned.
    
    agentClazz - the type of the spawned agents.
    
    agent - the spawned agent.
    
    initializationParameters - the initialization parameters.
  - fireKernelAgentDestroy
```
protected def fireKernelAgentDestroy() : void 
```
    Description copied from class: AbstractLifecycleService
    
    Notifies the listeners about the kernel agent destruction.
  - spawnAgent
```
public final def spawnAgent(nbAgents : int,
                            spawningAgent : UUID,
                            parent : Context,
                            agentId : UUID,
                            agentClazz : Class<? extends Agent>,
                            params : Object[]) : void 
```
    Description copied from interface: LifecycleService
    
    Spawn agents of the given type, and pass the parameters to its initialization function.
    This function is not blocking until all the agents are spawned.
    
    Specified by:
    
    spawnAgent in interface LifecycleService
    
    Parameters:
    
    nbAgents - the number of agents to spawn.
    
    spawningAgent - the agent which is spawning, if null, the root agent (Janus kernel) is assumed.
    
    parent - the parent entity that is creating the agents.
    
    agentId - the identifier of the agent to spawn. If null the identifier is randomly selected. If nbAgents is greater than 1, the agent identifier must be null.
    
    agentClazz - the type of the agents to spawn.
    
    params - the list of the parameters to pass to the agent initialization function.
  - canSpawnAgent
```
@Pure
public def canSpawnAgent() : boolean 
```
    Description copied from class: AbstractLifecycleService
    
    Replies if the service can spawn.
    
    Returns:
    
    true if the service can spawn an agent.
  - spawnAgent
```
protected def spawnAgent(nbAgents : int,
                         spawningAgent : UUID,
                         parent : Context,
                         agentClazz : Class<? extends Agent>,
                         params : Object[],
                         agentIds : (UUID)=>UUID) : void 
```
    Description copied from class: AbstractLifecycleService
    
    Spawn agents of the given type, and pass the parameters to its initialization function.
    This function is not blocking until all the agents are spawned.
    
    Parameters:
    
    nbAgents - the number of agents to spawn.
    
    spawningAgent - the agent which is spawning, if null, the root agent (Janus kernel) is assumed.
    
    parent - the parent entity that is creating the agents.
    
    agentClazz - the type of the agents to spawn.
    
    callback - function that is invoked when an identifier of spawned agent is known. The number of times this callback is invoked depends on the service's implementation. But, the contract is that is must be called at least one time when one or more agent is spawned.
    
    params - the list of the parameters to pass to the agent initialization function.
    
    agentIds - is the lambda that must be used to compute the UUID of an agent. This lambda should be thread-safe.
  - newAgentCreatorProcess
```
@Pure
protected def newAgentCreatorProcess(spawnQueries : AbstractLifecycleService.SpawnQueries,
                                           spawningAgent : UUID,
                                           parentContext : Context,
                                           agentType : Class<? extends Agent>,
                                           initializationParameters : Object[],
                                           agentIds : (UUID)=>UUID,
                                           agentInstanceCreator : (UUID)=>Agent) : AbstractLifecycleService.AgentCreationProcess 
```
    Description copied from class: AbstractLifecycleService
    
    Invoked to create the function for launching an agent. This function is defined for enabling overrding.
    
    Parameters:
    
    spawnQueries - the object ot track the spawn queries.
    
    spawningAgent - is the identifier of the agent that has invoked the spawn function.
    
    parentContext - is the context in which the agent is created.
    
    agentType - is the type of agent to be created.
    
    initializationParameters - is the list of parameters to pass to the agent for its initialization.
    
    agentIds - is a lambda that replies a valid UUID for an agent. This lambda is thread-safe.
    
    agentInstanceCreator - is a lambda that enables to create an instance of agent. This lambda is thread-safe.
    
    Since:
    
    0.12
  - onAgentFrameworkStop
```
protected def onAgentFrameworkStop() : void 
```
    Description copied from class: AbstractLifecycleService
    
    This function is called each time the agent framework should be stopped. This function is provided for being overridden by the sub-classes of the current class.
    Within the AbstractLifecycleService, this function fires the kernel agent destruction event.
    
    Since:
    
    0.8.0
  - onAgentCreated
```
protected def onAgentCreated(agent : Agent) : void 
```
    Description copied from class: AbstractLifecycleService
    
    This function is called each time an agent was created. This function is provided for being overridden by the sub-classes of the current class.
    Within the AbstractLifecycleService, this function does nothing.
    
    Parameters:
    
    agent - the spawned agent.
    
    Since:
    
    0.8.0
  - fireAgentSpawningEvents
```
protected def fireAgentSpawningEvents(spawningAgent : UUID,
                                      parent : Context,
                                      agentClazz : Class<? extends Agent>,
                                      params : Object[],
                                      spawnedAgent : Agent) : void 
```
    Description copied from class: AbstractLifecycleService
    
    Fire the events related to the agent spawn.
    
    Parameters:
    
    spawningAgent - the creator, if null, the root agent (Janus kernel) is assumed.
    
    parent - the context in which the agents are created.
    
    agentClazz - the type of the spawned agents.
    
    spawnedAgent - the spawned agent.
  - fireAgentSpawnFailureEvent
```
protected def fireAgentSpawnFailureEvent(spawningAgent : UUID,
                                         parent : Context,
                                         agentClazz : Class<? extends Agent>,
                                         cause : String) : void 
```
    Description copied from class: AbstractLifecycleService
    
    Fire the events related a failure of agent spawn.
    
    Parameters:
    
    spawningAgent - the creator.
    
    parent - the context in which the agents are created.
    
    agentClazz - the type of the spawned agents.
    
    cause - the cause of the failure.
  - isEmptyRootContext
```
@Pure
protected def isEmptyRootContext(context : Context) : boolean 
```
    Description copied from class: AbstractLifecycleService
    
    Replies if the given context is the root context and is empty.
    
    Parameters:
    
    context - the agent context to test.
    
    Returns:
    
    true if the given context is the root context, and it is empty.
  - isKillableAgent
```
@Pure
public def isKillableAgent(life : AgentLife,
                                 id : UUID) : boolean 
```
    Description copied from class: AbstractLifecycleService
    
    Replies if the given agent could be kill according to the SARL specification.
    An agent could be kill if is has no internal member.
    
    Parameters:
    
    life - the internal data structure for the agent.
    
    id - the identifier of the agent.
    
    Returns:
    
    true if the agent could be killed.
  - isAlive
```
@Pure
public def isAlive(life : AgentLife) : boolean 
```
    Description copied from class: AbstractLifecycleService
    
    Replies if the agent is alive. This function is usually invoked to determine if the agent is killable.
    
    Parameters:
    
    life - the internal data structure for the agent.
    
    Returns:
    
    true if the agent is alive.
    
    Since:
    
    0.11
  - killAgent
```
public def killAgent(agent : Agent,
                     forceKillable : boolean,
                     terminationCause : Object) : boolean 
```
    Description copied from interface: LifecycleService
    
    Kill the given agent.
    An agent could be killed only if it does not contain sub-agents.
    Because the agent reference is passed to this function, only the objects which have this reference could kill the agent.
    
    Specified by:
    
    killAgent in interface LifecycleService
    
    Parameters:
    
    agent - the agent to kill.
    
    forceKillable - indicates if the kill of the agent should be tested before killing it. Usually, the agent cannot be killed when it contains other agents. This flag enables or disables to the run of this test. If true, the agent is always assumed to be killable.
    
    terminationCause - is the cause of the termination of the agent. If it is null, the agent does not provide a specific termination cause.
    
    Returns:
    
    true if the agent was killed by this call; false if the agent is unknown or already killed.
  - onAgentKilled
```
protected def onAgentKilled(agent : Agent) : void 
```
    Description copied from class: AbstractLifecycleService
    
    This function is called each time an agent was killed. This function is provided for being overridden by the sub-classes of the current class.
    Within the AbstractLifecycleService, this function does nothing.
    
    Parameters:
    
    agent - the killed agent.
    
    Since:
    
    0.8.0
  - fireAgentDestructionEvents
```
protected def fireAgentDestructionEvents(agent : Agent,
                                         defaultContextBeforeKilled : ContextReference,
                                         leavedContexts : ConcurrentCollection<ContextReference>,
                                         terminationCause : Object) : void 
```
  - fireAgentKillFailureEvent
```
protected def fireAgentKillFailureEvent(agent : Agent,
                                        innerContext : ContextReference,
                                        cause : Object) : void 
```
    Description copied from class: AbstractLifecycleService
    
    Fire the events related a failure of agent killing.
    
    Parameters:
    
    agent - the agent that has failed to commit a suicide.
    
    innerContext - the context in which the events should be fired.
    
    cause - the cause of the failure.
  - addDynamicSkillProvider
```
public def addDynamicSkillProvider(provider : DynamicSkillProvider) : void 
```
    Description copied from class: AbstractLifecycleService
    
    Add a dynamic skill provider that must be used for the agents that are spawned after the call to this function.
    
    Specified by:
    
    addDynamicSkillProvider in interface LifecycleService
    
    Parameters:
    
    provider - is the provider of skills for newly created agents.
  - removeDynamicSkillProvider
```
public def removeDynamicSkillProvider(provider : DynamicSkillProvider) : void 
```
    Description copied from class: AbstractLifecycleService
    
    Remove a dynamic skill provider that must be not be used any more for the agents that are spawned.
    
    Specified by:
    
    removeDynamicSkillProvider in interface LifecycleService
    
    Parameters:
    
    provider - is the provider of skills to be removed.
  - getExecutor
```
@Pure
protected def getExecutor() : ExecutorService 
```

Class AbstractLifecycleService

Nested Class Summary

Nested classes/interfaces inherited from interface com.google.common.util.concurrent.Service

Nested classes/interfaces inherited from interface com.google.common.util.concurrent.Service

Constructor Summary

Method Summary

Methods inherited from class io.sarl.sre.services.AbstractSreService

Methods inherited from class com.google.common.util.concurrent.AbstractService

Methods inherited from class java.lang.Object

Methods inherited from interface com.google.common.util.concurrent.Service

Constructor Detail

AbstractLifecycleService

Method Detail

getSpawnEnable

setSpawnEnable

getLogger

onStart

onStop

addLifecycleServiceListener

removeLifecycleServiceListener

addKernelAgentLifecycleListener

removeKernelAgentLifecycleListener

fireAgentDestroy

fireAgentSpawned

fireKernelAgentDestroy

spawnAgent

canSpawnAgent

spawnAgent

newAgentCreatorProcess

onAgentFrameworkStop

onAgentCreated

fireAgentSpawningEvents

fireAgentSpawnFailureEvent

isEmptyRootContext

isKillableAgent

isAlive

killAgent

onAgentKilled

fireAgentDestructionEvents

fireAgentKillFailureEvent

addDynamicSkillProvider

removeDynamicSkillProvider

getExecutor