kaos.core.csi.registration
Interface DirectoryRegistration

All Known Subinterfaces:
Registration

public interface DirectoryRegistration

Defines the operations to register and deregister entities and entity hosting environments in the KAoS Directory Service and operations to modify the registration information.

Author:
KAoS Team $Revision: 1.8 $

Method Summary
 KAoSAgentDescription createKAoSAgentDescription(java.lang.String guid, java.lang.String nickname, java.util.Vector domainNames, java.lang.String transportName, JasBean agentInitInfo)
          Create an instance of the KAoSAgentDescription using the given parameters.
 void deregisterEntity(AgentDescription entityDescription)
          Deregister the entity described by the given AgentDescription from the KAoS Directory Service.
 void deregisterEntityHostingEnv(EntityHostEnvDescription hostEnvDescription)
          Deregister the entity hosting environment described by the given EntityHostEnvDescription from the KAoS Directory Service.
 void modifyEntityProperties(java.lang.String entityGUID, java.util.List properties)
          Modify properties of the entity identified by the given entityGUID.
 void modifyEntitySpatialProperties(java.lang.String entityGUID, Location3D objectLocation, Orientation3D objectOrientation, Block3D objectOccupiedSpace)
          Modify given spatial properties of the entity identified by the given entityGUID in the KAoS Directory Service *AND* the SpatialReasoner.
 void modifyObjectSpatialProperties(java.lang.String objectID, Location3D objectLocation, Orientation3D objectOrientation, Block3D objectOccupiedSpace)
          Modify spatial properties of the object identified by the given objectID in the SpatialReasoner.
 void registerDomain(java.lang.String domainName)
          Register domain with the given name in the KAoS Directory Service.
 void registerEntity(AgentDescription entityDescription, boolean guarded, boolean replace)
          Register the entity described by the given AgentDescription in the KAoS Directory Service.
 void registerEntityHostingEnv(EntityHostEnvDescription eheDescription, boolean guarded, boolean replace)
          Register the entity hosting environment described by the given EntityHostEnvDescription in the KAoS Directory Service.
 void registerEntityWithProperties(AgentDescription entityDescription, java.util.List properties, boolean guarded, boolean replace)
          Register the entity described by the given AgentDescription and the List of Properties in the KAoS Directory Service.
 void registerEntityWithSpatialProperties(AgentDescription entityDescription, Location3D objectLocation, Orientation3D objectOrientation, Block3D objectOccupiedSpace, boolean guarded, boolean replace)
          Register the entity described by the given AgentDescription and the spatial properties in the KAoS Directory Service *AND* the SpatialReasoner.
 void registerObjectWithSpatialProperties(java.lang.String objectID, java.util.Set objectOntologyType, Location3D objectLocation, Orientation3D objectOrientation, Block3D objectOccupiedSpace)
          Register object identified by the given objectID and its spatial properties in the SpatialReasoner.
 

Method Detail

registerDomain

void registerDomain(java.lang.String domainName)
                    throws DirectoryFailure,
                           AlreadyRegisteredException
Register domain with the given name in the KAoS Directory Service.

Parameters:
domainName - String containing the name of domain to register.
Throws:
DirectoryFailure - if the connection to the DS cannot be established.
AlreadyRegisteredException - if the registering domain has been already registered in the DS

registerEntity

void registerEntity(AgentDescription entityDescription,
                    boolean guarded,
                    boolean replace)
                    throws DirectoryFailure,
                           AlreadyRegisteredException,
                           GuardInstantiationException
Register the entity described by the given AgentDescription in the KAoS Directory Service.

Parameters:
entityDescription - AgentDescription is the JAS AgentDescription, whose subclasses describe the various types of entities to be registered in KAoS: agents, guards, domains, containers. Those entities are subjects to policies or potential subjects to policies, or the entities are using KAoS for messaging.
guarded - boolean indicating the guarded/unguarded status for agents and containers. If the entity is to be guarded, the implementation of this method will instantiate a guard, or check if a guard already exists and proceed with the registration via the guard.
replace - boolean indicating whether to replace existing AgentDescription.
Throws:
DirectoryFailure - if the connection to the DS cannot be established.
AlreadyRegisteredException - if the registering entity has been already registered in the DS (if the replace = false and there is already registration for the specified AgentDescription).
GuardInstantiationException

registerEntityWithProperties

void registerEntityWithProperties(AgentDescription entityDescription,
                                  java.util.List properties,
                                  boolean guarded,
                                  boolean replace)
                                  throws DirectoryFailure,
                                         AlreadyRegisteredException,
                                         GuardInstantiationException
