Evaluating Software Design Patterns
— the "Gang of Four" patterns implemented in Java 6

dk.rode.thesis.meta.util
Class Arguments

java.lang.Object
  extended by dk.rode.thesis.meta.util.Arguments
All Implemented Interfaces:
Iterable<Arguments.Argument>

public class Arguments
extends Object
implements Iterable<Arguments.Argument>

An arguments object represents a collection of String arguments that may or may not have an associated String value.

Argument names are expected to be prefixed with a dash (-), and are looked up in a case-insensitive manner.

Example:

   -foo -bar barbar -goo goo goo goo -foobar
 
Here, four argument names are present: foo, bar, goo, and foobar. foo and foobar have no associated values, while bar has the value barbar associated, and goo has goo goo goo.

Author:
Gunni Rode / rode.dk

Nested Class Summary
static class Arguments.Argument
          An argument represents a single argument, with or without an associated value.
 
Field Summary
 Map<String,Arguments.Argument> arguments
          Actual arguments stored according to insertion order.
 
Constructor Summary
Arguments(Arguments arguments)
          Copy constructor.
Arguments(String... args)
          Constructor.
 
Method Summary
 boolean equals(Object object)
          Returns true if object is an Arguments instance storing the same arguments as these arguments, false if not.
 Arguments.Argument getArgument(String name)
          Returns the argument having the name supplied as name, regardless if it has an associated value or not.
 Arguments.Argument getArgument(String name, boolean mustHaveValue)
          Returns the argument having the name supplied as name, regardless if it has an associated value or not if mustHaveValue is false.
 List<Arguments.Argument> getArguments(String prefix)
          Returns a list of arguments having a name that starts with the prefix supplied as prefix, if any.
 String getArgumentValue(String name)
          Returns the argument value associated with the argument name supplied as name, if any.
<V> V
getArgumentValue(String name, Class<V> type)
          Returns the argument value associated with the argument name supplied as name, if any, transformed to the type supplied as type using the static type.valueOf(String) method.
 String getArgumentValue(String name, String defaultValue)
          Returns the argument value associated with the argument name supplied as name, if any.
<V> V
getArgumentValue(String name, V defaultValue, Class<V> type)
          Returns the argument value associated with the argument name supplied as name, if any, transformed to the type supplied as type using the static type.valueOf(String) method.
private static String getName(String name)
          Returns a valid argument name based on name.
 boolean hasArgument(String name)
          Returns true if an argument has the name supplied as name, regardless if it has an associated value or not.
 int hashCode()
          Returns the hash code of these arguments.
 Iterator<Arguments.Argument> iterator()
          Returns an iterator that is backed by these arguments.
static Map<String,Arguments.Argument> parse(String... args)
          Parses the arguments supplied in args, and returns a corresponding map, ordered according to the order of args.
 boolean setArgument(String name, String value)
          Updates or adds the argument having the name supplied as name with the associated value supplied as value, if any.
 int size()
          Returns the number of arguments.
 String toString()
          Returns the string representation of these arguments.
 
Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait
 

Field Detail

arguments

public Map<String,Arguments.Argument> arguments
Actual arguments stored according to insertion order.

All names contained as keys do not have a prefixed dash (-).

Never null, but can be empty.

Constructor Detail

Arguments

public Arguments(Arguments arguments)
Copy constructor.

Parameters:
arguments - The arguments to copy; cannot be null.
Throws:
NullPointerException - If arguments is null.

Arguments

public Arguments(String... args)
Constructor.

The arguments are parsed as described in the class documentation.

Parameters:
args - The actual arguments to parse; can be null.
See Also:
parse(String...)
Method Detail

equals

public boolean equals(Object object)
Returns true if object is an Arguments instance storing the same arguments as these arguments, false if not.

Overrides:
equals in class Object
Parameters:
object - The object to test; can be null.
Returns:
True if equal, false if not.

getArgument

public Arguments.Argument getArgument(String name)
Returns the argument having the name supplied as name, regardless if it has an associated value or not.

The comparison on argument name is performed in a case-insensitive manner.

Parameters:
name - The argument name; cannot be null, and may start with a dash.
Returns:
The corresponding argument, or null.
Throws:
NullPointerException - If name is null.
IllegalArgumentException - If name is empty or illegal.

getArgument

public Arguments.Argument getArgument(String name,
                                      boolean mustHaveValue)
Returns the argument having the name supplied as name, regardless if it has an associated value or not if mustHaveValue is false. If true, an argument is only returned if it has an associated value.

The comparison on argument name is performed in a case-insensitive manner.

Parameters:
name - The argument name; cannot be null, and may start with a dash.
mustHaveValue - True if an argument should only be returned if it has an associated value.
Returns:
The corresponding argument, or null.
Throws:
NullPointerException - If name is null.
IllegalArgumentException - If name is empty or illegal.

getArguments

