[hibernate-commits] Hibernate SVN: r16986 - beanvalidation/trunk/validation-api/src/main/java/javax/validation.

[hibernate-commits at lists.jboss.org]

Author: epbernard
Date: 2009-07-01 08:17:39 -0400 (Wed, 01 Jul 2009)
New Revision: 16986

Added:
   beanvalidation/trunk/validation-api/src/main/java/javax/validation/PathBuilder.java
Log:
BVAL-171 Prototype for a PathBuilder

Added: beanvalidation/trunk/validation-api/src/main/java/javax/validation/PathBuilder.java
===================================================================
--- beanvalidation/trunk/validation-api/src/main/java/javax/validation/PathBuilder.java	                        (rev 0)
+++ beanvalidation/trunk/validation-api/src/main/java/javax/validation/PathBuilder.java	2009-07-01 12:17:39 UTC (rev 16986)
@@ -0,0 +1,134 @@
+package javax.validation;
+
+/**
+ * Define a fluent API to build a Path object and define
+ * its sub nodes.
+ * A Path object accepted by a given Bean Validation provider
+ * must be built by a PathBuilder provided by this Bean
+ * Validation provider. In other words, Path implementations
+ * are not portable across implementations.
+ *
+ * <pre>PathBuilder builder = ...;
+ * // addresses["home"].inhabitants[].lastname
+ * Path path = builder.path("addresses")
+ *                    .addSubNode("inhabitants")
+ *                        .inIterable()
+ *                            .atKey("home")
+ *                    .addSubNode("lastname")
+ *                        .inIterable()
+ *                    .build();
+ * </pre>
+ *
+ * Once a Path object is returned ( by calling #build() ),
+ * instances of the fluent API should no longer be used
+ * and an IllegalStateException is raised upon any of the
+ * method call
+ *
+ * @author Emmanuel Bernard
+ */
+public interface PathBuilder {
+
+    /**
+     * Start the creation of a Path object whose root node is
+     * named rootNode.
+     *
+     * @param rootNode root node name
+     * @return a builder representing the root node
+     */
+    PathBuilder.NodeBuilderWithDefinedContext buildPath(String rootNode);
+
+    /**
+     * Represent a node whose context is known
+     * (ie index, key and isInIterable)
+     */
+    interface NodeBuilderWithDefinedContext {
+        /**
+         * Add a subNode to the path
+         *
+         * @param name property
+         * @return a builder representing this node
+         */
+        NodeBuilderWithCustomizableContext addSubNode(String name);
+
+        /**
+         * Return a Path object whose state is represented by
+         * the path builder.
+         * Methods of the PathBuilder instance this object comes
+         * from and the path builder nested
+         * objects return IllegalStateException from now on.
+         */
+        Path build();
+    }
+
+    /**
+     * Represent a subnode whose context is
+     * configurable (ie index, key and isInIterable)
+     */
+    //ContextualizableNodeBuilder
+    //NodeBuilderWithCustomizableContext
+    interface NodeBuilderWithCustomizableContext {
+        /**
+         * Mark the node as being in an Iterable or a Map
+         * @return a builder representing iterable details
+         */
+        NodeContextBuilder inIterable();
+
+        /**
+         * Add a subNode to the path
+         *
+         * @param name property
+         * @return a builder representing this node
+         */
+        NodeBuilderWithCustomizableContext addSubNode(String name);
+
+        /**
+         * Return a Path object whose state is represented by
+         * the path builder.
+         * Methods of the PathBuilder instance this object comes
+         * from and the path builder nested
+         * objects return IllegalStateException from now on.
+         */
+        Path build();
+    }
+
+    /**
+     * Represent choices for a node which is
+     * in an Iterator or Map.
+     * If the iterator is an indexed collection or a map,
+     * the index or the key should be set.
+     */
+    interface NodeContextBuilder {
+        /**
+         * Define the key the object is into the Map
+         *
+         * @param key map key
+         * @return a builder representing the current node
+         */
+        NodeBuilderWithDefinedContext atKey(Object key);
+
+        /**
+         * Define the index the object is into the List or array
+         *
+         * @param index index
+         * @return a builder representing the current node
+         */
+        NodeBuilderWithDefinedContext atIndex(Integer index);
+
+        /**
+         * Add a subNode to the path
+         *
+         * @param name property
+         * @return a builder representing this node
+         */
+        NodeBuilderWithCustomizableContext addSubNode(String name);
+
+        /**
+         * Return a Path object whose state is represented by
+         * the path builder.
+         * Methods of the PathBuilder instance this object comes
+         * from and the path builder nested
+         * objects return IllegalStateException from now on.
+         */
+        Path build();
+    }
+}