com.franz.agbase
Class GeoExtension

java.lang.Object
  extended by com.franz.agbase.GeoExtension

public class GeoExtension
extends java.lang.Object

This class implements Geospatial Analysis tools.

An AllegroGraph triple store can be used to store geographic locations in a compact and efficiently searchable representation. The methods in this class implement search operations on locations.

This class is instantiated from an AllegroGraph instance with a call to AllegroGraph.getGeoExtension().


Method Summary
 void addCartesianDatatypeMapping(java.lang.String label, GeospatialSubtype subtype)
          Add a predicate mapping for a geospatial subtype encoding.
 void addCartesianPredicateMapping(java.lang.String label, GeospatialSubtype subtype)
          Add a predicate mapping for a geospatial subtype encoding.
 void addSphericalDatatypeMapping(java.lang.String label, GeospatialSubtype subtype)
          Add a predicate mapping for a geospatial subtype encoding.
 void addSphericalPredicateMapping(java.lang.String label, GeospatialSubtype subtype)
          Add a predicate mapping for a geospatial subtype encoding.
 void addSubtype(GeospatialSubtype subtype)
          Associate a GeospatialSubtype with a triple store.
 java.lang.Object[] decodeUPI(UPI upi)
          Decode a geospatial UPI into subtype, longitude and latitude.
 java.lang.Object[] decodeUPIs(UPI[] upi)
          Decode an array of geospatial UPIs into subtype, longitude and latitude arrays.
 UPI encodeUPI(GeospatialSubtype subtype, double longitude, double latitude)
          Create a geospatial UPI instance encoding a location.
 UPI[] encodeUPIs(GeospatialSubtype subtype, double[] longlat)
          Create an array of geospatial UPI instances encoding locations.
 UPI[] encodeUPIs(GeospatialSubtype subtype, double[] longitude, double latitude)
          Create an array of geospatial UPI instances encoding locations.
 UPI[] encodeUPIs(GeospatialSubtype subtype, double[] longitude, double[] latitude)
          Create an array of geospatial UPI instances encoding locations.
 UPI[] encodeUPIs(GeospatialSubtype subtype, double longitude, double[] latitude)
          Create an array of geospatial UPI instances encoding locations.
 TriplesIterator getStatementsInBoundingBox(GeospatialSubtype subtype, java.lang.Object predicate, double xMin, double xMax, double yMin, double yMax, boolean indexedOnly, boolean includeDeleted)
          Find all the triples in some bounding box.
 TriplesIterator getStatementsInHKm(GeospatialSubtype subtype, java.lang.Object predicate, double lon, double lat, double radius, boolean indexedOnly, boolean includeDeleted)
          Find all the triples in a circle.
 TriplesIterator getStatementsInHMiles(GeospatialSubtype subtype, java.lang.Object predicate, double lon, double lat, double radius, boolean indexedOnly, boolean includeDeleted)
          Find all the triples in a circle.
 TriplesIterator getStatementsInHRadians(GeospatialSubtype subtype, java.lang.Object predicate, double lon, double lat, double radius, boolean indexedOnly, boolean includeDeleted)
          Find all the triples in a circle.
 TriplesIterator getStatementsInRadius(GeospatialSubtype subtype, java.lang.Object predicate, double x, double y, double radius, boolean indexedOnly, boolean includeDeleted)
          Find all the triples in a circle.
 GeospatialSubtype[] getSubtypes()
          Query all the geospatial subtypes defined in the triple store.
 GeospatialSubtype registerCartesianStriping(double lonMin, double lonMax, double latMin, double latMax, double stripWidth)
          Register a cartesian striping subtype.
 GeospatialSubtype registerLatitudeStripingInDegrees(double width)
          Register a latitude striping subtype.
 GeospatialSubtype registerLatitudeStripingInDegrees(double width, java.lang.Double latMin, java.lang.Double latMax, java.lang.Double lonMin, java.lang.Double lonMax)
          Register a latitude striping subtype.
 GeospatialSubtype registerLatitudeStripingInKm(double width)
          Register a latitude striping subtype.
 GeospatialSubtype registerLatitudeStripingInKm(double width, java.lang.Double latMin, java.lang.Double latMax, java.lang.Double lonMin, java.lang.Double lonMax)
          Register a latitude striping subtype.
 GeospatialSubtype registerLatitudeStripingInMiles(double width)
          Register a latitude striping subtype.
 GeospatialSubtype registerLatitudeStripingInMiles(double width, java.lang.Double latMin, java.lang.Double latMax, java.lang.Double lonMin, java.lang.Double lonMax)
          Register a latitude striping subtype.
 GeospatialSubtype registerLatitudeStripingInRadians(double width)
          Register a latitude striping subtype.
 GeospatialSubtype registerLatitudeStripingInRadians(double width, java.lang.Double latMin, java.lang.Double latMax, java.lang.Double lonMin, java.lang.Double lonMax)
          Register a latitude striping subtype.
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Method Detail

