com.metamatrix.common.object
Class Multiplicity

java.lang.Object
  com.metamatrix.common.object.Multiplicity

All Implemented Interfaces:

java.io.Serializable, java.lang.Comparable

public abstract class Multiplicity
extends java.lang.Object
implements java.io.Serializable, java.lang.Comparable

Multiplicity is the specification of the range of allowable cardinality values that a set may assume. Essentially, multiplicity is a (possibly infinite) subset of the nonnegative integers. The Multiplicity class represents an interface for handling and manipulating multiplicity specifications.

In practice, it is usually a finite set of integer intervals, most often a single interval with a minimum and maximum value. Any set must be finite, but the upper bound can be finite or unbounded (the latter is called "many"); the upper bound must be greater than zero (multiplicity of zero is not useful). Note that although the set may be unbounded, any particular cardinality is always finite.

The multiplicity is usually defined simply as a text expression consisting of a comman-separated list of integer intervals, each in the form "minimum..maximum", where minimum and maximum are integers, or maximum can be a "*" which indicates an unbounded interval. An interval may also have the form number, where number is an integer representing an interval of a single integer. The multiplicity defined as a single star ("*") is equivalent to the expression "0..*", and indicates that the cardinality is unrestricted (i.e., "zero or more", or "many"). Examples of well-formed multiplicity text expressions include:

0..1

1

0..*

*

1..*

1..5

1..5,10,13..18,20..*

Generally, a well-formed multiplicity text expression will have intervals that monotonically increase (e.g., 1..5,10,13 rather than 10,1..5,13), and will have two continguous intervals combined into a single interval (e.g., 1..8 rather than 1..5,6..8, and 0..1 rather than 0,1).

The Multiplicity class is an abstract class that is intended to hide all implementation details from the user. In this manner, the user only sees and uses the Multiplicity interface definition and its static getInstance and getUnboundedInstance methods, but the best possible implementation class with the most efficient representation is used for each instance. Various implementation classes are provided to efficiently handle the unbounded case and the single interval case, both of which are by far the most commonly used. However, any well-formed multiplicity text expression will be handled as well.

The Multiplicity class (and subclasses) are also immutable, and therefore may be referenced by multiple users without the chance of the instance being modified. This also simplifies the interface (since no modification methods need be provided) and makes possible the use of different underlying classes to handle different situations without exposing the specific implementation classes to the user; modification methods would make this very difficult to successfully implement.

See Also:

Serialized Form

Field Summary

protected static Multiplicity	DEFAULT
static boolean	DEFAULT_ORDERING The default value for isOrdered.
protected static int	DEFAULT_SINGLE_VALUE The default single multiplicity value.
static boolean	DEFAULT_UNIQUENESS The default value for isUnique.
static java.lang.String	INTERVAL_DELIMITER The delimiter string "," used between two intervals.
protected static char	INTERVAL_DELIMITER_CHAR
protected static int	INTERVAL_DELIMITER_LENGTH
protected static int	MINIMUM_SINGLE_VALUE The minimum single multiplicity value allowed.
static java.lang.String	RANGE_DELIMITER The delimiter string ".." used between the minimum and maximum values.
protected static char	RANGE_DELIMITER_CHAR
protected static int	RANGE_DELIMITER_LENGTH
protected static Multiplicity	UNBOUNDED
protected static char	UNBOUNDED_CHAR
static java.lang.String	UNBOUNDED_DEFINITION The String definition of completely unbounded of either the maximum or both minimum and maximum if the multiplicity is considered unlimited.
static int	UNBOUNDED_VALUE The value of either the maximum or both minimum and maximum if the multiplicity is considered unlimited.

Constructor Summary

protected	Multiplicity()
protected	Multiplicity(boolean isOrdered, boolean isUnique)

Method Summary

protected int	compareFlags(Multiplicity that)
abstract int	compareTo(java.lang.Object obj) Compares this object to another.
static Multiplicity	getInstance() Obtain an instance that represents a singular multiplicity of "1" that is unordered and not unique.
static Multiplicity	getInstance(int number) Obtain an instance for a single-interval multiplicity of the specified value that is unordered and not unique.
static Multiplicity	getInstance(int number, boolean isOrdered, boolean isUnique) Obtain an instance for a single-interval multiplicity of the specified value.
static Multiplicity	getInstance(int minimum, int maximum) Obtain an instance for a single-interval multiplicity over the specified range that is unordered and not unique.
static Multiplicity	getInstance(int minimum, int maximum, boolean isOrdered, boolean isUnique) Obtain an instance for a single-interval multiplicity over the specified range.
static Multiplicity	getInstance(java.lang.String defn) Obtain an instance by parsing the specified multiplicity text expression, that is unordered and not unique.
static Multiplicity	getInstance(java.lang.String defn, boolean isOrdered, boolean isUnique) Obtain an instance by parsing the specified multiplicity text expression.
abstract int	getMaximum() Get the maximum number of values required for this property.
abstract int	getMinimum() Get the minimum number of values required for this property.
static Multiplicity	getUnboundedInstance() Obtain an instance that represents an unbounded multiplicity, which is equivalent to the text expression "*", that is unordered and not unique.
static Multiplicity	getUnboundedInstance(boolean isOrdered, boolean isUnique) Obtain an instance that represents an unbounded multiplicity, which is equivalent to the text expression "*".
abstract boolean	isIncluded(int cardinality) Determine whether the specified cardinality is included in this multiplicity expression.
boolean	isOrdered() Return whether the multiplicity is defined as requiring an order.
boolean	isUnique() Return whether the multiplicity is defined as requiring uniqueness.
abstract boolean	isUnlimited() Obtain whether the multiplicity has a maximum value that is unlimited.
abstract java.lang.String	toString() Returns a string representing the current state of the object.

