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/03 20:35:32 UTC
curator git commit: completed site doc
Repository: curator
Updated Branches:
refs/heads/CURATOR-322 d37477354 -> f039be918
completed site doc
Project: http://git-wip-us.apache.org/repos/asf/curator/repo
Commit: http://git-wip-us.apache.org/repos/asf/curator/commit/f039be91
Tree: http://git-wip-us.apache.org/repos/asf/curator/tree/f039be91
Diff: http://git-wip-us.apache.org/repos/asf/curator/diff/f039be91
Branch: refs/heads/CURATOR-322
Commit: f039be918b8b52fd18f23bb653851cc646b29c87
Parents: d374773
Author: randgalt <ra...@apache.org>
Authored: Tue May 3 13:35:27 2016 -0500
Committer: randgalt <ra...@apache.org>
Committed: Tue May 3 13:35:27 2016 -0500
----------------------------------------------------------------------
.../apache/curator/framework/schema/Schema.java | 2 +-
.../src/site/confluence/schema.confluence | 104 +++++++++++++++++++
2 files changed, 105 insertions(+), 1 deletion(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/curator/blob/f039be91/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 465085d..3e6d448 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
@@ -34,7 +34,7 @@ public class Schema
private final DataValidator dataValidator;
private final Allowance ephemeral;
private final Allowance sequential;
- private final Schema.Allowance watched;
+ private final Allowance watched;
private final boolean canBeDeleted;
public enum Allowance
http://git-wip-us.apache.org/repos/asf/curator/blob/f039be91/curator-framework/src/site/confluence/schema.confluence
----------------------------------------------------------------------
diff --git a/curator-framework/src/site/confluence/schema.confluence b/curator-framework/src/site/confluence/schema.confluence
index 57420ca..dc79fb0 100644
--- a/curator-framework/src/site/confluence/schema.confluence
+++ b/curator-framework/src/site/confluence/schema.confluence
@@ -1,10 +1,114 @@
h1. Schema/Documentation Support
+In larger ZooKeeper applications you will end with many paths to ZNodes that have specific meanings and
+uses. E.g. "/myapp/clients/clusters/instances" or "/myapp/writers/locks". These paths can become unwieldy
+and difficult to reason about. Ideally, you should have a simple way to commonly refer to these paths,
+a way to validate how they are used, and a way to document what they are used for.
+
Curator provides a mechanism to:
* Document your ZooKeeper paths
* Validate operations on ZooKeeper paths
* Map a simple string to a ZooKeeper path
+h2. Schema and SchemaSet
+
+The basic specification is the Schema class:
+
+|| Field || Type || Required || Description ||
+| name | String | Y | A unique name for this schema |
+| path | String | Y | A full path to a ZNode or a regex pattern to a ZNode |
+| documentation | String | N | User displayable documentation for this schema |
+| dataValidator | DataValidator | N | _see below_ |
+| ephemeral | can/must/cannot | N | Whether the schema allows for ephemerals at the path |
+| sequential | can/must/cannot | N | Whether the schema allows for sequentials at the path |
+| watched | can/must/cannot | N | Whether the schema allows for watchers at the path |
+| canBeDeleted | true/false | N | Whether the schema allows the path to be deleted |
+
+All the Schema instances are combined into a SchemaSet and this can be set in the CuratorFrameworkFactory
+when creating a CuratorFramework instance. Schemas in a SchemaSet are applied in the following order:
+
+# Exact match on full path (i.e. non-regex)
+# Match on the first regex path, searched in the order given to the SchemaSet constructor
+
+h3. DataValidator
+
+DataValidators are used to optionally validate the data of a ZNode when the node is created or
+data is being set. It is a functor of the form:
+
+{code}
+boolean isValid(String path, byte[] data);
+{code}
+
+h2. Loading JSON Schema from a file/stream
+
+An optional utility is provided to load SchemaSets from a JSON file or stream: SchemaSetLoader
+*NOTE:* to avoid adding a new dependency to Curator, the Jackson library has been used with "provided" scope.
+You will need to add a dependency to jackson-core and jackson-databind to your project.
+
+The JSON stream should be an array of named schemas:
+
+{code}
+[
+ {
+ "name": "name", required - name of the schema
+ "path": "path or pattern", required - full path or regex pattern
+ "isRegex": true/false, optional - true if path is a regular expression - default is false
+ "dataValidator": "name", optional - name of a data validator - default is no validator
+ "documentation": "docs", optional - user displayable docs - default is ""
+ "ephemeral": "allowance", optional - "can", "must" or "cannot" - default is "can"
+ "sequential": "allowance", optional - "can", "must" or "cannot" - default is "can"
+ "watched": "allowance", optional - "can", "must" or "cannot" - default is "can"
+ "canBeDeleted": "true/false optional - true if ZNode at path can be deleted - default is true
+ }
+]
+{code}
+
+h2. Examples
+
+h3. Example 1
+
+{code}
+[
+ {
+ "name": "test",
+ "path": "/a/b/c",
+ "ephemeral": "must",
+ "sequential": "cannot"
+ }
+]
+{code}
+
+* This SchemaSet has only 1 schema
+* The schema applies only to the path "/a/b/c"
+* The ZNode "/a/b/c" must be ephemeral, cannot be sequential, can be watched, and can be deleted
+
+h3. Example 2
+
+{code}
+[
+ {
+ "name": "test",
+ "path": "/a/b/c",
+ "ephemeral": "must",
+ "sequential": "cannot"
+ },
+ {
+ "name": "test2",
+ "path": "/a/.*",
+ "isRegex": true,
+ "dataValidator": "test"
+ "ephemeral": "cannot",
+ "canBeDeleted": false
+ }
+]
+{code}
+* This SchemaSet has 2 schemas
+* The first schema applies only to the path "/a/b/c"
+* The ZNode "/a/b/c" must be ephemeral, cannot be sequential, can be watched, and can be deleted
+* The second schema is regex and applies to any path that matches the expression "/a/.\*"
+* The ZNodes that match "/a/.\*" cannot be ephemeral, can be sequential, can be watched, and cannot be deleted
+* The second schema also has a data validator. The data validator named "test" (configured when constructing the SchemaSetLoader) will
+be called to validate data for ZNodes that match "/a/.\*" when create() or setData() are called.