Index: java/net/deterlab/abac/Context.java
===================================================================
--- java/net/deterlab/abac/Context.java	(revision 56ec930e01e71105b85ee15e8f8d3314a562a616)
+++ java/net/deterlab/abac/Context.java	(revision e36ea1d2124f37b1cb324dbc84671ca0f5efa7e5)
@@ -1,12 +1,7 @@
 package net.deterlab.abac;
 
-import org.apache.commons.collections15.*;
-import org.apache.commons.collections15.functors.*;
-
 import edu.uci.ics.jung.graph.*;
-import edu.uci.ics.jung.graph.event.*;
 import edu.uci.ics.jung.graph.util.*;
 
-import java.awt.geom.Point2D;
 import java.io.*;
 import java.util.*;
@@ -18,35 +13,65 @@
 import org.bouncycastle.asn1.x509.*;
 import org.bouncycastle.x509.*;
-import org.bouncycastle.x509.util.*;
 import org.bouncycastle.openssl.*;
 
 /**
  * Represents a global graph of credentials in the form of principals and
- * attributes.
+ * attributes.  Contains the identities and credentials that can be used in a
+ * proof.
+ * @author <a href="http://abac.deterlab.net">ISI ABAC team</a>
+ * @version 1.3
  */
 public class Context {
-    static final int ABAC_CERT_SUCCESS = 0;
-    static final int ABAC_CERT_INVALID = -1;
-    static final int ABAC_CERT_BAD_SIG = -2;
-    static final int ABAC_CERT_MISSING_ISSUER = -3;
-
+    /** Certificate imported successfully */
+    public static final int ABAC_CERT_SUCCESS = 0;
+    /** Certificate import failed, invalid certificate */
+    public static final int ABAC_CERT_INVALID = -1;
+    /** Certificate import failed, signature filed */
+    public static final int ABAC_CERT_BAD_SIG = -2;
+    /** Certificate import failed, unknown issuer */
+    public static final int ABAC_CERT_MISSING_ISSUER = -3;
+
+    /** Internal graph representation */
     protected Graph<Role,Credential> g;
+    /** Set of edges in the graph that were added by the logic.  */
     protected Set<Credential> derived_edges;
+    /** Internal persistent query object */
     protected Query pq;
+    /** True when the graph has been changed since the last set of implied
+     * edges were calculated. */
     protected boolean dirty;
+    /** Set of identities known to this Context. */
     protected Set<Identity> identities;
 
+    /** Translation from issuer CN to issuer pubkey identifier */
     protected Map<String, String> nicknames;
+    /** Translation from issuer pubkey identifier to issuer CN */
     protected Map<String, String> keys;
 
+    /**
+     * The result of a query on this context.  The credentials form a partial
+     * or total proof, and success indicates whether the proof succeeded.
+     * @author <a href="http://abac.deterlab.net">ISI ABAC team</a>
+     * @version 1.3
+     */
     public class QueryResult {
+	/** Credentials returned */
 	protected Collection<Credential> creds;
+	/** True if the proof succeeded. */
 	protected boolean success;
 
-	public QueryResult(Collection<Credential> c, boolean s) {
+	/**
+	 * Construct a result from components.
+	 * @param c the collection of credentials in the proof
+	 * @param s a boolean, true if the query succeeded.
+	 */
+	QueryResult(Collection<Credential> c, boolean s) {
 	    creds = c;
 	    success = s;
 	}
 
+	/**
+	 * Empty constructor
+	 */
 	public QueryResult() { 
 	    creds = new TreeSet<Credential>();
@@ -54,9 +79,20 @@
 	}
 
+	/**
+	 * Return the credentials in the proof.
+	 * @return the collection of credentials
+	 */
 	public Collection<Credential> getCredentials() { return creds; }
+	/**
+	 * Return the success in the proof.
+	 * @return the boolean, true on success
+	 */
 	public boolean getSuccess() { return success; }
     }
 
 
+    /**
+     * Create an empty Context.
+     */
     public Context() {
         /* create the graph */
@@ -71,4 +107,8 @@
     }
 
+    /**
+     * Create a context from another context.
+     * @param c the Context to copy
+     */
     public Context(Context c) {
 	this();
@@ -80,6 +120,24 @@
     }
 
+    /**
+     * Load an Identity from a file.
+     * @param fn a String containing the file name.
+     * @return one of the static int return codes.
+     */
     public int loadIDFile(String fn) { return loadIDChunk(new File(fn)); }
+    /**
+     * Load an Identity from a file.
+     * @param fn a File containing the file name.
+     * @return one of the static int return codes.
+     */
     public int loadIDFile(File fn) { return loadIDChunk(fn); }
+    /**
+     * Load an Identity from an object.  Supported objects are an Identity, a
+     * String, a File, or a java.security.cert.X509Certificate.  A string
+     * creates an new identity, and the others are derived from the contents of
+     * the data or file.
+     * @param c an object convertable to an identity as above.
+     * @return one of the static int return codes.
+     */
     public int loadIDChunk(Object c) {
 	try {
@@ -104,10 +162,28 @@
     }
 
+    /**
+     * Load an attribute certificate from a file.
+     * @param fn a String containing the file name.
+     * @return one of the static int return codes.
+     */
     public int loadAttributeFile(String fn) { 
 	return loadAttributeChunk(new File(fn));
     }
 
+    /**
+     * Load an attribute certificate from a file.
+     * @param fn a File containing the file name.
+     * @return one of the static int return codes.
+     */
     public int loadAttributeFile(File fn) { return loadAttributeChunk(fn); }
 
+    /**
+     * Load an Identity from an object.  Supported objects are a Credential, a
+     * String, a File, or an org.bouncycastle.x509.X509V2AttributeCertificate.
+     * A string creates an new Credential, and the others are derived from the
+     * contents of the data or file.
+     * @param c an object convertable to a Credential as above.
+     * @return one of the static int return codes.
+     */
     public int loadAttributeChunk(Object c) {
 	try {
@@ -133,4 +209,11 @@
     }
 
+    /**
+     * Determine if prinicpal possesses role in the current context.  If so,
+     * return a proof of that, otherwise return a partial proof of it.
+     * @param role a String encoding the role to check for.
+     * @param principal a String with the principal ID in it.
+     * @return a Context.QueryResult containing the result.
+     */
     public QueryResult query(String role, String principal) {
 	derive_implied_edges();
@@ -143,5 +226,6 @@
 
     /**
-     * Returns a collection of the credentials in the graph.
+     * Return a collection of the credentials in the graph.s
+     * @return a collection of the credentials in the graph.
      */
     public Collection<Credential> credentials() {
@@ -156,5 +240,17 @@
     }
 
+    /**
+     * Returns true if the given Identity is known in this Context.  A jabac
+     * extension.
+     * @param i the Identity to look for
+     * @return a boolean, true if the Identity is known.
+     */
     public boolean knowsIdentity(Identity i) { return identities.contains(i); }
+    /**
+     * Returns true if an Identity with the given string representation is
+     * known in this Context.  A jabac extension.
+     * @param k the string representing the Identity to look for 
+     * @return a boolean, true if the Identity is known.
+     */
     public boolean knowsKeyID(String k) {
 	boolean known = false;
@@ -167,4 +263,5 @@
     /**
      * Add a credential to the graph.
+     * @param cred the Credential to add
      */
     protected void add_credential(Credential cred) {
@@ -191,4 +288,5 @@
     /**
      * Remove a credential from the graph.
+     * @param cred the Credential to remove
      */
     protected void remove_credential(Credential cred) {
@@ -200,4 +298,5 @@
     /**
      * Add a role w/o an edge
+     * @param v the Role to add
      */
     protected void add_vertex(Role v) {
@@ -208,4 +307,8 @@
     }
 
+    /**
+     * Remove a role and connected edges.
+     * @param v the Role to remove
+     */
     protected void remove_vertex(Role v) {
 	if (g.containsVertex(v)) {
@@ -239,4 +342,5 @@
      * Single iteration of deriving implied edges. Returns the number of new
      * links added.
+     * @return the number of new links added.
      */
     protected int derive_links_iter() {
@@ -301,4 +405,5 @@
      * Add a derived edge in the graph. Returns true only if the edge does not
      * exist.
+     * @return a boolean, true if an edge has been added
      */
     protected boolean add_derived_edge(Role head, Role tail) {
@@ -331,4 +436,5 @@
      * common name they are disambiguated.  Only one entry for keyid is
      * allowed.
+     * @param i the Identity to add
      */
     protected void addIdentity(Identity id) { 
@@ -352,4 +458,7 @@
      * strings.  If any of the smallest strings is in the map, replace it with
      * the value.
+     * @param is the string to manipulate
+     * @param m the Map containing translations
+     * @return the string after modification
      */
     protected String replace(String is, Map<String, String> m) {
@@ -369,6 +478,19 @@
     }
 
-    public String expandKeyID(String s) { return replace(s, nicknames); }
-    public String expandNickname(String s) { return replace(s, keys); }
+    /**
+     * Expand menmonic names in a Role string, e.g. the CN of the issuer
+     * certificate, into the full key ID.  Used internally by Roles to provide
+     * transparent use of mnemonics
+     * @param s the string to expand
+     * @return the String after expansion.
+     */
+    String expandKeyID(String s) { return replace(s, nicknames); }
+    /**
+     * Convert key IDs to  menmonic names in a Role string.  The inverse of
+     * expandKeyID.
+     * @param s the string to expand
+     * @return the String after expansion.
+     */
+    String expandNickname(String s) { return replace(s, keys); }
 
     /**
@@ -378,4 +500,9 @@
      * PEM files are put in there.  If errors is not null, errors reading files
      * are added indexed by filename.
+     * @param zf the File to read
+     * @param keys a Collection into which to insert unmatched keys
+     * @param errors a Map from entry name to generated exception
+     * @throws IOException if the file is unreadable.  Per entry exceptions are
+     *			   returned in the errors parameter.
      */
     public void readZipFile(File zf, Collection<KeyPair> keys, 
@@ -444,13 +571,32 @@
 	}
     }
-
+    /**
+     * Equivalent to readZipFile(d, null, null).
+     * @param d the File to read
+     * @throws IOException if the file is unreadable. To see per-entry
+     *			    exceptions use a signature with the errors parameter
+     */
     public void readZipFile(File d) 
 	    throws IOException {
 	readZipFile(d, null, null);
     }
+    /**
+     * Equivalent to readZipFile(d, null, errors).
+     * @param d the File to read
+     * @param errors a Map from entry name to generated exception
+     * @throws IOException if the file is unreadable.  Per entry exceptions are
+     *			   returned in the errors parameter.
+     */
     public void readZipFile(File d, 
 	    Map<String, Exception> errors) throws IOException {
 	readZipFile(d, null, errors);
     }
+    /**
+     * Equivalent to readZipFile(d, keys, null).
+     * @param d the File to read
+     * @param keys a Collection into which to insert unmatched keys
+     * @throws IOException if the file is unreadable. To see per-entry
+     *			    exceptions use a signature with the errors parameter
+     */
     public void readZipFile(File d, 
 	    Collection<KeyPair> keys) throws IOException {
@@ -458,4 +604,13 @@
     }
 
+    /**
+     * Read a PEM file that contains an X509 Certificate, a key pair, or both.
+     * If a cert is present it is converted into an Identity.  A key pair is
+     * returned as a java.security.KeyPair and both are returned as an Identity
+     * with an associated key pair.
+     * @param r a PEMReader from which to read
+     * @return an object encoding the contents (as above)
+     * @throws IOException for an unreadable or badly formated input
+     */
     protected Object readPEM(PEMReader r) throws IOException {
 	Identity i = null;
@@ -501,4 +656,9 @@
      * PEM files are put in there.  If errors is not null, errors reading files
      * are added indexed by filename.
+     * @param d the File to read.  If it is a directory its contents are read
+     * @param keys a Collection into which to insert unmatched keys
+     * @param errors a Map from entry name to generated exception
+     * @throws IOException if the file is unreadable.  Per file exceptions are
+     *			   returned in the errors parameter.
      */
     public void readDirectory(File d, Collection<KeyPair> keys, 
@@ -568,15 +728,44 @@
 	}
     }
-
+    /**
+     * Equivalent to readDirectory(d, null, null).
+     * @param d the File to read.  If it is a directory its contents are read
+     * @throws IOException if the file is unreadable.  To see per-file 
+     *                     exceptions use a signature with the errors parameter.
+     */
     public void readDirectory(File d) {
 	readDirectory(d, null, null);
     }
+    /**
+     * Equivalent to readDirectory(d, null, null).
+     * @param d the File to read.  If it is a directory its contents are read
+     * @param errors a Map from entry name to generated exception
+     * @throws IOException if the file is unreadable.  Per file exceptions are
+     *			   returned in the errors parameter.
+     */
     public void readDirectory(File d, Map<String, Exception> errors) {
 	readDirectory(d, null, errors);
     }
+    /**
+     * Equivalent to readDirectory(d, null, null).
+     * @param d the File to read.  If it is a directory its contents are read
+     * @param keys a Collection into which to insert unmatched keys
+     * @throws IOException if the file is unreadable.  To see per-file 
+     *                     exceptions use a signature with the errors parameter.
+     */
     public void readDirectory(File d, Collection<KeyPair> keys) {
 	readDirectory(d, keys, null);
     }
 
+    /**
+     * Write the certificates that make up the context as a zip file, with an
+     * entry for each credential or identity.
+     * @param f the File to write
+     * @param allIDs a boolean, if true write certificates for all Identities,
+     * whether used in signing a credential or not.
+     * @param withPrivateKeys a boolean, if true write the Identities as PEM
+     * file containing both the certificate and the private keys.
+     * @throws IOException if there is a problem writhing the file.
+     */
     public void writeZipFile(File f, boolean allIDs, boolean withPrivateKeys) 
 	    throws IOException {
@@ -602,7 +791,10 @@
 
     /**
-     * Get to the SHA1 hash of the key.
-     */
-    public static String extractKeyID(PublicKey k) {
+     * Get to the SHA1 hash of the key.  Used by Roles and Identities to get a
+     * key ID.
+     * @param k the PublicKey to get the ID from.
+     * @return a String with the key identifier
+     */
+    static String extractKeyID(PublicKey k) {
 	SubjectPublicKeyInfo ki = extractSubjectPublicKeyInfo(k);
 	SubjectKeyIdentifier id = 
@@ -619,6 +811,8 @@
      * Extratct the SubjectPublicKeyInfo.  Useful for some other encryptions,
      * notably Certificate.make_cert().
-     */
-    public static SubjectPublicKeyInfo extractSubjectPublicKeyInfo(
+     * @param k the PublicKey to get the ID from.
+     * @return a String with the key identifier
+     */
+    static SubjectPublicKeyInfo extractSubjectPublicKeyInfo(
 	    PublicKey k) {
 	ASN1Sequence seq = null;
