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 ++++++++- .../java/com/c2kernel/lookup/ldap/LDAPLookup.java | 2 +- .../com/c2kernel/persistency/ClusterStorage.java | 387 +++++++++++++-------- .../persistency/ClusterStorageManager.java | 16 - .../com/c2kernel/persistency/NextKeyManager.java | 24 ++ .../c2kernel/persistency/TransactionManager.java | 10 - .../com/c2kernel/process/auth/Authenticator.java | 71 +++- .../java/com/c2kernel/process/auth/ProxyLogin.java | 15 +- 8 files changed, 513 insertions(+), 185 deletions(-) (limited to 'src/main/java/com/c2kernel') 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; diff --git a/src/main/java/com/c2kernel/lookup/ldap/LDAPLookup.java b/src/main/java/com/c2kernel/lookup/ldap/LDAPLookup.java index 10c1830..2d0067d 100644 --- a/src/main/java/com/c2kernel/lookup/ldap/LDAPLookup.java +++ b/src/main/java/com/c2kernel/lookup/ldap/LDAPLookup.java @@ -503,7 +503,7 @@ public class LDAPLookup implements Lookup return search(getFullDN(path), LDAPConnection.SCOPE_ONE,filter,searchCons); } - public LDAPAttributeSet createAttributeSet(Path path) throws ObjectCannotBeUpdated { + protected LDAPAttributeSet createAttributeSet(Path path) throws ObjectCannotBeUpdated { LDAPAttributeSet attrs = new LDAPAttributeSet(); if (path instanceof RolePath) { diff --git a/src/main/java/com/c2kernel/persistency/ClusterStorage.java b/src/main/java/com/c2kernel/persistency/ClusterStorage.java index 76aaf1e..29f9174 100644 --- a/src/main/java/com/c2kernel/persistency/ClusterStorage.java +++ b/src/main/java/com/c2kernel/persistency/ClusterStorage.java @@ -1,160 +1,265 @@ - package com.c2kernel.persistency; + import com.c2kernel.entity.C2KLocalObject; import com.c2kernel.persistency.outcome.Outcome; import com.c2kernel.persistency.outcome.Viewpoint; import com.c2kernel.process.auth.Authenticator; import com.c2kernel.utils.Logger; -/** Interface for persistency managers of entities. It allows different kernel objects to be stored in different backend. For instance, - * Properties may be stored in LDAP, while Events, Outcomes and Viewpoints could be stored in a relational database. There are old generic - * query methods, but these are deprecated. The kernel does no analytical querying of the ClusterStorages, only simple gets and puts. - * - * Each first-level path under the Item is defined as a Cluster. Different Clusters may be stored in different places. - * Each ClusterStorage must support {@link #get(Integer, String)} and {@link #getClusterContents(Integer, String)} for clusters they return - * {@link #READ} and {@link #READWRITE} from queryClusterSupport - * and {@link #put(Integer, C2KLocalObject)} and {@link #delete(Integer, String)} for clusters they return {@link #WRITE} and {@link #READWRITE} - * from {@link #getClusterContents(Integer, String)}. - * Operations that have notbeen declared as not supported should throw a ClusterStorageException. - * If a cluster does not exist, get should return null, and delete should return with no action. -*/ +/** + * Interface for persistency managers of entities. It allows different kernel + * objects to be stored in different backend. For instance, Properties may be + * stored in LDAP, while Events, Outcomes and Viewpoints could be stored in a + * relational database. There are old generic query methods, but these are + * deprecated. The kernel does no analytical querying of the ClusterStorages, + * only simple gets and puts. + * + * Each first-level path under the Item is defined as a Cluster. Different + * Clusters may be stored in different places. Each ClusterStorage must support + * {@link #get(Integer, String)} and + * {@link #getClusterContents(Integer, String)} for clusters they return + * {@link #READ} and {@link #READWRITE} from queryClusterSupport and + * {@link #put(Integer, C2KLocalObject)} and {@link #delete(Integer, String)} + * for clusters they return {@link #WRITE} and {@link #READWRITE} from + * {@link #getClusterContents(Integer, String)}. Operations that have notbeen + * declared as not supported should throw a ClusterStorageException. If a + * cluster does not exist, get should return null, and delete should return with + * no action. + */ public abstract class ClusterStorage { - /** - * Constant to return from {@link #queryClusterSupport(String)} for Cluster types this storage does not support. - */ - public static final short NONE = 0; - /** - * Constant to return from {@link #queryClusterSupport(String)} for Cluster types this storage can read from a database but not write. - * An example would be pre-existing data in a database that is mapped to Items in some way. - */ - public static final short READ = 1; - /** - * Constant to return from {@link #queryClusterSupport(String)} for Cluster types this storage can write to a database but not read. - * An example would be a realtime database export of data, which is transformed in an unrecoverable way for use in other systems. - */ - public static final short WRITE = 2; - /** - * Constant to return from {@link #queryClusterSupport(String)} for data stores that CRISTAL may use for both reading and writing for the given Cluster type. - */ - public static final short READWRITE = 3; - - // Cluster types - /** - * The defined path of the root of the CRISTAL Kernel object cluster tree. A zero-length string. - */ - public static final String ROOT = ""; - /** - * The root of the Property object cluster. All Property paths start with this. Defined as "Property". Properties are - * stored underneath according to their name e.g. "Property/Name" - */ - public static final String PROPERTY = "Property"; - /** - * The root of the Collection object cluster. All Collection paths start with this. Defined as "Collection". Collections - * are stored underneath by name e.g. "Collection/Composition" - */ - public static final String COLLECTION = "Collection"; - /** - * The cluster which holds the Item workflow. Defined as "LifeCycle". Holds the workflow inside, which is named "workflow", - * hence "LifeCycle/workflow". - * @see com.c2kernel.lifecycle.instance.Workflow - */ - public static final String LIFECYCLE = "LifeCycle"; - /** - * This cluster holds all outcomes of this Item. The path to each outcome is "Outcome/Schema Name/Schema Version/Event ID" - */ - public static final String OUTCOME = "Outcome"; - /** - * This is the cluster that contains all event for this Item. This cluster may be instantiated in a client as a History, which is a - * RemoteMap. Events are stored with their ID: "/AuditTrail/Event ID" - */ - public static final String HISTORY = "AuditTrail"; - /** - * This cluster contains all viewpoints. Its name is defined as "ViewPoint". The paths of viewpoint objects stored here follow this pattern: - * "ViewPoint/Schema Name/Viewpoint Name" - */ - public static final String VIEWPOINT = "ViewPoint"; - /** - * Agents store their persistent jobs in this cluster that have been pushed to them by activities configured to do so. The name is defined as "Job" - * and each new job received is assigned an integer ID one more than the highest already present. - */ - public static final String JOB = "Job"; - - /** - * An array of all currently supported cluster types, for iterative purposes. - */ - public static final String[] allClusterTypes = { PROPERTY, COLLECTION, LIFECYCLE, OUTCOME, HISTORY, VIEWPOINT, JOB }; - - // connection maintenance - public abstract void open(Authenticator auth) - throws ClusterStorageException; - public abstract void close() - throws ClusterStorageException; - - // introspection - public abstract short queryClusterSupport(String clusterType); - public abstract String getName(); - // for addressing queries - public abstract String getId(); - - - /** Quickly gets the first string of the slashed path */ - public static String getClusterType(String path) { - try { - if (path == null || path.length() == 0) return ClusterStorage.ROOT; - int start = path.charAt(0) == '/' ? 1 : 0; - int end = path.indexOf('/', start + 1); - if (end == -1) end = path.length(); - return path.substring(start, end); - } catch (Exception ex) { - Logger.error(ex); - return ClusterStorage.ROOT; - } - } + /** + * Constant to return from {@link #queryClusterSupport(String)} for Cluster + * types this storage does not support. + */ + public static final short NONE = 0; + /** + * Constant to return from {@link #queryClusterSupport(String)} for Cluster + * types this storage can read from a database but not write. An example + * would be pre-existing data in a database that is mapped to Items in some + * way. + */ + public static final short READ = 1; + /** + * Constant to return from {@link #queryClusterSupport(String)} for Cluster + * types this storage can write to a database but not read. An example would + * be a realtime database export of data, which is transformed in an + * unrecoverable way for use in other systems. + */ + public static final short WRITE = 2; + /** + * Constant to return from {@link #queryClusterSupport(String)} for data + * stores that CRISTAL may use for both reading and writing for the given + * Cluster type. + */ + public static final short READWRITE = 3; + + // Cluster types + /** + * The defined path of the root of the CRISTAL Kernel object cluster tree. A + * zero-length string. + */ + public static final String ROOT = ""; + /** + * The root of the Property object cluster. All Property paths start with + * this. Defined as "Property". Properties are stored underneath according + * to their name e.g. "Property/Name" + */ + public static final String PROPERTY = "Property"; + /** + * The root of the Collection object cluster. All Collection paths start + * with this. Defined as "Collection". Collections are stored underneath by + * name e.g. "Collection/Composition" + */ + public static final String COLLECTION = "Collection"; + /** + * The cluster which holds the Item workflow. Defined as "LifeCycle". Holds + * the workflow inside, which is named "workflow", hence + * "LifeCycle/workflow". + * + * @see com.c2kernel.lifecycle.instance.Workflow + */ + public static final String LIFECYCLE = "LifeCycle"; + /** + * This cluster holds all outcomes of this Item. The path to each outcome is + * "Outcome/Schema Name/Schema Version/Event ID" + */ + public static final String OUTCOME = "Outcome"; + /** + * This is the cluster that contains all event for this Item. This cluster + * may be instantiated in a client as a History, which is a RemoteMap. + * Events are stored with their ID: "/AuditTrail/Event ID" + */ + public static final String HISTORY = "AuditTrail"; + /** + * This cluster contains all viewpoints. Its name is defined as "ViewPoint". + * The paths of viewpoint objects stored here follow this pattern: + * "ViewPoint/Schema Name/Viewpoint Name" + */ + public static final String VIEWPOINT = "ViewPoint"; + /** + * Agents store their persistent jobs in this cluster that have been pushed + * to them by activities configured to do so. The name is defined as "Job" + * and each new job received is assigned an integer ID one more than the + * highest already present. + */ + public static final String JOB = "Job"; + + /** + * An array of all currently supported cluster types, for iterative + * purposes. + */ + public static final String[] allClusterTypes = { PROPERTY, COLLECTION, + LIFECYCLE, OUTCOME, HISTORY, VIEWPOINT, JOB }; + + /** + * Connects to the storage. It must be possible to retrieve CRISTAL local + * objects after this method returns. + * + * @param auth + * The Authenticator instance that the user or server logged in + * with. + * @throws ClusterStorageException + * If storage initialization failed + */ + public abstract void open(Authenticator auth) + throws ClusterStorageException; + /** + * Shuts down the storage. Data must be completely written to disk before + * this method returns, so the process can exit. No further gets or puts + * should follow. + * + * @throws ClusterStorageException + * If closing failed + */ + public abstract void close() throws ClusterStorageException; + + /** + * Declares whether or not this ClusterStorage can read or write a + * particular CRISTAL local object type. + * + * @param clusterType + * The Cluster type requested. Must be one of the Cluster type + * constants from this class. + * @return A ClusterStorage constant: NONE, READ, WRITE, or READWRITE + */ + public abstract short queryClusterSupport(String clusterType); + + /** + * @return A full name of this storage for logging + */ + public abstract String getName(); + + /** + * @return A short code for this storage for reference + */ + public abstract String getId(); + + /** + * Utility method to find the cluster for a particular Local Object (the + * first part of its path) + * + * @param Local + * object path + * @return The cluster to which it belongs + */ + protected static String getClusterType(String path) { + try { + if (path == null || path.length() == 0) + return ClusterStorage.ROOT; + int start = path.charAt(0) == '/' ? 1 : 0; + int end = path.indexOf('/', start + 1); + if (end == -1) + end = path.length(); + return path.substring(start, end); + } catch (Exception ex) { + Logger.error(ex); + return ClusterStorage.ROOT; + } + } + + /** + * Gives the path for a local object. Varies by Cluster. + * + * @param C2KLocalObject + * @return Its path + */ public static String getPath(C2KLocalObject obj) { String root = obj.getClusterType(); - if (root == null) return null; // no storage allowed + if (root == null) + return null; // no storage allowed if (obj instanceof Outcome) { - Outcome oc = (Outcome)obj; - return root+"/"+oc.getSchemaType()+"/"+oc.getSchemaVersion()+"/"+oc.getName(); - } - else if (obj instanceof Viewpoint) { - Viewpoint vp = (Viewpoint)obj; - return root+"/"+vp.getSchemaName()+"/"+vp.getName(); - } - else - return root+"/"+obj.getName(); + Outcome oc = (Outcome) obj; + return root + "/" + oc.getSchemaType() + "/" + + oc.getSchemaVersion() + "/" + oc.getName(); + } else if (obj instanceof Viewpoint) { + Viewpoint vp = (Viewpoint) obj; + return root + "/" + vp.getSchemaName() + "/" + vp.getName(); + } else + return root + "/" + obj.getName(); } /* object manipulation */ - // retrieve object by path - public abstract C2KLocalObject get(Integer sysKey, String path) - throws ClusterStorageException; - // store object by path - public abstract void put(Integer sysKey, C2KLocalObject obj) - throws ClusterStorageException; - // delete cluster - public abstract void delete(Integer sysKey, String path) - throws ClusterStorageException; - - // db specific queries - @Deprecated - public Object query(Object query) - throws ClusterStorageException { - throw new ClusterStorageException("Query not supported on this storage"); - } - - @Deprecated - public String queryToXML(String query, boolean genericFormat) - throws ClusterStorageException { - throw new ClusterStorageException("Query not supported on this storage"); - } - - - // directory listing - public abstract String[] getClusterContents(Integer sysKey, String path) - throws ClusterStorageException; + // retrieve object by path + /** + * Fetches a CRISTAL local object from storage + * + * @param sysKey + * The system key of the containing Item + * @param path + * The path of the local object + * @return The C2KLocalObject, or null if the object was not found + * @throws ClusterStorageException + * when retrieval failed + */ + public abstract C2KLocalObject get(Integer sysKey, String path) + throws ClusterStorageException; + + /** + * Stores a CRISTAL local object. The path is automatically generated. + * + * @param sysKey + * The Item that the object will be stored under + * @param obj + * The C2KLocalObject to store + * @throws ClusterStorageException + * When storage fails + */ + public abstract void put(Integer sysKey, C2KLocalObject obj) + throws ClusterStorageException; + + /** + * Remove a CRISTAL local object from storage. This should be used sparingly + * and responsibly, as it violated traceability. Objects removed in this way + * are not expected to be recoverable. + * + * @param sysKey + * The containing Item + * @param path + * The path of the object to be removed + * @throws ClusterStorageException + * When deletion fails or is not allowed + */ + public abstract void delete(Integer sysKey, String path) + throws ClusterStorageException; + + // directory listing + /** + * Queries the local path below the given root and returns the possible next + * elements. + * + * @param sysKey + * The Item to query + * @param path + * The path within that Item to query. May be ClusterStorage.ROOT + * (empty String) + * @return A String array of the possible next path elements + * @throws ClusterStorageException + * When an error occurred during the query + */ + public abstract String[] getClusterContents(Integer sysKey, String path) + throws ClusterStorageException; } diff --git a/src/main/java/com/c2kernel/persistency/ClusterStorageManager.java b/src/main/java/com/c2kernel/persistency/ClusterStorageManager.java index c9ede04..b1489e0 100644 --- a/src/main/java/com/c2kernel/persistency/ClusterStorageManager.java +++ b/src/main/java/com/c2kernel/persistency/ClusterStorageManager.java @@ -386,20 +386,4 @@ public class ClusterStorageManager { Logger.msg(logLevel, "Total number of cached entities: "+memoryCache.size()); } } - - @Deprecated - public Object query(String id, Object query) throws ClusterStorageException { - ClusterStorage requiredStorage = allStores.get(id); - if (requiredStorage == null) - throw new ClusterStorageException("Storage "+id+" not found."); - return requiredStorage.query(query); - } - - @Deprecated - public String queryToXML(String id, String query, boolean genericFormat) throws ClusterStorageException { - ClusterStorage requiredStorage = allStores.get(id); - if (requiredStorage == null) - throw new ClusterStorageException("Storage "+id+" not found."); - return requiredStorage.queryToXML(query, genericFormat); - } } diff --git a/src/main/java/com/c2kernel/persistency/NextKeyManager.java b/src/main/java/com/c2kernel/persistency/NextKeyManager.java index e0d0013..5afc872 100644 --- a/src/main/java/com/c2kernel/persistency/NextKeyManager.java +++ b/src/main/java/com/c2kernel/persistency/NextKeyManager.java @@ -5,15 +5,39 @@ import com.c2kernel.common.ObjectNotFoundException; import com.c2kernel.lookup.AgentPath; import com.c2kernel.lookup.ItemPath; +/** + * @author abranson + * + */ public interface NextKeyManager { + /** + * + * @return + * @throws ObjectCannotBeUpdated + * @throws ObjectNotFoundException + */ public ItemPath generateNextEntityKey() throws ObjectCannotBeUpdated, ObjectNotFoundException; + /** + * @return + * @throws ObjectCannotBeUpdated + * @throws ObjectNotFoundException + */ public AgentPath generateNextAgentKey() throws ObjectCannotBeUpdated, ObjectNotFoundException; + /** + * @param sysKey + * @throws ObjectCannotBeUpdated + * @throws ObjectNotFoundException + */ public void writeLastEntityKey(int sysKey) throws ObjectCannotBeUpdated, ObjectNotFoundException; + /** + * @return + * @throws ObjectNotFoundException + */ public ItemPath getLastEntityPath() throws ObjectNotFoundException; } diff --git a/src/main/java/com/c2kernel/persistency/TransactionManager.java b/src/main/java/com/c2kernel/persistency/TransactionManager.java index 94b8123..7362ae1 100644 --- a/src/main/java/com/c2kernel/persistency/TransactionManager.java +++ b/src/main/java/com/c2kernel/persistency/TransactionManager.java @@ -329,14 +329,4 @@ public class TransactionManager { } - @Deprecated - public Object query(String id, Object query) throws ClusterStorageException { - return storage.query(id, query); - } - - @Deprecated - public String queryToXML(String id, String query, boolean genericFormat) throws ClusterStorageException { - return storage.queryToXML(id, query, genericFormat); - } - } diff --git a/src/main/java/com/c2kernel/process/auth/Authenticator.java b/src/main/java/com/c2kernel/process/auth/Authenticator.java index 40defc4..44745da 100644 --- a/src/main/java/com/c2kernel/process/auth/Authenticator.java +++ b/src/main/java/com/c2kernel/process/auth/Authenticator.java @@ -3,14 +3,71 @@ package com.c2kernel.process.auth; import com.c2kernel.common.InvalidDataException; import com.c2kernel.common.ObjectNotFoundException; - +/** + * This interface is used by the kernel to store an authenticated connection + * and/or token that will be used by kernel components. The CRISTAL property + * 'Authenticator' is used to specify the implementation used. It is + * instantiated by the connect() methods of the Gateway, and will be found in + * the AgentProxy returned by connect(). Lookup and ClusterStorage instances are + * initialized with this Authenticator, which is expected to maintain the same + * user's connection through the process lifetime, reconnecting if the + * connection is lost. + * + * @since 3.0 + * + */ public interface Authenticator { - - public boolean authenticate(String agentName, String password, String resource) throws InvalidDataException, ObjectNotFoundException; - - public boolean authenticate(String resource) throws InvalidDataException, ObjectNotFoundException; - + + /** + * Authenticates a CRISTAL agent. If this method returns true, then the + * connect method will create and return an AgentProxy for the given + * username using the Lookup and ProxyManager. + * + * @param agentName + * The username of the Agent to be authenticated. This must be + * already present as an Agent in the CRISTAL directory. + * @param password + * The Agent's password + * @param resource + * The authentication resource/domain/realm of the agent. + * Included so that domains may include CRISTAL users from + * different realms. This parameter is passed into the connect() + * method if required. May be null. + * @return a boolean indicating if the authentication was successful. If so, + * then the Gateway will generate an AgentProxy for the given user. + * @throws ObjectNotFoundException + * When the Agent doesn't exist + * @throws InvalidDataException + * When authentication fails for another reason + */ + public boolean authenticate(String agentName, String password, + String resource) throws InvalidDataException, + ObjectNotFoundException; + + /** + * Authenticates a superuser connection for the server. It must be able to + * act on behalf of any other Agent, as the server needs to do this. + * Credentials may be in the CRISTAL properties, or some other mechanism. + * + * @param resource + * @return + * @throws InvalidDataException + * @throws ObjectNotFoundException + */ + public boolean authenticate(String resource) throws InvalidDataException, + ObjectNotFoundException; + + /** + * Lookup and storage implementations that need to use user or superuser + * authentication can retrieve it using this method. This will be highly + * implementation specific. + * + * @return the connection/token created during authentication + */ public Object getAuthObject(); - + + /** + * Close or expire the connection as the CRISTAL process shuts down. + */ public void disconnect(); } diff --git a/src/main/java/com/c2kernel/process/auth/ProxyLogin.java b/src/main/java/com/c2kernel/process/auth/ProxyLogin.java index 94416cf..665158c 100644 --- a/src/main/java/com/c2kernel/process/auth/ProxyLogin.java +++ b/src/main/java/com/c2kernel/process/auth/ProxyLogin.java @@ -4,9 +4,18 @@ import java.util.Properties; import com.c2kernel.entity.proxy.AgentProxy; +/** + * This interface is used by client processes to implement alternative login + * mechanisms aside from the standard username and password. Implementations may + * synchronize Agents with an external user library, such as Active Directory. + * Implementations are expected to set up the Gateway process and its + * authenticated components itself. + * + */ public interface ProxyLogin { - public void initialize(Properties props) throws Exception; - public AgentProxy authenticate(String resource) throws Exception; - + public void initialize(Properties props) throws Exception; + + public AgentProxy authenticate(String resource) throws Exception; + } -- cgit v1.2.3