THIS IS A TEST INSTANCE. ALL YOUR CHANGES WILL BE LOST!!!!
...
| Code Block | ||
|---|---|---|
| ||
/**
* 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<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<V> param, V 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 ana immutablemap mapwhich thatshould containscontain value for every parameter that meets one of the following
conditions:* conditions.
*
* 1<p>1) set(...) has been called to set value for this parameter.
*
* 2<p>2) The parameter is a public field of this WithParams instance. This includes fields
* inherited from its interfaces and super-classes.
*
* @return<p>The ansubclass immutablewhich mapimplements ofthis parametersinterface andcould values.
meet this requirement by returning */a
* member default Map<Param<?>, Object> getParamMap() {...}
/**
* A subclass of this interface should override this method to provide a mutable map that can be used to store
* parameter values.
field of the given map type, after having initialized this member field using the
* {@link ParamUtils#initializeMapWithDefaultValues(Map, WithParams)} method.
*
* @return aA map mutablewhich mapmaps fromparameter paramdefinition to paramparameter value.
*/
Map<Param<?>, Object> getUserDefinedParamMapgetParamMap();
}
|
2) We propose to add the following subclasses of Param<?> to simplify the creation of parameters with primitive-typed values (e.g. long, int, boolean).
...
3) We propose to add the following subclasses of ParamValidator<?> to simplify the creation of parameter validators with numerical util method to facilitate the initialization of parameter map with default parameter values.
| Code Block | ||
|---|---|---|
| ||
/** *Utility Factory methods for reading and writing stages. */ public class ParamUtils { /** * Updates the paramMap with default values of all public Param-typed fields of the given * instance. A parameter's value will not be updated if this parameter is already found in the * map. * * <p>Note: This method should be called after all public Param-typed fields of the given * instance have been defined. A good choice is to call this method in the constructor of the * given instance. */ public static void initializeMapWithDefaultValues(Map<Param<?>, Object> paramMap, WithParams<?> instance) {...} } |
4) We propose to add the following subclasses of ParamValidator<?> to simplify the creation of parameter validators with numerical values.
| Code Block | ||
|---|---|---|
| ||
/** * Factory methods for common validation functions. The numerical methods only support Int, Long, * Float, and Double. */ public class ParamValidators { // Always return true. public static <T> 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 lowerBoundcommon validation functions. The numerical methods only support Int, Long, * Float, and Double. */ public class ParamValidators { // Always return true. public static <T> ParamValidator<T> alwaysTruegtEq(double lowerBound) {...} // Check if the parameter value is greaterless than lowerBoundupperBound. public static <T> ParamValidator<T> gtlt(double lowerBoundupperBound) {...} // Check if the parameter value is greaterless than or equal to lowerBoundupperBound. public static <T> ParamValidator<T> gtEqltEq(double lowerBoundupperBound) {...} //** * Check if the parameter value is less than in the range from lowerBound to upperBound. * * @param lowerInclusive publicif statictrue, <T>range ParamValidator<T>includes lt(double upperBound) {...} value = lowerBound * //@param CheckupperInclusive if the parametertrue, range includes value is= lessupperBound than or equal to upperBound.*/ public static <T> ParamValidator<T> ltEqinRange(double lowerBound, double upperBound, boolean lowerInclusive, boolean upperInclusive) {...} //** * Check if the parameter value is in the range from [lowerBound, to upperBound]. * * @param lowerInclusive if true,public rangestatic includes<T> valueParamValidator<T> =inRange(double lowerBound , double upperBound) {...} * @param// upperInclusiveCheck if true,the rangeparameter includes value =is upperBound in the array of allowed */values. public static <T> ParamValidator<T> inRange(double lowerBound, double upperBound, boolean lowerInclusive, boolean upperInclusive inArray(T... allowed) {...} // Check if the parameter value is in the range [lowerBound, upperBound]not null. public static <T> ParamValidator<T> inRange(double lowerBound, double upperBoundnotNull() {...} } |
Proposed Changes
...
| Code Block | ||
|---|---|---|
| ||
// An example interface that provides pre-defined parameters.
public interface MyParams<T> extends WithParams<T> {
Param<Boolean> BOOLEAN_PARAM = new BooleanParam("booleanParam", "Description", false);
Param<Integer> INT_PARAM = new IntParam("intParam", "Description", 1, ParamValidators.lt(100));
Param<Long> LONG_PARAM = new LongParam("longParam", "Description", 2L, ParamValidators.lt(100));
Param<Integer[]> INT_ARRAY_PARAM = new IntArrayParam("intArrayParam", "Description", new Integer[] {3, 4});
Param<String[]> STRING_ARRAY_PARAM = new StringArrayParam("stringArrayParam", "Description", new String[] {"5", "6"});
}
// An example stage class that defines its own parameters and also inherits parameters from MyParams.
public static class MyStage implements Stage<MyStage>, MyParams<MyStage> {
private final Map<Param<?>, Object> paramMap = new HashMap<>();
Param<Integer> extraIntParam = new IntParam("extraIntParam", "Description", 100, ParamValidator.ALWAYS_TRUE);
public MyStage() {}
@Override
public Map<Param<?>, Object> getUserDefinedParamMap() {
return paramMap ParamUtils.initializeMapWithDefaultValues(paramMap, this);
}
// Skipped implementation of save() and load().
}
public static void main(String[] args) {
MyStage stage = new MyStage();
// Gets the value of a parameter defined in the MyParams interface without first setting its value.
Long[] longArrayValue = stage.get(MyParams.LONG_ARRAY_PARAM);
// Sets and gets value of a parameter defined in the MyParams interface.
stage.set(MyParams.INT_PARAM, 1);
Integer intValue = stage.get(MyParams.INT_PARAM);
// Sets and gets value of a parameter defined in the MyStage class.
stage.set(stage.extraIntParam, 2);
Integer extraIntValue = stage.get(stage.extraIntParam);
// Sets and gets value of a parameter identified by its name string.
Param<?> longParam = stage.getParam("longParam");
stage.set(longParam, 3L);
Long longValue = (Long) stage.get(stage.getParam("longParam"));
} |
...