Page History

/**
 * Definition of a parameter, including name, class, description, default value and the validator.
 *
 * @param <T> The type of the parameter value
 */
public class Param<T> implements Serializable {
    public final String name;
    public final Class<?>Class<T> clazz;
    public final String description;
    public final T defaultValue;
    public final ParamValidator<T> validator;

    public Param(String name, Class<T> clazz, String description, T defaultValue, ParamValidator<T> validator) {...}

    // Encodes the given object into a json-formatted string
    public String jsonEncode(ObjectT value) throws IOException {...}

    // Decodes the json-formatted string into an object of the given type.
    public T jsonDecode(String json) throws IOException {...}
}

/**
 * Interface for classes that take parameters. It provides APIs to set and get parameters.
 *
 * @param <T> The class type of WithParams implementation itself.
 */
@PublicEvolving
public interface WithParams<T> {
    /** Gets a param by name. */
    default <V> Param<?>Param<V> getParam(String name) {...}

    /**
     * Sets the value of the given parameter in the user-defined map.
     *
     * @param param the parameter
     * @param value the value
     * @return the WithParams instance itself
     */
    default <V> T set(Param<?>Param<V> param, ObjectV value) {...}

    /**
     * Gets the value of the given parameter. Returns the value from the user-defined map if set(...) has been
     * explicitly called to set value for this parameter. Otherwise, returns the default value from the definition of
     * this parameter.
     *
     * @param param the parameter
     * @param <V> the type of the parameter
     * @return the value of the parameter
     */
    default <V> V get(Param<V> param) {...}

    /**
     * Returns an immutable map that contains value for every parameter that meets one of the following conditions:
     * 1) set(...) has been called to set value for this parameter.
     * 2) The parameter is a field of this WithParams instance. This includes public, protected and private fields. And
     * this also includes fields inherited from its interfaces and super-classes.
     *
     * @return an immutable map of parameters and values.
     */
    default Map<Param<?>, Object> getParamMap() {...}

    /**
     * Returns a mutable map that can be used to set values for parameters. A subclass of this interface should override
     * this method if it wants to support users to set non-default parameter values.
     *
     * @return a mutable map of parameters and value overrides.
     */
    default Map<Param<?>, Object> getUserDefinedParamMap() {
        return null;
    }
}

/**
 * Factory methods for common validation functions. The numerical methods only support Int, Long,
 * Float, and Double.
 */
public class ParamValidators {
    // Always return true.
    public static final<T> ParamValidator<?> ALWAYS_TRUE = (Object value) -> true;ParamValidator<T> alwaysTrue() {...}

    // Check if the parameter value is greater than lowerBound.
    public static <T> ParamValidator<T> gt(double lowerBound) {...}

    // Check if the parameter value is greater than or equal to lowerBound.
    public static <T> ParamValidator<T> gtEq(double lowerBound) {...}

    // Check if the parameter value is less than upperBound.
    public static <T> ParamValidator<T> lt(double upperBound) {...}

    // Check if the parameter value is less than or equal to upperBound.
    public static <T> ParamValidator<T> ltEq(double upperBound) {...}

    /**
     * Check if the parameter value is in the range from lowerBound to upperBound.
     *
     * @param lowerInclusive if true, range includes value = lowerBound
     * @param upperInclusive if true, range includes value = upperBound
     */
    public static <T> ParamValidator<T> inRange(double lowerBound, double upperBound, boolean lowerInclusive, boolean upperInclusive) {...}

    // Check if the parameter value is in the range [lowerBound, upperBound].
    public static <T> ParamValidator<T> inRange(double lowerBound, double upperBound) {...}
}