Methods inherited from class java.lang.Object

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

Field Detail

UNBOUNDED_DEFINITION

public static final java.lang.String UNBOUNDED_DEFINITION

The String definition of completely unbounded of either the maximum or both minimum and maximum if the multiplicity is considered unlimited.

See Also:

Constant Field Values

UNBOUNDED_CHAR

protected static final char UNBOUNDED_CHAR

See Also:

Constant Field Values

RANGE_DELIMITER

public static final java.lang.String RANGE_DELIMITER

The delimiter string ".." used between the minimum and maximum values.

See Also:

Constant Field Values

RANGE_DELIMITER_CHAR

protected static final char RANGE_DELIMITER_CHAR

See Also:

Constant Field Values

RANGE_DELIMITER_LENGTH

protected static final int RANGE_DELIMITER_LENGTH

INTERVAL_DELIMITER

public static final java.lang.String INTERVAL_DELIMITER

The delimiter string "," used between two intervals.

See Also:

Constant Field Values

INTERVAL_DELIMITER_CHAR

protected static final char INTERVAL_DELIMITER_CHAR

See Also:

Constant Field Values

INTERVAL_DELIMITER_LENGTH

protected static final int INTERVAL_DELIMITER_LENGTH

UNBOUNDED_VALUE

public static final int UNBOUNDED_VALUE

The value of either the maximum or both minimum and maximum if the multiplicity is considered unlimited.

See Also:

Constant Field Values

MINIMUM_SINGLE_VALUE

protected static final int MINIMUM_SINGLE_VALUE

The minimum single multiplicity value allowed. A multiplicity of 0 is undefined.

See Also:

Constant Field Values

DEFAULT_SINGLE_VALUE

protected static final int DEFAULT_SINGLE_VALUE

The default single multiplicity value.

See Also:

Constant Field Values

DEFAULT_ORDERING

public static final boolean DEFAULT_ORDERING

The default value for isOrdered.

See Also:

Constant Field Values

DEFAULT_UNIQUENESS

public static final boolean DEFAULT_UNIQUENESS

The default value for isUnique.

See Also:

Constant Field Values

UNBOUNDED

protected static final Multiplicity UNBOUNDED

DEFAULT

protected static final Multiplicity DEFAULT

Constructor Detail

Multiplicity

protected Multiplicity(boolean isOrdered,
                       boolean isUnique)

Multiplicity

protected Multiplicity()

Method Detail

getInstance

public static Multiplicity getInstance(java.lang.String defn,
                                       boolean isOrdered,
                                       boolean isUnique)
                                throws MultiplicityExpressionException

Obtain an instance by parsing the specified multiplicity text expression. The text expression must be well-formed.

Parameters:

expression - the string definition of the multiplicity specification; if null, then the default Multiplicity instance of "1" is returned.

isOrdered - the ordering constraint for the multiplicity

isUnique - the uniqueness constraint for the multiplicity

Returns:

the MultiplicityInstance that best captures the specified definition.

Throws:

MultiplicityExpressionException - if the expression is not well-formed and cannot be parsed.

getInstance

public static Multiplicity getInstance(java.lang.String defn)
                                throws MultiplicityExpressionException

Obtain an instance by parsing the specified multiplicity text expression, that is unordered and not unique. The text expression must be well-formed.

Parameters:

expression - the string definition of the multiplicity specification; if null, then the default Multiplicity instance of "1" is returned.

Returns:

the MultiplicityInstance that best captures the specified definition.

Throws:

MultiplicityExpressionException - if the expression is not well-formed and cannot be parsed.

getUnboundedInstance

public static Multiplicity getUnboundedInstance()

Obtain an instance that represents an unbounded multiplicity, which is equivalent to the text expression "*", that is unordered and not unique.

Returns:

the MultiplicityInstance representing "*".

getUnboundedInstance

