Package org.voltdb.types

Class GeographyValue

java.lang.Object
org.voltdb.types.GeographyValue
public class GeographyValue extends Object
The Java class used to represent data with the SQL type GEOGRAPHY. For now, this means polygons, but may include other kinds of geospatial types in the future.

  • Field Details

    • DEFAULT_LENGTH

      public static final int DEFAULT_LENGTH
      The default length (in bytes) for a column with type GEOGRAPHY, if no length is specified.
      See Also:

    • MIN_SERIALIZED_LENGTH

      public static final int MIN_SERIALIZED_LENGTH
      The minimum-allowed length (in bytes) for a column with type GEOGRAPHY. This is the length of a polygon with just three vertices.
      See Also:

    • MAX_SERIALIZED_LENGTH

      public static final int MAX_SERIALIZED_LENGTH
      The maximum-allowed length (in bytes) for a column with type GEOGRAPHY. This is the usual max column length.
      See Also:

  • Constructor Details

    • GeographyValue

      public GeographyValue(List<List<GeographyPointValue>> rings)
      Create a polygon from a list of rings. Each ring is a list of points:
      1. The first ring in the list is the outer ring, also known as the shell.
      2. Subsequent rings should be inside of the outer ring and represent "holes" in the polygon.
      3. The shell should have its vertices listed in counter-clockwise order, so that the area inside the ring is on the left side of the line segments formed by adjacent vertices.
      4. Each hole, or inner ring, should have its vertices listed in clockwise order, so that the area inside the ring (the "hole") is on the right side of the line segments formed by adjacent vertices.
      Note that this is the same as the order expected by the OGC standard's Well-Known Text format. Note also that the rings here are lists of GeographyPointValues, and that they are closed. That is to say, the first vertex and the last vertex must be equal.
      Parameters:
      rings - A list of lists of points that will form a polygon.

    • GeographyValue

      public GeographyValue(String wkt)
      Create a GeographyValue object from an OGC well-known text-formatted string. Currently only polygons can be created via this method. Well-known text format for polygons is composed of the "POLYGON" keyword followed by a list of rings enclosed in parenthesis. For example:

      POLYGON((0 0, 20 0, 20 20, 0 20, 0 0),(5 5, 5 15, 15 15, 15 5, 5 5))

      Each point in a ring is composed of a coordinate of longitude and a coordinate of latitude separated by a space. Note that longitude comes first in this notation. Additional notes about rings:
      1. The first ring in the list is the outer ring, also known as the shell.
      2. Subsequent rings should be inside of the outer ring and represent "holes" in the polygon.
      3. The shell should have its vertices listed in counter-clockwise order, so that the area inside the ring is on the left side of the line segments formed by adjacent vertices.
      4. Each hole, or inner ring, should have its vertices listed in clockwise order, so that the area inside the ring (the "hole") is on the right side of the line segments formed by adjacent vertices.
      5. Each ring must be closed; that is, the last point in the ring must be equal to this first.
      Parameters:
      wkt - A well-known text-formatted string for a polygon.

  • Method Details

    • fromWKT

      public static GeographyValue fromWKT(String text)
      Create a GeographyValue object from a well-known text string. This format is described in the WKT constructor for this class.
      Parameters:
      text - A well-known text string
      Returns:
      A new instance of GeographyValue

    • getRings

      public List<List<GeographyPointValue>> getRings()
      Return the list of rings of a polygon. The list has the same values as the list of rings used to construct the polygon, or the sequence of WKT rings used to construct the polygon.
      Returns:
      A list of rings.

    • toString

      public String toString()
      Return a representation of this object as well-known text.
      Overrides:
      toString in class Object
      Returns:
      A well-known text string for this object.

    • toWKT

      public String toWKT()
      Return a representation of this object as well-known text.
      Returns:
      A well-known text string for this object.

    • equals

      public boolean equals(Object o)
      Overrides:
      equals in class Object

    • getLengthInBytes

      public int getLengthInBytes()
      Return the number of bytes in the serialization for this polygon. Returned value does not include the 4-byte length prefix that precedes variable-length types.
      Returns:
      The number of bytes in the serialization for this polygon.

    • getValueDisplaySize

      public static int getValueDisplaySize(int numBytes)
      Given a column of type GEOGRAPHY(nbytes), return an upper bound on the number of characters needed to represent any entity of this type in WKT.
      Parameters:
      numBytes - The size of the GEOGRAPHY value in bytes
      Returns:
      Upper bound of characters needed for WKT string

    • flattenToBuffer

      public void flattenToBuffer(ByteBuffer buf)
      Serialize this object to a ByteBuffer. (Assumes that the 4-byte length prefix for variable-length data has already been serialized.)
      Parameters:
      buf - The ByteBuffer into which the serialization will be placed.

    • serialize

      public void serialize(DataOutput output) throws IOException
      Serialize this object to a DataOutput

      To be consisitent with flattenToBuffer(ByteBuffer)
      (Assumes that the 4-byte length prefix for variable-length data has already been serialized.)

      Parameters:
      output - into which this object will be serialized
      Throws:
      IOException - if any I/O error occurs

    • unflattenFromBuffer

      public static GeographyValue unflattenFromBuffer(ByteBuffer inBuffer, int offset)
      Deserialize a GeographyValue from a ByteBuffer from an absolute offset. (Assumes that the 4-byte length prefix has already been deserialized, and that offset points to the start of data just after the prefix.)
      Parameters:
      inBuffer - The ByteBuffer from which to read a GeographyValue
      offset - The absolute offset in the ByteBuffer from which to read data
      Returns:
      A new GeographyValue instance.

    • unflattenFromBuffer

      public static GeographyValue unflattenFromBuffer(ByteBuffer inBuffer)
      Deserialize a GeographyValue from a ByteBuffer at the ByteBuffer's current position. (Assumes that the 4-byte length prefix has already been deserialized.)
      Parameters:
      inBuffer - The ByteBuffer from which to read a GeographyValue
      Returns:
      A new GeographyValue instance.

    • add

      @Deprecated public GeographyValue add(GeographyPointValue offset)
      Deprecated.
      Create a new GeographyValue which is offset from this one by the given point. The latitude and longitude values stay in range because we are using the normalizing operations in GeographyPointValue.
      Parameters:
      offset - The point by which to translate vertices in this
      Returns:
      The resulting GeographyValue.