kaos.brahms.blik
Class BLIKImpl

java.lang.Object
  kaos.brahms.blik.BLIKImpl

All Implemented Interfaces:

BLIK

public class BLIKImpl
extends java.lang.Object
implements BLIK

Defines the Brahms Logical Interface to KAoS.

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.
static BLIK	getInstance(Transport dsTransport) Retrieve an instance of BLIK.
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.
protected void	logMessage(java.lang.String msg, java.lang.Exception e, int logLevel)
protected void	logMessage(java.lang.String msg, int logLevel)
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.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

getInstance

public static BLIK getInstance(Transport dsTransport)
                        throws java.lang.Exception

Retrieve an instance of BLIK.

Parameters:

transportName - String specifying the name of the transport to use for communication with the KAoS Directory Service.

Returns:

a singleton, BLIK.

Throws:

java.lang.Exception

registerActor

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

Register the specified KAoSActor in the KAoS Directory Service.

Specified by:

registerActor in interface BLIK

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

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

Register the AgentHostingEnvironmentin the KAoS Directory Service.

Specified by:

registerAgentHostingEnv in interface BLIK

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

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

Register the specified KAoSActor in the KAoS Directory Service.

Specified by:

registerDomain in interface BLIK

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

public void deregisterActor(KAoSActor actor)
                     throws DirectoryFailure,
                            NotRegisteredException

Deregister the specified KAoSActor from the KAoS Directory Service.

Specified by:

deregisterActor in interface BLIK

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

public void deregisterAgentHostingEnv(AgentHostingEnvironment env)
                               throws DirectoryFailure,
                                      NotRegisteredException

Deregister the AgentHostingEnvironment from the KAoS Directory Service.

Specified by:

deregisterAgentHostingEnv in interface BLIK

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

public void deregisterDomain(KAoSDomain domain)
                      throws DirectoryFailure,
                             NotRegisteredException

Deregister the KAoSDomain from the KAoS Directory Service.

Specified by:

deregisterDomain in interface BLIK

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

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

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

Specified by:

getDomain in interface BLIK

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

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

Return KAoSActor, whose GUID is specified.

Specified by:

getActor in interface BLIK

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

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

Return a List of KAoSActors satisfying the given query.

Specified by:

getActors in interface BLIK

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

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

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

Specified by:

getActorsWithAttributes in interface BLIK

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

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

Description copied from interface: BLIK

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.

Specified by:

checkPermission in interface BLIK

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

public 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.

Specified by:

registerTriggerConditionListener in interface BLIK

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

public 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.

Specified by:

getObligationsForTriggerCondition in interface BLIK

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

public 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.

Specified by:

requestAction in interface BLIK

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

public 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.

Specified by:

requestAction in interface BLIK

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

public 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.

Specified by:

requestAction in interface BLIK

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

public 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.

Specified by:

registerObserver in interface BLIK

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

public 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.

Specified by:

deregisterObserver in interface BLIK

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

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

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

Specified by:

setMapping in interface BLIK

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.

logMessage

protected void logMessage(java.lang.String msg,
                          int logLevel)

logMessage

protected void logMessage(java.lang.String msg,
                          java.lang.Exception e,
                          int logLevel)