diff options
Diffstat (limited to 'src/main/java/com/c2kernel/lookup/Lookup.java')
| -rw-r--r-- | src/main/java/com/c2kernel/lookup/Lookup.java | 173 |
1 files changed, 166 insertions, 7 deletions
diff --git a/src/main/java/com/c2kernel/lookup/Lookup.java b/src/main/java/com/c2kernel/lookup/Lookup.java index 026ad19..5c6d1e9 100644 --- a/src/main/java/com/c2kernel/lookup/Lookup.java +++ b/src/main/java/com/c2kernel/lookup/Lookup.java @@ -9,68 +9,227 @@ import com.c2kernel.common.ObjectNotFoundException; import com.c2kernel.process.auth.Authenticator;
import com.c2kernel.property.PropertyDescriptionList;
+/**
+ * @author abranson
+ *
+ */
public interface Lookup {
+ /**
+ * Called when a server starts up. The Lookup implementation should ensure that the initial structure of its directory is valid, and create it on first boot.
+ *
+ * @throws ObjectNotFoundException When initialization data is not found
+ */
public void initializeDirectory() throws ObjectNotFoundException;
+ /**
+ * Connect to the directory using the credentials supplied in the Authenticator.
+ *
+ * @param user The connected Authenticator. The Lookup implementation may use the AuthObject in this to communicate with the database.
+ */
public void open(Authenticator user);
+ /**
+ * Shutdown the lookup
+ */
public void close();
// Path resolution
+ /**
+ * Decide whether a path references an Item or an Agent, from its directory data
+ * @param path The path of the Item or Agent
+ * @return TraceableEntity.class or ActiveEntity.class
+ * @throws ObjectNotFoundException When the path doesn't exist in the directory
+ */
public Class<?> getItemClass(Path path) throws ObjectNotFoundException;
- public ItemPath resolvePath(DomainPath domainPath) throws InvalidItemPathException, ObjectNotFoundException;
-
+ /**
+ * Find the ItemPath for which a DomainPath is an alias.
+ *
+ * @param domainPath The path to resolve
+ * @return The ItemPath it points to (should be an AgentPath if the path references an Agent)
+ * @throws InvalidItemPathException
+ * @throws ObjectNotFoundException
+ */
+ public ItemPath resolvePath(DomainPath domainPath) throws InvalidItemPathException, ObjectNotFoundException;
+
+ /**
+ * Resolve a path to a CORBA Object Item or Agent
+ *
+ * @param path The path to be resolved
+ * @return The CORBA Object
+ * @throws ObjectNotFoundException When the Path doesn't exist, or doesn't have an IOR associated with it
+ */
public org.omg.CORBA.Object resolve(Path path) throws ObjectNotFoundException;
// Path management
+ /**
+ * Register a new a Path in the directory.
+ *
+ * @param newPath The path to add
+ * @throws ObjectCannotBeUpdated When there is an error writing to the directory
+ * @throws ObjectAlreadyExistsException When the Path has already been registered
+ */
public void add(Path newPath) throws ObjectCannotBeUpdated, ObjectAlreadyExistsException;
+ /**
+ * Remove a Path from the directory
+ * @param path The path to remove
+ * @throws ObjectCannotBeUpdated When an error occurs writing to the directory
+ */
public void delete(Path path) throws ObjectCannotBeUpdated;
// Path finding and searching
+ /**
+ * Checks if a particular Path exists in the directory
+ * @param path The path to check
+ * @return boolean true if the path exists, false if it doesn't
+ */
public boolean exists(Path path);
+ /**
+ * List the next-level-deep children of a Path
+ *
+ * @param path The parent Path
+ * @return An Iterator of child Paths
+ */
public Iterator<Path> getChildren(Path path);
- public Iterator<Path> search(Path path, String name);
-
+ /**
+ * Find a path with a particular name (last component)
+ *
+ * @param start Search root
+ * @param name The name to search for
+ * @return An Iterator of matching Paths. Should be an empty Iterator if there are no matches.
+ */
+ public Iterator<Path> search(Path start, String name);
+
+ /**
+ * Search for Items in the specified path with the given property name and value
+ * @param start Search root
+ * @param propname Property name
+ * @param propvalue The property value to search for
+ * @return An Iterator of matching Paths
+ */
public Iterator<Path> search(Path start, String propname, String propvalue);
+ /**
+ * Search for Items of a particular type, based on its PropertyDescription outcome
+ * @param start Search root
+ * @param props Properties unmarshalled from an ItemDescription's property description outcome.
+ * @return An Iterator of matching Paths
+ */
public Iterator<Path> search(Path start, PropertyDescriptionList props);
- public Iterator<Path> searchEntities(Path path);
+ /**
+ * Find all ItemPaths in a given subtree of the directory.
+ *
+ * @param start Search root
+ * @return An Iterator of matching Paths
+ */
+ public Iterator<Path> searchEntities(Path start);
+ /**
+ * Find all DomainPaths in a given subtree of the directory
+ *
+ * @param start Search root
+ * @return An Iterator of matching Paths
+ */
public Iterator<Path> searchAliases(DomainPath start);
+ /**
+ * Find all DomainPaths that are aliases for a particular Item or Agent
+ * @param itemPath The ItemPath
+ * @return An Iterator of DomainPaths that are aliases for that Item
+ */
public Iterator<Path> searchAliases(ItemPath itemPath);
// Role and agent management
+ /**
+ * @param agentName
+ * @return
+ * @throws ObjectNotFoundException
+ */
public AgentPath getAgentPath(String agentName) throws ObjectNotFoundException;
+ /**
+ * @param roleName
+ * @return
+ * @throws ObjectNotFoundException
+ */
public RolePath getRolePath(String roleName) throws ObjectNotFoundException;
- public RolePath createRole(String role, boolean b) throws ObjectAlreadyExistsException, ObjectCannotBeUpdated;
-
+ /**
+ * @param role
+ * @param hasJobList
+ * @return
+ * @throws ObjectAlreadyExistsException
+ * @throws ObjectCannotBeUpdated
+ */
+ public RolePath createRole(String role, boolean hasJobList) throws ObjectAlreadyExistsException, ObjectCannotBeUpdated;
+
+ /**
+ * @param agent
+ * @param rolePath
+ * @throws ObjectCannotBeUpdated
+ * @throws ObjectNotFoundException
+ */
public void addRole(AgentPath agent, RolePath rolePath) throws ObjectCannotBeUpdated, ObjectNotFoundException;
+ /**
+ * @param rolePath
+ * @return
+ * @throws ObjectNotFoundException
+ */
public AgentPath[] getAgents(RolePath rolePath) throws ObjectNotFoundException;
+ /**
+ * @param agentPath
+ * @return
+ */
public RolePath[] getRoles(AgentPath agentPath);
+ /**
+ * @param agentPath
+ * @param role
+ * @return
+ */
public boolean hasRole(AgentPath agentPath, RolePath role);
+ /**
+ * @param agent
+ * @param role
+ * @throws ObjectCannotBeUpdated
+ * @throws ObjectNotFoundException
+ */
public void removeRole(AgentPath agent, RolePath role) throws ObjectCannotBeUpdated, ObjectNotFoundException;
+ /**
+ * @param agentPath
+ * @return
+ * @throws ObjectNotFoundException
+ */
public String getAgentName(AgentPath agentPath) throws ObjectNotFoundException;
+ /**
+ * @param agent
+ * @param newPassword
+ * @throws ObjectNotFoundException
+ * @throws ObjectCannotBeUpdated
+ * @throws NoSuchAlgorithmException
+ */
public void setAgentPassword(AgentPath agent, String newPassword) throws ObjectNotFoundException, ObjectCannotBeUpdated, NoSuchAlgorithmException;
+ /**
+ * @param role
+ * @param hasJobList
+ * @throws ObjectNotFoundException
+ * @throws ObjectCannotBeUpdated
+ */
public void setHasJobList(RolePath role, boolean hasJobList) throws ObjectNotFoundException, ObjectCannotBeUpdated;
|