curator-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From randg...@apache.org
Subject [06/16] curator git commit: documentation and cleanup
Date Tue, 03 May 2016 15:20:58 GMT
documentation and cleanup


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

Branch: refs/heads/CURATOR-322
Commit: 33534a099884fc8336c85aaf518e10485de4efe1
Parents: 7f27631
Author: randgalt <randgalt@apache.org>
Authored: Mon May 2 16:35:55 2016 -0500
Committer: randgalt <randgalt@apache.org>
Committed: Mon May 2 16:35:55 2016 -0500

----------------------------------------------------------------------
 .../framework/CuratorFrameworkFactory.java      |  9 +---
 .../framework/schema/DefaultDataValidator.java  |  3 ++
 .../apache/curator/framework/schema/Schema.java | 53 +++++++++++++-------
 .../curator/framework/schema/SchemaBuilder.java | 48 +++++++++++++-----
 .../curator/framework/schema/SchemaSet.java     | 35 +++++++++++--
 .../framework/schema/SchemaViolation.java       | 18 +++++++
 6 files changed, 124 insertions(+), 42 deletions(-)
----------------------------------------------------------------------


http://git-wip-us.apache.org/repos/asf/curator/blob/33534a09/curator-framework/src/main/java/org/apache/curator/framework/CuratorFrameworkFactory.java
----------------------------------------------------------------------
diff --git a/curator-framework/src/main/java/org/apache/curator/framework/CuratorFrameworkFactory.java
b/curator-framework/src/main/java/org/apache/curator/framework/CuratorFrameworkFactory.java
index c17534f..915aee1 100644
--- a/curator-framework/src/main/java/org/apache/curator/framework/CuratorFrameworkFactory.java
+++ b/curator-framework/src/main/java/org/apache/curator/framework/CuratorFrameworkFactory.java
@@ -144,14 +144,7 @@ public class CuratorFrameworkFactory
         private boolean useContainerParentsIfAvailable = true;
         private ConnectionStateErrorPolicy connectionStateErrorPolicy = new StandardConnectionStateErrorPolicy();
         private ConnectionHandlingPolicy connectionHandlingPolicy = Boolean.getBoolean("curator-use-classic-connection-handling")
