Package org.apache.avalon.framework.parameters

Class 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.

    Version:
    $Id: Parameters.java 30977 2004-07-30 03:57:54 -0500 (Fri, 30 Jul 2004) niclas $
    Author:
    Avalon Development Team
    See Also:
    Serialized Form

    • Constructor Summary

      Constructors 
      Constructor Description
      Parameters()  

    • Method Summary

      All Methods Static Methods Instance Methods Concrete Methods Deprecated Methods 
      Modifier and Type Method Description
      protected void checkWriteable()
      Checks is this Parameters object is writeable.
      boolean equals​(java.lang.Object other)
      Compare this parameters instance with the supplied object for equality.
      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
      int hashCode()
      Returns a hashed value of the Parameters instance.
      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.
      private int parseInt​(java.lang.String value)
      Parses string represenation of the int value.
      private long parseLong​(java.lang.String value)
      Parses string represenation of the long value.
      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.
      java.lang.String toString()  

      • Methods inherited from class java.lang.Object

        clone, finalize, getClass, notify, notifyAll, wait, wait, wait

    • Field Detail

      • EMPTY_PARAMETERS

        public static final Parameters EMPTY_PARAMETERS
        Empty Parameters object
        Since:
        4.1.2

      • m_parameters

        private java.util.Map m_parameters

      • m_readOnly

        private boolean m_readOnly

    • 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

      • parseInt

        private int parseInt​(java.lang.String value)
              throws java.lang.NumberFormatException
        Parses string represenation of the int value.

        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:
        value - the value to parse
        Returns:
        the integer value
        Throws:
        java.lang.NumberFormatException - if the specified value can not be parsed

      • 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

      • parseLong

        private long parseLong​(java.lang.String value)
                throws java.lang.NumberFormatException
        Parses string represenation of the long value.

        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:
        value - the value to parse
        Returns:
        the long value
        Throws:
        java.lang.NumberFormatException - if the specified value can not be parsed

      • 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.

      • equals

        public boolean equals​(java.lang.Object other)
        Compare this parameters instance with the supplied object for equality. The equality is mainly driven by the underlying HashMap which forms the basis of the class. I.e. if the underlying HashMaps are equal and the Readonly attributes are equal in the Parameters instances being compared, then this method returns equality.
        Overrides:
        equals in class java.lang.Object
        Parameters:
        other - the object to compare this parameters instance with
        Returns:
        true if this parameters instance is equal to the supplied object
        Since:
        4.3

      • hashCode

        public int hashCode()
        Returns a hashed value of the Parameters instance. This method returns a semi-unique value for all instances, yet an identical value for instances where equals() returns true.
        Overrides:
        hashCode in class java.lang.Object
        Returns:
        a hashed value of the instance
        Since:
        4.3

      • toString

        public java.lang.String toString()
        Overrides:
        toString in class java.lang.Object

      • 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