com.rubecula.jquantity
Class Item

java.lang.Object
  com.rubecula.jquantity.Item

All Implemented Interfaces:

Auditable, java.lang.Comparable, Identifiable, Presentable, java.io.Serializable

Direct Known Subclasses:

BaseNumber, BaseUnit, Complex

public abstract class Item

extends java.lang.Object

implements Presentable, Auditable, java.lang.Comparable, java.io.Serializable

Abstract base class from which to derive other more concrete classes. This class provides support for the Presentable, Auditable, Comparable and Serializable interfaces.
Instances of sub-classes can be "presented", resulting in an instance of Presentation (which in turn can be rendered as a string).
This class provides no numerical logic - it is simply a slightly more intelligent and potentially persistent extension of Object.

Since:

V_0_3

Version:

$Revision: 1.8 $

Author:

Robin Hillyard

See Also:

Serialized Form

Field Summary

private static java.lang.String	$LEFT_ARROW Constant String representing left arrow.
private static java.lang.String	$RIGHT_ARROW Constant String representing right arrow.
private static boolean	DEBUG Private Class Field which records whether the DEBUG flag is set.
static java.lang.String	JQUANTITY_TEST Constant String for the relative path of the test directory.

Constructor Summary

Item()

Method Summary

java.lang.String	audit() Method to return a detailed (unlabeled) string from an object for debugging purposes.
void	audit(java.io.PrintStream out, java.lang.String label) Method to output detailed string from an object for debugging purposes.
int	compareTo(java.lang.Object that) This method is the default compareTo method for Items (most of the classes in the JQuantity package extend Item).
protected static void	Debug(java.lang.String string) protected class method to print string to System.out if debug mode is set.
protected java.lang.String	getClassNameShort() Method to yield the shortened name of this Class.
java.lang.String	getType() This method is primarily for development purposes: it yields the name of the class of the presentable object or, in some cases, the class of the presentable object indirectly referenced.
protected static boolean	IsDebug() Method to get the debug status.
Presentation	present() Convert this Presentable object into a Presentation with default attributes.
protected static void	SetDebug(boolean debug) Method to set the debug status.
protected void	test(java.io.PrintStream out, Item check) Protected method to test an Item by passing it to audit(java.io.PrintStream,String), comparing it to another item, reporting the result.
protected void	test(java.io.PrintStream out, Item check, java.lang.String label) Protected method to test an Item by passing it to audit(java.io.PrintStream,String), comparing it to another item, reporting the result.
java.lang.String	toString() This is the default toString method for all Items.
protected static java.lang.String	Wrap(java.lang.String string) Class method to wrap a string in $LEFT_ARROW and $RIGHT_ARROW.

Methods inherited from class java.lang.Object

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

Methods inherited from interface com.rubecula.util.Presentable

makePresentableInstance, present

Methods inherited from interface com.rubecula.util.Auditable

audit

Methods inherited from interface com.rubecula.util.Identifiable

getIdentifier

Field Detail

DEBUG

private static boolean DEBUG

Private Class Field which records whether the DEBUG flag is set. Initial value: false.

JQUANTITY_TEST

public static final java.lang.String JQUANTITY_TEST

Constant String for the relative path of the test directory. Value: jquantity/test

See Also:

Constant Field Values

$RIGHT_ARROW

private static final java.lang.String $RIGHT_ARROW

Constant String representing right arrow. Value: >

See Also:

Constant Field Values

$LEFT_ARROW

private static final java.lang.String $LEFT_ARROW

Constant String representing left arrow. Value: <

See Also:

Constant Field Values

Constructor Detail

Item

public Item()

Method Detail

Wrap

protected static java.lang.String Wrap(java.lang.String string)

Class method to wrap a string in $LEFT_ARROW and $RIGHT_ARROW. Note: this method relates to the Auditable class and would be defined there if that was legal.

Parameters:

string - the string to be wrapped.

Returns:

string wrapped in "<>".

compareTo

public int compareTo(java.lang.Object that)

This method is the default compareTo method for Items (most of the classes in the JQuantity package extend Item). If it is invoked, then there was no method declared which matched the objects more precisely. Each subclass (A) of Item is expected to declare a method of signature int compareTo(A). Furthermore, any subclass (A) of a class (B) which is itself a subclass of Item should provide a public constructor with signature: A(B).

So why is this method necessary at all? Surely polymporphism takes care of all this stuff? Well, not quite. First of all, the jquantity package is complex because it involves so many apparently unrelated classes and interfaces, which nevertheless are directly comparable (for example, Manifest and WholeNumber). Second, there is always the danger of coding infinite recursions in the individual compareTo(Object) methods. Thirdly, there is the fact that it is impossible in general to ensure that the "that" object is in any sense more primitive than the "this" object. Frequently, it will be the other way around, in which case the comparison must be reversed.

There are four possibilities for the relationship between the classes of this and that:

1. this isa that-class and that isa this-class, i.e. the classes are the same;
2. this isa that-class (but not that isa this-class);
3. that isa this-class (but not this isa that-class);
4. neither this isa that-class nor that isa this-class.

