Merge branch 'master' of ssh://dev.cccs.uwe.ac.uk:22/var/git/cristal-kernel

1 files changed, 108 insertions, 33 deletions

diff --git a/src/main/java/com/c2kernel/lookup/Lookup.java b/src/main/java/com/c2kernel/lookup/Lookup.java
index 026ad19..5384e7c 100644
--- a/src/main/java/com/c2kernel/lookup/Lookup.java
+++ b/src/main/java/com/c2kernel/lookup/Lookup.java
@@ -1,77 +1,152 @@
 package com.c2kernel.lookup;

 

-import java.security.NoSuchAlgorithmException;

 import java.util.Iterator;

 

-import com.c2kernel.common.ObjectAlreadyExistsException;

-import com.c2kernel.common.ObjectCannotBeUpdated;

 import com.c2kernel.common.ObjectNotFoundException;

 import com.c2kernel.process.auth.Authenticator;

+import com.c2kernel.property.Property;

 import com.c2kernel.property.PropertyDescriptionList;

 

+/**

+ * @author abranson

+ *

+ */

 public interface Lookup {

 	

-	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

+	/**

+	 * Fetch the correct subclass class of ItemPath for a particular Item, derived from its lookup entry. 

+	 * This is used by the CORBA Server to make sure the correct Item subclass is used. 

+	 * 

+	 * @param sysKey The system key of the Item

+	 * @return an ItemPath or AgentPath

+	 * @throws InvalidItemPathException When the system key is invalid/out-of-range

+	 * @throws ObjectNotFoundException When the Item does not exist in the directory.

+	 */

+	public ItemPath getItemPath(int sysKey) throws InvalidItemPathException, ObjectNotFoundException;

 	

-	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

-	

-	public void add(Path newPath) throws ObjectCannotBeUpdated, ObjectAlreadyExistsException;

-

-	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);

-

-	public Iterator<Path> search(Path start, String propname, String propvalue);

+	/**

+	 * 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, Property... props);

 	

+	/**

+	 * 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);

-	

-	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;

-

-	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);

 

-	public void removeRole(AgentPath agent, RolePath role) throws ObjectCannotBeUpdated, ObjectNotFoundException;

-

+	/**

+	 * @param agentPath

+	 * @return

+	 * @throws ObjectNotFoundException

+	 */

 	public String getAgentName(AgentPath agentPath) throws ObjectNotFoundException;

 	

-	public void setAgentPassword(AgentPath agent, String newPassword) throws ObjectNotFoundException, ObjectCannotBeUpdated, NoSuchAlgorithmException;

-	

-	public void setHasJobList(RolePath role, boolean hasJobList) throws ObjectNotFoundException, ObjectCannotBeUpdated;

-

-

 }