Updated Branches: refs/heads/master 9b5475314 -> 37f117c8e
ACCUMULO-2107 Javadoc for core/constraints. Project: http://git-wip-us.apache.org/repos/asf/accumulo/repo Commit: http://git-wip-us.apache.org/repos/asf/accumulo/commit/37f117c8 Tree: http://git-wip-us.apache.org/repos/asf/accumulo/tree/37f117c8 Diff: http://git-wip-us.apache.org/repos/asf/accumulo/diff/37f117c8 Branch: refs/heads/master Commit: 37f117c8e16d450965f15fee7e31ce12b9fd399f Parents: 9b54753 Author: Bill Havanki <[email protected]> Authored: Thu Jan 9 12:23:50 2014 -0500 Committer: Bill Havanki <[email protected]> Committed: Thu Jan 9 12:23:50 2014 -0500 ---------------------------------------------------------------------- .../accumulo/core/constraints/Constraint.java | 76 ++++++++++++++------ .../accumulo/core/constraints/Violations.java | 32 +++++++++ .../core/data/ConstraintViolationSummary.java | 9 +-- 3 files changed, 90 insertions(+), 27 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/accumulo/blob/37f117c8/core/src/main/java/org/apache/accumulo/core/constraints/Constraint.java ---------------------------------------------------------------------- diff --git a/core/src/main/java/org/apache/accumulo/core/constraints/Constraint.java b/core/src/main/java/org/apache/accumulo/core/constraints/Constraint.java index 1ddc892..3c5f797 100644 --- a/core/src/main/java/org/apache/accumulo/core/constraints/Constraint.java +++ b/core/src/main/java/org/apache/accumulo/core/constraints/Constraint.java @@ -24,49 +24,79 @@ import org.apache.accumulo.core.security.AuthorizationContainer; import org.apache.accumulo.core.security.Authorizations; /** - * Accumulo uses Constraint objects to determine if mutations will be applied to a table. - * - * This interface expects implementers to return violation codes. The reason codes are returned instead of arbitrary strings it to encourage conciseness. - * Conciseness is needed because violations are aggregated. If a user sends a batch of 10,000 mutations to accumulo, only aggregated counts about which - * violations occurred are returned. - * - * If the Constraint implementer was allowed to return arbitrary violation strings like the following : - * - * Value "abc" is not a number Value "vbg" is not a number - * - * Then this would not aggregate very well, because the same violation is represented with two different strings. - * - * - * + * <p> + * Constraint objects are used to determine if mutations will be applied to a table. + * </p> + * + * <p> + * This interface expects implementers to return violation codes. The reason codes are returned instead of arbitrary strings to encourage conciseness. + * Conciseness is needed because violations are aggregated. If a user sends a batch of 10,000 mutations to Accumulo, only aggregated counts about which + * violations occurred are returned. If the constraint implementer were allowed to return arbitrary violation strings like the following: + * </p> + * + * <p> + * Value "abc" is not a number<br> + * Value "vbg" is not a number + * </p> + * + * <p> + * This would not aggregate very well, because the same violation is represented with two different strings. + * </p> */ - public interface Constraint { + /** + * The environment within which a constraint exists. + */ interface Environment { + /** + * Gets the key extent of the environment. + * + * @return key extent + */ KeyExtent getExtent(); + /** + * Gets the user within the environment. + * + * @return user + */ String getUser(); + /** + * Gets the authorizations in the environment. + * + * @return authorizations + * @deprecated Use {@link #getAuthorizationsContainer()} instead. + */ @Deprecated Authorizations getAuthorizations(); + /** + * Gets the authorizations in the environment. + * + * @return authorizations + */ AuthorizationContainer getAuthorizationsContainer(); } /** - * Implementers of this method should return a short one sentence description of what a given violation code means. - * + * Gets a short, one-sentence description of what a given violation code means. + * + * @param violationCode numeric violation code + * @return matching violation description */ - String getViolationDescription(short violationCode); /** - * Checks a mutation for constrain violations. If the mutation contains no violations, then the implementation should return null. Otherwise it should return + * Checks a mutation for constraint violations. If the mutation contains no violations, returns null. Otherwise, returns * a list of violation codes. - * - * Violation codes must be non negative. Negative violation codes are reserved for system use. - * + * + * Violation codes must be non-negative. Negative violation codes are reserved for system use. + * + * @param env constraint environment + * @param mutation mutation to check + * @return list of violation codes, or null if none */ - List<Short> check(Environment env, Mutation mutation); } http://git-wip-us.apache.org/repos/asf/accumulo/blob/37f117c8/core/src/main/java/org/apache/accumulo/core/constraints/Violations.java ---------------------------------------------------------------------- diff --git a/core/src/main/java/org/apache/accumulo/core/constraints/Violations.java b/core/src/main/java/org/apache/accumulo/core/constraints/Violations.java index fe41d54..eda1a67 100644 --- a/core/src/main/java/org/apache/accumulo/core/constraints/Violations.java +++ b/core/src/main/java/org/apache/accumulo/core/constraints/Violations.java @@ -24,6 +24,9 @@ import java.util.Set; import org.apache.accumulo.core.data.ConstraintViolationSummary; +/** + * A class for accumulating constraint violations across a number of mutations. + */ public class Violations { private static class CVSKey { @@ -54,10 +57,18 @@ public class Violations { private HashMap<CVSKey,ConstraintViolationSummary> cvsmap; + /** + * Creates a new empty object. + */ public Violations() { cvsmap = new HashMap<CVSKey,ConstraintViolationSummary>(); } + /** + * Checks if this object is empty, i.e., that no violations have been added. + * + * @return true if empty + */ public boolean isEmpty() { return cvsmap.isEmpty(); } @@ -72,11 +83,22 @@ public class Violations { } } + /** + * Adds a violation. If a matching violation was already added, then its + * count is increased. + * + * @param cvs summary of violation + */ public void add(ConstraintViolationSummary cvs) { CVSKey cvsk = new CVSKey(cvs); add(cvsk, cvs); } + /** + * Adds all violations from the given object to this one. + * + * @param violations violations to add + */ public void add(Violations violations) { Set<Entry<CVSKey,ConstraintViolationSummary>> es = violations.cvsmap.entrySet(); @@ -86,6 +108,11 @@ public class Violations { } + /** + * Adds a list of violations. + * + * @param cvsList list of violation summaries + */ public void add(List<ConstraintViolationSummary> cvsList) { for (ConstraintViolationSummary constraintViolationSummary : cvsList) { add(constraintViolationSummary); @@ -93,6 +120,11 @@ public class Violations { } + /** + * Gets the violations as a list of summaries. + * + * @return list of violation summaries + */ public List<ConstraintViolationSummary> asList() { return new ArrayList<ConstraintViolationSummary>(cvsmap.values()); } http://git-wip-us.apache.org/repos/asf/accumulo/blob/37f117c8/core/src/main/java/org/apache/accumulo/core/data/ConstraintViolationSummary.java ---------------------------------------------------------------------- diff --git a/core/src/main/java/org/apache/accumulo/core/data/ConstraintViolationSummary.java b/core/src/main/java/org/apache/accumulo/core/data/ConstraintViolationSummary.java index d081a8a..63c85a4 100644 --- a/core/src/main/java/org/apache/accumulo/core/data/ConstraintViolationSummary.java +++ b/core/src/main/java/org/apache/accumulo/core/data/ConstraintViolationSummary.java @@ -31,10 +31,11 @@ public class ConstraintViolationSummary { /** * Creates a new summary. * - * @param constrainClass - * @param violationCode - * @param violationDescription - * @param numberOfViolatingMutations + * @param constrainClass class of constraint that was violated + * @param violationCode violation code + * @param violationDescription description of violation + * @param numberOfViolatingMutations number of mutations that produced this + * particular violation */ public ConstraintViolationSummary(String constrainClass, short violationCode, String violationDescription, long numberOfViolatingMutations) { this.constrainClass = constrainClass;
