From 2353f4fc4252f7067478d6a9d8993daeb5d66e6a Mon Sep 17 00:00:00 2001 From: Andrew Branson Date: Fri, 6 Jun 2014 17:14:26 +0200 Subject: Partial javadoc and scope tightening of the new interfaces. --- src/main/java/com/c2kernel/lookup/Lookup.java | 173 ++++++++++++++++++++++++-- 1 file changed, 166 insertions(+), 7 deletions(-) (limited to 'src/main/java/com/c2kernel/lookup/Lookup.java') 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 getChildren(Path path); - public Iterator 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 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 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 search(Path start, PropertyDescriptionList props); - public Iterator 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 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 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 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; -- cgit v1.2.3