saffron.util
Class EnumeratedValues

java.lang.Object
  |
  +--saffron.util.EnumeratedValues

All Implemented Interfaces:

Cloneable

Direct Known Subclasses:

SaffronJdbcConnection.Property, SqlJoinOperator.ConditionType, SqlJoinOperator.JoinType, SqlNode.Kind, SqlOperator.Syntax

public class EnumeratedValues

extends Object

implements Cloneable

EnumeratedValues is a helper class for declaring a set of symbolic constants which have names, ordinals, and possibly descriptions. The ordinals do not have to be contiguous.

Typically, for a particular set of constants, you derive a class from this interface, and declare the constants as public static final members. Give it a private constructor, and a public static final ClassName instance member to hold the singleton instance.

Nested Class Summary

static class	EnumeratedValues.BasicValue BasicValue is an obvious implementation of EnumeratedValues.Value.
static interface	EnumeratedValues.Value A Value represents a member of an enumerated type.

Field Summary

private static String[]	emptyStringArray
private int	max the largest ordinal value
private int	min the smallest ordinal value
private EnumeratedValues.Value[]	ordinalToValueMap An array mapping ordinals to EnumeratedValues.Values.
private HashMap	valuesByName map symbol names to values

Constructor Summary

EnumeratedValues()
Creates a new empty, mutable enumeration.

EnumeratedValues(EnumeratedValues.Value[] values)
Creates an enumeration, with an array of values, and freezes it.

EnumeratedValues(String[] names)
Creates an enumeration, initialize it with an array of strings, and freezes it.

EnumeratedValues(String[] names, int[] codes)
Create an enumeration, initializes it with arrays of code/name pairs, and freezes it.

EnumeratedValues(String[] names, int[] codes, String[] descriptions)
Create an enumeration, initializes it with arrays of code/name pairs, and freezes it.

Method Summary

Error	badValue(int ordinal) Returns an error indicating that the value is illegal.
protected Object	clone()
String	getDescription(int ordinal) Returns the description associated with an ordinal; the return value is null if the ordinal is not a member of the enumeration.
int	getMax() Returns the largest ordinal defined by this enumeration.
int	getMin() Returns the smallest ordinal defined by this enumeration.
EnumeratedValues	getMutableClone() Creates a mutable enumeration from an existing enumeration, which may already be immutable.
String	getName(int ordinal) Returns the name associated with an ordinal; the return value is null if the ordinal is not a member of the enumeration.
String[]	getNames() Returns the names in this enumeration, in no particular order.
int	getOrdinal(String name) Returns the ordinal associated with a name
EnumeratedValues.Value	getValue(String name) Returns the ordinal associated with a name.
boolean	isImmutable()
boolean	isValid(int ordinal) Returns whether ordinal is valid for this enumeration.
void	makeImmutable() Freezes the enumeration, preventing it from being further modified.
void	register(EnumeratedValues.Value value) Associates a symbolic name with an ordinal value.
Error	unexpected(EnumeratedValues.Value value) Returns an exception indicating that we didn't expect to find this value here.

Methods inherited from class java.lang.Object

equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

valuesByName

private HashMap valuesByName

map symbol names to values

min

private int min

the smallest ordinal value

max

private int max

the largest ordinal value

ordinalToValueMap

private EnumeratedValues.Value[] ordinalToValueMap

An array mapping ordinals to EnumeratedValues.Values. It is biased by the min value. It is built by makeImmutable().

emptyStringArray

private static final String[] emptyStringArray

Constructor Detail

EnumeratedValues

public EnumeratedValues()

Creates a new empty, mutable enumeration.

EnumeratedValues

public EnumeratedValues(EnumeratedValues.Value[] values)

Creates an enumeration, with an array of values, and freezes it.

EnumeratedValues

public EnumeratedValues(String[] names)

Creates an enumeration, initialize it with an array of strings, and freezes it.

EnumeratedValues

public EnumeratedValues(String[] names,
                        int[] codes)

Create an enumeration, initializes it with arrays of code/name pairs, and freezes it.

EnumeratedValues

public EnumeratedValues(String[] names,
                        int[] codes,
                        String[] descriptions)

Create an enumeration, initializes it with arrays of code/name pairs, and freezes it.

Method Detail

clone

protected Object clone()

Overrides:

clone in class Object

getMutableClone

public EnumeratedValues getMutableClone()

Creates a mutable enumeration from an existing enumeration, which may already be immutable.

register

public void register(EnumeratedValues.Value value)

Associates a symbolic name with an ordinal value.

Pre-condition:

value != null, !isImmutable(), value.getName() != null

makeImmutable

public void makeImmutable()

Freezes the enumeration, preventing it from being further modified.

isImmutable

public final boolean isImmutable()

getMin

public final int getMin()

Returns the smallest ordinal defined by this enumeration.

getMax

public final int getMax()

Returns the largest ordinal defined by this enumeration.

isValid

public final boolean isValid(int ordinal)

Returns whether ordinal is valid for this enumeration. This method is particularly useful in pre- and post-conditions, for example

@param axisCode Axis code, must be a {@link AxisCode} value
 @pre AxisCode.instance.isValid(axisCode)

Parameters:

ordinal - Suspected ordinal from this enumeration.

Returns:

Whether ordinal is valid.

getName

public final String getName(int ordinal)

Returns the name associated with an ordinal; the return value is null if the ordinal is not a member of the enumeration.

Pre-condition:

isImmutable()

getDescription

public final String getDescription(int ordinal)

Returns the description associated with an ordinal; the return value is null if the ordinal is not a member of the enumeration.

Pre-condition:

isImmutable()

getOrdinal

public final int getOrdinal(String name)

Returns the ordinal associated with a name

Throws:

Error - if the name is not a member of the enumeration

getValue

public EnumeratedValues.Value getValue(String name)

Returns the ordinal associated with a name.

Throws:

Error - if the name is not a member of the enumeration

getNames

public String[] getNames()

Returns the names in this enumeration, in no particular order.

badValue

public Error badValue(int ordinal)

Returns an error indicating that the value is illegal. (The client needs to throw the error.)

unexpected

public Error unexpected(EnumeratedValues.Value value)

Returns an exception indicating that we didn't expect to find this value here.