accumulo-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From md...@apache.org
Subject [2/3] git commit: ACCUMULO-2030 Javadoc for core/security.
Date Sat, 28 Dec 2013 00:51:58 GMT
ACCUMULO-2030 Javadoc for core/security.

Signed-off-by: Mike Drob <mdrob@cloudera.com>


Project: http://git-wip-us.apache.org/repos/asf/accumulo/repo
Commit: http://git-wip-us.apache.org/repos/asf/accumulo/commit/c41900ed
Tree: http://git-wip-us.apache.org/repos/asf/accumulo/tree/c41900ed
Diff: http://git-wip-us.apache.org/repos/asf/accumulo/diff/c41900ed

Branch: refs/heads/master
Commit: c41900edca7c58e583323ec57c8aff2ccde91660
Parents: bea6e94
Author: Bill Havanki <bhavanki@cloudera.com>
Authored: Mon Oct 7 16:57:07 2013 -0400
Committer: Mike Drob <mdrob@cloudera.com>
Committed: Fri Dec 27 16:48:49 2013 -0800

----------------------------------------------------------------------
 .../core/security/AuthorizationContainer.java   |  8 +-
 .../accumulo/core/security/Authorizations.java  | 75 ++++++++++++++---
 .../core/security/ColumnVisibility.java         | 89 ++++++++++++++------
 .../accumulo/core/security/Credentials.java     | 26 ++++++
 .../core/security/NamespacePermission.java      | 25 +++++-
 .../core/security/SystemPermission.java         | 25 +++++-
 .../accumulo/core/security/TablePermission.java | 25 +++++-
 .../core/security/VisibilityConstraint.java     |  9 ++
 .../core/security/VisibilityEvaluator.java      | 41 ++++++++-
 .../core/security/VisibilityParseException.java | 12 ++-
 10 files changed, 287 insertions(+), 48 deletions(-)
----------------------------------------------------------------------


http://git-wip-us.apache.org/repos/asf/accumulo/blob/c41900ed/core/src/main/java/org/apache/accumulo/core/security/AuthorizationContainer.java
----------------------------------------------------------------------
diff --git a/core/src/main/java/org/apache/accumulo/core/security/AuthorizationContainer.java
b/core/src/main/java/org/apache/accumulo/core/security/AuthorizationContainer.java
index 041bf3c..382e20b 100644
--- a/core/src/main/java/org/apache/accumulo/core/security/AuthorizationContainer.java
+++ b/core/src/main/java/org/apache/accumulo/core/security/AuthorizationContainer.java
@@ -18,9 +18,15 @@ package org.apache.accumulo.core.security;
 
 import org.apache.accumulo.core.data.ByteSequence;
 
+/**
+ * An interface for classes that contain a collection of authorizations.
+ */
 public interface AuthorizationContainer {
   /**
-   * Checks for the existence of this UTF-8 encoded authorization.
+   * Checks whether this object contains the given authorization.
+   *
+   * @param auth authorization, as a string encoded in UTF-8
+   * @return true if authorization is in this collection
    */
   public boolean contains(ByteSequence auth);
 }

http://git-wip-us.apache.org/repos/asf/accumulo/blob/c41900ed/core/src/main/java/org/apache/accumulo/core/security/Authorizations.java
----------------------------------------------------------------------
diff --git a/core/src/main/java/org/apache/accumulo/core/security/Authorizations.java b/core/src/main/java/org/apache/accumulo/core/security/Authorizations.java
index 5cecefb..67349d4 100644
--- a/core/src/main/java/org/apache/accumulo/core/security/Authorizations.java
+++ b/core/src/main/java/org/apache/accumulo/core/security/Authorizations.java
@@ -34,17 +34,28 @@ import org.apache.accumulo.core.util.ArgumentChecker;
 import org.apache.accumulo.core.util.ByteBufferUtil;
 import org.apache.commons.codec.binary.Base64;
 
+/**
+ * A collection of authorization strings.
+ */
 public class Authorizations implements Iterable<byte[]>, Serializable, AuthorizationContainer
{
   
   private static final long serialVersionUID = 1L;
   
