Package com.lmax.simpledsl.api

Interface DslValues

  • All Known Subinterfaces:
    DslParams, RepeatingGroup
    public interface DslValues
    Base class for value containers such as DslParams and RepeatingGroup.

    Provides a range of methods to access the supplied values in a convenient form such as parsed into an int.

    • Method Summary

      All Methods Instance Methods Abstract Methods Default Methods 
      Modifier and Type Method Description
      DslArg[] getParams()
      Get the supported parameters.
      boolean hasParam​(java.lang.String name)
      Determine if a parameter is defined.
      default boolean hasParamAndValue​(java.lang.String name)
      Determine if a parameter is defined and has a value.
      boolean hasValue​(java.lang.String name)
      Determine if a value was supplied for a parameter.
      java.lang.String value​(java.lang.String name)
      Retrieve the value supplied for a parameter.
      default <T extends java.lang.Enum<T>>
      T      		 valueAs​(java.lang.String name, java.lang.Class<T> enumType)
      Retrieve the value supplied for a parameter, mapping it to the specified Enum.
      default <T> T valueAs​(java.lang.String name, java.util.function.Function<java.lang.String,​T> mapper)
      Retrieve the value supplied for a parameter, mapping it using the specified function.
      default java.math.BigDecimal valueAsBigDecimal​(java.lang.String name)
      Retrieve the value supplied for a parameter as a BigDecimal.
      default boolean valueAsBoolean​(java.lang.String name)
      Retrieve the value supplied for a parameter as a boolean.
      default double valueAsDouble​(java.lang.String name)
      Retrieve the value supplied for a parameter as a double.
      default int valueAsInt​(java.lang.String name)
      Retrieve the value supplied for a parameter as an int.
      default long valueAsLong​(java.lang.String name)
      Retrieve the value supplied for a parameter as a long.
      default java.util.Optional<java.lang.String> valueAsOptional​(java.lang.String name)
      Retrieve the value supplied for a parameter as an Optional.
      default <T> java.util.Optional<T> valueAsOptionalOf​(java.lang.String name, java.util.function.Function<java.lang.String,​T> mapper)
      Retrieve the value supplied for a parameter as an Optional.
      default java.lang.String valueAsParam​(java.lang.String name)
      Retrieve the value supplied for a parameter formatted as a parameter.
      default java.lang.String valueAsParamNamed​(java.lang.String oldParamName, java.lang.String newParamName)
      Retrieve the value supplied for a parameter formatted as a parameter with the given name.
      java.lang.String[] values​(java.lang.String name)
      Retrieve the values supplied for a parameter as an array.
      default <T extends java.lang.Enum<T>>
      T[]      		 valuesAs​(java.lang.String name, java.lang.Class<T> enumType)
      Retrieve the values supplied for a parameter, mapping each provided value using the specified function and returning an array of these values.
      default <T> T[] valuesAs​(java.lang.String name, java.lang.Class<T> type, java.util.function.Function<java.lang.String,​T> mapper)
      Retrieve the values supplied for a parameter, mapping each provided value using the specified function and returning a Stream of these values.
      default <T> java.lang.Object[] valuesAs​(java.lang.String name, java.util.function.Function<java.lang.String,​T> mapper)
      Retrieve the values supplied for a parameter, mapping each provided value using the specified function and returning a Stream of these values.
      default java.math.BigDecimal[] valuesAsBigDecimals​(java.lang.String name)
      Retrieve the values supplied for a parameter as a BigDecimal array.
      default double[] valuesAsDoubles​(java.lang.String name)
      Retrieve the values supplied for a parameter as a double array.
      default int[] valuesAsInts​(java.lang.String name)
      Retrieve the values supplied for a parameter as an int array.
      default java.util.List<java.lang.String> valuesAsList​(java.lang.String name)
      Retrieve the values supplied for a parameter as a List.
      default <T> java.util.List<T> valuesAsListOf​(java.lang.String name, java.util.function.Function<java.lang.String,​T> mapper)
      Retrieve the values supplied for a parameter as a List.
      default long[] valuesAsLongs​(java.lang.String name)
      Retrieve the values supplied for a parameter as a long array.
      default java.util.Optional<java.util.List<java.lang.String>> valuesAsOptional​(java.lang.String name)
      Retrieve the values supplied for a parameter as an Optional List.
      default java.util.OptionalDouble valuesAsOptionalDouble​(java.lang.String name)
      Retrieve the values supplied for a parameter as an OptionalDouble.
      default java.util.OptionalInt valuesAsOptionalInt​(java.lang.String name)
      Retrieve the values supplied for a parameter as an OptionalInt.
      default java.util.OptionalLong valuesAsOptionalLong​(java.lang.String name)
      Retrieve the values supplied for a parameter as an OptionalLong.

    • Method Detail

      • hasValue

        boolean hasValue​(java.lang.String name)
        Determine if a value was supplied for a parameter.

        Returns true when the parameter is supplied with an empty value.

        Parameters:
        name - the name of the parameter.
        Returns:
        true if the parameter was supplied, otherwise false.
        Throws:
        java.lang.IllegalArgumentException - if name does not match the name of a supported parameter.

      • hasParam

        boolean hasParam​(java.lang.String name)
        Determine if a parameter is defined.

        Returns true when the parameter is defined.

        Parameters:
        name - the name of the parameter.
        Returns:
        true if the parameter is defined, otherwise false.

      • value

        java.lang.String value​(java.lang.String name)
        Retrieve the value supplied for a parameter.

        May return null if the parameter is optional and a value has not been supplied.

        Parameters:
        name - the name of the parameter.
        Returns:
        the value supplied for that parameter.
        Throws:
        java.lang.IllegalArgumentException - if name does not match the name of a supported parameter or if the parameter supports multiple values.

      • values

        java.lang.String[] values​(java.lang.String name)
        Retrieve the values supplied for a parameter as an array.

        Returns an empty array if the parameter is optional and a value has not been supplied.

        Parameters:
        name - the name of the parameter.
        Returns:
        an array of values supplied for the parameter.
        Throws:
        java.lang.IllegalArgumentException - if name does not match the name of a supported parameter.

      • hasParamAndValue

        default boolean hasParamAndValue​(java.lang.String name)
        Determine if a parameter is defined and has a value.

        Returns true when the parameter is defined and supplied with an empty value.

        Parameters:
        name - the name of the parameter.
        Returns:
        true if the parameter is defined and has a value, otherwise false.

      • valueAs

        default <T> T valueAs​(java.lang.String name,
                      java.util.function.Function<java.lang.String,​T> mapper)
        Retrieve the value supplied for a parameter, mapping it using the specified function.
        Type Parameters:
        T - the return type of mapper.
        Parameters:
        name - the name of the parameter.
        mapper - the mapping Function.
        Returns:
        the value supplied for that parameter.
        Throws:
        java.lang.IllegalArgumentException - if name does not match the name of a supported parameter or if the parameter supports multiple values.

      • valueAs

        default <T extends java.lang.Enum<T>> T valueAs​(java.lang.String name,
                                                java.lang.Class<T> enumType)
        Retrieve the value supplied for a parameter, mapping it to the specified Enum.
        Type Parameters:
        T - the Enum type.
        Parameters:
        name - the name of the parameter.
        enumType - the Enum type.
        Returns:
        the value supplied for that parameter.
        Throws:
        java.lang.IllegalArgumentException - if name does not match the name of a supported parameter or if the parameter supports multiple values.

      • valuesAs

        default <T> java.lang.Object[] valuesAs​(java.lang.String name,
                                        java.util.function.Function<java.lang.String,​T> mapper)
        Retrieve the values supplied for a parameter, mapping each provided value using the specified function and returning a Stream of these values.

        Returns an empty Stream if the parameter is optional and a value has not been supplied.

        Type Parameters:
        T - the return type of mapper.
        Parameters:
        name - the name of the parameter.
        mapper - the mapping Function.
        Returns:
        a Stream of values supplied for the parameter.
        Throws:
        java.lang.IllegalArgumentException - if name does not match the name of a supported parameter.

      • valuesAs

        default <T> T[] valuesAs​(java.lang.String name,
                         java.lang.Class<T> type,
                         java.util.function.Function<java.lang.String,​T> mapper)
        Retrieve the values supplied for a parameter, mapping each provided value using the specified function and returning a Stream of these values.

        Returns an empty Stream if the parameter is optional and a value has not been supplied.

        Type Parameters:
        T - the return type of mapper.
        Parameters:
        name - the name of the parameter.
        type - the return type of mapper
        mapper - the mapping Function.
        Returns:
        a Stream of values supplied for the parameter.
        Throws:
        java.lang.IllegalArgumentException - if name does not match the name of a supported parameter.

      • valuesAs

        default <T extends java.lang.Enum<T>> T[] valuesAs​(java.lang.String name,
                                                   java.lang.Class<T> enumType)
        Retrieve the values supplied for a parameter, mapping each provided value using the specified function and returning an array of these values.

        Returns an empty Stream if the parameter is optional and a value has not been supplied.

        Type Parameters:
        T - the Enum type.
        Parameters:
        name - the name of the parameter.
        enumType - the Enum type.
        Returns:
        a Stream of values supplied for the parameter.
        Throws:
        java.lang.IllegalArgumentException - if name does not match the name of a supported parameter.

      • valueAsOptional

        default java.util.Optional<java.lang.String> valueAsOptional​(java.lang.String name)
        Retrieve the value supplied for a parameter as an Optional.

        The optional will be empty if the parameter was not supplied.

        Parameters:
        name - the name of the parameter
        Returns:
        an Optional containing the value supplied for the parameter, if any.
        Throws:
        java.lang.IllegalArgumentException - if name does not match the name of a supported parameter or if the parameter supports multiple values.

      • valueAsOptionalOf

        default <T> java.util.Optional<T> valueAsOptionalOf​(java.lang.String name,
                                                    java.util.function.Function<java.lang.String,​T> mapper)
        Retrieve the value supplied for a parameter as an Optional.

        The optional will be empty if the parameter was not supplied.

        Type Parameters:
        T - the return type of mapper.
        Parameters:
        name - the name of the parameter.
        mapper - the mapping Function.
        Returns:
        an Optional containing the value supplied for the parameter, if any.
        Throws:
        java.lang.IllegalArgumentException - if name does not match the name of a supported parameter or if the parameter supports multiple values.

      • valueAsBoolean

        default boolean valueAsBoolean​(java.lang.String name)
        Retrieve the value supplied for a parameter as a boolean.

        The value is parsed using Boolean.parseBoolean(String).

        Parameters:
        name - the name of the parameter.
        Returns:
        the value supplied for that parameter.
        Throws:
        java.lang.IllegalArgumentException - if name does not match the name of a supported parameter or if the parameter supports multiple values.

      • valueAsInt

        default int valueAsInt​(java.lang.String name)
        Retrieve the value supplied for a parameter as an int.
        Parameters:
        name - the name of the parameter.
        Returns:
        the value supplied for that parameter.
        Throws:
        java.lang.IllegalArgumentException - if name does not match the name of a supported parameter or if the parameter supports multiple values.
        java.lang.NumberFormatException - if the supplied value can't be parsed as an int (including because it wasn't supplied).

      • valueAsLong

        default long valueAsLong​(java.lang.String name)
        Retrieve the value supplied for a parameter as a long.
        Parameters:
        name - the name of the parameter.
        Returns:
        the value supplied for that parameter.
        Throws:
        java.lang.IllegalArgumentException - if name does not match the name of a supported parameter or if the parameter supports multiple values.
        java.lang.NumberFormatException - if the supplied value can't be parsed as a long (including because it wasn't supplied).

      • valueAsDouble

        default double valueAsDouble​(java.lang.String name)
        Retrieve the value supplied for a parameter as a double.

        The value is parsed using Double.parseDouble(String).

        Parameters:
        name - the name of the parameter.
        Returns:
        the value supplied for that parameter.
        Throws:
        java.lang.IllegalArgumentException - if name does not match the name of a supported parameter or if the parameter supports multiple values.
        java.lang.NumberFormatException - if the supplied value can't be parsed as a double

      • valueAsBigDecimal

        default java.math.BigDecimal valueAsBigDecimal​(java.lang.String name)
        Retrieve the value supplied for a parameter as a BigDecimal.

        The value is parsed using BigDecimal(String).

        Parameters:
        name - the name of the parameter.
        Returns:
        the value supplied for that parameter.
        Throws:
        java.lang.IllegalArgumentException - if name does not match the name of a supported parameter or if the parameter supports multiple values.
        java.lang.NumberFormatException - if the supplied value can't be parsed as a BigDecimal

      • valueAsParam

        default java.lang.String valueAsParam​(java.lang.String name)
        Retrieve the value supplied for a parameter formatted as a parameter. For example, if the parameter user was given the value jenny, then valueAsParam("user") would return user: jenny.

        This is useful when reusing DSL methods to build higher level functions. e.g. 

        
   public void createUserAndLogin(String... args) {
     DslParams params = new DslParams(args,
                                      new RequiredParam("user"),
                                      new RequiredParam("accountType"));
     createUser(params.valueAsParam("user"), "password: password");
     login(params.valueAsParam("user"), "password: password");
   }
        Parameters:
        name - the name of the parameter.
        Returns:
        the value supplied for that parameter, formatted as a parameter ready to pass on to another method that uses Simple-DSL.
        Throws:
        java.lang.IllegalArgumentException - if name does not match the name of a supported parameter or if the parameter supports multiple values.

      • valueAsParamNamed

        default java.lang.String valueAsParamNamed​(java.lang.String oldParamName,
                                           java.lang.String newParamName)
        Retrieve the value supplied for a parameter formatted as a parameter with the given name. For example, if the parameter user was given the value jenny, then valueAsParamNamed("user", "person") would return person: jenny.

        This is useful when reusing DSL methods to build higher level functions. e.g. 

        
   public void createUserAndLogin(String... args) {
     DslParams params = new DslParams(args,
                                      new RequiredParam("user"),
                                      new RequiredParam("accountType"));
     generateRandomUser(params.valueAsParamNamed("user", "rememberUserAs"));
     login(params.valueAsParam("user"), "password: password");
   }
        Parameters:
        oldParamName - the name of the parameter.
        newParamName - the new name of the parameter.
        Returns:
        the value supplied for that parameter, formatted as a parameter ready to pass on to another method that uses Simple-DSL.
        Throws:
        java.lang.IllegalArgumentException - if name does not match the name of a supported parameter or if the parameter supports multiple values.

      • valuesAsList

        default java.util.List<java.lang.String> valuesAsList​(java.lang.String name)
        Retrieve the values supplied for a parameter as a List. Returns an empty list if the parameter is optional and a value has not been supplied.
        Parameters:
        name - the name of the parameter.
        Returns:
        a List of values supplied for the parameter.
        Throws:
        java.lang.IllegalArgumentException - if name does not match the name of a supported parameter.

      • valuesAsListOf

        default <T> java.util.List<T> valuesAsListOf​(java.lang.String name,
                                             java.util.function.Function<java.lang.String,​T> mapper)
        Retrieve the values supplied for a parameter as a List. Returns an empty list if the parameter is optional and a value has not been supplied.
        Type Parameters:
        T - the return type of mapper.
        Parameters:
        name - the name of the parameter.
        mapper - the mapping Function.
        Returns:
        a List of values supplied for the parameter.
        Throws:
        java.lang.IllegalArgumentException - if name does not match the name of a supported parameter.

      • valuesAsOptional

        default java.util.Optional<java.util.List<java.lang.String>> valuesAsOptional​(java.lang.String name)
        Retrieve the values supplied for a parameter as an Optional List.

        Returns an empty Optional if the parameter is optional and a value has not been supplied.

        In most cases valuesAsList(java.lang.String) is the more suitable method. This variant is useful if there is an important difference between a parameter being set to an empty list vs not being supplied.

        For example, a test that checks the properties of a user may have an optional check for the roles assigned to that user: 

        
     DslParams params = new DslParams(args,
                                      new RequiredParam("user"),
                                      new OptionalParam("suspended"),
                                      new OptionalParam("roles").setAllowMultipleValues());
     params.valuesAsOptional("roles").ifPresent(roles -> getDriver().verifyRoles(params.value("user"), roles));

        It's also possible to achieve this distinction by checking the parameter was supplied using hasValue(java.lang.String).

        Parameters:
        name - the name of the parameter.
        Returns:
        a List of values supplied for the parameter.
        Throws:
        java.lang.IllegalArgumentException - if name does not match the name of a supported parameter.

      • valuesAsOptionalInt

        default java.util.OptionalInt valuesAsOptionalInt​(java.lang.String name)
        Retrieve the values supplied for a parameter as an OptionalInt.

        Returns an empty Optional if the parameter is optional and a value has not been supplied.

        Parameters:
        name - the name of the parameter.
        Returns:
        the value of the parameter, or empty
        Throws:
        java.lang.IllegalArgumentException - if name does not match the name of a supported parameter.

      • valuesAsOptionalLong

        default java.util.OptionalLong valuesAsOptionalLong​(java.lang.String name)
        Retrieve the values supplied for a parameter as an OptionalLong.

        Returns an empty Optional if the parameter is optional and a value has not been supplied.

        Parameters:
        name - the name of the parameter.
        Returns:
        the value of the parameter, or empty
        Throws:
        java.lang.IllegalArgumentException - if name does not match the name of a supported parameter.

      • valuesAsOptionalDouble

        default java.util.OptionalDouble valuesAsOptionalDouble​(java.lang.String name)
        Retrieve the values supplied for a parameter as an OptionalDouble.

        Returns an empty Optional if the parameter is optional and a value has not been supplied.

        Parameters:
        name - the name of the parameter.
        Returns:
        the value of the parameter, or empty
        Throws:
        java.lang.IllegalArgumentException - if name does not match the name of a supported parameter.

      • valuesAsInts

        default int[] valuesAsInts​(java.lang.String name)
        Retrieve the values supplied for a parameter as an int array.

        Returns an empty array if the parameter is optional and a value has not been supplied.

        Parameters:
        name - the name of the parameter.
        Returns:
        an array of values supplied for the parameter.
        Throws:
        java.lang.IllegalArgumentException - if name does not match the name of a supported parameter.
        java.lang.NumberFormatException - if any of the supplied values can not be parsed as an int.

      • valuesAsLongs

        default long[] valuesAsLongs​(java.lang.String name)
        Retrieve the values supplied for a parameter as a long array.

        Returns an empty array if the parameter is optional and a value has not been supplied.

        Parameters:
        name - the name of the parameter.
        Returns:
        an array of values supplied for the parameter.
        Throws:
        java.lang.IllegalArgumentException - if name does not match the name of a supported parameter.
        java.lang.NumberFormatException - if any of the supplied values can not be parsed as an long.

      • valuesAsDoubles

        default double[] valuesAsDoubles​(java.lang.String name)
        Retrieve the values supplied for a parameter as a double array.

        Returns an empty array if the parameter is optional and a value has not been supplied.

        Parameters:
        name - the name of the parameter.
        Returns:
        an array of values supplied for the parameter.
        Throws:
        java.lang.IllegalArgumentException - if name does not match the name of a supported parameter.
        java.lang.NumberFormatException - if any of the supplied values can not be parsed as an double.

      • valuesAsBigDecimals

        default java.math.BigDecimal[] valuesAsBigDecimals​(java.lang.String name)
        Retrieve the values supplied for a parameter as a BigDecimal array.

        Returns an empty array if the parameter is optional and a value has not been supplied.

        Parameters:
        name - the name of the parameter.
        Returns:
        an array of values supplied for the parameter.
        Throws:
        java.lang.IllegalArgumentException - if name does not match the name of a supported parameter.
        java.lang.NumberFormatException - if any of the supplied values can not be parsed as an BigDecimal.

      • getParams

        DslArg[] getParams()
        Get the supported parameters. Supplied values will have been parsed into the parameters.
        Returns:
        the array of DslArgs supplied to the constructor.