curator-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From randg...@apache.org
Subject curator git commit: completed site doc
Date Tue, 03 May 2016 18:35:32 GMT
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 <randgalt@apache.org>
Authored: Tue May 3 13:35:27 2016 -0500
Committer: randgalt <randgalt@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.


Mime
View raw message