kaos.brahms.blik
Interface BLIK

All Known Implementing Classes:

BLIKImpl

public interface BLIK

Defines the Brahms Logical Interface to KAoS.

Author:

KAoS Team $Revision: 1.9 $

Method Summary

void	checkPermission(KAoSActor actionActor, java.lang.String attemptedActionName, java.util.HashMap actionProperties, java.lang.String conceptMappingName) Check permission for the action described by the given action name and properties.
void	deregisterActor(KAoSActor actor) Deregister the specified KAoSActor from the KAoS Directory Service.
void	deregisterAgentHostingEnv(AgentHostingEnvironment env) Deregister the AgentHostingEnvironment from the KAoS Directory Service.
void	deregisterDomain(KAoSDomain domain) Deregister the KAoSDomain from the KAoS Directory Service.
void	deregisterObserver(KAoSObserver observer, java.lang.String updateType, java.io.Serializable updateCondition, java.lang.String observableGUID) Deregister the given KAoSObserver from the registry of observers associated with the KAoSObservable, whose GUID is given.
KAoSActor	getActor(java.lang.String actorGUID) Return KAoSActor, whose GUID is specified.
java.util.List	getActors(QueryState query) Return a List of KAoSActors satisfying the given query.
java.util.List	getActorsWithAttributes(java.util.Hashtable searchAttributes) Return a List of KAoSActors whose attributes match exactly all specified attributes.
KAoSDomain	getDomain(java.lang.String name) Return a KAoSDomain of the domain, whose name is specified.
java.util.Vector	getObligationsForTriggerCondition(KAoSActor actionActor, java.lang.String triggerActionName, java.util.HashMap triggeraActionProperties, java.lang.String conceptMappingName) Based on the specified trigger action actor, name and properties, select all applicable obligation ActionInstanceDescriptions.
void	registerActor(KAoSActor actor, boolean guarded, boolean replace) Register the specified KAoSActor in the KAoS Directory Service.
void	registerAgentHostingEnv(AgentHostingEnvironment env, boolean replace) Register the AgentHostingEnvironmentin the KAoS Directory Service.
void	registerDomain(KAoSDomain domain, boolean replace) Register the specified KAoSActor in the KAoS Directory Service.
void	registerObserver(KAoSObserver observer, java.lang.String updateType, java.io.Serializable updateCondition, java.lang.String observableGUID) Register the given KAoSObserver with the KAoSObservable, whose GUID is given for updates described by the updateType and updateConditions.
void	registerTriggerConditionListener(java.lang.String triggerActionClassName, TriggerConditionListener listenerRef) Request registration of the specified TriggerConditionListener in the Guard's registry of trigger listeners.
java.lang.String	requestAction(FeedbackReceiver feedbackReceiver, java.lang.String receiverID, java.lang.String owlActionDescription) This method sends a command to an entity identified by the given receiverID to perform an action described by the given String, which is in the OWL format.
java.lang.String	requestAction(FeedbackReceiver feedbackReceiver, java.lang.String receiverID, java.lang.String actionName, java.util.HashMap properties) This method sends a command to an entity identified by the given receiverID to perform an action described by the given action name and properties.
java.lang.Object	requestAction(java.lang.String receiverID, java.lang.String actionName, java.util.HashMap properties) This method sends a command to an entity identified by the given receiverID to perform an action described by the given action name and properties.
boolean	setMapping(java.lang.String mappingName, java.lang.String fileNameLoc) Set the ontology mapping, whose name and location are given.

Method Detail

registerActor

void registerActor(KAoSActor actor,
                   boolean guarded,
                   boolean replace)
                   throws DirectoryFailure,
                          AlreadyRegisteredException,
                          GuardInstantiationException

Register the specified KAoSActor in the KAoS Directory Service.

Parameters:

actor - KAoSActor containing actor properties to be stored in the KAoS Directory Service.

guarded - boolean indicating whether the registering actor is going to be guarded.

replace - boolean indicating whether to replace existing registration information for the given KAoSActor.

Throws:

DirectoryFailure - if the connection to the DS cannot be established.

AlreadyRegisteredException - if the registering KAoSActor has been already registered in the DS (if the replace = false and there is already registration for the specified KAoSActor).

