[hibernate-issues] [Hibernate-JIRA] Commented: (BVAL-171) Provide a PathBuilder and deprecate the String based property APIs

[Emmanuel Bernard (JIRA)]

    [ http://opensource.atlassian.com/projects/hibernate/browse/BVAL-171?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=33559#action_33559 ] 

Emmanuel Bernard commented on BVAL-171:
---------------------------------------

PathBuilder API

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 {

    /**
     * Add a subNode to the path.
     *
     * name describes a single property. In particular,
     * dot (.) are not allowed.
     *
     * @param name property
     * @return a builder representing this node
     */
    NodeBuilderDefinedContext addSubNode(String name);

    /**
     * Represent a node whose context is known
     * (ie index, key and isInIterable)
     */
    interface NodeBuilderDefinedContext {
		
        /**
         * Add a subNode to the path.
         *
         * <code>name</code> describes a single property. In particular,
         * dot (.) are not allowed.
         *
         * @param name property <code>name</code>
         * @return @return a builder representing node <code>name</code>
         */
        NodeBuilderCustomizableContext addSubNode(String name);

        /**
         * Return a Path object whose state is represented by
         * the path builder.
         * 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.
         */
        Path build();
    }

    /**
     * Represent a subnode whose context is
     * configurable (ie index, key and isInIterable)
     */
    interface NodeBuilderCustomizableContext {

        /**
         * 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.
         *
         * <code>name</code> describes a single property. In particular,
         * dot (.) are not allowed.
         *
         * @param name property <code>name</code>
         * @return a builder representing this node
         */
        NodeBuilderCustomizableContext addSubNode(String name);

        /**
         * Return a Path object whose state is represented by
         * the path builder.
         * 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.
         */
        Path build();
    }

    /**
     * Represent refinement 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
         */
        NodeBuilderDefinedContext atKey(Object key);

        /**
         * Define the index the object is into the List or array
         *
         * @param index index
         * @return a builder representing the current node
         */
        NodeBuilderDefinedContext atIndex(Integer index);

        /**
         * Add a subNode to the path.
         *
         * <code>name</code> describes a single property. In particular,
         * dot (.) are not allowed.
         *
         * @param name property <code>name</code>
         * @return a builder representing this node
         */
        NodeBuilderCustomizableContext addSubNode(String name);

        /**
         * Return a Path object whose state is represented by
         * the path builder.
         * 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.
         */
        Path build();
    }
}


> Provide a PathBuilder and deprecate the String based property APIs
> ------------------------------------------------------------------
>
>                 Key: BVAL-171
>                 URL: http://opensource.atlassian.com/projects/hibernate/browse/BVAL-171
>             Project: Bean Validation
>          Issue Type: New Feature
>          Components: spec-general
>    Affects Versions: 1.0 proposed final draft
>            Reporter: Emmanuel Bernard
>             Fix For: 1.0 final
>
>


-- 
This message is automatically generated by JIRA.
-
If you think it was sent incorrectly contact one of the administrators: http://opensource.atlassian.com/projects/hibernate/secure/Administrators.jspa
-
For more information on JIRA, see: http://www.atlassian.com/software/jira