   private Set<ByteSequence> auths = new HashSet<ByteSequence>();
-  private List<byte[]> authsList = new ArrayList<byte[]>();
+  private List<byte[]> authsList = new ArrayList<byte[]>();  // sorted order
   
+  /**
+   * An empty set of authorizations.
+   */
   public static final Authorizations EMPTY = new Authorizations();
   
   private static final boolean[] validAuthChars = new boolean[256];
   
+  /**
+   * A special header string used when serializing instances of this class.
+   *
+   * @see #serialize()
+   */
   public static final String HEADER = "!AUTH1:";
   
   static {
@@ -88,8 +99,11 @@ public class Authorizations implements Iterable<byte[]>, Serializable,
Authoriza
   }
   
   /**
-   * A convenience constructor that accepts a collection of string authorizations that have
each already been encoded as UTF-8 bytes.
+   * Constructs an authorization object from a collection of string authorizations that have
each already been encoded as UTF-8 bytes. Warning: This method
+   * does not verify that each encoded string is valid UTF-8.
    * 
+   * @param authorizations collection of authorizations, as strings encoded in UTF-8
+   * @throws IllegalArgumentException if authorizations is null
    * @see #Authorizations(String...)
    */
   public Authorizations(Collection<byte[]> authorizations) {
@@ -100,8 +114,11 @@ public class Authorizations implements Iterable<byte[]>, Serializable,
Authoriza
   }
   
   /**
-   * A convenience constructor that accepts a collection of string authorizations that have
each already been encoded as UTF-8 bytes.
+   * Constructs an authorization object from a list of string authorizations that have each
already been encoded as UTF-8 bytes. Warning: This method does not
+   * verify that each encoded string is valid UTF-8.
    * 
+   * @param authorizations list of authorizations, as strings encoded in UTF-8 and placed
in buffers
+   * @throws IllegalArgumentException if authorizations is null
    * @see #Authorizations(String...)
    */
   public Authorizations(List<ByteBuffer> authorizations) {
@@ -113,10 +130,12 @@ public class Authorizations implements Iterable<byte[]>, Serializable,
Authoriza
   }
   
