kaos.dfra.dlik
Class DLIKImpl

java.lang.Object
  kaos.dfra.dlik.DLIKImpl

All Implemented Interfaces:

DLIK

public class DLIKImpl
extends java.lang.Object
implements DLIK

Defines the DFRA Logical Interface to KAoS.

Field Summary

Fields inherited from interface kaos.dfra.dlik.DLIK

NEGATIVE_DOMAIN_MODALITY, POSITIVE_DOMAIN_MODALITY

Method Summary

protected void	checkForNullArgument(java.lang.Object arg, java.lang.String methodName, java.lang.String argName) Utility method: if the exp is true, then the arg is null.
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 domainName) Return a DomainDescription of the domain, whose name is specified.
static DLIK	getInstance(Transport dsTransport) Retrieve an instance of DLIK.
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.
protected void	logMessage(java.lang.String msg, java.lang.Exception e, int logLevel)
protected void	logMessage(java.lang.String msg, int logLevel)
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.

Methods inherited from class java.lang.Object

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

Method Detail

getInstance

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

Retrieve an instance of DLIK.

Parameters:

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

Returns:

a singleton, DLIK.

Throws:

java.lang.Exception

registerAgent

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

Specified by:

registerAgent in interface DLIK

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 and 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 the instantiation of Guard failed.

registerDomain

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

Specified by:

registerDomain in interface DLIK

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

public void deregisterAgent(KAoSAgentDescription desc)
                     throws DirectoryFailure,
                            NotRegisteredException

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

Specified by:

deregisterAgent in interface DLIK

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

public void deregisterDomain(DomainDescription domainDesc)
                      throws DirectoryFailure,
                             NotRegisteredException

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

Specified by:

deregisterDomain in interface DLIK

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

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

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

Specified by:

getDomain in interface DLIK

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

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

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

Specified by:

getAgentDescriptionForGUID in interface DLIK

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

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

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

Specified by:

getAgentDescriptionForNickname in interface DLIK

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

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

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

Specified by:

getAgentsWithAttributes in interface DLIK

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

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

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

Specified by:

getAllAgents in interface DLIK

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

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

Specified by:

checkPermission in interface DLIK

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

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 DLIK

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

Specified by:

getObligationsForTriggerCondition in interface DLIK

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.

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

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 DLIK

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)

checkForNullArgument

protected void checkForNullArgument(java.lang.Object arg,
                                    java.lang.String methodName,
                                    java.lang.String argName)
                             throws java.lang.IllegalArgumentException

Utility method: if the exp is true, then the arg is null.

Throws:

java.lang.IllegalArgumentException - if arg is null