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(); + } +}