Top Description Fields Constructors Methods
org.apache.avalon.framework.parameters

public Class Parameters

extends Object
implements Serializable
Class Inheritance
All Implemented Interfaces
java.io.Serializable
Imports
java.io.Serializable, java.util.Enumeration, .HashMap, .Iterator, .Map, .Properties, org.apache.avalon.framework.configuration.Configuration, .ConfigurationException
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.

Author
Avalon Development Team
Version
$Id: Parameters.java 506231 2007-02-12 02:36:54Z crossley $

Field Summary

Modifier and TypeField and Description
public static final Parameters
EMPTY_PARAMETERS

Empty Parameters object

private Map<K, V>
m_parameters

private boolean
m_readOnly

Constructor Summary

AccessConstructor and Description
public
Parameters()

Method Summary

Modifier and TypeMethod and Description
protected final void
checkWriteable()

Checks is this Parameters object is writeable.

public boolean

Returns:

true if this parameters instance is equal to the supplied object
equals(Object
the object to compare this parameters instance with
other)

Overrides java.lang.Object.equals.

Compare this parameters instance with the supplied object for equality.
public static Parameters

Returns:

This Parameters instance.
fromConfiguration(final Configuration
the Configuration
configuration)

Create a Parameters object from a Configuration object.

public static Parameters

Returns:

This Parameters instance.
fromConfiguration(final Configuration
the Configuration
configuration, final String
the element name for the parameters
elementName)

Create a Parameters object from a Configuration object using the supplied element name.

public static Parameters

Returns:

This Parameters instance.
fromProperties(final Properties
the Properties
properties)

Create a Parameters object from a Properties object.

public String[]

Returns:

the parameters names
getNames()

Retrieve an array of all parameter names.

public String

Returns:

the value of parameter
getParameter(final String
the name of parameter
name)

Retrieve the String value of the specified parameter.

public String

Returns:

the value of parameter
getParameter(final String
the name of parameter
name, final String
the default value, returned if parameter does not exist or parameter's name is null
defaultValue)

Retrieve the String value of the specified parameter.

public boolean

Returns:

the value
getParameterAsBoolean(final String
the parameter name
name)

Retrieve the boolean value of the specified parameter.

public boolean

Returns:

the value
getParameterAsBoolean(final String
the parameter name
name, final boolean
the default value if parameter does not exist or is of wrong type
defaultValue)

Retrieve the boolean value of the specified parameter.

public float

Returns:

the value
getParameterAsFloat(final String
the parameter name
name)

Retrieve the float value of the specified parameter.

public float

Returns:

the value
getParameterAsFloat(final String
the parameter name
name, final float
the default value if parameter does not exist or is of wrong type
defaultValue)

Retrieve the float value of the specified parameter.

public int

Returns:

the integer parameter type
getParameterAsInteger(final String
the name of parameter
name)

Retrieve the int value of the specified parameter.

public int

Returns:

the integer parameter type
getParameterAsInteger(final String
the name of parameter
name, final int
value returned if parameter does not exist or is of wrong type
defaultValue)

Retrieve the int value of the specified parameter.

public long

Returns:

the long parameter type
getParameterAsLong(final String
the name of parameter
name)

Retrieve the long value of the specified parameter.

public long

Returns:

the long parameter type
getParameterAsLong(final String
the name of parameter
name, final long
value returned if parameter does not exist or is of wrong type
defaultValue)

Retrieve the long value of the specified parameter.

public Iterator<E>

Returns:

a iterator of parameter names
getParameterNames()

Deprecated Use getNames() instead
Return an Iterator view of all parameter names.
public int

Returns:

a hashed value of the instance
hashCode()

Overrides java.lang.Object.hashCode.

Returns a hashed value of the Parameters instance.
public boolean

Returns:

true if parameter is a name
isParameter(final String
the parameter name
name)

Test if the specified parameter can be retrieved.

public void
makeReadOnly()

Make this Parameters read-only so that it will throw a IllegalStateException if someone tries to modify it.

public Parameters

Returns:

This Parameters instance.
merge(final Parameters
the other Parameters
other)

Merge parameters from another Parameters instance into this.

private int

Returns:

the integer value
parseInt(final String
the value to parse
value)

Parses string represenation of the int value.

private long

Returns:

the long value
parseLong(final String
the value to parse
value)

Parses string represenation of the long value.

public void
removeParameter(final String
a String value
name)

Remove a parameter from the parameters object

public String

Returns:

The previous value of the parameter or null.
setParameter(final String
a String value
name, final String
a String value
value)

Set the String value of a specified parameter.

public static Properties

Returns:

a Properties instance
toProperties(final Parameters
a Parameters instance
params)

Creates a java.util.Properties object from an Avalon Parameters object.

public String
toString()

Overrides java.lang.Object.toString.

Returns a string representation of the object.
Inherited from java.lang.Object:
clonefinalizegetClassnotifynotifyAllwaitwaitwait

Field Detail

EMPTY_PARAMETERSback to summary
public static final Parameters EMPTY_PARAMETERS

Empty Parameters object

Since
4.1.2
m_parametersback to summary
private Map<K, V> m_parameters
m_readOnlyback to summary
private boolean m_readOnly

Constructor Detail

Parametersback to summary
public Parameters()

Method Detail

checkWriteableback to summary
protected final void checkWriteable() throws IllegalStateException

Checks is this Parameters object is writeable.

Exceptions
IllegalStateException:
if this Parameters object is read-only
equalsback to summary
public boolean equals(Object other)