registerCartesianStriping

public GeospatialSubtype registerCartesianStriping(double lonMin,
                                                   double lonMax,
                                                   double latMin,
                                                   double latMax,
                                                   double stripWidth)
                                            throws AllegroGraphException
Register a cartesian striping subtype.

Parameters:
lonMin -
lonMax -
latMin -
latMax -
stripWidth -
Returns:
a GeospatialSubtype instance
Throws:
AllegroGraphException

getSubtypes

public GeospatialSubtype[] getSubtypes()
                                throws AllegroGraphException
Query all the geospatial subtypes defined in the triple store.

Returns:
an array of GeospatialSubtype instances.
Throws:
AllegroGraphException

registerLatitudeStripingInDegrees

public GeospatialSubtype registerLatitudeStripingInDegrees(double width)
                                                    throws AllegroGraphException
Register a latitude striping subtype.

Parameters:
width - in degrees
Returns:
a GeospatialSubtype instance
Throws:
AllegroGraphException

registerLatitudeStripingInDegrees

public GeospatialSubtype registerLatitudeStripingInDegrees(double width,
                                                           java.lang.Double latMin,
                                                           java.lang.Double latMax,
                                                           java.lang.Double lonMin,
                                                           java.lang.Double lonMax)
                                                    throws AllegroGraphException
Register a latitude striping subtype.

Parameters:
width - width in degrees
latMin - the minimum latitude included in the strip. A null value specifies the built-in default of the server.
latMax - the maximum latitude included in the strip. A null value specifies the built-in default of the server.
lonMin - the minimum longitude included in the strip. A null value specifies the built-in default of the server.
lonMax - the maximum longitude included in the strip. A null value specifies the built-in default of the server.
Returns:
a GeospatialSubtype instance
Throws:
AllegroGraphException

registerLatitudeStripingInMiles

public GeospatialSubtype registerLatitudeStripingInMiles(double width)
                                                  throws AllegroGraphException
Register a latitude striping subtype.

Parameters:
width - in miles
Returns:
a GeospatialSubtype instance
Throws:
AllegroGraphException

registerLatitudeStripingInMiles

public GeospatialSubtype registerLatitudeStripingInMiles(double width,
                                                         java.lang.Double latMin,
                                                         java.lang.Double latMax,
                                                         java.lang.Double lonMin,
                                                         java.lang.Double lonMax)
                                                  throws AllegroGraphException
Register a latitude striping subtype.

Parameters:
width - width in miles
latMin - the minimum latitude included in the strip. A null value specifies the built-in default of the server.
latMax - the maximum latitude included in the strip. A null value specifies the built-in default of the server.
lonMin - the minimum longitude included in the strip. A null value specifies the built-in default of the server.
lonMax - the maximum longitude included in the strip. A null value specifies the built-in default of the server.
Returns:
a GeospatialSubtype instance
Throws:
AllegroGraphException

registerLatitudeStripingInKm

public GeospatialSubtype registerLatitudeStripingInKm(double width)
                                               throws AllegroGraphException
Register a latitude striping subtype.

Parameters:
width - in kilometers
Returns:
a GeospatialSubtype instance
Throws:
AllegroGraphException

registerLatitudeStripingInKm

public GeospatialSubtype registerLatitudeStripingInKm(double width,
                                                      java.lang.Double latMin,
                                                      java.lang.Double latMax,
                                                      java.lang.Double lonMin,
                                                      java.lang.Double lonMax)
                                               throws AllegroGraphException
Register a latitude striping subtype.

Parameters:
width - width in kilometers
latMin - the minimum latitude included in the strip. A null value specifies the built-in default of the server.
latMax - the maximum latitude included in the strip. A null value specifies the built-in default of the server.
lonMin - the minimum longitude included in the strip. A null value specifies the built-in default of the server.
lonMax - the maximum longitude included in the strip. A null value specifies the built-in default of the server.
Returns:
a GeospatialSubtype instance
Throws:
AllegroGraphException

registerLatitudeStripingInRadians

public GeospatialSubtype registerLatitudeStripingInRadians(double width)
                                                    throws AllegroGraphException
Register a latitude striping subtype.

Parameters:
width - in radians
Returns:
a GeospatialSubtype instance
Throws:
AllegroGraphException

registerLatitudeStripingInRadians

public GeospatialSubtype registerLatitudeStripingInRadians(double width,
                                                           java.lang.Double latMin,
                                                           java.lang.Double latMax,
                                                           java.lang.Double lonMin,
                                                           java.lang.Double lonMax)
                                                    throws AllegroGraphException
