kaos.dfra.dlik
Interface DLIK

All Known Implementing Classes:

DLIKImpl

public interface DLIK

Defines the DFRA Logical Interface to KAoS.

Author:

KAoS Team $Revision: 1.9 $

Field Summary

static java.lang.String	NEGATIVE_DOMAIN_MODALITY
static java.lang.String	POSITIVE_DOMAIN_MODALITY

Method Summary

void	addCommandListener(CommandListener listener)
void	assignAgentToRole(java.lang.String agentName, java.lang.String roleName, java.lang.String contextName) Assign an agent to an additional role (does not remove any existing roles).
void	checkPermission(java.lang.String actorGUID, 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	deregisterAgent(java.lang.String agentName) Deregister the agent from KAoS.
java.util.Properties	getActionProperties(ActionInfo kaosAction) Convert a KAoS BasicActionDescription to a Properties object.
KAoSAgentDescription	getAgentDescriptionForGUID(java.lang.String agentGUID) Return a KAoSAgentDescription for an agent, whose GUID is specified.
java.util.List	getAgentDescriptionForNickname(java.lang.String agentNickname) Return a List of KAoSAgentDescriptions of agents, whose nickname is specified.
java.util.List	getAgentRoles(java.lang.String agentName)
java.util.List	getAgentsWithAttributes(java.util.Hashtable searchAttributes) Return a List of KAoSAgentDescriptions whose attributes match exactly all specified attributes.
java.util.List	getAllAgents() Return a List of guids of all agents registered in the KAoS Directory Service.
DomainDescription	getDomain(java.lang.String name) Return a DomainDescription of the domain, whose name is specified.
java.util.List<ActionInstanceDescription>	getObligationsForTriggerCondition(java.lang.String actionActorGUID, java.lang.String triggerActionName, java.util.HashMap triggerActionProperties, java.lang.String conceptMappingName) Based on the specified trigger action actor, name and properties, select all applicable obligation ActionInstanceDescriptions.
java.util.Vector	getPoliciesForAgent(java.lang.String agentName) Get all of the obligations for an agent (all roles, all action types).
java.util.List<ActionInstanceDescription>	getPoliciesForAgentAction(java.lang.String agentName, java.lang.String actionType) Get all of the obligations of a specific action type for an agent.
java.util.Vector	getPoliciesForAgentRole(java.lang.String agentName, java.lang.String roleName, java.lang.String contextName) Get the obligations associated with a specific role for an agent (one role, all action types).
boolean	isAgentMemberOfRole(java.lang.String agentName, java.lang.String roleName, java.lang.String contextName)
KAoSAgentDescription	registerAgent(java.lang.String agentName, java.lang.String roleName, java.lang.String contextName) Register an agent in its starting role with KAoS.
void	registerTriggerConditionListener(java.lang.String triggerActionClassName, TriggerConditionListener listenerRef) Request registration of the specified TriggerConditionListener in the Guard's registry of trigger listeners.
void	removeAgentFromRole(java.lang.String agentName, java.lang.String roleName, java.lang.String contextName) Remove an agent from a previously assigned Role.
void	removeCommandListener(CommandListener listener)
void	reportIntruder(double latitude, double longitude) Send a message to the KAoS CMDR agent, the message contains the GPS coordinates of an intruder.
void	sendMessageTo(java.lang.String receiverName, java.io.Serializable messageContent) Send a message to a specified agent that is registered with KAoS.
boolean	setMapping(java.lang.String mappingName, java.lang.String fileNameLoc) Set the ontology mapping, whose name and location are given.

Field Detail

POSITIVE_DOMAIN_MODALITY

static final java.lang.String POSITIVE_DOMAIN_MODALITY

See Also:

Constant Field Values

NEGATIVE_DOMAIN_MODALITY

static final java.lang.String NEGATIVE_DOMAIN_MODALITY

See Also:

Constant Field Values

Method Detail

registerAgent

KAoSAgentDescription registerAgent(java.lang.String agentName,
                                   java.lang.String roleName,
                                   java.lang.String contextName)
                                   throws DirectoryFailure,
                                          GuardInstantiationException

Register an agent in its starting role with KAoS.

Parameters:

agentName -

roleName -

Returns:

Throws:

AlreadyRegisteredException

DirectoryFailure

GuardInstantiationException

assignAgentToRole

void assignAgentToRole(java.lang.String agentName,
                       java.lang.String roleName,
                       java.lang.String contextName)
                       throws AlreadyRegisteredException,
                              DirectoryFailure,
                              GuardInstantiationException

Assign an agent to an additional role (does not remove any existing roles).

Parameters:

agentName -

roleName -

Throws:

AlreadyRegisteredException

DirectoryFailure

GuardInstantiationException

removeAgentFromRole

void removeAgentFromRole(java.lang.String agentName,
                         java.lang.String roleName,
                         java.lang.String contextName)
                         throws NotRegisteredException,
                                DirectoryFailure

Remove an agent from a previously assigned Role.

Parameters:

agentName -

roleName -

Throws:

NotRegisteredException

DirectoryFailure

deregisterAgent

void deregisterAgent(java.lang.String agentName)
                     throws NotRegisteredException,
                            DirectoryFailure

Deregister the agent from KAoS.

Parameters:

agentName -

Throws:

NotRegisteredException

DirectoryFailure

getActionProperties

java.util.Properties getActionProperties(ActionInfo kaosAction)

Convert a KAoS BasicActionDescription to a Properties object.

Parameters:

kaosAction -

Returns:

getPoliciesForAgent

java.util.Vector getPoliciesForAgent(java.lang.String agentName)
                                     throws java.net.URISyntaxException

Get all of the obligations for an agent (all roles, all action types). Get a Vector of KAoS which are the obliged actions from KAoS for the given agent based on the agent's role assignments.

Parameters:

agentName -

Returns:

Vector

Throws:

java.net.URISyntaxException

getPoliciesForAgentRole

java.util.Vector getPoliciesForAgentRole(java.lang.String agentName,
                                         java.lang.String roleName,
                                         java.lang.String contextName)
                                         throws ServiceFailure,
                                                java.lang.Exception

Get the obligations associated with a specific role for an agent (one role, all action types). Get a Vector of KAoS which are the obliged actions from KAoS for the given agent based on the agent's role assignments.

Parameters:

agentName -

roleName -

contextName -

Returns:

Vector

Throws:

java.net.URISyntaxException

ServiceFailure

java.lang.Exception

getPoliciesForAgentAction

java.util.List<ActionInstanceDescription> getPoliciesForAgentAction(java.lang.String agentName,
                                                                    java.lang.String actionType)
                                                                    throws java.net.URISyntaxException

Get all of the obligations of a specific action type for an agent. (all roles, one action type [AssignRole|NavigateAction|WaypointAction]). See http://ontology.ihmc.us/DFRARoles.owl for available action types (the subclasses of DFRAAction owl class) Get a Vector of KAoS which are the obliged actions from KAoS for the given agent based on the agent's role assignments.

Parameters:

agentName -

Returns:

Vector

Throws:

java.net.URISyntaxException

isAgentMemberOfRole

boolean isAgentMemberOfRole(java.lang.String agentName,
                            java.lang.String roleName,
                            java.lang.String contextName)
                            throws DirectoryFailure

Throws:

DirectoryFailure

getAgentRoles

java.util.List getAgentRoles(java.lang.String agentName)

addCommandListener

void addCommandListener(CommandListener listener)

removeCommandListener

void removeCommandListener(CommandListener listener)

reportIntruder

void reportIntruder(double latitude,
                    double longitude)
                    throws DirectoryFailure,
                           SearchException,
                           NotLocatableException,
                           TransportFailure

Send a message to the KAoS CMDR agent, the message contains the GPS coordinates of an intruder. This is the demo transition from PhaseI(USF) to PhaseII(IHMC)

Parameters:

latitude -

longitude -

Throws:

DirectoryFailure

SearchException

NotLocatableException

TransportFailure

sendMessageTo

void sendMessageTo(java.lang.String receiverName,
                   java.io.Serializable messageContent)
                   throws DirectoryFailure,
                          SearchException,
                          NotLocatableException,
                          TransportFailure

Send a message to a specified agent that is registered with KAoS.

Parameters:

receiverName - - name recipient agent used to register with KAoS

messageContent - - any Serializable

Throws:

DirectoryFailure

SearchException

NotLocatableException

TransportFailure

getDomain

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

Return a DomainDescription 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 domain to be looked-up has not been registered in the DS.

getAgentDescriptionForGUID

KAoSAgentDescription getAgentDescriptionForGUID(java.lang.String agentGUID)
                                                throws DirectoryFailure,
                                                       NotRegisteredException

Return a KAoSAgentDescription for an agent, whose GUID is specified.

Parameters:

agentGUID - String specifying the guid of the agent to lookup.

Throws:

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

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

getAgentDescriptionForNickname

java.util.List getAgentDescriptionForNickname(java.lang.String agentNickname)
                                              throws DirectoryFailure,
                                                     NotRegisteredException

Return a List of KAoSAgentDescriptions of agents, whose nickname is specified.

Parameters:

agentNickname - String specifying the agentNickname of the agent(s) to lookup.

Throws:

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

NotRegisteredException - if no agents with the given nickname have been registered in the DS.

getAgentsWithAttributes

java.util.List getAgentsWithAttributes(java.util.Hashtable searchAttributes)
                                       throws DirectoryFailure,
                                              NotRegisteredException

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

Parameters:

searchAttributes - Hashtable containing attribute name => attribute value mappings. NOTE: the names of defaul tentity attributes are defined in interfaces: kaos.core.service.directory.KAoSEntityDescription kaos.core.service.directory.KAoSAgentDescription

Returns:

List of KAoSAgentDescriptions 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.

NotRegisteredException

getAllAgents

java.util.List getAllAgents()
                            throws DirectoryFailure,
                                   SearchException

Return a List of guids of all agents registered in the KAoS Directory Service.

Returns:

List of guids of all agents registered in the DS.

Throws:

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

SearchException - if search failed.

checkPermission

void checkPermission(java.lang.String actorGUID,
                     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:

actorGUID - String containing the GUID of the agent attempting to perform the action to check permission for.

attemptedActionName - String containing the ontological name of the attempted action. NOTE: many ontological names of actions and their properties are defined in: kaos.ontology.vocabulary.ActionConcepts

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

conceptMappingName - String containing the mapping of vocabulary between DFRA and KAoS ontologies. Optional.

Throws:

KAoSSecurityException - if the attempted action is not allowed.

java.lang.NullPointerException - if - will be thrown if any of the required arguments is null (consistent with the semantics of Java checking permission).

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.List<ActionInstanceDescription> getObligationsForTriggerCondition(java.lang.String actionActorGUID,
                                                                            java.lang.String triggerActionName,
                                                                            java.util.HashMap triggerActionProperties,
                                                                            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:

actionActorGUID - String containing the GUID of the agent 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 DFRA and KAoS ontologies. Optional.

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.

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.

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.