API and JavaDoc changes for Spatial Datatypes

src/main/java/com/microsoft/sqlserver/jdbc/Geography.java

@@ -5,34 +5,42 @@
 
 package com.microsoft.sqlserver.jdbc;
 
+import java.nio.BufferUnderflowException;
 import java.nio.ByteBuffer;
 import java.nio.ByteOrder;
 
 
+/**
+ * Geography datatype represents data in a round-earth coordinate system.
+ */
+
 public class Geography extends SQLServerSpatialDatatype {
 
     /**
-     * Private constructor used for creating a Geography object from WKT and srid.
+     * Private constructor used for creating a Geography object from WKT and Spatial Reference Identifier.
      * 
-     * @param WellKnownText
+     * @param wkt
      *        Well-Known Text (WKT) provided by the user.
      * @param srid
      *        Spatial Reference Identifier (SRID) provided by the user.
      * @throws SQLServerException
      *         if an exception occurs
      */
-    private Geography(String WellKnownText, int srid) throws SQLServerException {
-        this.wkt = WellKnownText;
+    private Geography(String wkt, int srid) throws SQLServerException {
+        if (null == wkt || wkt.length() <= 0) {
+            throwIllegalWKT();
+        }
+
+        this.wkt = wkt;
         this.srid = srid;
 
         try {
             parseWKTForSerialization(this, currentWktPos, -1, false);
         } catch (StringIndexOutOfBoundsException e) {
-            String strError = SQLServerException.getErrString("R_illegalWKT");
-            throw new SQLServerException(strError, null, 0, null);
+            throwIllegalWKT();
         }
 
-        serializeToWkb(false);
+        serializeToWkb(false, this);
         isNull = false;
     }
 
@@ -45,11 +53,19 @@ private Geography(String WellKnownText, int srid) throws SQLServerException {
      *         if an exception occurs
      */
     private Geography(byte[] wkb) throws SQLServerException {
+        if (null == wkb || wkb.length <= 0) {
+            throwIllegalWKB();
+        }
+
         this.wkb = wkb;
         buffer = ByteBuffer.wrap(wkb);
         buffer.order(ByteOrder.LITTLE_ENDIAN);
 
-        parseWkb();
+        try {
+            parseWkb(this);
+        } catch (BufferUnderflowException e) {
+            throwIllegalWKB();
+        }
 
         WKTsb = new StringBuffer();
         WKTsbNoZM = new StringBuffer();
@@ -62,8 +78,8 @@ private Geography(byte[] wkb) throws SQLServerException {
     }
 
     /**
-     * Returns a Geography instance from an Open Geospatial Consortium (OGC) Well-Known Text (WKT) representation
-     * augmented with any Z (elevation) and M (measure) values carried by the instance.
+     * Constructor for a Geography instance from an Open Geospatial Consortium (OGC) Well-Known Text (WKT)
+     * representation augmented with any Z (elevation) and M (measure) values carried by the instance.
      * 
      * @param wkt
      *        Well-Known Text (WKT) provided by the user.
@@ -78,7 +94,8 @@ public static Geography STGeomFromText(String wkt, int srid) throws SQLServerExc
     }
 
     /**
-     * Returns a Geography instance from an Open Geospatial Consortium (OGC) Well-Known Binary (WKB) representation.
+     * Constructor for a Geography instance from an Open Geospatial Consortium (OGC) Well-Known Binary (WKB)
+     * representation.
      * 
      * @param wkb
      *        Well-Known Binary (WKB) provided by the user.
@@ -91,7 +108,7 @@ public static Geography STGeomFromWKB(byte[] wkb) throws SQLServerException {
     }
 
     /**
-     * Returns a constructed Geography from an internal SQL Server format for spatial data.
+     * Constructor for a Geography instance from an internal SQL Server format for spatial data.
      * 
      * @param wkb
      *        Well-Known Binary (WKB) provided by the user.
@@ -104,8 +121,8 @@ public static Geography deserialize(byte[] wkb) throws SQLServerException {
     }
 
     /**
-     * Returns a Geography instance from an Open Geospatial Consortium (OGC) Well-Known Text (WKT) representation. SRID
-     * is defaulted to 4326.
+     * Constructor for a Geography instance from an Open Geospatial Consortium (OGC) Well-Known Text (WKT)
+     * representation. Spatial Reference Identifier is defaulted to 4326.
      * 
      * @param wkt
      *        Well-Known Text (WKT) provided by the user.
@@ -118,20 +135,21 @@ public static Geography parse(String wkt) throws SQLServerException {
     }
 
     /**
-     * Constructs a Geography instance that represents a Point instance from its X and Y values and an SRID.
+     * Constructor for a Geography instance that represents a Point instance from its latitude and longitude values and
+     * a Spatial Reference Identifier.
      * 
-     * @param x
-     *        x coordinate
-     * @param y
-     *        y coordinate
+     * @param lat
+     *        latitude
+     * @param lon
+     *        longitude
      * @param srid
-     *        SRID
+     *        Spatial Reference Identifier value
      * @return Geography Geography instance
      * @throws SQLServerException
      *         if an exception occurs
      */
-    public static Geography point(double x, double y, int srid) throws SQLServerException {
-        return new Geography("POINT (" + x + " " + y + ")", srid);
+    public static Geography point(double lat, double lon, int srid) throws SQLServerException {
+        return new Geography("POINT (" + lat + " " + lon + ")", srid);
     }
 
     /**
@@ -147,7 +165,7 @@ public String STAsText() throws SQLServerException {
             buffer = ByteBuffer.wrap(wkb);
             buffer.order(ByteOrder.LITTLE_ENDIAN);
 
-            parseWkb();
+            parseWkb(this);
 
             WKTsb = new StringBuffer();
             WKTsbNoZM = new StringBuffer();
@@ -165,7 +183,7 @@ public String STAsText() throws SQLServerException {
      */
     public byte[] STAsBinary() {
         if (null == wkbNoZM) {
-            serializeToWkb(true);
+            serializeToWkb(true, this);
         }
         return wkbNoZM;
     }
@@ -198,25 +216,25 @@ public boolean hasZ() {
     }
 
     /**
-     * Returns the X coordinate value.
+     * Returns the latitude value.
      * 
-     * @return double value that represents the X coordinate.
+     * @return double value that represents the latitude.
      */
-    public Double getX() {
-        if (null != internalType && internalType == InternalSpatialDatatype.POINT && points.length == 2) {
-            return points[0];
+    public Double getLatitude() {
+        if (null != internalType && internalType == InternalSpatialDatatype.POINT && xValues.length == 1) {
+            return xValues[0];
         }
         return null;
     }
 
     /**
-     * Returns the Y coordinate value.
+     * Returns the longitude value.
      * 
-     * @return double value that represents the Y coordinate.
+     * @return double value that represents the longitude.
      */
-    public Double getY() {
-        if (null != internalType && internalType == InternalSpatialDatatype.POINT && points.length == 2) {
-            return points[1];
+    public Double getLongitude() {
+        if (null != internalType && internalType == InternalSpatialDatatype.POINT && yValues.length == 1) {
+            return yValues[0];
         }
         return null;
     }
@@ -302,111 +320,4 @@ public String asTextZM() {
     public String toString() {
         return wkt;
     }
-
-    protected void serializeToWkb(boolean noZM) {
-        ByteBuffer buf = ByteBuffer.allocate(determineWkbCapacity());
-        createSerializationProperties();
-
-        buf.order(ByteOrder.LITTLE_ENDIAN);
-        buf.putInt(srid);
-        buf.put(version);
-        buf.put(serializationProperties);
-
-        if (!isSinglePoint && !isSingleLineSegment) {
-            buf.putInt(numberOfPoints);
-        }
-
-        for (int i = 0; i < numberOfPoints; i++) {
-            buf.putDouble(points[2 * i + 1]);
-            buf.putDouble(points[2 * i]);
-        }
-
-        if (!noZM) {
-            if (hasZvalues) {
-                for (int i = 0; i < numberOfPoints; i++) {
-                    buf.putDouble(zValues[i]);
-                }
-            }
-            if (hasMvalues) {
-                for (int i = 0; i < numberOfPoints; i++) {
-                    buf.putDouble(mValues[i]);
-                }
-            }
-        }
-
-        if (isSinglePoint || isSingleLineSegment) {
-            wkb = buf.array();
-            return;
-        }
-
-        buf.putInt(numberOfFigures);
-        for (int i = 0; i < numberOfFigures; i++) {
-            buf.put(figures[i].getFiguresAttribute());
-            buf.putInt(figures[i].getPointOffset());
-        }
-
-        buf.putInt(numberOfShapes);
-        for (int i = 0; i < numberOfShapes; i++) {
-            buf.putInt(shapes[i].getParentOffset());
-            buf.putInt(shapes[i].getFigureOffset());
-            buf.put(shapes[i].getOpenGISType());
-        }
-
-        if (version == 2 && null != segments) {
-            buf.putInt(numberOfSegments);
-            for (int i = 0; i < numberOfSegments; i++) {
-                buf.put(segments[i].getSegmentType());
-            }
-        }
-
-        if (noZM) {
-            wkbNoZM = buf.array();
-        } else {
-            wkb = buf.array();
-
-        }
-        return;
-    }
-
-    protected void parseWkb() {
-        srid = buffer.getInt();
-        version = buffer.get();
-        serializationProperties = buffer.get();
-
-        interpretSerializationPropBytes();
-        readNumberOfPoints();
-        readPoints();
-
-        if (hasZvalues) {
-            readZvalues();
-        }
-
-        if (hasMvalues) {
-            readMvalues();
-        }
-
-        if (!(isSinglePoint || isSingleLineSegment)) {
-            readNumberOfFigures();
-            readFigures();
-            readNumberOfShapes();
-            readShapes();
-        }
-
-        determineInternalType();
-
-        if (buffer.hasRemaining()) {
-            if (version == 2 && internalType.getTypeCode() != 8 && internalType.getTypeCode() != 11) {
-                readNumberOfSegments();
-                readSegments();
-            }
-        }
-    }
-
-    private void readPoints() {
-        points = new double[2 * numberOfPoints];
-        for (int i = 0; i < numberOfPoints; i++) {
-            points[2 * i + 1] = buffer.getDouble();
-            points[2 * i] = buffer.getDouble();
-        }
-    }
-}
+}