   /**
-   * Constructs an authorizations object a serialized form. This is NOT a constructor for
a set of authorizations of size one.
+   * Constructs an authorizations object from a serialized form. This is NOT a constructor
for a set of authorizations of size one. Warning: This method does
+   * not verify that the encoded serialized form is valid UTF-8.
    * 
    * @param authorizations
-   *          a serialized authorizations string produced by {@link #getAuthorizationsArray()}
or {@link #serialize()} (converted to UTF-8 bytes)
+   *          a serialized authorizations string produced by {@link #getAuthorizationsArray()}
or {@link #serialize()}, converted to UTF-8 bytes
+   * @throws IllegalArgumentException if authorizations is null
    */
   public Authorizations(byte[] authorizations) {
     
@@ -153,6 +172,7 @@ public class Authorizations implements Iterable<byte[]>, Serializable,
Authoriza
    * 
    * @param authorizations
    *          array of authorizations
+   * @throws IllegalArgumentException if authorizations is null
    */
   public Authorizations(String... authorizations) {
     setAuthorizations(authorizations);
@@ -170,17 +190,19 @@ public class Authorizations implements Iterable<byte[]>, Serializable,
Authoriza
   }
   
   /**
-   * Retrieve a serialized form of the underlying set of authorizations.
+   * Returns a serialized form of these authorizations.
    * 
-   * @see #Authorizations(byte[])
+   * @return serialized form of these authorizations, as a string encoded in UTF-8
+   * @see #serialize()
    */
   public byte[] getAuthorizationsArray() {
     return serialize().getBytes(Constants.UTF8);
   }
   
   /**
-   * Retrieve authorizations as a list of strings that have been encoded as UTF-8 bytes.
-   * 
+   * Gets the authorizations in sorted order. The returned list is not modifiable.
+   *
+   * @return authorizations, each as a string encoded in UTF-8
    * @see #Authorizations(Collection)
    */
   public List<byte[]> getAuthorizations() {
@@ -194,7 +216,10 @@ public class Authorizations implements Iterable<byte[]>, Serializable,
Authoriza
   }
   
   /**
-   * Retrieve authorizations as a list of strings that have been encoded as UTF-8 bytes.
+   * Gets the authorizations in sorted order. The returned list is not modifiable.
+   *
+   * @return authorizations, each as a string encoded in UTF-8 and within a buffer
+   * @see #Authorizations(List)
    */
   public List<ByteBuffer> getAuthorizationsBB() {
     return ByteBufferUtil.toImmutableByteBufferList(getAuthorizations());
@@ -214,14 +239,20 @@ public class Authorizations implements Iterable<byte[]>, Serializable,
Authoriza
   }
   
   /**
-   * Checks for the existence of this UTF-8 encoded authorization.
+   * Checks whether this object contains the given authorization.
+   *
+   * @param auth authorization, as a string encoded in UTF-8
+   * @return true if authorization is in this collection
    */
   public boolean contains(byte[] auth) {
     return auths.contains(new ArrayByteSequence(auth));
   }
   
   /**
-   * Checks for the existence of this UTF-8 encoded authorization.
+   * Checks whether this object contains the given authorization. Warning: This method does
not verify that the encoded string is valid UTF-8.
+   *
+   * @param auth authorization, as a string encoded in UTF-8
+   * @return true if authorization is in this collection
    */
   @Override
   public boolean contains(ByteSequence auth) {
@@ -229,7 +260,10 @@ public class Authorizations implements Iterable<byte[]>, Serializable,
Authoriza
   }
   
   /**
-   * Checks for the existence of this authorization.
+   * Checks whether this object contains the given authorization.
+   *
+   * @param auth authorization
+   * @return true if authorization is in this collection
    */
   public boolean contains(String auth) {
     return auths.contains(auth.getBytes(Constants.UTF8));
@@ -258,10 +292,20 @@ public class Authorizations implements Iterable<byte[]>, Serializable,
Authoriza
     return result;
   }
   
+  /**
+   * Gets the size of this collection of authorizations.
+   *
+   * @return collection size
+   */
   public int size() {
     return auths.size();
   }
   
+  /**
+   * Checks if this collection of authorizations is empty.
+   *
+   * @return true if this collection contains no authorizations
+   */
   public boolean isEmpty() {
     return auths.isEmpty();
   }
@@ -272,7 +316,10 @@ public class Authorizations implements Iterable<byte[]>, Serializable,
Authoriza
   }
   