GuardInstantiationException

registerAgentHostingEnv

void registerAgentHostingEnv(AgentHostingEnvironment env,
                             boolean replace)
                             throws DirectoryFailure,
                                    AlreadyRegisteredException

Register the AgentHostingEnvironmentin the KAoS Directory Service.

Parameters:

env - AgentHostingEnvironment containing environment properties to be stored in the KAoS Directory Service.

replace - boolean indicating whether to replace existing registration information for the given AgentHostingEnvironment.

Throws:

DirectoryFailure - if the connection to the DS cannot be established.

AlreadyRegisteredException - if the registering AgentHostingEnvironment has been already registered in the DS (if the replace = false and there is already registration for the specified AgentHostingEnvironment).

registerDomain

void registerDomain(KAoSDomain domain,
                    boolean replace)
                    throws DirectoryFailure,
                           AlreadyRegisteredException

Register the specified KAoSActor in the KAoS Directory Service.

Parameters:

actor - KAoSDomain containing unique domain name, parent/children domain names, modality and priority.

replace - boolean indicating whether to replace existing registration information for the given KAoSDomain.

Throws:

DirectoryFailure - if the connection to the DS cannot be established.

AlreadyRegisteredException - if the registering KAoSDomain has been already registered in the DS (if the replace = false and there is already registration for the specified KAoSDomain).

deregisterActor

void deregisterActor(KAoSActor actor)
                     throws DirectoryFailure,
                            NotRegisteredException

Deregister the specified KAoSActor from the KAoS Directory Service.

Parameters:

actor - KAoSActor be deregistered.

Throws:

DirectoryFailure - if the connection to the DS cannot be established.

NotRegisteredException - if the KAoSActor to be deregistered has not been registered in the DS.

deregisterAgentHostingEnv

void deregisterAgentHostingEnv(AgentHostingEnvironment env)
                               throws DirectoryFailure,
                                      NotRegisteredException

Deregister the AgentHostingEnvironment from the KAoS Directory Service.

Parameters:

env - AgentHostingEnvironment to be deregistered.

Throws:

DirectoryFailure - if the connection to the DS cannot be established.

NotRegisteredException - if the AgentHostingEnvironment to be deregistered has not been registered in the DS.

deregisterDomain

void deregisterDomain(KAoSDomain domain)
                      throws DirectoryFailure,
                             NotRegisteredException

Deregister the KAoSDomain from the KAoS Directory Service.

Parameters:

domain - KAoSDomain to be deregistered.

Throws:

DirectoryFailure - if the connection to the DS cannot be established.

NotRegisteredException - if the KAoSDomain to be deregistered has not been registered in the DS.

getDomain

KAoSDomain getDomain(java.lang.String name)
                     throws DirectoryFailure,
                            NotRegisteredException

Return a KAoSDomain of the domain, whose name is specified.

Parameters:

name - String specifying the name of the domain to lookup.

Throws:

DirectoryFailure - if the connection to the DS cannot be established.

NotRegisteredException - if the requested KAoSDomain to be looked-up has not been registered in the DS.

getActor

KAoSActor getActor(java.lang.String actorGUID)
                   throws DirectoryFailure,
                          NotRegisteredException

Return KAoSActor, whose GUID is specified.

Parameters:

actorGUID - String specifying the guid of the actor to lookup.

Throws:

DirectoryFailure - if the connection to the DS cannot be established.

NotRegisteredException - if the KAoSActor to be looked-up has not been registered in the DS.

getActors

java.util.List getActors(QueryState query)
                         throws DirectoryFailure,
                                NoSuchActorException

Return a List of KAoSActors satisfying the given query.

Parameters:

query - QueryState formulating the query to retrieve KAoSActors satisfying the query.

Throws:

DirectoryFailure - if the connection to the DS cannot be established.

NoSuchActorException - if no actors matching the query properties could be found.

getActorsWithAttributes

java.util.List getActorsWithAttributes(java.util.Hashtable searchAttributes)
                                       throws DirectoryFailure,
                                              NoSuchActorException

Return a List of KAoSActors whose attributes match exactly all specified attributes.

Parameters:

