Module org.opengis.geoapi

Package org.opengis.geometry

Interface DirectPosition

All Superinterfaces:

Position

@Classifier(DATATYPE)
@UML(identifier="DirectPosition",
     specification=ISO_19107)
public interface DirectPosition
extends Position

Holds the coordinates for a position within some coordinate reference system. Since DirectPositions, as data types, will often be included in larger objects (such as geometries) that have references to coordinate reference system (CRS), the getCoordinateReferenceSystem() method may return null if this particular DirectPosition is included in a larger object with such a reference to a CRS. In this case, the coordinate reference system is implicitly assumed to take on the value of the containing object's CRS.

Optional operation

A direct position can optionally be modifiable. If this DirectPosition is unmodifiable, then all setter methods will throw UnsupportedOperationException.

Since:

1.0

Convenience extension to OGC/ISO standard

The ISO specification defines this interface in the coordinate sub-package. GeoAPI moved this interface into the org.opengis.geometry root package for convenience, because it is extensively used.

Method Summary

Modifier and Type	Method	Description
boolean	equals(Object object)	Compares this direct position with the specified object for equality.
default double[]	getCoordinate()	Deprecated, for removal: This API element is subject to removal in a future version. Renamed getCoordinates().
double	getCoordinate(int dimension)	Returns the coordinate at the specified dimension.
default CoordinateReferenceSystem	getCoordinateReferenceSystem()	The coordinate reference system (CRS) in which the coordinate tuple is given.
default double[]	getCoordinates()	A copy of the coordinates stored as an array of double values.
int	getDimension()	The length of coordinate sequence (the number of entries).
default DirectPosition	getDirectPosition()	Deprecated. This method is inherited from GM_Position, which has been removed in ISO 19107:2019.
default double	getOrdinate(int dimension)	Deprecated. Renamed getCoordinate(int).
int	hashCode()	Returns a hash code value for this direct position.
default void	setCoordinate(int dimension, double value)	Sets the coordinate value along the specified dimension.
default void	setOrdinate(int dimension, double value)	Deprecated. Renamed setCoordinate(int, double).

Method Details

getDirectPosition

@Deprecated(since="3.1")
default DirectPosition getDirectPosition()

Deprecated.

This method is inherited from GM_Position, which has been removed in ISO 19107:2019.

Returns this direct position.

Specified by:

getDirectPosition in interface Position

Returns:

this (usually).

getCoordinateReferenceSystem

@UML(identifier="coordinateReferenceSystem",
     obligation=MANDATORY,
     specification=ISO_19107)
default CoordinateReferenceSystem getCoordinateReferenceSystem()

The coordinate reference system (CRS) in which the coordinate tuple is given. May be null if this particular DirectPosition is included in a larger object with such a reference to a coordinate reference system. In this case, the coordinate reference system is implicitly assumed to take on the value of the containing object's CRS.

Default implementation

The default implementation returns null. Implementations should override this method if the CRS is known or can be taken from the containing object.

Returns:

the coordinate reference system (CRS), or null.

getDimension

@UML(identifier="dimension",
     obligation=MANDATORY,
     specification=ISO_19107)
int getDimension()

The length of coordinate sequence (the number of entries). This is determined by the coordinate reference system.

Returns:

the dimensionality of this position.

getCoordinates

@UML(identifier="coordinate",
     obligation=MANDATORY,
     specification=ISO_19107)
default double[] getCoordinates()

A copy of the coordinates stored as an array of double values. Changes to the returned array will not affect this DirectPosition. The array length shall be equal to the dimension.

Default implementation

The default implementation invokes getCoordinate(int) for all indices from 0 inclusive to getDimension() exclusive, and stores the values in a newly created array.

Returns:

a copy of the coordinates. Changes in the returned array will not be reflected back in this DirectPosition object.

Since:

3.1

getCoordinate

@Deprecated(since="3.1",
            forRemoval=true)
default double[] getCoordinate()

Deprecated, for removal: This API element is subject to removal in a future version.

Renamed getCoordinates(). To be removed because of the risk of confusion with getCoordinate(int).

A copy of the coordinates presented as an array of double values.

Returns:

a copy of the coordinates. Changes in the returned array will not be reflected back in this DirectPosition object.

getCoordinate

double getCoordinate(int dimension)

Returns the coordinate at the specified dimension.

Parameters:

dimension - the dimension in the range 0 to dimension−1.

Returns:

the coordinate at the specified dimension.

Throws:

IndexOutOfBoundsException - if the given index is negative or is equal or greater than the number of dimensions.

Since:

3.1

getOrdinate

@Deprecated(since="3.1")
default double getOrdinate(int dimension)
                    throws IndexOutOfBoundsException

Deprecated.

Renamed getCoordinate(int).

Returns the coordinate at the specified dimension.

Parameters:

dimension - the dimension in the range 0 to dimension−1.

Returns:

the coordinate at the specified dimension.

Throws:

IndexOutOfBoundsException - if the given index is negative or is equal or greater than the number of dimensions.

setCoordinate

default void setCoordinate(int dimension,
 double value)

Sets the coordinate value along the specified dimension. This is an optional operation.

Default implementation

The default implementation throws UnsupportedOperationException. Implementations need to override this method if this direct position is mutable.

Parameters:

dimension - the dimension for the coordinate of interest.

value - the coordinate value of interest.

Throws:

IndexOutOfBoundsException - if the given index is negative or is equal or greater than the position dimension.

UnsupportedOperationException - if this direct position is immutable.

Since:

3.1

setOrdinate

@Deprecated(since="3.1")
default void setOrdinate(int dimension,
 double value)
                  throws IndexOutOfBoundsException,
UnsupportedOperationException

Deprecated.

Renamed setCoordinate(int, double).

Sets the coordinate value along the specified dimension.

Parameters:

dimension - the dimension for the coordinate of interest.

value - the coordinate value of interest.

Throws:

IndexOutOfBoundsException - if the given index is negative or is equal or greater than the position dimension.

UnsupportedOperationException - if this direct position is immutable.

equals

boolean equals(Object object)

Compares this direct position with the specified object for equality. Two direct positions are considered equal if the following conditions are met:

• object is non-null and is an instance of DirectPosition.
• Both direct positions have the same number of dimensions.
• Both direct positions have the same or equal coordinate reference system.
• For all dimension i, the coordinate value of both direct positions at that dimension are equals in the sense of Double.equals(Object).

In other words, this method shall be equivalent to the following code:

public boolean equals(Object obj) {
    return (obj instanceof DirectPosition other)
            && Arrays.equals(getCoordinates(), other.getCoordinates())
            && Objects.equals(getCoordinateReferenceSystem(), other.getCoordinateReferenceSystem());
}

Overrides:

equals in class Object

Parameters:

object - the object to compare with this direct position for equality.

Returns:

true if the given object is equal to this direct position.

hashCode

int hashCode()

Returns a hash code value for this direct position. This method shall be equivalent to the following code:

public int hashCode() {
    return Arrays.hashCode(getCoordinates()) + Objects.hashCode(getCoordinateReferenceSystem());
}

Overrides:

hashCode in class Object

Returns:

a hash code value for this direct position.