public static Multiplicity getUnboundedInstance(boolean isOrdered,
                                                boolean isUnique)

Obtain an instance that represents an unbounded multiplicity, which is equivalent to the text expression "*".

Parameters:

isOrdered - the ordering constraint for the multiplicity

isUnique - the uniqueness constraint for the multiplicity

Returns:

the MultiplicityInstance representing "*".

getInstance

public static Multiplicity getInstance()

Obtain an instance that represents a singular multiplicity of "1" that is unordered and not unique. This is considered the default multiplicity, since many situations will require a cardinality of 1.

Returns:

the MultiplicityInstance representing "1".

getInstance

public static Multiplicity getInstance(int number,
                                       boolean isOrdered,
                                       boolean isUnique)

Obtain an instance for a single-interval multiplicity of the specified value. The corresponding text expression is "number".

Parameters:

number - the size of the single interval; must be a positive integer value.

isOrdered - the ordering constraint for the multiplicity

isUnique - the uniqueness constraint for the multiplicity

Returns:

the MultiplicityInstance that best captures the specified definition.

Throws:

java.lang.IllegalArgumentException - if the value is negative or zero.

getInstance

public static Multiplicity getInstance(int minimum,
                                       int maximum,
                                       boolean isOrdered,
                                       boolean isUnique)

Obtain an instance for a single-interval multiplicity over the specified range. The corresponding text expression is "minimum..maximum".

Parameters:

minimum - the minimum value for the interval; must be positive, and may be zero only if maximum is non-zero.

maximum - the maximum value for the interval; must be equal to or greater than minimum, and may be Multiplicity.UNBOUNDED_VALUE for an unbounded maximum value.

isOrdered - the ordering constraint for the multiplicity

isUnique - the uniqueness constraint for the multiplicity

Returns:

the MultiplicityInstance that best captures the specified definition.

Throws:

java.lang.IllegalArgumentException - if the two values are not compatible.

getInstance

public static Multiplicity getInstance(int number)

Obtain an instance for a single-interval multiplicity of the specified value that is unordered and not unique. The corresponding text expression is "number".

Parameters:

number - the size of the single interval; must be a positive integer value.

Returns:

the MultiplicityInstance that best captures the specified definition.

Throws:

java.lang.IllegalArgumentException - if the value is negative or zero.

getInstance

public static Multiplicity getInstance(int minimum,
                                       int maximum)

Obtain an instance for a single-interval multiplicity over the specified range that is unordered and not unique. The corresponding text expression is "minimum..maximum".

Parameters:

minimum - the minimum value for the interval; must be positive, and may be zero only if maximum is non-zero.

maximum - the maximum value for the interval; must be equal to or greater than minimum, and may be Multiplicity.UNBOUNDED_VALUE for an unbounded maximum value.

Returns:

the MultiplicityInstance that best captures the specified definition.

Throws:

java.lang.IllegalArgumentException - if the two values are not compatible.

getMaximum

public abstract int getMaximum()

Get the maximum number of values required for this property. The result from this method will be equal to or greater than zero.

Returns:

the maximum number of property values required.

isOrdered

public boolean isOrdered()

Return whether the multiplicity is defined as requiring an order.

Returns:

true if the instances order is important.

isUnique

public boolean isUnique()

Return whether the multiplicity is defined as requiring uniqueness.

Returns:

true if the instances uniqueness is important.

getMinimum

public abstract int getMinimum()

Get the minimum number of values required for this property. The result from this method will be equal to or greater than zero.

Returns:

the minimum number of property values required.

isIncluded

public abstract boolean isIncluded(int cardinality)

Determine whether the specified cardinality is included in this multiplicity expression.

Returns:

true if the cardinality is included in the range of allowable values for this multiplicity.

isUnlimited

public abstract boolean isUnlimited()

Obtain whether the multiplicity has a maximum value that is unlimited.

Returns:

true if the maximum value of this multiplicity is unlimited.

toString

public abstract java.lang.String toString()

Returns a string representing the current state of the object.

Overrides:

toString in class java.lang.Object

Returns:

the string representation of this instance.

compareTo

public abstract int compareTo(java.lang.Object obj)

Compares this object to another. If the specified object is an instance of the MetaMatrixSessionID class, then this method compares the contents; otherwise, it throws a ClassCastException (as instances are comparable only to instances of the same class).

Note: this method is consistent with equals(), meaning that (compare(x, y)==0) == (x.equals(y)).

Specified by:

compareTo in interface java.lang.Comparable

Parameters:

obj - the object that this instance is to be compared to.

Returns:

a negative integer, zero, or a positive integer as this object is less than, equal to, or greater than the specified object, respectively.

Throws:

java.lang.IllegalArgumentException - if the specified object reference is null

java.lang.ClassCastException - if the specified object's type prevents it from being compared to this instance.

compareFlags

protected int compareFlags(Multiplicity that)