org.osid.binding.java

Interface Coordinate

All Superinterfaces:

java.lang.Comparable<Coordinate>, OsidPrimitive, java.io.Serializable

All Known Subinterfaces:

Coordinate

public interface Coordinate
extends OsidPrimitive, java.lang.Comparable<Coordinate>

Supplements the OSID Coordinate interface for Java.

Method Summary

Methods

Modifier and Type	Method and Description
int	compareTo(Coordinate coordinate) Compares this coordinate with the specified Coordinate to determine the natural order.
boolean	equals(java.lang.Object obj) Determines if the given Coordinate is equal to this one.
Coordinate	getClosestBound() Gets the closest bound of the coordinate.
Coordinate	getFarthestBound() Gets the farthest bound of the coordinate.
SpatialUnit	getOuterBound() Gets the outer bound of the coordinate.
int	hashCode() Returns a hash code value for this Coordinate.
boolean	isCloser(Coordinate one, Coordinate another) Tests if one Coordinate is closer to origin than another to this Coordinate.
boolean	isExclusive(Coordinate coordinate) Tests if this Coordinate, as specified by its uncertainty, does not overlap the given Coordinate.
boolean	isFarther(Coordinate one, Coordinate another) Tests if one Coordinate is farther from origin than another from this Coordinate.
boolean	isInclusive(Coordinate coordinate) Tests if this Coordinate, as specified by its uncertainty, completely includes the given Coordinate ranged by its uncertainty.
boolean	isLarger(Coordinate coordinate) Tests if this Coordinate is greater in area than the given Coordinate.
boolean	isSmaller(Coordinate coordinate) Tests if this Coordinate is less in area than the given Coordinate.

Methods inherited from interface org.osid.binding.java.OsidPrimitive

toString

Method Detail

isLarger

boolean isLarger(Coordinate coordinate)

Tests if this Coordinate is greater in area than the given Coordinate. A greater Coordinate is one whose values minus uncertainty is greater than another plus its uncertainty. An uncertainty of infinity is undefined and returns false. It is possible for isLarger(), isSmaller(), and equals() to be all false among two Coordinates due to uncertainties in the values. In this case, compareTo() may elect to return a value to provide a natural ordering but should not be used to determine equality. equals() tends to have a stricter definition of equality.

Parameters:

coordinate - the coordinate to compare

Returns:

true if this coordinate is larger, false otherwise

Throws:

NullArgumentException - coordinate is null

UnsupportedException - cannot compare coordinate

isSmaller

boolean isSmaller(Coordinate coordinate)

Tests if this Coordinate is less in area than the given Coordinate. A lesser Coordinate is one whose values plus uncertainty is less than another minus its uncertainty. An uncertainty of infinity is undefined and returns false. It is possible for isLarger(), isSmaller(), and equals() to be all false among two Coordinates due to uncertainties in the values. In this case, compareTo() may elect to return a value to provide a natural ordering but should not be used to determine equality. equals() tends to have a stricter definition of equality.

Parameters:

coordinate - the coordinate to compare

Returns:

true if this coordinate is less, false otherwise

Throws:

NullArgumentException - coordinate is null

UnsupportedException - cannot compare coordinate

isCloser

boolean isCloser(Coordinate one,
               Coordinate another)

Tests if one Coordinate is closer to origin than another to this Coordinate. A greater Coordinate is one whose values minus uncertainty is greater than another plus its uncertainty. An uncertainty of infinity is undefined and returns false. It is possible for isCloser() and isFarther() to be both false among two Coordinates due to uncertainties in the values.

Parameters:

one - the coordinate to compare

another - the coordinate to compare

Returns:

true if this one is closer than another, false otherwise

Throws:

NullArgumentException - one or another is null

UnsupportedException - cannot compare coordinate

isFarther

boolean isFarther(Coordinate one,
                Coordinate another)

Tests if one Coordinate is farther from origin than another from this Coordinate. A greater Coordinate is one whose values minus uncertainty is greater than another plus its uncertainty. An uncertainty of infinity is undefined and returns false. It is possible for isCloser() and isFarther() to be both false among two Coordinates due to uncertainties in the values.

Parameters:

one - the coordinate to compare

another - the coordinate to compare

Returns:

true if this one is closer than another, false otherwise

Throws:

NullArgumentException - one or another is null

UnsupportedException - cannot compare coordinate

isInclusive

boolean isInclusive(Coordinate coordinate)

Tests if this Coordinate, as specified by its uncertainty, completely includes the given Coordinate ranged by its uncertainty. If either coordinate has an uncertainty of infinity this method returns false. It is possible for isInclusive() and isExclsuive() to be both false among two Coordinates due to uncertainties in the values.

Parameters:

coordinate - the coordinate to compare

Returns:

true if this coordinate includes the given coordinate, false otherwise

Throws:

NullArgumentException - coordinate is null

UnsupportedException - cannot compare coordinate

isExclusive

boolean isExclusive(Coordinate coordinate)

Tests if this Coordinate, as specified by its uncertainty, does not overlap the given Coordinate. If either coordinate has an uncertainty of infinity this method returns false. It is possible for isInclusive() and isExclsuive() to be both false among two Coordinates due to uncertainties in the values.

Parameters:

coordinate - the coordinate to compare

Returns:

true if this coordinate is excluded, false otherwise

Throws:

NullArgumentException - coordinate is null

UnsupportedException - cannot compare coordinate

getOuterBound

SpatialUnit getOuterBound()

Gets the outer bound of the coordinate. The outer bound is the coordinate plus the uncertainty. This method returns the area around the Coordinate with the largest radius allowed by its uncertainty.

Returns:

the coordinate upper bound

getClosestBound

Coordinate getClosestBound()

Gets the closest bound of the coordinate. The closest bound is the coordinate of the same granularity in the uncertainty range closest to the origin.

Returns:

the coordinate lower bound

getFarthestBound

Coordinate getFarthestBound()

Gets the farthest bound of the coordinate. The farthest bound is the coordinate of the same granularity in the uncertainty range farthest from the origin.

Returns:

the coordinate upper bound

compareTo

int compareTo(Coordinate coordinate)

Compares this coordinate with the specified Coordinate to determine the natural order. Returns a negative integer, zero, or a positive integer as this coordinate is less than, equal to, or greater than the specified coordinate. The natural ordering is determined first by the natural ordering of the coordinate type, then by its values. This method is not useful for numeric comparisons. The ranges implied by their granularities and uncertainties may overlap in such a way that two unequal Coordinates may be neither less than or greater than the other. If compareTo a coordinate is zero, then equals() must be true and their hash codes must also be equal for consistent behavior. For orderings that may yield inconsistent behavior, an external Comparator should be used.

Specified by:

compareTo in interface java.lang.Comparable<Coordinate>

Parameters:

coordinate - the coordinate to be compared

Returns:

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

Throws:

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

equals

boolean equals(java.lang.Object obj)

Determines if the given Coordinate is equal to this one. Two Coordinates are equal if their coordinate types, values, and uncertainties are equal. If equals() is true, then compareTo() must be zero and their hash codes must also be equal for consistent behavior. For orderings that may yield inconsistent behavior, an external Comparator should be used. If obj is null or if a different interface, this method returns false.

Overrides:

equals in class java.lang.Object

Parameters:

obj - an object to compare

Returns:

true if the given object is equal to this Coordinate, false otherwise

hashCode

int hashCode()

Returns a hash code value for this Coordinate. The hash code is determined by the coordinate type, values, and uncertainty.

Overrides:

hashCode in class java.lang.Object

Returns:

a hash code value for this object