org.apache.avalon.framework.parameters

Class Parameters

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: $Id: Parameters.java 30977 2004-07-30 03:57:54 -0500 (Fri, 30 Jul 2004) niclas $

Author: Avalon Development Team

Field Summary
static ParametersEMPTY_PARAMETERS
Empty Parameters object
Mapm_parameters
Static initializer to initialize the empty Parameters object
booleanm_readOnly
Method Summary
protected voidcheckWriteable()
Checks is this Parameters object is writeable.
booleanequals(Object other)
Compare this parameters instance with the supplied object for equality.
static ParametersfromConfiguration(Configuration configuration)
Create a Parameters object from a Configuration object.
static ParametersfromConfiguration(Configuration configuration, String elementName)
Create a Parameters object from a Configuration object using the supplied element name.
static ParametersfromProperties(Properties properties)
Create a Parameters object from a Properties object.
String[]getNames()
Retrieve an array of all parameter names.
StringgetParameter(String name)
Retrieve the String value of the specified parameter.
StringgetParameter(String name, String defaultValue)
Retrieve the String value of the specified parameter.
booleangetParameterAsBoolean(String name)
Retrieve the boolean value of the specified parameter.
booleangetParameterAsBoolean(String name, boolean defaultValue)
Retrieve the boolean value of the specified parameter.
floatgetParameterAsFloat(String name)
Retrieve the float value of the specified parameter.
floatgetParameterAsFloat(String name, float defaultValue)
Retrieve the float value of the specified parameter.
intgetParameterAsInteger(String name)
Retrieve the int value of the specified parameter.
intgetParameterAsInteger(String name, int defaultValue)
Retrieve the int value of the specified parameter.
longgetParameterAsLong(String name)
Retrieve the long value of the specified parameter.
longgetParameterAsLong(String name, long defaultValue)
Retrieve the long value of the specified parameter.
IteratorgetParameterNames()
Return an Iterator view of all parameter names.
inthashCode()
Returns a hashed value of the Parameters instance.
booleanisParameter(String name)
Test if the specified parameter can be retrieved.
voidmakeReadOnly()
Make this Parameters read-only so that it will throw a IllegalStateException if someone tries to modify it.
Parametersmerge(Parameters other)
Merge parameters from another Parameters instance into this.
intparseInt(String value)
Parses string represenation of the int value.
longparseLong(String value)
Parses string represenation of the long value.
voidremoveParameter(String name)
Remove a parameter from the parameters object
StringsetParameter(String name, String value)
Set the String value of a specified parameter.
static PropertiestoProperties(Parameters params)
Creates a java.util.Properties object from an Avalon Parameters object.
StringtoString()

Field Detail

EMPTY_PARAMETERS

public static final Parameters EMPTY_PARAMETERS
Empty Parameters object

Since: 4.1.2

m_parameters

private Map m_parameters
Static initializer to initialize the empty Parameters object

m_readOnly

private boolean m_readOnly

Method Detail

checkWriteable

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

Throws: IllegalStateException if this Parameters object is read-only

equals

public boolean equals(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.

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

fromConfiguration

public static Parameters fromConfiguration(Configuration configuration)
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)
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)
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)
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)
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)
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)
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

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.

Returns: a hashed value of the instance

Since: 4.3

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.

parseInt

private int parseInt(String value)
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: NumberFormatException if the specified value can not be parsed

parseLong

private long parseLong(String value)
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: NumberFormatException if the specified value can not be parsed

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)
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

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

toString

public String toString()