For case 1, it is expected for any subclass (A) of Item that there is defined a method int compareTo(A). In case 2, it may be possible to widen that into this-class and then perform the comparison. In case 3, it may be possible to compare the objects in the opposite ordering: i.e. to evaluate
- that.compareTo(this). In case 4, there is nothing to be done - no comparison is valid, unless explicitly provided for in this-class - or if that implements an interface such that there is defined in this-class a method int compareTo(interface).

Note also that extenders of this class should implement int compareTo(A) in such a way that if the objects to be compared are equal (in the sense of this.equals(that)) then 0 should be returned without further ado. Also note that since the methods isEqual(that) typically invoke compareTo, a compareTo method must not invoke isEqual.

The following is the standard javadoc for the compareTo(Object) method as defined in the Comparable interface:
Compares this object with the specified object for order. Returns a negative integer, zero, or a positive integer as this object is less than, equal to, or greater than the specified object.

The implementor must ensure sgn(x.compareTo(y)) == -sgn(y.compareTo(x)) for all x and y. (This implies that x.compareTo(y) must throw an exception iff y.compareTo(x) throws an exception.)

The implementor must also ensure that the relation is transitive: (x.compareTo(y)>0 && y.compareTo(z)>0) implies x.compareTo(z)>0.

Finally, the implementer must ensure that x.compareTo(y)==0 implies that sgn(x.compareTo(z)) == sgn(y.compareTo(z)), for all z.

It is strongly recommended, but not strictly required that (x.compareTo(y)==0) == (x.equals(y)). Generally speaking, any class that implements the Comparable interface and violates this condition should clearly indicate this fact. The recommended language is "Note: this class has a natural ordering that is inconsistent with equals."

Specified by:

compareTo in interface java.lang.Comparable

Parameters:

that - the Object to be compared.

Returns:

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

Throws:

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

See Also:

Object.getClass(), Class.isInstance(java.lang.Object), Class.getName(), Class.getSuperclass(), Method.invoke(java.lang.Object, java.lang.Object[]), Integer.intValue(), IllegalAccessException, InvocationTargetException, InvocationTargetException.getTargetException(), NoSuchMethodException, Class.getConstructor(java.lang.Class[]), Constructor.newInstance(java.lang.Object[])

present

public Presentation present()
                     throws PresentationException

Convert this Presentable object into a Presentation with default attributes.

Returns:

an appropriate instance of Presentation.

Throws:

PresentationException - if this object cannot be presented with given attributes.

See Also:

Presentable.present(AttrMap), AttrMap.AttrMap()

getType

public java.lang.String getType()

This method is primarily for development purposes: it yields the name of the class of the presentable object or, in some cases, the class of the presentable object indirectly referenced. The text returned is short class name (subclasses may choose to override this).

Specified by:

getType in interface Presentable

Returns:

a representation of the effective class of this object.

See Also:

getClassNameShort()

audit

public java.lang.String audit()

Method to return a detailed (unlabeled) string from an object for debugging purposes.

Specified by:

audit in interface Auditable

Returns:

the detailed string.

See Also:

Auditable.audit(String)

audit

public void audit(java.io.PrintStream out,
                  java.lang.String label)

Method to output detailed string from an object for debugging purposes.

Specified by:

audit in interface Auditable

Parameters:

out - the output stream.

label - the label to attach to the output (may be null).

See Also:

Auditable.audit(String), getClassNameShort(), PrintStream.println(String)

toString

public java.lang.String toString()

This is the default toString method for all Items. Specific classes will override as appropriate.

Returns:

a String representing this Item by first converting it to a Presentation and then rendering that with no length constraint.

See Also:

present(), Presentation.toString()

test

protected final void test(java.io.PrintStream out,
                          Item check,
                          java.lang.String label)

Protected method to test an Item by

• passing it to audit(java.io.PrintStream,String),
• comparing it to another item,
• reporting the result.

Parameters:

out - whither the output

check - Item to compare against

label - label to use for the audit

See Also:

audit(PrintStream, String), compareTo(Object), PrintStream.println(java.lang.String)

test

protected final void test(java.io.PrintStream out,
                          Item check)

Protected method to test an Item by

• passing it to audit(java.io.PrintStream,String),
• comparing it to another item,
• reporting the result.

The label used for the audit will be: compare with check:

Parameters:

out - whither the output

check - Item to compare against

See Also:

test(PrintStream, Item, String), Identifiable.getIdentifier()

getClassNameShort

protected java.lang.String getClassNameShort()

Method to yield the shortened name of this Class.

Returns:

the canonical class name (result of getClass().toString()), but having removed all the characters up to and including the final period.

See Also:

Object.getClass(), Class.toString(), String.lastIndexOf(int), String.substring(int)

SetDebug

protected static void SetDebug(boolean debug)

Method to set the debug status.

Parameters:

debug - true or false.

See Also:

DEBUG

IsDebug

protected static boolean IsDebug()

Method to get the debug status.

Returns:

current debug status.

See Also:

DEBUG

Debug

protected static void Debug(java.lang.String string)

protected class method to print string to System.out if debug mode is set.

Parameters:

string - the string to be output for logging/debugging

See Also:

DEBUG, System.out, PrintStream.println(java.lang.String)