Parameters.java

package org.weborganic.furi;


import java.util.Set;


/**
 * An interface to hold a collection of parameters for use during the expansion process.
 * 
 * @author Christophe Lauret
 * @version 5 November 2009
 */
public interface Parameters {

    /**
     * Returns the value for the specified parameter.
     * 
     * @param name The name of the parameter.
     * 
     * @return The value for this parameter or <code>null</code> if not specified.
     */
    String getValue(String name);

    /**
     * Returns the values for the specified parameter.
     * 
     * @param name The name of the parameter.
     * 
     * @return The values for this parameter or <code>null</code> if not specified.
     */
    String[] getValues(String name);

    /**
     * Indicates whether the parameters for the given name has a value.
     * 
     * A parameter has a value if: - it is defined in the parameter list - its array of value has at
     * least one value that is not an empty string
     * 
     * @param name The name of the parameter.
     * 
     * @return <code>true</code> if it has a value; <code>false</code> otherwise.
     */
    boolean exists(String name);

    /**
     * Indicates whether the parameters for the given name has a value.
     * 
     * <p>A parameter has a value if:
     * <ul>
     *   <li>It is defined in the parameter list</li>
     *   <li>Its array of value has at least one value that is not an empty string</li>
     * </ul>
     * 
     * @param name The name of the parameter.
     * 
     * @return <code>true</code> if it has a value;
     *         <code>false</code> otherwise.
     */
    boolean hasValue(String name);

    /**
     * Returns the set of parameter names as an unmodifiable set.
     * 
     * @return The set of parameter names as an unmodifiable set.
     */
    Set<String> names();

    /**
     * Set a parameter with only one value.
     * 
     * @param name The name of the parameter.
     * @param value The value.
     */
    void set(String name, String value);

    /**
     * Set a parameter with only multiple values.
     * 
     * @param name The name of the parameter.
     * @param values The values.
     */
    void set(String name, String[] values);

}