Register the entity described by the given AgentDescription and the List of Properties in the KAoS Directory Service.

Parameters:
entityDescription - AgentDescription is the JAS AgentDescription, whose subclasses describe the various types of entities to be registered in KAoS: agents, guards, domains, containers. Those entities are subjects to policies or potential subjects to policies, or the entities are using KAoS for messaging.
properties - List of Property objects further describing the registering entity.
guarded - boolean indicating the guarded/unguarded status for agents and containers. If the entity is to be guarded, the implementation of this method will instantiate a guard, or check if a guard already exists and proceed with the registration via the guard.
replace - boolean indicating whether to replace existing AgentDescription.
Throws:
DirectoryFailure - if the connection to the DS cannot be established.
AlreadyRegisteredException - if the registering entity has been already registered in the DS (if the replace = false and there is already registration for the specified AgentDescription).
GuardInstantiationException

registerEntityWithSpatialProperties

void registerEntityWithSpatialProperties(AgentDescription entityDescription,
                                         Location3D objectLocation,
                                         Orientation3D objectOrientation,
                                         Block3D objectOccupiedSpace,
                                         boolean guarded,
                                         boolean replace)
                                         throws DirectoryFailure,
                                                AlreadyRegisteredException,
                                                GuardInstantiationException
Register the entity described by the given AgentDescription and the spatial properties in the KAoS Directory Service *AND* the SpatialReasoner.

Parameters:
entityDescription - AgentDescription is the JAS AgentDescription, whose subclasses describe the various types of entities to be registered in KAoS: agents, guards, domains, containers. Those entities are subjects to policies or potential subjects to policies, or the entities are using KAoS for messaging.
objectLocation - Location3D containing the X,Y,Z coordinates of the registering entity.
objectOrientation - Orientation3D containing the X,Y,Z radius of the registering entity.
objectOccupiedSpace - Block3D containing corner locations determining the occupied space of the registering entity.
guarded - boolean indicating the guarded/unguarded status for agents and containers. If the entity is to be guarded, the implementation of this method will instantiate a guard, or check if a guard already exists and proceed with the registration via the guard.
replace - boolean indicating whether to replace existing AgentDescription.
Throws:
DirectoryFailure - if the connection to the DS cannot be established.
AlreadyRegisteredException - if the registering entity has been already registered in the DS (if the replace = false and there is already registration for the specified AgentDescription).
GuardInstantiationException

registerObjectWithSpatialProperties

void registerObjectWithSpatialProperties(java.lang.String objectID,
                                         java.util.Set objectOntologyType,
                                         Location3D objectLocation,
                                         Orientation3D objectOrientation,
                                         Block3D objectOccupiedSpace)
                                         throws DirectoryFailure,
                                                AlreadyRegisteredException
Register object identified by the given objectID and its spatial properties in the SpatialReasoner. Important: Note that the object is *not* registered in the KAoS DirectoryService, only in the SpatialReasoner. If you want to register a given object in the KAoS Directory service, use method registerEntityWithSpatialProperties(), which will do both, register in the KAoS DS and the SpatialReasoner.

Parameters:
objectID - String uniquely identifying registering object in the SpatialReasoner.
objectOntologyType - Set containing Strings describing the ontological types of the registering object in the SpatialReasoner.
objectLocation - Location3D containing the X,Y,Z coordinates of the registering object.
objectOrientation - Orientation3D containing the X,Y,Z radius of the registering object.
objectOccupiedSpace - Block3D containing corner locations determining the occupied space of the registering object.
Throws:
DirectoryFailure - if the connection to the SpatialReasoner cannot be established.
AlreadyRegisteredException - if the registering object has been already registered in the SpatialReasoner.

registerEntityHostingEnv

void registerEntityHostingEnv(EntityHostEnvDescription eheDescription,
                              boolean guarded,
                              boolean replace)
                              throws DirectoryFailure,
                                     AlreadyRegisteredException,
                                     GuardInstantiationException
Register the entity hosting environment described by the given EntityHostEnvDescription in the KAoS Directory Service.

Parameters:
eheDescription - EntityHostEnvDescription describes the hosting environment for agents and guards.
guarded - boolean indicating the guarded/unguarded status for the environment. If the hosted environemnt is to be guarded, the implementation of this method will instantiate a guard, or check if a guard already exists and proceed with the registration via the guard.
replace - boolean indicating whether to replace existing EntityHostEnvDescription.
Throws:
DirectoryFailure - if the connection to the DS cannot be established.
AlreadyRegisteredException - if the registering hosting environment has been already registered in the DS (if the replace = false and there is already registration for the specified EntityHostEnvDescription).
GuardInstantiationException