searchAttributes - Hashtable containing attribute name => attribute value mappings.

Returns:

List of KAoSActors containing all attributes specified in the search attributes Hashtable.

Throws:

DirectoryFailure - if the connection to the DS cannot be established.

NoSuchActorException - if no actors matching the query properties could be found.

checkPermission

void checkPermission(KAoSActor actionActor,
                     java.lang.String attemptedActionName,
                     java.util.HashMap actionProperties,
                     java.lang.String conceptMappingName)
                     throws KAoSSecurityException,
                            java.lang.NullPointerException,
                            ServiceFailure

Check permission for the action described by the given action name and properties. If the action is allowed exit quietly, otherwise throw the KAoSSecurityException or NullPointerException.

Parameters:

actionActor - KAoSActor attempting to perform the action to check permission for.

attemptedActionName - String containing the ontological name of the attempted action.

actionProperties - HashMap containing the ontological names and their values of properties of the attempted action.

conceptMappingName - String containing the mapping of vocabulary between Brahms and KAoS ontologies ("Brahms" has been used for some of the demo scenarions)

Throws:

KAoSSecurityException - if the attempted action is not allowed.

java.lang.NullPointerException - if any arguments are null.

ServiceFailure - if the policy service is not available.

registerTriggerConditionListener

void registerTriggerConditionListener(java.lang.String triggerActionClassName,
                                      TriggerConditionListener listenerRef)
                                      throws TriggerConditionListenerRegistrationException

Request registration of the specified TriggerConditionListener in the Guard's registry of trigger listeners. Associate the listener with the specified trigger action, whose name is given.

Parameters:

triggerActionClassName - String containing the name of the action class the given trigger listener is going to monitor.

listenerRef - TriggerConditionListener, an instance of a listener, which will be monitoring the action, whose name is given. When Guard receives a policy, whose action matches the triggerActionClassName, Guard will send an update to the listenerRef.

Throws:

TriggerConditionListenerRegistrationException - if the listener registration fails.

getObligationsForTriggerCondition

java.util.Vector getObligationsForTriggerCondition(KAoSActor actionActor,
                                                   java.lang.String triggerActionName,
                                                   java.util.HashMap triggeraActionProperties,
                                                   java.lang.String conceptMappingName)
                                                   throws ObligationViolationException,
                                                          ServiceFailure

Based on the specified trigger action actor, name and properties, select all applicable obligation ActionInstanceDescriptions. ActionInstanceDescriptions will be sorted in descending order by the priority of the matching obligation policy.

Parameters:

actionActor - KAoSActor performing the trigger action.

triggerActionName - String containing the ontological name of the trigger action.

triggeraActionProperties - HashMap containing the ontological names and their values of properties of the trigger action.

conceptMappingName - String containing the mapping of vocabulary between Brahms and KAoS ontologies ("Brahms" has been used for some of the demo scenarions).

Returns:

A Vector of obligation ActionInstanceDescriptions for the trigger action. The returned control ActionInstanceDescriptions are sorted in descending sequence by their policy priority. Or, the method returns null, if a Thread waiting to complete execution of this method has been interrupted. The Thread's interrupted status will be re-established.

Throws:

ObligationViolationException - if obligation constraints are not satisfied.

ServiceFailure - if the policy service is not available.

requestAction

java.lang.String requestAction(FeedbackReceiver feedbackReceiver,
                               java.lang.String receiverID,
                               java.lang.String owlActionDescription)
                               throws ActionFailureException,
                                      NotLocatableException,
                                      TransportFailure

This method sends a command to an entity identified by the given receiverID to perform an action described by the given String, which is in the OWL format. Feedback from the action execution is sent to the given feedbackReceiver.

Parameters:

feedbackReceiver - is the FeedbackReceiver requesting the action. All feedback from the action execution will be sent to it.

receiverID - is the String that identifies the entity, which is requested to perform the action. The receiverID is the one that the action executor has registered with KAoS.

owlActionDescription - is an OWL String that describes the action. It includes the action name and all action properties and their values.

Returns:

String containing the unique id of the requested action. This id will be used by the FeedbackReceiver to track the status of action execution.

Throws:

ActionFailureException - containing the reason for failure. See ontology to determine specific reasons available for a given action

NotLocatableException - when the entity reqested to perform the action cannot be located.

TransportFailure

requestAction

java.lang.String requestAction(FeedbackReceiver feedbackReceiver,
                               java.lang.String receiverID,
                               java.lang.String actionName,
                               java.util.HashMap properties)
                               throws ActionFailureException,
                                      NotLocatableException,
                                      TransportFailure

This method sends a command to an entity identified by the given receiverID to perform an action described by the given action name and properties. Feedback from the action execution is sent to the given feedbackReceiver.

Parameters:

feedbackReceiver - is the FeedbackReceiver requesting the action. All feedback from the action execution will be sent to it.

receiverID - is the String that identifies the entity, which is requested to perform the action. The receiverID is the one that the action executor has registered with KAoS.

actionName - is a String representing the name of the action as defined in the associated ontology.

properties - is an HashMap of ontological Strings representing the desired properties of the action and the associated values.

Returns:

String containing the unique id of the requested action. This id will be used by the FeedbackReceiver to track the status of action execution.

Throws:

ActionFailureException - containing the reason for failure. See ontology to determine specific reasons available for a given action

NotLocatableException - when the entity reqested to perform the action cannot be located.

TransportFailure

requestAction

java.lang.Object requestAction(java.lang.String receiverID,
                               java.lang.String actionName,
                               java.util.HashMap properties)
                               throws ActionFailureException,
                                      NotLocatableException,
                                      TransportFailure

This method sends a command to an entity identified by the given receiverID to perform an action described by the given action name and properties. The result is returned synchronously to the caller.

Parameters:

receiverID - is the String that identifies the entity, which is requested to perform the action. The receiverID is the one that the action executor has registered with KAoS.

actionName - is a String representing the name of the action as defined in the associated ontology.

properties - is a HashMap of Strings representing names of the desired properties as defined in the associated ontology and their values.

Returns:

Object containing the result of the requested action.

Throws:

ActionFailureException - containing the reason for failure. See ontology to determine specific reasons available for a given action

NotLocatableException - when the entity reqested to perform the action cannot be located.

TransportFailure

registerObserver

void registerObserver(KAoSObserver observer,
                      java.lang.String updateType,
                      java.io.Serializable updateCondition,
                      java.lang.String observableGUID)
                      throws NotLocatableException,
                             TransportFailure

Register the given KAoSObserver with the KAoSObservable, whose GUID is given for updates described by the updateType and updateConditions.

Parameters:

observer - KAoSObserver requesting registration for updates.

updateType - String indicating type of update the KAoSObserver is interested in.

updateCondition - Serializable describing the conditions under which to send the update.

observableGUID - String containing the GUID of the KAoSObservable to register with.

Throws:

NotLocatableException - when the KAoSObservable cannot be located.

TransportFailure - when transport services fails.

deregisterObserver

void deregisterObserver(KAoSObserver observer,
                        java.lang.String updateType,
                        java.io.Serializable updateCondition,
                        java.lang.String observableGUID)
                        throws NotLocatableException,
                               TransportFailure

Deregister the given KAoSObserver from the registry of observers associated with the KAoSObservable, whose GUID is given.

Parameters:

observer - KAoSObserver deregistering.

updateType - String indicating type of update the KAoSObserver is no longer interested in.

updateCondition - Serializable containing the condition the KAoSObserver is no longer interested in.

observableGUID - String specifying the GUID of the observable, from which to deregister for the given update type.

Throws:

NotLocatableException - when the KAoSObservable cannot be located.

TransportFailure - when transport services fail.

setMapping

boolean setMapping(java.lang.String mappingName,
                   java.lang.String fileNameLoc)

Set the ontology mapping, whose name and location are given.

Parameters:

mappingName - The String specifying the name of the mapping. *** Note *** This name has to be passed to KAoSActorImpl.setConceptMappingName(mappingName) before specifying the terms from the mappingName ontology.

fileNameLoc - The String specifying the name and path of the file containing the mapping.

Returns:

boolean indicating success(true)/failure(false) of the operation. Success means that the file containing the mapping has been found, read and the mapping has been stored.