Overrides java.lang.Object.equals.

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:Object

the object to compare this parameters instance with

Returns:boolean

true if this parameters instance is equal to the supplied object

Since
4.3
fromConfigurationback to summary
public static Parameters fromConfiguration(final 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:Configuration

the Configuration

Returns:Parameters

This Parameters instance.

Exceptions
ConfigurationException:
if an error occurs
fromConfigurationback to summary
public static Parameters fromConfiguration(final Configuration configuration, final String elementName) throws ConfigurationException

Create a Parameters object from a Configuration object using the supplied element name.

Parameters
configuration:Configuration

the Configuration

elementName:String

the element name for the parameters

Returns:Parameters

This Parameters instance.

Exceptions
ConfigurationException:
if an error occurs
Since
4.1
fromPropertiesback to summary
public static Parameters fromProperties(final Properties properties)

Create a Parameters object from a Properties object.

Parameters
properties:Properties

the Properties

Returns:Parameters

This Parameters instance.

getNamesback to summary
public String[] getNames()

Retrieve an array of all parameter names.

Returns:String[]

the parameters names

getParameterback to summary
public String getParameter(final 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:String

the name of parameter

Returns:String

the value of parameter

Exceptions
ParameterException:
if the specified parameter cannot be found
getParameterback to summary
public String getParameter(final String name, final String defaultValue)

Retrieve the String value of the specified parameter.

If the specified parameter cannot be found, defaultValue is returned.

Parameters
name:String

the name of parameter

defaultValue:String

the default value, returned if parameter does not exist or parameter's name is null

Returns:String

the value of parameter

getParameterAsBooleanback to summary
public boolean getParameterAsBoolean(final 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:String

the parameter name

Returns:boolean

the value

Exceptions
ParameterException:
if an error occurs
getParameterAsBooleanback to summary
public boolean getParameterAsBoolean(final String name, final boolean defaultValue)

Retrieve the boolean value of the specified parameter.

If the specified parameter cannot be found, defaultValue is returned.

Parameters
name:String

the parameter name

defaultValue:boolean

the default value if parameter does not exist or is of wrong type

Returns:boolean

the value

getParameterAsFloatback to summary
public float getParameterAsFloat(final 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:String

the parameter name

Returns:float

the value

Exceptions
ParameterException:
if the specified parameter cannot be found or is not a Float value
getParameterAsFloatback to summary
public float getParameterAsFloat(final String name, final float defaultValue)

Retrieve the float value of the specified parameter.

If the specified parameter cannot be found, defaultValue is returned.

Parameters
name:String

the parameter name

defaultValue:float

the default value if parameter does not exist or is of wrong type

Returns:float

the value

getParameterAsIntegerback to summary
public int getParameterAsInteger(final 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:String

the name of parameter

Returns:int

the integer parameter type

Exceptions
ParameterException:
if the specified parameter cannot be found or is not an Integer value
getParameterAsIntegerback to summary
public int getParameterAsInteger(final String name, final 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:String

the name of parameter

defaultValue:int

value returned if parameter does not exist or is of wrong type

Returns:int

the integer parameter type

getParameterAsLongback to summary
public long getParameterAsLong(final 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:String

the name of parameter

Returns:long

the long parameter type

Exceptions
ParameterException:
if the specified parameter cannot be found or is not a Long value.
getParameterAsLongback to summary
public long getParameterAsLong(final String name, final 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:String

the name of parameter

defaultValue:long

value returned if parameter does not exist or is of wrong type

Returns:long

the long parameter type

getParameterNamesback to summary
public Iterator<E> getParameterNames()

Deprecated

Use getNames() instead

Return an Iterator view of all parameter names.

Returns:Iterator<E>

a iterator of parameter names

hashCodeback to summary
public int hashCode()

Overrides java.lang.Object.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:int

a hashed value of the instance

Since
4.3
isParameterback to summary
public boolean isParameter(final String name)

Test if the specified parameter can be retrieved.

Parameters
name:String

the parameter name

Returns:boolean

true if parameter is a name

makeReadOnlyback to summary
public void makeReadOnly()

Make this Parameters read-only so that it will throw a IllegalStateException if someone tries to modify it.

mergeback to summary
public Parameters merge(final Parameters other)

Merge parameters from another Parameters instance into this.

Parameters
other:Parameters

the other Parameters

Returns:Parameters

This Parameters instance.

parseIntback to summary
private int parseInt(final String value) throws 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:String

the value to parse

Returns:int

the integer value

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

the value to parse

Returns:long

the long value

Exceptions
NumberFormatException:
if the specified value can not be parsed
removeParameterback to summary
public void removeParameter(final String name)

Remove a parameter from the parameters object

Parameters
name:String

a String value

Since
4.1
setParameterback to summary
public String setParameter(final String name, final String value) throws IllegalStateException

Set the String value of a specified parameter.

If the specified value is null the parameter is removed.

Parameters
name:String

a String value

value:String

a String value

Returns:String

The previous value of the parameter or null.

Exceptions
IllegalStateException:
if the Parameters object is read-only
toPropertiesback to summary
public static Properties toProperties(final Parameters params)

Creates a java.util.Properties object from an Avalon Parameters object.

Parameters
params:Parameters

a Parameters instance

Returns:Properties

a Properties instance

toStringback to summary
public String toString()

Overrides java.lang.Object.toString.

Doc from java.lang.Object.toString.

Returns a string representation of the object.

Returns:String

a string representation of the object.