Parameters (Avalon Framework API)
Keywords: org.apache.avalon.framework.parameters.Parameters class

Overview | Package | Class | Use | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

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

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

Field Summary
`static Parameters` | `EMPTY_PARAMETERS` Empty Parameters object

Constructor Summary
`Parameters()`

Method Summary
`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

Overview | Package | Class | Use | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

Copyright © The Apache Software Foundation. All Rights Reserved.