? new ClassicConnectionHandlingPolicy() : new StandardConnectionHandlingPolicy();
-        private SchemaSet schemaSet = new SchemaSet()
-        {
-            @Override
-            public String toDocumentation()
-            {
-                return "Default schema";
-            }
-        };
+        private SchemaSet schemaSet = SchemaSet.getDefaultSchemaSet();
 
         /**
          * Apply the current values and build a new CuratorFramework

http://git-wip-us.apache.org/repos/asf/curator/blob/33534a09/curator-framework/src/main/java/org/apache/curator/framework/schema/DefaultDataValidator.java
----------------------------------------------------------------------
diff --git a/curator-framework/src/main/java/org/apache/curator/framework/schema/DefaultDataValidator.java
b/curator-framework/src/main/java/org/apache/curator/framework/schema/DefaultDataValidator.java
index 05e1f7c..f28db57 100644
--- a/curator-framework/src/main/java/org/apache/curator/framework/schema/DefaultDataValidator.java
+++ b/curator-framework/src/main/java/org/apache/curator/framework/schema/DefaultDataValidator.java
@@ -1,5 +1,8 @@
 package org.apache.curator.framework.schema;
 
+/**
+ * The default data validator - always returns true
+ */
 public class DefaultDataValidator implements DataValidator
 {
     @Override

http://git-wip-us.apache.org/repos/asf/curator/blob/33534a09/curator-framework/src/main/java/org/apache/curator/framework/schema/Schema.java
----------------------------------------------------------------------
diff --git a/curator-framework/src/main/java/org/apache/curator/framework/schema/Schema.java
b/curator-framework/src/main/java/org/apache/curator/framework/schema/Schema.java
index ed8fecb..05aa6f1 100644
--- a/curator-framework/src/main/java/org/apache/curator/framework/schema/Schema.java
+++ b/curator-framework/src/main/java/org/apache/curator/framework/schema/Schema.java
@@ -4,6 +4,9 @@ import com.google.common.base.Preconditions;
 import org.apache.zookeeper.CreateMode;
 import java.util.regex.Pattern;
 
+/**
+ * Represents and documents operations allowed for a given path pattern
+ */
 public class Schema
 {
     private final Pattern path;
@@ -11,8 +14,7 @@ public class Schema
     private final DataValidator dataValidator;
     private final Allowance ephemeral;
     private final Allowance sequential;
-    private final boolean canBeWatched;
-    private final boolean canHaveChildren;
+    private final Schema.Allowance watched;
     private final boolean canBeDeleted;
 
     public enum Allowance
@@ -22,20 +24,36 @@ public class Schema
         CANNOT
     }
 
-    public static SchemaBuilder builder(String path)
+    /**
+     * Start a builder for the given path pattern.
+     *
+     * @param pathRegex regex for the path. This schema applies to all matching paths
+     * @return builder
+     */
+    public static SchemaBuilder builder(String pathRegex)
     {
-        return new SchemaBuilder(Pattern.compile(path));
+        return builder(Pattern.compile(pathRegex));
     }
 
-    public Schema(Pattern path, String documentation, DataValidator dataValidator, Allowance
ephemeral, Allowance sequential, boolean canBeWatched, boolean canHaveChildren, boolean canBeDeleted)
+    /**
+     * Start a builder for the given path pattern.
+     *
+     * @param pathRegex regex for the path. This schema applies to all matching paths
+     * @return builder
+     */
+    public static SchemaBuilder builder(Pattern pathRegex)
+    {
+        return new SchemaBuilder(pathRegex);
+    }
+
+    Schema(Pattern path, String documentation, DataValidator dataValidator, Allowance ephemeral,
Allowance sequential, Allowance watched, boolean canBeDeleted)
     {
         this.path = Preconditions.checkNotNull(path, "path cannot be null");
         this.documentation = Preconditions.checkNotNull(documentation, "documentation cannot
be null");
         this.dataValidator = Preconditions.checkNotNull(dataValidator, "dataValidator cannot
be null");
         this.ephemeral = Preconditions.checkNotNull(ephemeral, "ephemeral cannot be null");
         this.sequential = Preconditions.checkNotNull(sequential, "sequential cannot be null");
-        this.canBeWatched = canBeWatched;
-        this.canHaveChildren = canHaveChildren;
+        this.watched = Preconditions.checkNotNull(watched, "watched cannot be null");
         this.canBeDeleted = canBeDeleted;
     }
 
@@ -49,10 +67,15 @@ public class Schema
 
     public void validateWatcher(boolean isWatching)
     {
-        if ( isWatching && !canBeWatched )
+        if ( isWatching && (watched == Allowance.CANNOT) )
         {
             throw new SchemaViolation(this, "Cannot be watched");
         }
+
+        if ( !isWatching && (watched == Allowance.MUST) )
+        {
+            throw new SchemaViolation(this, "Must be watched");
+        }
     }
 
     public void validateCreate(CreateMode mode, byte[] data)
@@ -113,14 +136,9 @@ public class Schema
         return sequential;
     }
 
-    public boolean canBeWatched()
-    {
-        return canBeWatched;
-    }
-
-    public boolean canHaveChildren()
+    public Schema.Allowance getWatched()
     {
-        return canHaveChildren;
+        return watched;
     }
 
     public boolean canBeDeleted()
@@ -161,8 +179,7 @@ public class Schema
             ", dataValidator=" + dataValidator +
             ", isEphemeral=" + ephemeral +
             ", isSequential=" + sequential +
-            ", canBeWatched=" + canBeWatched +
-            ", canHaveChildren=" + canHaveChildren +
+            ", watched=" + watched +
             ", canBeDeleted=" + canBeDeleted +
             '}';
     }
@@ -172,7 +189,7 @@ public class Schema
         return path.pattern() + '\n'
             + documentation + '\n'
             + "Validator: " + dataValidator.getClass().getSimpleName() + '\n'
-            + String.format("ephemeral: %s | sequential: %s | canBeWatched: %s | canHaveChildren:
%s | canBeDeleted: %s", ephemeral, sequential, canBeWatched, canHaveChildren, canBeDeleted)
+ '\n'
+            + String.format("ephemeral: %s | sequential: %s | watched: %s | | canBeDeleted:
%s", ephemeral, sequential, watched, canBeDeleted) + '\n'
             ;
     }
 }

http://git-wip-us.apache.org/repos/asf/curator/blob/33534a09/curator-framework/src/main/java/org/apache/curator/framework/schema/SchemaBuilder.java
----------------------------------------------------------------------
diff --git a/curator-framework/src/main/java/org/apache/curator/framework/schema/SchemaBuilder.java
b/curator-framework/src/main/java/org/apache/curator/framework/schema/SchemaBuilder.java
index 383a16b..33b42ce 100644
--- a/curator-framework/src/main/java/org/apache/curator/framework/schema/SchemaBuilder.java
+++ b/curator-framework/src/main/java/org/apache/curator/framework/schema/SchemaBuilder.java
@@ -10,51 +10,73 @@ public class SchemaBuilder
     private DataValidator dataValidator = new DefaultDataValidator();
     private Schema.Allowance ephemeral = Schema.Allowance.CAN;
     private Schema.Allowance sequential = Schema.Allowance.CAN;
-    private boolean canBeWatched = true;
-    private boolean canHaveChildren = true;
+    private Schema.Allowance watched = Schema.Allowance.CAN;
     private boolean canBeDeleted = true;
 
+    /**
+     * Build a new schema from the currently set values
+     *
+     * @return new schema
+     */
     public Schema build()
     {
-        return new Schema(path, documentation, dataValidator, ephemeral, sequential, canBeWatched,
canHaveChildren, canBeDeleted);
+        return new Schema(path, documentation, dataValidator, ephemeral, sequential, watched,
canBeDeleted);
     }
 
+    /**
+     * @param documentation user displayable documentation for the schema
+     * @return this for chaining
+     */
     public SchemaBuilder documentation(String documentation)
     {
         this.documentation = Preconditions.checkNotNull(documentation, "documentation cannot
be null");
         return this;
     }
 
+    /**
+     * @param dataValidator a data validator - will be used to validate data set for the
znode
+     * @return this for chaining
+     */
     public SchemaBuilder dataValidator(DataValidator dataValidator)
     {
         this.dataValidator = Preconditions.checkNotNull(dataValidator, "dataValidator cannot
be null");
         return this;
     }
 
+    /**
+     * @param ephemeral whether can, must or cannot be ephemeral
+     * @return this for chaining
+     */
     public SchemaBuilder ephemeral(Schema.Allowance ephemeral)
     {
-        this.ephemeral = ephemeral;
+        this.ephemeral = Preconditions.checkNotNull(ephemeral, "ephemeral cannot be null");
         return this;
     }
 
+    /**
+     * @param sequential whether can, must or cannot be sequential
+     * @return this for chaining
+     */
     public SchemaBuilder sequential(Schema.Allowance sequential)
     {
-        this.sequential = sequential;
+        this.sequential = Preconditions.checkNotNull(sequential, "sequential cannot be null");
         return this;
     }
 
-    public SchemaBuilder canBeWatched(boolean canBeWatched)
+    /**
+     * @param watched whether can, must or cannot be watched
+     * @return this for chaining
+     */
+    public SchemaBuilder watched(Schema.Allowance watched)
     {
-        this.canBeWatched = canBeWatched;
-        return this;
-    }
-
-    public SchemaBuilder canHaveChildren(boolean canHaveChildren)
-    {
-        this.canHaveChildren = canHaveChildren;
+        this.watched = watched;
         return this;
     }
 
+    /**
+     * @param canBeDeleted true if znode can be deleted
+     * @return this for chaining
+     */
     public SchemaBuilder canBeDeleted(boolean canBeDeleted)
     {
         this.canBeDeleted = canBeDeleted;

http://git-wip-us.apache.org/repos/asf/curator/blob/33534a09/curator-framework/src/main/java/org/apache/curator/framework/schema/SchemaSet.java
----------------------------------------------------------------------
diff --git a/curator-framework/src/main/java/org/apache/curator/framework/schema/SchemaSet.java
b/curator-framework/src/main/java/org/apache/curator/framework/schema/SchemaSet.java
index 8a6e19c..113e42a 100644
--- a/curator-framework/src/main/java/org/apache/curator/framework/schema/SchemaSet.java
+++ b/curator-framework/src/main/java/org/apache/curator/framework/schema/SchemaSet.java
@@ -12,6 +12,9 @@ import java.util.Collections;
 import java.util.concurrent.ExecutionException;
 import java.util.regex.Pattern;
 
+/**
+ * Collection of all schemas for a Curator instance
+ */
 public class SchemaSet
 {
     private final Logger log = LoggerFactory.getLogger(getClass());
@@ -37,18 +40,39 @@ public class SchemaSet
         .softValues()
         .build(cacheLoader);
 
-    private static final Schema defaultSchema = new Schema(Pattern.compile(".*"), "Default
schema", new DefaultDataValidator(), Schema.Allowance.CAN, Schema.Allowance.CAN, true, true,
true);
+    private static final Schema defaultSchema = new Schema(Pattern.compile(".*"), "Default
schema", new DefaultDataValidator(), Schema.Allowance.CAN, Schema.Allowance.CAN, Schema.Allowance.CAN,
true);
 
-    public SchemaSet()
+    /**
+     * Return the default (empty) schema set
+     *
+     * @return default schema set
+     */
+    public static SchemaSet getDefaultSchemaSet()
     {
-        this(Collections.<Schema>emptySet());
+        return new SchemaSet(Collections.<Schema>emptySet())
+        {
+            @Override
+            public String toDocumentation()
+            {
+                return "Default schema";
+            }
+        };
     }
 
+    /**
+     * @param schemas the schemas for the set
+     */
     public SchemaSet(Collection<Schema> schemas)
     {
         this.schemas = ImmutableSet.copyOf(Preconditions.checkNotNull(schemas, "schemas cannot
be null"));
     }
 
+    /**
+     * Find the first matching schema for the path and return it
+     *
+     * @param path ZNode full path
+     * @return matching schema or a default schema
+     */
     public Schema getSchema(String path)
     {
         if ( schemas.size() == 0 )
@@ -65,6 +89,11 @@ public class SchemaSet
         }
     }
 
+    /**
+     * Build a user displayable documentation string for the schemas in this set
+     *
+     * @return documentation
+     */
     public String toDocumentation()
     {
         StringBuilder str = new StringBuilder("Curator Schemas:\n\n");

http://git-wip-us.apache.org/repos/asf/curator/blob/33534a09/curator-framework/src/main/java/org/apache/curator/framework/schema/SchemaViolation.java
----------------------------------------------------------------------
diff --git a/curator-framework/src/main/java/org/apache/curator/framework/schema/SchemaViolation.java
b/curator-framework/src/main/java/org/apache/curator/framework/schema/SchemaViolation.java
index 6935094..afd6bbf 100644
--- a/curator-framework/src/main/java/org/apache/curator/framework/schema/SchemaViolation.java
+++ b/curator-framework/src/main/java/org/apache/curator/framework/schema/SchemaViolation.java
@@ -1,9 +1,27 @@
 package org.apache.curator.framework.schema;
 
+/**
+ * Thrown by the various <code>validation</code> methods in a Schema
+ */
 public class SchemaViolation extends RuntimeException
 {
+    private final Schema schema;
+    private final String violation;
+
     public SchemaViolation(Schema schema, String violation)
     {
         super(String.format("Schema violation: %s for schema: %s", violation, schema));
+        this.schema = schema;
+        this.violation = violation;
+    }
+
+    public Schema getSchema()
+    {
+        return schema;
+    }
+
+    public String getViolation()
+    {
+        return violation;
     }
 }


Mime
View raw message