Package org.apache.avalon.framework.parameters

Class Parameters

java.lang.Object
org.apache.avalon.framework.parameters.Parameters
All Implemented Interfaces:
Serializable
public class Parameters extends Object implements 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.

Version:
CVS $Revision: 1.41 $ $Date: 2004/02/11 14:34:25 $
Author:
Avalon Development Team
See Also:

  • Field Details

    • EMPTY_PARAMETERS

      public static final Parameters EMPTY_PARAMETERS
      Empty Parameters object
      Since:
      4.1.2

  • Constructor Details

    • Parameters

      public Parameters()

  • Method Details

    • setParameter

      public String setParameter(String name, String value) throws 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:
      IllegalStateException - if the Parameters object is read-only

    • removeParameter

      public void removeParameter(String name)
      Remove a parameter from the parameters object
      Parameters:
      name - a String value
      Since:
      4.1

    • getParameterNames

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

    • getNames

      public String[] getNames()
      Retrieve an array of all parameter names.
      Returns:
      the parameters names

    • isParameter

      public boolean isParameter(String name)
      Test if the specified parameter can be retrieved.
      Parameters:
      name - the parameter name
      Returns:
      true if parameter is a name

    • getParameter

      public String getParameter(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 String getParameter(String name, 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(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(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(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(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(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(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(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(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 IllegalStateException
      Checks is this Parameters object is writeable.
      Throws:
      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, 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(Properties properties)
      Create a Parameters object from a Properties object.
      Parameters:
      properties - the Properties
      Returns:
      This Parameters instance.

    • toProperties

      public static Properties toProperties(Parameters params)
      Creates a java.util.Properties object from an Avalon Parameters object.
      Parameters:
      params - a Parameters instance
      Returns:
      a Properties instance