public List<Arguments.Argument> getArguments(String prefix)
Returns a list of arguments having a name that starts with the prefix supplied as prefix, if any.

If prefix is null, all arguments are returned.

Modifying the returned list will not affect these arguments.

Parameters:
prefix - The argument prefix; cannot be null, and may start with a dash.
Returns:
A list of matching arguments; never null, but can be empty.
Throws:
IllegalArgumentException - If prefix is empty or illegal.

getArgumentValue

public String getArgumentValue(String name)
Returns the argument value associated with the argument name supplied as name, if any.

Parameters:
name - The argument name; cannot be null, and may start with a dash.
Returns:
The argument value, or null.
Throws:
NullPointerException - If name is null.
IllegalArgumentException - If name is empty or illegal.

getArgumentValue

public <V> V getArgumentValue(String name,
                              Class<V> type)
Returns the argument value associated with the argument name supplied as name, if any, transformed to the type supplied as type using the static type.valueOf(String) method.

If no such method is found in type, null is returned.

If the transformation fails, null is returned.

Type Parameters:
V - The type to transform the argument value into using its static valueOf(String) method.
Parameters:
name - The argument name; cannot be null, and may start with a dash.
type - The class of the desired type that the argument value should be transformed to by type.valueOf(String); cannot be null.
Returns:
The argument value as a V type; can be null.
Throws:
NullPointerException - If name is null.
IllegalArgumentException - If name is empty or illegal.


getArgumentValue

public String getArgumentValue(String name,
                               String defaultValue)
Returns the argument value associated with the argument name supplied as name, if any.

defaultValue is returned if no such argument is found or it does not have an associated value.

Parameters:
name - The argument name; cannot be null, and may start with a dash.
defaultValue - The default value; can be null.
Returns:
The argument value, or defaultValue (which can be null).
Throws:
NullPointerException - If name is null.
IllegalArgumentException - If name is empty or illegal.

getArgumentValue

public <V> V getArgumentValue(String name,
                              V defaultValue,
                              Class<V> type)
Returns the argument value associated with the argument name supplied as name, if any, transformed to the type supplied as type using the static type.valueOf(String) method.

If no such method is found in type, null is returned.

If no argument value is found or the transformation fails, defaultValue is returned.

Type Parameters:
V - The type to transform the argument value into using its static valueOf(String) method.
Parameters:
name - The argument name; cannot be null, and may start with a dash.
defaultValue - The default value; can be null.
type - The class of the desired type that the argument value should be transformed to by type.valueOf(String); cannot be null.
Returns:
The argument value as a V type; can be null.
Throws:
NullPointerException - If name is null.
IllegalArgumentException - If name is empty or illegal.


getName

private static final String getName(String name)
Returns a valid argument name based on name.

Parameters:
name - The name to make valid; cannot be null.
Returns:
A valid argument name; never null.
Throws:
NullPointerException - If name is null.
IllegalArgumentException - If name is empty or illegal.

hasArgument

public boolean hasArgument(String name)
Returns true if an argument has the name supplied as name, regardless if it has an associated value or not.

Parameters:
name - The argument name; cannot be null, and may start with a dash.
Returns:
True if such an argument exist, false if not.
Throws:
NullPointerException - If name is null.
IllegalArgumentException - If name is empty or illegal.

hashCode

public int hashCode()
Returns the hash code of these arguments.

Overrides:
hashCode in class Object
Returns:
The hash code.

iterator

public Iterator<Arguments.Argument> iterator()
Returns an iterator that is backed by these arguments.

Specified by:
iterator in interface Iterable<Arguments.Argument>
Returns:
An iterator; never null.

parse

public static final Map<String,Arguments.Argument> parse(String... args)
Parses the arguments supplied in args, and returns a corresponding map, ordered according to the order of args.

Argument names are expected to be prefixed with a single dash. Everything else is considered an argument value.

Parameters:
args - The arguments to parse; can be null or empty.
Returns:
A map containing the arguments; never null, but can be empty.

setArgument

public boolean setArgument(String name,
                           String value)
Updates or adds the argument having the name supplied as name with the associated value supplied as value, if any.

If an argument with that name is already contained, it will be updated; if not, a new argument will be added.

Parameters:
name - The argument name; cannot be null, and may start with a dash.
value - The associated argument value; can be null.
Returns:
True if an argument with the name name already exists, false if not.
Throws:
NullPointerException - If name is null.
IllegalArgumentException - If name is empty or illegal.

size

public int size()
Returns the number of arguments.

Returns:
The number of arguments.

toString

public String toString()
Returns the string representation of these arguments.

Overrides:
toString in class Object
Returns:
The string representation; never null.

Gunni Rode / rode.dk

Feel free to use and/or modify the Java 6 source code developed for this thesis AT YOUR OWN RISK, but note that the source code comes WITHOUT ANY — and I do mean WITHOUT ANY — form of warranty WHAT SO EVER!

The original thesis and source code are available at rode.dk/thesis.