You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@curator.apache.org by ra...@apache.org on 2016/05/19 19:02:21 UTC
[06/35] curator git commit: documentation and cleanup
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-3.0
Commit: 33534a099884fc8336c85aaf518e10485de4efe1
Parents: 7f27631
Author: randgalt <ra...@apache.org>
Authored: Mon May 2 16:35:55 2016 -0500
Committer: randgalt <ra...@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;
}
}