org.apache.avalon.framework.parameters

Class Parameters

Implemented Interfaces:
Serializable

public class Parameters
extends java.lang.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.38 $ $Date: 2003/02/11 16:25:49 $

Author:
Avalon Development Team

Field Summary

static Parameters
EMPTY_PARAMETERS
Empty Parameters object

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, String elementName)
Create a Parameters object from a Configuration object using the supplied element name.
static Parameters
fromProperties(Properties properties)
Create a Parameters object from a Properties object.
String[]
getNames()
Retrieve an array of all parameter names.
String
getParameter(String name)
Retrieve the String value of the specified parameter.
String
getParameter(String name, String defaultValue)
Retrieve the String value of the specified parameter.
boolean
getParameterAsBoolean(String name)
Retrieve the boolean value of the specified parameter.
boolean
getParameterAsBoolean(String name, boolean defaultValue)
Retrieve the boolean value of the specified parameter.
float
getParameterAsFloat(String name)
Retrieve the float value of the specified parameter.
float
getParameterAsFloat(String name, float defaultValue)
Retrieve the float value of the specified parameter.
int
getParameterAsInteger(String name)
Retrieve the int value of the specified parameter.
int
getParameterAsInteger(String name, int defaultValue)
Retrieve the int value of the specified parameter.
long
getParameterAsLong(String name)
Retrieve the long value of the specified parameter.
long
getParameterAsLong(String name, long defaultValue)
Retrieve the long value of the specified parameter.
Iterator
getParameterNames()
Deprecated. Use getNames() instead
boolean
isParameter(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(String name)
Remove a parameter from the parameters object
String
setParameter(String name, String value)
Set the String value of a specified parameter.
static Properties
toProperties(Parameters params)
Creates a java.util.Properties object from an Avalon Parameters object.

Field Details

EMPTY_PARAMETERS

public static final Parameters EMPTY_PARAMETERS
Empty Parameters object

Since:
4.1.2

Method Details

checkWriteable

protected final void checkWriteable()
            throws IllegalStateException
Checks is this Parameters object is writeable.


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.


getNames

public String[] getNames()
Retrieve an array of all parameter names.

Returns:
the parameters names


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


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


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


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


getParameterNames

public Iterator getParameterNames()

Deprecated. Use getNames() instead

Return an Iterator view of all parameter names.

Returns:
a iterator of parameter 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


makeReadOnly

public void makeReadOnly()
Make this Parameters read-only so that it will throw a IllegalStateException if someone tries to modify it.


merge

public Parameters merge(Parameters other)
Merge parameters from another Parameters instance into this.

Parameters:
other - the other Parameters

Returns:
This Parameters instance.


removeParameter

public void removeParameter(String name)
Remove a parameter from the parameters object

Parameters:
name - a String value

Since:
4.1


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.


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


"Copyright B) 2001 Apache Jakarta Project. All Rights Reserved."