Parameters
Date: 2016-02-08

org.apache.avalon.framework.parameters

## Class Parameters

- java.lang.Object
- - org.apache.avalon.framework.parameters.Parameters

- All Implemented Interfaces:
    java.io.Serializable

      public class Parameters
      extends java.lang.Object
      implements java.io.Serializable

  The `Parameters` class represents a set of key-value pairs.

  The `Parameters` object provides a mechanism to obtain values based on a `String` name. There are convenience methods that allow you to use defaults if the value does not exist, as well as obtain the value in any of the same formats that are in the `Configuration` interface.

  While there are similarities between the `Parameters` object and the java.util.Properties object, there are some important semantic differences. First, `Parameters` are read-only. Second, `Parameters` are easily derived from `Configuration` objects. Lastly, the `Parameters` object is derived from XML fragments that look like this:

        <parameter name="param-name" value="param-value" />

  Note: this class is not thread safe by default. If you require thread safety please synchronize write access to this class to prevent potential data corruption.

  See Also:
    Serialized Form

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static Parameters` | `EMPTY_PARAMETERS` Empty Parameters object

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `Parameters()`

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `protected void` | `checkWriteable()` Checks is this `Parameters` object is writeable.
    `static Parameters` | `fromConfiguration(Configuration configuration)` Create a `Parameters` object from a `Configuration` object.
    `static Parameters` | `fromConfiguration(Configuration configuration, java.lang.String elementName)` Create a `Parameters` object from a `Configuration` object using the supplied element name.
    `static Parameters` | `fromProperties(java.util.Properties properties)` Create a `Parameters` object from a `Properties` object.
    `java.lang.String[]` | `getNames()` Retrieve an array of all parameter names.
    `java.lang.String` | `getParameter(java.lang.String name)` Retrieve the `String` value of the specified parameter.
    `java.lang.String` | `getParameter(java.lang.String name, java.lang.String defaultValue)` Retrieve the `String` value of the specified parameter.
    `boolean` | `getParameterAsBoolean(java.lang.String name)` Retrieve the `boolean` value of the specified parameter.
    `boolean` | `getParameterAsBoolean(java.lang.String name, boolean defaultValue)` Retrieve the `boolean` value of the specified parameter.
    `float` | `getParameterAsFloat(java.lang.String name)` Retrieve the `float` value of the specified parameter.
    `float` | `getParameterAsFloat(java.lang.String name, float defaultValue)` Retrieve the `float` value of the specified parameter.
    `int` | `getParameterAsInteger(java.lang.String name)` Retrieve the `int` value of the specified parameter.
    `int` | `getParameterAsInteger(java.lang.String name, int defaultValue)` Retrieve the `int` value of the specified parameter.
    `long` | `getParameterAsLong(java.lang.String name)` Retrieve the `long` value of the specified parameter.
    `long` | `getParameterAsLong(java.lang.String name, long defaultValue)` Retrieve the `long` value of the specified parameter.
    `java.util.Iterator` | `getParameterNames()` Deprecated. Use getNames() instead
    `boolean` | `isParameter(java.lang.String name)` Test if the specified parameter can be retrieved.
    `void` | `makeReadOnly()` Make this Parameters read-only so that it will throw a `IllegalStateException` if someone tries to modify it.
    `Parameters` | `merge(Parameters other)` Merge parameters from another `Parameters` instance into this.
    `void` | `removeParameter(java.lang.String name)` Remove a parameter from the parameters object
    `java.lang.String` | `setParameter(java.lang.String name, java.lang.String value)` Set the `String` value of a specified parameter.
    `static java.util.Properties` | `toProperties(Parameters params)` Creates a `java.util.Properties` object from an Avalon Parameters object.

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Field Detail

    - #### EMPTY_PARAMETERS

          public static final Parameters EMPTY_PARAMETERS

      Empty Parameters object
      Since:
        4.1.2

  - ### Constructor Detail

    - #### Parameters

          public Parameters()

  - ### Method Detail

    - #### setParameter

          public java.lang.String setParameter(java.lang.String name,
                                      java.lang.String value)
                                        throws java.lang.IllegalStateException

      Set the `String` value of a specified parameter.

      If the specified value is null the parameter is removed.
      Parameters:
        `name` - a `String` value
        `value` - a `String` value
      Returns:
        The previous value of the parameter or null.
      Throws:
        `java.lang.IllegalStateException` - if the Parameters object is read-only

    - #### removeParameter

          public void removeParameter(java.lang.String name)

      Remove a parameter from the parameters object
      Parameters:
        `name` - a `String` value
      Since:
        4.1

    - #### getParameterNames

          public java.util.Iterator getParameterNames()

      Deprecated. Use getNames() instead
      Return an `Iterator` view of all parameter names.
      Returns:
        a iterator of parameter names

    - #### getNames

          public java.lang.String[] getNames()

      Retrieve an array of all parameter names.
      Returns:
        the parameters names

    - #### isParameter

          public boolean isParameter(java.lang.String name)

      Test if the specified parameter can be retrieved.
      Parameters:
        `name` - the parameter name
      Returns:
        true if parameter is a name

    - #### getParameter

          public java.lang.String getParameter(java.lang.String name)
                                        throws ParameterException

      Retrieve the `String` value of the specified parameter.

      If the specified parameter cannot be found, an exception is thrown.
      Parameters:
        `name` - the name of parameter
      Returns:
        the value of parameter
      Throws:
        `ParameterException` - if the specified parameter cannot be found

    - #### getParameter

          public java.lang.String getParameter(java.lang.String name,
                                      java.lang.String defaultValue)

      Retrieve the `String` value of the specified parameter.

      If the specified parameter cannot be found, `defaultValue` is returned.
      Parameters:
        `name` - the name of parameter
        `defaultValue` - the default value, returned if parameter does not exist or parameter's name is null
      Returns:
        the value of parameter

    - #### getParameterAsInteger

          public int getParameterAsInteger(java.lang.String name)
                                    throws ParameterException

      Retrieve the `int` value of the specified parameter.

      If the specified parameter cannot be found, an exception is thrown. Hexadecimal numbers begin with 0x, Octal numbers begin with 0o and binary numbers begin with 0b, all other values are assumed to be decimal.
      Parameters:
        `name` - the name of parameter
      Returns:
        the integer parameter type
      Throws:
        `ParameterException` - if the specified parameter cannot be found or is not an Integer value

    - #### getParameterAsInteger

          public int getParameterAsInteger(java.lang.String name,
                                  int defaultValue)

      Retrieve the `int` value of the specified parameter.

      If the specified parameter cannot be found, `defaultValue` is returned. Hexadecimal numbers begin with 0x, Octal numbers begin with 0o and binary numbers begin with 0b, all other values are assumed to be decimal.
      Parameters:
        `name` - the name of parameter
        `defaultValue` - value returned if parameter does not exist or is of wrong type
      Returns:
        the integer parameter type

    - #### getParameterAsLong

          public long getParameterAsLong(java.lang.String name)
                                  throws ParameterException

      Retrieve the `long` value of the specified parameter.

      If the specified parameter cannot be found, an exception is thrown. Hexadecimal numbers begin with 0x, Octal numbers begin with 0o and binary numbers begin with 0b, all other values are assumed to be decimal.
      Parameters:
        `name` - the name of parameter
      Returns:
        the long parameter type
      Throws:
        `ParameterException` - if the specified parameter cannot be found or is not a Long value.

    - #### getParameterAsLong

          public long getParameterAsLong(java.lang.String name,
                                long defaultValue)

      Retrieve the `long` value of the specified parameter.

      If the specified parameter cannot be found, `defaultValue` is returned. Hexadecimal numbers begin with 0x, Octal numbers begin with 0o and binary numbers begin with 0b, all other values are assumed to be decimal.
      Parameters:
        `name` - the name of parameter
        `defaultValue` - value returned if parameter does not exist or is of wrong type
      Returns:
        the long parameter type

    - #### getParameterAsFloat

          public float getParameterAsFloat(java.lang.String name)
                                    throws ParameterException

      Retrieve the `float` value of the specified parameter.

      If the specified parameter cannot be found, an exception is thrown.
      Parameters:
        `name` - the parameter name
      Returns:
        the value
      Throws:
        `ParameterException` - if the specified parameter cannot be found or is not a Float value

    - #### getParameterAsFloat

          public float getParameterAsFloat(java.lang.String name,
                                  float defaultValue)

      Retrieve the `float` value of the specified parameter.

      If the specified parameter cannot be found, `defaultValue` is returned.
      Parameters:
        `name` - the parameter name
        `defaultValue` - the default value if parameter does not exist or is of wrong type
      Returns:
        the value

    - #### getParameterAsBoolean

          public boolean getParameterAsBoolean(java.lang.String name)
                                        throws ParameterException

      Retrieve the `boolean` value of the specified parameter.

      If the specified parameter cannot be found, an exception is thrown.
      Parameters:
        `name` - the parameter name
      Returns:
        the value
      Throws:
        `ParameterException` - if an error occurs
        `ParameterException`

    - #### getParameterAsBoolean

          public boolean getParameterAsBoolean(java.lang.String name,
                                      boolean defaultValue)

      Retrieve the `boolean` value of the specified parameter.

      If the specified parameter cannot be found, `defaultValue` is returned.
      Parameters:
        `name` - the parameter name
        `defaultValue` - the default value if parameter does not exist or is of wrong type
      Returns:
        the value

    - #### merge

          public Parameters merge(Parameters other)

      Merge parameters from another `Parameters` instance into this.
      Parameters:
        `other` - the other Parameters
      Returns:
        This `Parameters` instance.

    - #### makeReadOnly

          public void makeReadOnly()

      Make this Parameters read-only so that it will throw a `IllegalStateException` if someone tries to modify it.

    - #### checkWriteable

          protected final void checkWriteable()
                                       throws java.lang.IllegalStateException

      Checks is this `Parameters` object is writeable.
      Throws:
        `java.lang.IllegalStateException` - if this `Parameters` object is read-only

    - #### fromConfiguration

          public static Parameters fromConfiguration(Configuration configuration)
                                              throws ConfigurationException

      Create a `Parameters` object from a `Configuration` object. This acts exactly like the following method call:

               Parameters.fromConfiguration(configuration, "parameter");

      Parameters:
        `configuration` - the Configuration
      Returns:
        This `Parameters` instance.
      Throws:
        `ConfigurationException` - if an error occurs

    - #### fromConfiguration

          public static Parameters fromConfiguration(Configuration configuration,
                                     java.lang.String elementName)
                                              throws ConfigurationException

      Create a `Parameters` object from a `Configuration` object using the supplied element name.
      Parameters:
        `configuration` - the Configuration
        `elementName` - the element name for the parameters
      Returns:
        This `Parameters` instance.
      Throws:
        `ConfigurationException` - if an error occurs
      Since:
        4.1

    - #### fromProperties

          public static Parameters fromProperties(java.util.Properties properties)

      Create a `Parameters` object from a `Properties` object.
      Parameters:
        `properties` - the Properties
      Returns:
        This `Parameters` instance.

    - #### toProperties

          public static java.util.Properties toProperties(Parameters params)

      Creates a `java.util.Properties` object from an Avalon Parameters object.
      Parameters:
        `params` - a `Parameters` instance
      Returns:
        a `Properties` instance