Register a latitude striping subtype.

Parameters:
width - width in radians
latMin - the minimum latitude included in the strip. A null value specifies the built-in default of the server.
latMax - the maximum latitude included in the strip. A null value specifies the built-in default of the server.
lonMin - the minimum longitude included in the strip. A null value specifies the built-in default of the server.
lonMax - the maximum longitude included in the strip. A null value specifies the built-in default of the server.
Returns:
a GeospatialSubtype instance
Throws:
AllegroGraphException

addSubtype

public void addSubtype(GeospatialSubtype subtype)
                throws AllegroGraphException
Associate a GeospatialSubtype with a triple store.

Parameters:
subtype - the GeospatialSubtype instance
Throws:
AllegroGraphException

encodeUPI

public UPI encodeUPI(GeospatialSubtype subtype,
                     double longitude,
                     double latitude)
              throws AllegroGraphException
Create a geospatial UPI instance encoding a location.

Parameters:
subtype - the GeospatialSubtype instance that defines the encoding
longitude -
latitude -
Returns:
the UPI instance
Throws:
AllegroGraphException

encodeUPIs

public UPI[] encodeUPIs(GeospatialSubtype subtype,
                        double[] longitude,
                        double[] latitude)
                 throws AllegroGraphException
Create an array of geospatial UPI instances encoding locations.

Parameters:
subtype - the GeospatialSubtype instance that defines the encoding
longitude - an array of longitude values
latitude - an array of latitude values.
Returns:
an array of UPI instances. The length is the same as the length of the longer argument array. The last value in the shorter array is repeated.
Throws:
AllegroGraphException

encodeUPIs

public UPI[] encodeUPIs(GeospatialSubtype subtype,
                        double longitude,
                        double[] latitude)
                 throws AllegroGraphException
Create an array of geospatial UPI instances encoding locations.

Parameters:
subtype - the GeospatialSubtype instance that defines the encoding
longitude - a longitude value
latitude - an array of latitude values.
Returns:
an array of UPI instances. The length is the same as the length of the latitude array.
Throws:
AllegroGraphException

encodeUPIs

public UPI[] encodeUPIs(GeospatialSubtype subtype,
                        double[] longitude,
                        double latitude)
                 throws AllegroGraphException
Create an array of geospatial UPI instances encoding locations.

Parameters:
subtype - the GeospatialSubtype instance that defines the encoding
longitude - an array of longitude values
latitude - a latitude value
Returns:
an array of UPI instances. The length is the same as the length of the longitude array.
Throws:
AllegroGraphException

encodeUPIs

public UPI[] encodeUPIs(GeospatialSubtype subtype,
                        double[] longlat)
                 throws AllegroGraphException
Create an array of geospatial UPI instances encoding locations.

Parameters:
subtype - the GeospatialSubtype instance that defines the encoding
longlat - an array of alternating longitude and latitude values
Returns:
an array of UPI instances. The length is half the length of the argument array.
Throws:
AllegroGraphException

decodeUPI

public java.lang.Object[] decodeUPI(UPI upi)
                             throws AllegroGraphException
Decode a geospatial UPI into subtype, longitude and latitude.

Parameters:
upi -
Returns:
an array of 3 Object instances:
  • the GeospatialSubtype instance that defines the encoding
  • a Double instance containing the longitude value
  • a Double instance containing the latitude value
Throws:
AllegroGraphException

decodeUPIs

public java.lang.Object[] decodeUPIs(UPI[] upi)
                              throws AllegroGraphException
Decode an array of geospatial UPIs into subtype, longitude and latitude arrays.

Parameters:
upi - an array of UPI instances
Returns:
an array of 3 Object instances:
  • an array of GeospatialSubtype instances
  • an array of Double instances containing the longitude values
  • an array of Double instances containing the latitude values
Throws:
AllegroGraphException

getStatementsInBoundingBox

public TriplesIterator getStatementsInBoundingBox(GeospatialSubtype subtype,
                                                  java.lang.Object predicate,
                                                  double xMin,
                                                  double xMax,
                                                  double yMin,
                                                  double yMax,
                                                  boolean indexedOnly,
                                                  boolean includeDeleted)
                                           throws AllegroGraphException
Find all the triples in some bounding box.

Parameters:
subtype - the GeospatialSubtype of interest
predicate - a string, UPI instance, ot Value instance that identifies the predicate of the relevant triples
xMin -
xMax -
yMin -
yMax -
indexedOnly - if true, look only at indexed triples (this may be a lot faster if there are many unindexed triples).
includeDeleted - if true, include deleted triples in the search
Returns:
a Cursor instance that can iterate over the search result
Throws:
AllegroGraphException

getStatementsInRadius

