kaos.dfra.dlik
Interface DLIK

All Known Implementing Classes:

DLIKImpl

public interface DLIK

Defines the DFRA Logical Interface to KAoS.

Field Summary

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

Method Summary

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(KAoSAgentDescription desc) Deregister the agent with the given KAoSAgentDescription from the KAoS Directory Service.
void	deregisterDomain(DomainDescription domainDesc) Deregister a domain with the given description from the KAoS Directory Service.
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	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.Vector	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.
KAoSAgentDescription	registerAgent(java.lang.String agentNickname, boolean guarded, boolean nicknameAsGuid, java.util.List domainNames, java.lang.String transportName, boolean replace) Register an agent described by the given attributes in KAoS Directory Service.
DomainDescription	registerDomain(java.lang.String domainName, java.lang.String modality, java.lang.String priority, java.lang.String parentName, java.util.List childrenNames, boolean replace) Register domain with the given attributes in the KAoS Directory Service.
void	registerTriggerConditionListener(java.lang.String triggerActionClassName, TriggerConditionListener listenerRef) Request registration of the specified TriggerConditionListener in the Guard's registry of trigger listeners.
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 agentNickname,
                                   boolean guarded,
                                   boolean nicknameAsGuid,
                                   java.util.List domainNames,
                                   java.lang.String transportName,
                                   boolean replace)
                                   throws DirectoryFailure,
                                          AlreadyRegisteredException,
                                          GuardInstantiationException

Register an agent described by the given attributes in KAoS Directory Service.

Parameters:

agentNickname - String containing the nickname of the registering agent.

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

nicknameAsGuid - boolean indicating whether to use the nickname as the agent's guid.

domainNames - List containing the names of the domains to join.

transportName - String containing the name of the transport to use. Valid values: corba, tcp, grid.

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

Returns:

KAoSAgentDescription created based on the given attributes. This KAoSAgentDescription is stored in the KAoS Directory Service.

Throws:

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

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

GuardInstantiationException - if Guard was requested and its instantiation failed.

registerDomain

DomainDescription registerDomain(java.lang.String domainName,
                                 java.lang.String modality,
                                 java.lang.String priority,
                                 java.lang.String parentName,
                                 java.util.List childrenNames,
                                 boolean replace)
                                 throws DirectoryFailure,
                                        AlreadyRegisteredException

Register domain with the given attributes in the KAoS Directory Service.

Parameters:

domainName - String containing unique domain name.

modality - String containing domain modality. Valid values: POSITIVE, NEGATIVE. Those two values will be mapped to the corresponding concepts in KAoS ontology. If null specified, then the default is POSITIVE.

priority - String containing the priority of the registering domain. I null specified, then the default is "0".

parentName - String containing the name of the parent domain. Optional.

childrenNames - List containing the names of the children domains. Optional.

replace - boolean, which indicates whether to replace existing domain registration with the provided info. Required.

Returns:

DomainDescription created based on the given attributes. This DomainDescription is stored in the KAoS Directory Service.

Throws:

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

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

deregisterAgent

void deregisterAgent(KAoSAgentDescription desc)
                     throws DirectoryFailure,
                            NotRegisteredException

Deregister the agent with the given KAoSAgentDescription from the KAoS Directory Service.

Parameters:

desc - KAoSAgentDescription describing the deregistering agent.

Throws:

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

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

deregisterDomain

void deregisterDomain(DomainDescription domainDesc)
                      throws DirectoryFailure,
                             NotRegisteredException

Deregister a domain with the given description from the KAoS Directory Service.

Parameters:

domainDesc - DomainDescription of the domain to deregister.

Throws:

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

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

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