   /**
-   * Returns a serialized form of these authorizations. Convert to UTF-8 bytes to deserialize
with {@link #Authorizations(byte[])}
+   * Returns a serialized form of these authorizations. Convert the returned
+   * string to UTF-8 bytes to deserialize with {@link #Authorizations(byte[])}.
+   *
+   * @return serialized form of authorizations
    */
   public String serialize() {
     StringBuilder sb = new StringBuilder(HEADER);

http://git-wip-us.apache.org/repos/asf/accumulo/blob/c41900ed/core/src/main/java/org/apache/accumulo/core/security/ColumnVisibility.java
----------------------------------------------------------------------
diff --git a/core/src/main/java/org/apache/accumulo/core/security/ColumnVisibility.java b/core/src/main/java/org/apache/accumulo/core/security/ColumnVisibility.java
index bd16b84..eb99807 100644
--- a/core/src/main/java/org/apache/accumulo/core/security/ColumnVisibility.java
+++ b/core/src/main/java/org/apache/accumulo/core/security/ColumnVisibility.java
@@ -42,13 +42,16 @@ public class ColumnVisibility {
   
   /**
    * Accessor for the underlying byte string.
-   * 
+   *
    * @return byte array representation of a visibility expression
    */
   public byte[] getExpression() {
     return expression;
   }
   
+  /**
+   * The node types in a parse tree for a visibility expression.
+   */
   public static enum NodeType {
     EMPTY, TERM, OR, AND,
   }
@@ -58,7 +61,13 @@ public class ColumnVisibility {
    */
   private static final Node EMPTY_NODE = new Node(NodeType.EMPTY, 0);
   
+  /**
+   * A node in the parse tree for a visibility expression.
+   */
   public static class Node {
+    /**
+     * An empty list of nodes.
+     */
     public final static List<Node> EMPTY = Collections.emptyList();
     NodeType type;
     int start;
@@ -115,10 +124,20 @@ public class ColumnVisibility {
     }
   }
   
+  /**
+   * A node comparator. Nodes sort according to node type, terms sort
+   * lexicographically. AND and OR nodes sort by number of children, or if
+   * the same by corresponding children.
+   */
   public static class NodeComparator implements Comparator<Node> {
     
     byte[] text;
     
+    /**
+     * Creates a new comparator.
+     *
+     * @param text expression string, encoded in UTF-8
+     */
     public NodeComparator(byte[] text) {
       this.text = text;
     }
@@ -209,8 +228,8 @@ public class ColumnVisibility {
   }
   
   /**
-   * Generates a byte[] that represents a normalized, but logically equivalent, form of the
supplied expression.
-   * 
+   * Generates a byte[] that represents a normalized, but logically equivalent, form of this
evaluator's expression.
+   *
    * @return normalized expression in byte[] form
    */
   public byte[] flatten() {
@@ -371,7 +390,7 @@ public class ColumnVisibility {
   }
   
   /**
-   * Empty visibility. Normally, elements with empty visibility can be seen by everyone.
Though, one could change this behavior with filters.
+   * Creates an empty visibility. Normally, elements with empty visibility can be seen by
everyone. Though, one could change this behavior with filters.
    * 
    * @see #ColumnVisibility(String)
    */
@@ -380,50 +399,51 @@ public class ColumnVisibility {
   }
   
   /**
-   * Set the column visibility for a Mutation.
-   * 
+   * Creates a column visibility for a Mutation.
+   *
    * @param expression
    *          An expression of the rights needed to see this mutation. The expression is
a sequence of characters from the set [A-Za-z0-9_-] along with the
-   *          binary operators "&" and "|" indicating that both operands are necessary,
or the either is necessary. The following are valid expressions for
+   *          binary operators "&amp;" and "|" indicating that both operands are necessary,
or that either is necessary. The following are valid expressions for
    *          visibility:
-   * 
+   *
    *          <pre>
    * A
    * A|B
-   * (A|B)&(C|D)
-   * orange|(red&yellow)
-   * 
+   * (A|B)&amp;(C|D)
+   * orange|(red&amp;yellow)
+   *
    * </pre>
-   * 
+   *
    *          <P>
    *          The following are not valid expressions for visibility:
-   * 
+   *
    *          <pre>
-   * A|B&C
+   * A|B&amp;C
    * A=B
    * A|B|
-   * A&|B
+   * A&amp;|B
    * ()
    * )
    * dog|!cat
    * </pre>
-   * 
+   *
    *          <P>
    *          You can use any character you like in your column visibility expression with
quoting. If your quoted term contains '&quot;' or '\' then escape
    *          them with '\'. The {@link #quote(String)} method will properly quote and escape
terms for you.
-   * 
+   *
    *          <pre>
    * &quot;A#C&quot;<span />&amp;<span />B
    * </pre>
-   * 
+   *
    */
   public ColumnVisibility(String expression) {
     this(expression.getBytes(Constants.UTF8));
   }
   
   /**
-   * A convenience method for constructing from a string already encoded in UTF-8 bytes and
contained in a {@link Text} object.
-   * 
+   * Creates a column visibility for a Mutation.
+   *
+   * @param expression visibility expression
    * @see #ColumnVisibility(String)
    */
   public ColumnVisibility(Text expression) {
@@ -431,8 +451,9 @@ public class ColumnVisibility {
   }
   
   /**
-   * A convenience method for constructing from a string already encoded in UTF-8 bytes.
-   * 
+   * Creates a column visibility for a Mutation from a string already encoded in UTF-8 bytes.
+   *
+   * @param expression visibility expression, encoded as UTF-8 bytes
    * @see #ColumnVisibility(String)
    */
   public ColumnVisibility(byte[] expression) {
@@ -456,6 +477,9 @@ public class ColumnVisibility {
   
   /**
    * Compares two ColumnVisibilities for string equivalence, not as a meaningful comparison
of terms and conditions.
+   *
+   * @param otherLe other column visibility
+   * @return true if this visibility equals the other via string comparison
    */
   public boolean equals(ColumnVisibility otherLe) {
     return Arrays.equals(expression, otherLe.expression);
@@ -466,16 +490,21 @@ public class ColumnVisibility {
     return Arrays.hashCode(expression);
   }
   
+  /**
+   * Gets the parse tree for this column visibility.
+   *
+   * @return parse tree node
+   */
   public Node getParseTree() {
     return node;
   }
   
   /**
-   * Use to properly quote terms in a column visibility expression. If no quoting is needed,
then nothing is done.
-   * 
+   * Properly quotes terms in a column visibility expression. If no quoting is needed, then
nothing is done.
+   *
    * <p>
    * Examples of using quote :
-   * 
+   *
    * <pre>
    * import static org.apache.accumulo.core.security.ColumnVisibility.quote;
    *   .
@@ -483,15 +512,19 @@ public class ColumnVisibility {
    *   .
    * ColumnVisibility cv = new ColumnVisibility(quote(&quot;A#C&quot;) + &quot;&amp;&quot;
+ quote(&quot;FOO&quot;));
    * </pre>
-   * 
+   *
+   * @param term term to quote
+   * @return quoted term (unquoted if unnecessary)
    */
   public static String quote(String term) {
     return new String(quote(term.getBytes(Constants.UTF8)), Constants.UTF8);
   }
   
   /**
-   * A convenience method to quote terms which are already encoded as UTF-8 bytes.
-   * 
+   * Properly quotes terms in a column visibility expression. If no quoting is needed, then
nothing is done.
+   *
+   * @param term term to quote, encoded as UTF-8 bytes
+   * @return quoted term (unquoted if unnecessary), encoded as UTF-8 bytes
    * @see #quote(String)
    */
   public static byte[] quote(byte[] term) {

http://git-wip-us.apache.org/repos/asf/accumulo/blob/c41900ed/core/src/main/java/org/apache/accumulo/core/security/Credentials.java
----------------------------------------------------------------------
diff --git a/core/src/main/java/org/apache/accumulo/core/security/Credentials.java b/core/src/main/java/org/apache/accumulo/core/security/Credentials.java
index 45708a8..f04e115 100644
--- a/core/src/main/java/org/apache/accumulo/core/security/Credentials.java
+++ b/core/src/main/java/org/apache/accumulo/core/security/Credentials.java
@@ -41,15 +41,31 @@ public class Credentials {
   private String principal;
   private AuthenticationToken token;
   
+  /**
+   * Creates a new credentials object.
+   *
+   * @param principal unique identifier for the entity (e.g. a user or service) authorized
for these credentials
+   * @param token authentication token used to prove that the principal for these credentials
has been properly verified
+   */
   public Credentials(String principal, AuthenticationToken token) {
     this.principal = principal;
     this.token = token;
   }
   
+  /**
+   * Gets the principal.
+   *
+   * @return unique identifier for the entity (e.g. a user or service) authorized for these
credentials
+   */
   public String getPrincipal() {
     return principal;
   }
   
+  /**
+   * Gets the authentication token.
+   *
+   * @return authentication token used to prove that the principal for these credentials
has been properly verified
+   */
   public AuthenticationToken getToken() {
     return token;
   }
@@ -57,6 +73,10 @@ public class Credentials {
   /**
    * Converts the current object to the relevant thrift type. The object returned from this
contains a non-destroyable version of the
    * {@link AuthenticationToken}, so this should be used just before placing on the wire,
and references to it should be tightly controlled.
+   *
+   * @param instance client instance
+   * @return Thrift credentials
+   * @throws RuntimeException if the authentication token has been destroyed (expired)
    */
   public TCredentials toThrift(Instance instance) {
     TCredentials tCreds = new TCredentials(getPrincipal(), getToken().getClass().getName(),
@@ -69,6 +89,9 @@ public class Credentials {
   /**
    * Converts the current object to a serialized form. The object returned from this contains
a non-destroyable version of the {@link AuthenticationToken}, so
    * references to it should be tightly controlled.
+   *
+   * @return serialized form of these credentials
+   * @throws AccumuloSecurityException
    */
   public final String serialize() {
     return (getPrincipal() == null ? "-" : Base64.encodeBase64String(getPrincipal().getBytes(Constants.UTF8)))
+ ":"
@@ -78,6 +101,9 @@ public class Credentials {
   
   /**
    * Converts the serialized form to an instance of {@link Credentials}. The original serialized
form will not be affected.
+   *
+   * @param serializedForm serialized form of credentials
+   * @return deserialized credentials
    */
   public static final Credentials deserialize(String serializedForm) {
     String[] split = serializedForm.split(":", 3);

http://git-wip-us.apache.org/repos/asf/accumulo/blob/c41900ed/core/src/main/java/org/apache/accumulo/core/security/NamespacePermission.java
----------------------------------------------------------------------
diff --git a/core/src/main/java/org/apache/accumulo/core/security/NamespacePermission.java
b/core/src/main/java/org/apache/accumulo/core/security/NamespacePermission.java
index fb6847b..1066bc4 100644
--- a/core/src/main/java/org/apache/accumulo/core/security/NamespacePermission.java
+++ b/core/src/main/java/org/apache/accumulo/core/security/NamespacePermission.java
@@ -19,8 +19,14 @@ package org.apache.accumulo.core.security;
 import java.util.ArrayList;
 import java.util.List;
 
+/**
+ * Accumulo namespace permissions. Each permission has an associated byte ID.
+ */
 public enum NamespacePermission {
-  // One can add new permissions, with new numbers, but please don't change or use numbers
previously assigned
+  /*
+   * One may add new permissions, but new permissions must use new numbers.
+   * Current numbers in use must not be changed.
+   */
   READ((byte) 0),
   WRITE((byte) 1),
   ALTER_NAMESPACE((byte) 2),
@@ -41,10 +47,20 @@ public enum NamespacePermission {
     this.permID = id;
   }
 
+  /**
+   * Gets the byte ID of this permission.
+   *
+   * @return byte ID
+   */
   public byte getId() {
     return this.permID;
   }
 
+  /**
+   * Returns a list of printable permission values.
+   *
+   * @return list of namespace permission values, as "Namespace." + permission name
+   */
   public static List<String> printableValues() {
     NamespacePermission[] a = NamespacePermission.values();
 
@@ -56,6 +72,13 @@ public enum NamespacePermission {
     return list;
   }
 
+  /**
+   * Gets the permission matching the given byte ID.
+   *
+   * @param id byte ID
+   * @return system permission
+   * @throws IndexOutOfBoundsException if the byte ID is invalid
+   */
   public static NamespacePermission getPermissionById(byte id) {
     NamespacePermission result = mapping[id];
     if (result != null)

http://git-wip-us.apache.org/repos/asf/accumulo/blob/c41900ed/core/src/main/java/org/apache/accumulo/core/security/SystemPermission.java
----------------------------------------------------------------------
diff --git a/core/src/main/java/org/apache/accumulo/core/security/SystemPermission.java b/core/src/main/java/org/apache/accumulo/core/security/SystemPermission.java
index 6bdb8e6..d9109ec 100644
--- a/core/src/main/java/org/apache/accumulo/core/security/SystemPermission.java
+++ b/core/src/main/java/org/apache/accumulo/core/security/SystemPermission.java
@@ -20,8 +20,14 @@ import java.util.ArrayList;
 import java.util.HashMap;
 import java.util.List;
 
+/**
+ * Accumulo system permissions. Each permission has an associated byte ID.
+ */
 public enum SystemPermission {
-  // One can add new permissions, with new numbers, but please don't change or use numbers
previously assigned
+  /*
+   * One may add new permissions, but new permissions must use new numbers.
+   * Current numbers in use must not be changed.
+   */
   GRANT((byte) 0),
   CREATE_TABLE((byte) 1),
   DROP_TABLE((byte) 2),
@@ -47,10 +53,20 @@ public enum SystemPermission {
     this.permID = id;
   }
   
+  /**
+   * Gets the byte ID of this permission.
+   *
+   * @return byte ID
+   */
   public byte getId() {
     return this.permID;
   }
   
+  /**
+   * Returns a list of printable permission values.
+   *
+   * @return list of system permission values, as "System." + permission name
+   */
   public static List<String> printableValues() {
     SystemPermission[] a = SystemPermission.values();
     
@@ -62,6 +78,13 @@ public enum SystemPermission {
     return list;
   }
   
+  /**
+   * Gets the permission matching the given byte ID.
+   *
+   * @param id byte ID
+   * @return system permission
+   * @throws IndexOutOfBoundsException if the byte ID is invalid
+   */
   public static SystemPermission getPermissionById(byte id) {
     if (mapping.containsKey(id))
       return mapping.get(id);

http://git-wip-us.apache.org/repos/asf/accumulo/blob/c41900ed/core/src/main/java/org/apache/accumulo/core/security/TablePermission.java
----------------------------------------------------------------------
diff --git a/core/src/main/java/org/apache/accumulo/core/security/TablePermission.java b/core/src/main/java/org/apache/accumulo/core/security/TablePermission.java
index 912b5fb..05895f5 100644
--- a/core/src/main/java/org/apache/accumulo/core/security/TablePermission.java
+++ b/core/src/main/java/org/apache/accumulo/core/security/TablePermission.java
@@ -19,8 +19,14 @@ package org.apache.accumulo.core.security;
 import java.util.ArrayList;
 import java.util.List;
 
+/**
+ * Accumulo table permissions. Each permission has an associated byte ID.
+ */
 public enum TablePermission {
-  // One can add new permissions, with new numbers, but please don't change or use numbers
previously assigned
+  /*
+   * One may add new permissions, but new permissions must use new numbers.
+   * Current numbers in use must not be changed.
+   */
   // CREATE_LOCALITY_GROUP(0),
   // DROP_LOCALITY_GROUP(1),
   READ((byte) 2),
@@ -42,10 +48,20 @@ public enum TablePermission {
     this.permID = id;
   }
   
+  /**
+   * Gets the byte ID of this permission.
+   *
+   * @return byte ID
+   */
   public byte getId() {
     return this.permID;
   }
   
+  /**
+   * Returns a list of printable permission values.
+   *
+   * @return list of table permission values, as "Table." + permission name
+   */
   public static List<String> printableValues() {
     TablePermission[] a = TablePermission.values();
     
@@ -57,6 +73,13 @@ public enum TablePermission {
     return list;
   }
   
+  /**
+   * Gets the permission matching the given byte ID.
+   *
+   * @param id byte ID
+   * @return table permission
+   * @throws IndexOutOfBoundsException if the byte ID is invalid
+   */
   public static TablePermission getPermissionById(byte id) {
     TablePermission result = mapping[id];
     if (result != null)

http://git-wip-us.apache.org/repos/asf/accumulo/blob/c41900ed/core/src/main/java/org/apache/accumulo/core/security/VisibilityConstraint.java
----------------------------------------------------------------------
diff --git a/core/src/main/java/org/apache/accumulo/core/security/VisibilityConstraint.java
b/core/src/main/java/org/apache/accumulo/core/security/VisibilityConstraint.java
index ae29cc7..43d89fa 100644
--- a/core/src/main/java/org/apache/accumulo/core/security/VisibilityConstraint.java
+++ b/core/src/main/java/org/apache/accumulo/core/security/VisibilityConstraint.java
@@ -25,6 +25,15 @@ import org.apache.accumulo.core.data.ColumnUpdate;
 import org.apache.accumulo.core.data.Mutation;
 import org.apache.accumulo.core.util.BadArgumentException;
 
+/**
+ * A constraint that checks the visibility of columns against the actor's
+ * authorizations. Violation codes:
+ * <p>
+ * <ul>
+ * <li>1 = failure to parse visibility expression</li>
+ * <li>2 = insufficient authorization</li>
+ * </ul>
+ */
 public class VisibilityConstraint implements Constraint {
   
   @Override

http://git-wip-us.apache.org/repos/asf/accumulo/blob/c41900ed/core/src/main/java/org/apache/accumulo/core/security/VisibilityEvaluator.java
----------------------------------------------------------------------
diff --git a/core/src/main/java/org/apache/accumulo/core/security/VisibilityEvaluator.java
b/core/src/main/java/org/apache/accumulo/core/security/VisibilityEvaluator.java
index 45b595f..725b2c7 100644
--- a/core/src/main/java/org/apache/accumulo/core/security/VisibilityEvaluator.java
+++ b/core/src/main/java/org/apache/accumulo/core/security/VisibilityEvaluator.java
@@ -21,9 +21,20 @@ import java.util.ArrayList;
 import org.apache.accumulo.core.constraints.Constraint.Environment;
 import org.apache.accumulo.core.security.ColumnVisibility.Node;
 
+/**
+ * A class which evaluates visibility expressions against a set of authorizations.
+ */
 public class VisibilityEvaluator {
   private AuthorizationContainer auths;
   
+  /**
+   * Creates a new {@link Authorizations} object with escaped forms of the
+   * authorizations in the given object.
+   *
+   * @param auths original authorizations
+   * @return authorizations object with escaped authorization strings
+   * @see #escape(byte[], boolean)
+   */
   static Authorizations escape(Authorizations auths) {
     ArrayList<byte[]> retAuths = new ArrayList<byte[]>(auths.getAuthorizations().size());
     
@@ -33,6 +44,14 @@ public class VisibilityEvaluator {
     return new Authorizations(retAuths);
   }
   
+  /**
+   * Properly escapes an authorization string. The string can be quoted if
+   * desired.
+   *
+   * @param auth authorization string, as UTF-8 encoded bytes
+   * @param quote true to wrap escaped authorization in quotes
+   * @return escaped authorization string
+   */
   public static byte[] escape(byte[] auth, boolean quote) {
     int escapeCount = 0;
     
@@ -59,18 +78,38 @@ public class VisibilityEvaluator {
     return auth;
   }
   
+  /**
+   * Creates a new evaluator for the authorizations found in the given
+   * environment.
+   *
+   * @param environment environment containing authorizations
+   */
   VisibilityEvaluator(Environment env) {
     this.auths = env.getAuthorizationsContainer();
   }
   
   /**
-   * The VisibilityEvaluator computes a trie from the given Authorizations, that ColumnVisibility
expressions can be evaluated against.
+   * Creates a new evaluator for the given collection of authorizations.
+   * Each authorization string is escaped before handling, and the original
+   * strings are unchanged.
+   *
+   * @param authorizations authorizations object
    */
   public VisibilityEvaluator(Authorizations authorizations) {
       this.auths = escape((Authorizations) authorizations);
   }
   
+  /**
+   * Evaluates the given column visibility against the authorizations provided to this evaluator.
+   * A visibility passes evaluation if all authorizations in it are contained in those known
to the evaluator, and
+   * all AND and OR subexpressions have at least two children.
+   *
+   * @param visibility column visibility to evaluate
+   * @return true if visibility passes evaluation
+   * @throws VisibilityParseException if an AND or OR subexpression has less than two children,
or a subexpression is of an unknown type
+   */
   public boolean evaluate(ColumnVisibility visibility) throws VisibilityParseException {
+    // The VisibilityEvaluator computes a trie from the given Authorizations, that ColumnVisibility
expressions can be evaluated against.
     return evaluate(visibility.getExpression(), visibility.getParseTree());
   }
   

http://git-wip-us.apache.org/repos/asf/accumulo/blob/c41900ed/core/src/main/java/org/apache/accumulo/core/security/VisibilityParseException.java
----------------------------------------------------------------------
diff --git a/core/src/main/java/org/apache/accumulo/core/security/VisibilityParseException.java
b/core/src/main/java/org/apache/accumulo/core/security/VisibilityParseException.java
index 2f46dc9..5b4a9f5 100644
--- a/core/src/main/java/org/apache/accumulo/core/security/VisibilityParseException.java
+++ b/core/src/main/java/org/apache/accumulo/core/security/VisibilityParseException.java
@@ -18,10 +18,20 @@ package org.apache.accumulo.core.security;
 
 import java.text.ParseException;
 
+/**
+ * An exception thrown when a visibility string cannot be parsed.
+ */
 public class VisibilityParseException extends ParseException {
   private static final long serialVersionUID = 1L;
   private String visibility;
-  
+
+  /**
+   * Creates a new exception.
+   *
+   * @param reason reason string
+   * @param visibility visibility that could not be parsed
+   * @param errorOffset offset into visibility where parsing failed
+   */
   public VisibilityParseException(String reason, byte[] visibility, int errorOffset) {
     super(reason, errorOffset);
     this.visibility = new String(visibility);


Mime
View raw message