modifyEntityProperties

void modifyEntityProperties(java.lang.String entityGUID,
                            java.util.List properties)
                            throws DirectoryFailure,
                                   NotRegisteredException,
                                   ModificationException
Modify properties of the entity identified by the given entityGUID.

Parameters:
entityGUID - String containing the entity GUID.
properties - List of Properties to be modified. Each Property contains the name, value, value description, modification type (add/remove/set, etc), modification result. Refer to the Property and ModificationResult interfaces for detailed description.
Throws:
DirectoryFailure - if the connection to the DS cannot be established.
NotRegisteredException - if the entity whose properties are to be modified has not been registered in the DS.
ModificationException - if one or more property update failed.

modifyEntitySpatialProperties

void modifyEntitySpatialProperties(java.lang.String entityGUID,
                                   Location3D objectLocation,
                                   Orientation3D objectOrientation,
                                   Block3D objectOccupiedSpace)
                                   throws DirectoryFailure,
                                          NotRegisteredException,
                                          ModificationException
Modify given spatial properties of the entity identified by the given entityGUID in the KAoS Directory Service *AND* the SpatialReasoner.

Parameters:
entityGUID - String containing the entity GUID.
objectLocation - modified Location3D containing the X,Y,Z coordinates of the entity.
objectOrientation - modified Orientation3D containing the X,Y,Z radius of the entity.
objectOccupiedSpace - modified Block3D containing corner locations determining the occupied space of the entity.
Throws:
DirectoryFailure - if the connection to the DS cannot be established.
NotRegisteredException - if the entity whose properties are to be modified has not been registered in the DS.
ModificationException - if one or more property update failed.

modifyObjectSpatialProperties

void modifyObjectSpatialProperties(java.lang.String objectID,
                                   Location3D objectLocation,
                                   Orientation3D objectOrientation,
                                   Block3D objectOccupiedSpace)
                                   throws DirectoryFailure,
                                          NotRegisteredException
Modify spatial properties of the object identified by the given objectID in the SpatialReasoner. Important: Note that the properties are *not* modified in the KAoS DirectoryService, only in the SpatialReasoner. If you want to modify properties of a given object in the KAoS Directory service, use method modifyEntitySpatialProperties(), which will do both, modify in the KAoS DS and the SpatialReasoner.

Parameters:
objectID - String uniquely identifying object, whose spatial properties will be modified in the SpatialReasoner.
objectLocation - modified Location3D containing the X,Y,Z coordinates of the entity.
objectOrientation - modified Orientation3D containing the X,Y,Z radius of the entity.
objectOccupiedSpace - modified Block3D containing corner locations determining the occupied space of the entity.
Throws:
DirectoryFailure - if the connection to the SpatialReasoner cannot be established.
NotRegisteredException - if the object, whose properties are to be modified has not been registered in the SpatialReasoner.

deregisterEntity

void deregisterEntity(AgentDescription entityDescription)
                      throws DirectoryFailure,
                             NotRegisteredException
Deregister the entity described by the given AgentDescription from the KAoS Directory Service.

Parameters:
entityDescription - AgentDescription of the entity to be deregistered.
Throws:
DirectoryFailure - if the connection to the DS cannot be established.
NotRegisteredException - if the entity to be deregistered has not been registered in the DS.

deregisterEntityHostingEnv

void deregisterEntityHostingEnv(EntityHostEnvDescription hostEnvDescription)
                                throws DirectoryFailure,
                                       NotRegisteredException
Deregister the entity hosting environment described by the given EntityHostEnvDescription from the KAoS Directory Service.

Parameters:
hostEnvDescription - EntityHostEnvDescription of the entity hosting environment to be deregistered.
Throws:
DirectoryFailure - if the connection to the DS cannot be established.
NotRegisteredException - if the entity to be deregistered has not been registered in the DS.

createKAoSAgentDescription

KAoSAgentDescription createKAoSAgentDescription(java.lang.String guid,
                                                java.lang.String nickname,
                                                java.util.Vector domainNames,
                                                java.lang.String transportName,
                                                JasBean agentInitInfo)
Create an instance of the KAoSAgentDescription using the given parameters.

Parameters:
guid - String containing the globally unique identifier for the agent, or null. If null is passed, then the Agent Naming Service will create the identifier.
nickname - String containing agent's nickname.
domainNames - Vector containing the names of the domains the agent will become a member of.
transportName - String specifying the name of the transport the agent wants to use, or null. If null is specified, then the Locators will be empty.


Copyright © 2005 IHMC All Rights Reserved.