public TriplesIterator getStatementsInRadius(GeospatialSubtype subtype,
                                             java.lang.Object predicate,
                                             double x,
                                             double y,
                                             double radius,
                                             boolean indexedOnly,
                                             boolean includeDeleted)
                                      throws AllegroGraphException
Find all the triples in a circle.

Parameters:
subtype - the GeospatialSubtype of interest
predicate - a string, UPI instance, or Value instance that identifies the predicate of the relevant triples
x - The position of the center in Cartesian coordinates.
y - The position of the center in Cartesian coordinates.
radius -
indexedOnly - if true, look only at indexed triples (this may be a lot faster if there are many unindexed triples).
includeDeleted - if true, include deleted triples in the search
Returns:
a Cursor instance that can iterate over the search result
Throws:
AllegroGraphException

getStatementsInHMiles

public TriplesIterator getStatementsInHMiles(GeospatialSubtype subtype,
                                             java.lang.Object predicate,
                                             double lon,
                                             double lat,
                                             double radius,
                                             boolean indexedOnly,
                                             boolean includeDeleted)
                                      throws AllegroGraphException
Find all the triples in a circle.

Parameters:
subtype - the GeospatialSubtype of interest
predicate - a string, UPI instance, ot Value instance that identifies the predicate of the relevant triples
lon - The position of the center in geographic coordinates.
lat - The position of the center in geographic coordinates.
radius - the radius of the circle in miles
indexedOnly - if true, look only at indexed triples (this may be a lot faster if there are many unindexed triples).
includeDeleted - if true, include deleted triples in the search
Returns:
a Cursor instance that can iterate over the search result
Throws:
AllegroGraphException

getStatementsInHKm

public TriplesIterator getStatementsInHKm(GeospatialSubtype subtype,
                                          java.lang.Object predicate,
                                          double lon,
                                          double lat,
                                          double radius,
                                          boolean indexedOnly,
                                          boolean includeDeleted)
                                   throws AllegroGraphException
Find all the triples in a circle.

Parameters:
subtype - the GeospatialSubtype of interest
predicate - a string, UPI instance, ot Value instance that identifies the predicate of the relevant triples
lon - The position of the center in geographic coordinates.
lat - The position of the center in geographic coordinates.
radius - the radius of the circle in kilometers
indexedOnly - if true, look only at indexed triples (this may be a lot faster if there are many unindexed triples).
includeDeleted - if true, include deleted triples in the search
Returns:
a Cursor instance that can iterate over the search result
Throws:
AllegroGraphException

getStatementsInHRadians

public TriplesIterator getStatementsInHRadians(GeospatialSubtype subtype,
                                               java.lang.Object predicate,
                                               double lon,
                                               double lat,
                                               double radius,
                                               boolean indexedOnly,
                                               boolean includeDeleted)
                                        throws AllegroGraphException
Find all the triples in a circle.

Parameters:
subtype - the GeospatialSubtype of interest
predicate - a string, UPI instance, ot Value instance that identifies the predicate of the relevant triples
lon - The position of the center in geographic coordinates.
lat - The position of the center in geographic coordinates.
radius - the radius of the circle in radians
indexedOnly - if true, look only at indexed triples (this may be a lot faster if there are many unindexed triples).
includeDeleted - if true, include deleted triples in the search
Returns:
a Cursor instance that can iterate over the search result
Throws:
AllegroGraphException

addSphericalPredicateMapping

public void addSphericalPredicateMapping(java.lang.String label,
                                         GeospatialSubtype subtype)
                                  throws AllegroGraphException
Add a predicate mapping for a geospatial subtype encoding.

Parameters:
label - the URL that identifies the predicate
subtype - the GeospatialSubtype of the encoded literal
Throws:
AllegroGraphException

addSphericalDatatypeMapping

public void addSphericalDatatypeMapping(java.lang.String label,
                                        GeospatialSubtype subtype)
                                 throws AllegroGraphException
Add a predicate mapping for a geospatial subtype encoding.

Parameters:
label - the URL that identifies the datatype
subtype - the GeospatialSubtype of the encoded literal
Throws:
AllegroGraphException

addCartesianPredicateMapping

public void addCartesianPredicateMapping(java.lang.String label,
                                         GeospatialSubtype subtype)
                                  throws AllegroGraphException
Add a predicate mapping for a geospatial subtype encoding.

Parameters:
label - the URL that identifies the predicate
subtype - the GeospatialSubtype of the encoded literal
Throws:
AllegroGraphException

addCartesianDatatypeMapping

public void addCartesianDatatypeMapping(java.lang.String label,
                                        GeospatialSubtype subtype)
                                 throws AllegroGraphException
Add a predicate mapping for a geospatial subtype encoding.

Parameters:
label - the URI that identifies the datatype
subtype - the GeospatialSubtype of the encoded literal
Throws:
AllegroGraphException