SpatialRules Developer's Guide

Unary operators take only one argument.

(<unary operator> <value>)

For example,

(sqrt (abs (variableRef "var")))

The following unary operators are supported:

Binary operators take only two arguments.

(<binary operator> <value>, <value>)

For example,

(mul (div (int "5"), (int "9")), (sub (property "temperature"), (int "32")))

The following binary operators are supported:

Character data. Strings are left unconverted as a Java String. This is the default data type and does not need to be explicitly specified.

Example comparing a property to a literal string value:

(eq (property "/Truck/Restrictions"), (char "HAZMAT"))))

Integer numeric. Values are converted to a Java int. The range for an "int" value is (-231) to (231-1).

(int "5")

Integer numeric. Values are converted to a Java long. The range for a "long" value is (-263) to (263-1).

(long "5")

Floating point numeric. Values are converted internally to a Java float. Java float values are defined by the 64-bit IEEE 754 floating-point numbers.

(float "5.5")

Floating point numeric. Values are converted internally to a Java double. Java double values are defined by the 64-bit IEEE 754 floating-point numbers.

(double "5.5")

Dates and times. Dates are converted internally to a Java Date and have the following string representation.

(date "yyyy-MM-dd HH:mm:ss:SSS z")

Example:

(date "2006-02-28 18:35:00:000 CDT")

The import command is used to import reference reatures from a file or URL. Features can automatically be added to a feature set by specifying a name. A number of data formats are supported such as KML, KMZ, GeoRSS, and Shapefiles.

The import command has the following general form:

The options are:

The corresponding Java class for this command is com.objectfx.rules.tools.ImportReferenceFeatures.

The submit command is used to submit data for evaluation to a SpatialRules server. The data can be provided in any number of formats including KML, KMZ, Shapefile and GeoRSS.

The submit command has the following general form:

The options are:

The corresponding Java class for this command is com.objectfx.rules.tools.SubmitDynamicFeatures.

The dbadmin command is used to manage the RulesDatabase. This command provides a way to import and export the entire contents of a RulesDatabase to a text form. Databases can be created and emptied (cleaned) as well.

The dbadmin command has the following general form:

The options are:

The corresponding Java class for this command is com.objectfx.rules.tools.DbAdmin.

Launches the server provided by ObjectFX.

The spatialrules command has the following options:

	The source code for the SpatialRules server is provided in the examples distribution. This is useful for modifying the server as necessary.

There is only one method for starting up Cron: startup(). When startup() is called, Cron checks to see if it has any jobs that need to be scheduled for execution. If there are, it creates the schedule for those jobs and then begins executing the schedule.

To start up Cron:

Cron.getInstance().startup();

Cron jobs are created by implementing the Callable (java.util.concurrent.Callable) interface and then submitting the implementation to Cron with one of the addJob() methods. When you submit a callable to Cron, it is associated with three properties used to create jobs:

The following is an example of a simple Cron job that writes a message to the console every 10 seconds.

Callable callable = new Callable(){
  public Object call() throws Exception {
    System.out.println("Called at " + new Date());
    return null;
  }
};

Cron cron = Cron.getInstance();
cron.addJob("Test-Group", "My-Job", callable, new TimeSpan(10, TimeUnit.SECONDS));
cron.startup();

To remove a job, just call removeJob(String jobName). This method returns true if a job with the specified name exists and is removed, otherwise it returns false.

Cron.getInstance().removeJob("My-Job");

Whenever a job is scheduled for execution, a Future (java.util.concurrent.Future) is created for it and added to a collection so that it can be retrieved asynchronously. The Futures are added to FIFO queues—one for each group—with a limit of 200 Futures on each to prevent them from growing indefinitely.

To retrieve the collection of all completed Futures for a group, call getResults(String groupName). Any Futures for that group that have not yet completed will be left in the queue.

For example, to iterate over the results and collect them up:

List<MyJobResult> results = new ArrayList<MyJobResult>()
for (Future future : Cron.getInstance().getResults("MyGroupName")) {
   if (!future.isCancelled()) {
      try {
         list.add((MyJobResult) future.get());
      } catch (final Exception e) {
         // Save results that had exceptions also.
         list.add(new MyJobResult(e));
      }
   }
}

There are two methods for shutting down Cron:

For example, to have Cron wait up to five seconds for any currently executing jobs:

Cron.getInstance().shutdown(5000);

When you call one of the shutdown methods, Cron stops queuing jobs for execution and then waits for the selected timeout period. If it reaches the end of the timeout period and not all of the jobs have completed, Cron will interrupt all of the still-executing threads and then return from the shutdown call.

To ensure a safe shutdown, any jobs that cannot tolerate an unexpected shutdown should either include a method for you to signal a shutdown or they should be able to detect when Cron interrupts the thread in which they are executing. The threads that Cron uses to execute tasks are all daemon threads. When the JVM exits, all Cron threads will be terminated, regardless of their current state.

The class diagram below depicts the geometry class hierarchy and the relationships between the geometry types. The following sections detail each of the classes shown in the diagram.

Figure C.1. Geometry Class Hierarchy

The geometry interface (com.objectfx.geometry.Geometry) is the root of the class hierarchy. It defines properties and methods common to all geometry implementations. These are listed below:

A point (com.objectfx.geometry.Point) is a zero-dimensional object, consisting of an X and Y coordinate value, representing a single location in space. Points can be used to define features such as vehicle locations, landmarks, and hazardous waste sites.

A point's boundary is the empty set. Point geometries have no validity constraints.

The following example illustrates how an instance of a point is constructed in the default Coordinate Reference System (WGS84):

Point pt1 = new Point2d(34, 46);

A line string (com.objectfx.geometry.LineString) is a one-dimensional sequence of two or more points which define a path. Line strings can be used to define features such as highways, streams, or the path of a moving object.

The boundary of a line string is its two endpoints. The interior of a line string is defined as the connected set of segments which lie between the endpoints. A line string must have at least 2 distinct points. A line string containing points that are all topologically equivalent is invalid.

The following example illustrates how an instance of a line string is constructed in the default Coordinate Reference System (WGS84):

double[] xs = new double[] { -100, -95, -92 };
double[] ys = new double[] { 35, 39, 32 };
LineString lineString = new LineString2d(xs, ys);

A linear ring (com.objectfx.geometry.LinearRing) is a type of line string which is closed and simple. A linear ring is closed because its start point is equal to its end point, and it is simple because it does not pass through the same point more than once. Linear rings are most often used to describe the exterior and interior boundaries of a polygon. Linear rings do not contain any area; a polygon should be used if the intent is to describe an area of space.

A linear ring's boundary is the empty set and being closed, the interior of a linear ring is continuous.

The figure below depicts a valid linear ring.

Figure C.2. Valid Linear Ring

The following figure shows examples of invalid linear rings: (A) shows a linear ring which self intersects. (B) shows a linear ring with a spike, a section which doubles back on itself. (C) shows a linear ring which intersects itself at a point.

Figure C.3. Invalid Linear Rings

The following example illustrates how an instance of a linear ring is constructed in the default Coordinate Reference System (WGS84):

double[] xs = new double[] { -100, -100, -95, -95, -100 };
double[] ys = new double[] { 35, 40, 40, 35, 35 };
LinearRing linearRing = new LinearRing2d(xs, ys);

Note that the last coordinate in a linear ring is not required during construction. If omitted, a closing x,y coordinate pair equivalent to the first will be added to the input coordinates.

A polygon (com.objectfx.geometry.Polygon) is a two-dimensional surface stored as a sequence of points defining its exterior bounding ring and 0 or more interior rings defining its holes. A polygon may be used to describe features that have an area, such as political boundaries, land masses, or areas of interest.

The boundary of a polygon is defined by the set of linear rings making up its exterior and interior boundaries. A polygon's interior is defined by the area spanning between, but not including, its exterior and interior rings. In addition to the validity constraints imposed by its set of linear rings, the interior rings of a polygon may only intersect the exterior or other interior rings at a single tangent point. They cannot cross nor share an edge.

The figure below depicts valid polygons. (A) shows a polygon with no interior rings. (B) shows a polygon with two interior rings. (C) shows a polygon with three interior rings, one touching the exterior ring at a tangent point, and two others intersecting at a tangent point.

Figure C.4. Valid Polygons

The figure below depicts invalid polygons. (A) shows a polygon with an interior ring intersecting at more than one tangent point. (B) shows a polygon with interior rings intersecting at more than one tangent point. (C) shows a polygon with an interior ring that is not completely enclosed by the exterior ring.

Figure C.5. Invalid Polygons

The following example illustrates how an instance of a polygon is constructed, with and without interior rings in the default Coordinate Reference System (WGS84):

double[] exteriorXs = new double[] { -100, -100, -90, -90, -100 };
double[] exteriorYs = new double[] { 30, 40, 40, 30, 30 };
LinearRing exteriorRing = new LinearRing2d(exteriorXs, exteriorYs);
Polygon noHoles = new Polygon2d(exteriorRing);

double[] interiorXs = new double[] { -99, -99, -97, -97, -99 };
double[] interiorYs = new double[] { 37, 38, 38, 37, 37 };
LinearRing interiorRing = new LinearRing2d(interiorXs, interiorYs);
LinearRing[] interiorRings = new LinearRing[] { interiorRing };
Polygon withHoles = new Polygon2d(exteriorRing, interiorRings);

A multi-point (com.objectfx.geometry.MultiPoint) is a zero-dimensional geometry consisting of a collection of point geometries that are not connected or ordered in any way. All member points must be of the same Coordinate Reference System. Multi-point geometries can be used to describe features such as disease outbreaks or traffic incidents locations in a particular area.

The boundary of an multi-point is the empty-set. Multi-point geometries have no validity constraints; member points may be disjoint or overlapping.

The following example illustrates the construction of a multi-point geometry in the default Coordinate Reference System (WGS84):

Point pt1 = new Point2d(34, 46);
Point pt2 = new Point2d(25, 54);
Point pt3 = new Point2d(29, 41);

Point[] points = new Point[] { pt1, pt2, pt3 };
MultiPoint multiPoint = new MultiPoint2d(points);

A multi-line string (com.objectfx.geometry.MultiLineString) is one-dimensional geometry consisting of a collection of line string geometries, which must all be of the same Coordinate Reference System. If all member geometries have endpoints which intersect, the boundary is the empty set. Multi-line strings can be used to describe such features as highway networks or river deltas.

The boundary of an multi-line string is considered to be any endpoints of member line strings which do not intersect other member line strings. Member line strings may be disjoint or overlapping. Multi-line string geometries must contain valid line strings in order to be considered valid.

The following example illustrates the construction of a multi-line string geometry in the default Coordinate Reference System (WGS84):

LineString ls1 = new LineString2d(
      new double[] { 10, 11, 12 },
      new double[] { 13, 14, 15 });
LineString ls2 = new LineString2d(
      new double[] { 7, 6, 5 },
      new double[] { 4, 3, 2 });

LineString[] lineStrings = new LineString[] { ls1, ls2 };
MultiLineString multiLineString = new MultiLineString2d(lineStrings);

A multi-polygon (com.objectfx.geometry.MultiPolygon) is a 2-dimensional geometry consisting of a collection of polygon geometries. All member polygons must be of the same Coordinate Reference System. The boundary of a multi-polygon consists of its member polygon's exterior and interior rings. The interior consists of the combined interiors of its member polygons. Multi-polygons can be used to describe features such as non-contiguous land masses (e.g. Hawaii) or political boundaries.

Multi-polygons must contain valid polygons in order to be considered valid. In addition, the boundaries of its member polygons may only intersect at a finite number of points. This means that members may not share an edge, as they would intersect at a continuous number of points.

The figure depicts three examples of valid multi-polygons. (A) shows a multi-polygon with two member polygons. (B) shows a multi-polygon with two member polygons intersecting at a finite number of points. (C) shows a polygon with an interior ring nested within the interior ring of another polygon.

Figure C.6. Valid Multi-Polygons

The following figure show examples of invalid multi-polygons: (A) shows a multi-polygon with overlapping member polygons. (B) shows a multi-polygon with one member connected by a segment.

Figure C.7. Invalid Multi-Polygons

The following example illustrates the construction of a multi-polygon in the default Coordinate Reference System (WGS84):

LinearRing poly1ExteriorRing = new LinearRing2d(
      new double[] { -100, -100, -90, -90, -100 },
      new double[] { 30, 40, 40, 30, 30 });
Polygon polygon1 = new Polygon2d(poly1ExteriorRing);

LinearRing poly2ExteriorRing = new LinearRing2d(
      new double[] { 50, 50, 60, 60, 50 }, 
      new double[] { 10, 20, 20, 10, 10 });
LinearRing poly2InteriorRing = new LinearRing2d(
      new double[] { 52, 52, 58, 58, 52 }, 
      new double[] { 12, 18, 18, 12, 12 });
LinearRing[] poly2InteriorRings = new LinearRing[] { poly2InteriorRing };
Polygon polygon2 = new Polygon2d(poly2ExteriorRing, poly2InteriorRings);

Polygon[] memberPolygons = new Polygon[] { polygon1, polygon2 };
MultiPolygon multiPolygon = new MultiPolygon2d(memberPolygons);

A geometry collection (com.objectfx.geometry.GeometryCollection) is a heterogeneous collection of geometries. Geometry collections may contain other geometry collections. All member geometries in a collection must be associated with the same Coordinate Reference System. Geometry collections are valid only if all their member geometries are valid.

The following example illustrates the construction of a geometry collection in the default Coordinate Reference System (WGS84):

Point point = new Point2d(54, 23);
LineString lineString = new LineString2d(
      new double[] { 7, 6, 5 },
      new double[] { 4, 3, 2 });
LinearRing polyExteriorRing = new LinearRing2d(
      new double[] { -100, -100, -90, -90, -100 },
      new double[] { 30, 40, 40, 30, 30 });
Polygon polygon = new Polygon2d(polyExteriorRing);

Geometry[] memberGeometries = new Geometry[] { point, lineString, polygon};
GeometryCollection geometryCollection = new GeometryCollection2d(memberGeometries);

An envelope (com.objectfx.geometry.Envelope) is a two dimensional geometry specified by two corners, the lower left and upper right. Envelopes are used to represent the minimum bounding rectangle (MBR) of a geometry, per Geometry.getEnvelope(), and also as search geometries when querying data for map image generation and simple area searches. Envelopes enforce that the minimum X ordinate is <= the maximum X ordinate and the minimum Y ordinate is <= the maximum Y value.

The following example illustrates how to construct an Envelope geometry in the default Coordinate Reference System (WGS84):

double minX = -105.0;
double minY = 25.0;
double maxX = -82.0;
double maxY = 51.0;

Envelope envelope = new Envelope(minX, minY, maxX, maxY);

An alternative way of constructing an envelope is to use the factory method Envelope.createEnvelope(). The following example shows how to create an envelope using the createEnvelope() method in the WGS84 Coordinate Reference System:

Envelope envelope = Envelope.createEnvelope(minX, minY, maxX, maxY, Geometry.WGS84);

The createEnvelope() method also allows construction of an envelope which spans the anti-meridian, provided that the Coordinate Reference System has a continuous X-axis which can wraparound, as with a geographic Coordinate Reference System. By specifying a maximum X value that is > the minimum X value, it is inferred that the envelope intends to span the anti-meridian. In these cases a wrapped envelope will be created. Wrapped envelopes are discussed in the next section.

A wrapped envelope (com.objectfx.geometry.WrappedEnvelope) is a specialization of an envelope, which contains an eastern and western envelope pair sharing a boundary on the anti-meridian. This type of envelope is most commonly used in queries when the area of interest spans the anti-meridian, or as the envelope of a geometry collection where the minimum bounding rectangle's shortest longitudinal path lies across the anti-meridian. Further details about dealing with geometries which span the anti-meridian can be found in Section C.4, “Boundary Cases”.

Wrapped envelopes may only be created using the Envelope.createEnvelope() factory method, specifying a specifying a maximum X value that is > the minimum X value. The following example shows the creation of a wrapped envelope in the WGS84 Coordinate Reference System which spans the anti-meridian:

double minX = 160.0;
double minY = 25.0;
double maxX = -170.0;
double maxY = 51.0;

// note that minX > maxX
WrappedEnvelope envelope = 
   (WrappedEnvelope) Envelope.createEnvelope(minX, minY, maxX, maxY, Geometry.WGS84);

Geometries intersect with each other if their boundaries and/or interiors intersect. The following set of tables illustrates the possible intersects cases.

Geometry A intersects geometry B is TRUE if the interiors of A and B intersect.

Geometry A intersects geometry B is TRUE if the boundary points of A intersect with the boundary points of B.

Geometry A intersects geometry B is TRUE if the boundary points of A intersect with the interior of B.

Geometry A intersects geometry B is TRUE if the boundary points of A intersect with the boundary points of B.

Geometries are considered disjoint if their boundaries and interiors do not intersect. Disjoint is the exact opposite of intersect. As the following table illustrates, geometry A is disjoint from geometry B if there is no intersection between the interior and boundary of A and the interior and boundary of B.

A geometry contains another geometry if the interior and boundary of the comparison geometry is completely contained in the interior of the other geometry. Contains is the exact opposite of within; any geometry A containing geometry B means that B is within A. In the following table, geometry A contains geometry B if all of the interior of A intersects with the interior of B and there is no intersection between the exterior of A and the interior and boundary of B.

Figure C.8. Examples of Contains Relationship

A geometry is within another geometry if its interior and boundary are completely contained in the interior of the other geometry. The following table illustrates that geometry A is within geometry B if the interior of A intersects with the interior of B and there is no intersection between the interior and boundary of A with the exterior of B. Within is the exact opposite of contains.

A geometry covers another geometry if it that geometry is completely contained in the interior or boundary of another geometry. Covers differs from contains in that the intersection of A's interior points with B's interior points can be a null set. For example, a point on a polygons boundary is covered by that polygon, but it is not contained by that polygon. The first set of tables below shows the patterns for the covers relation.

Geometry A covers geometry B is TRUE if the interiors of A and B intersect and there is no intersection between the exterior of A and the interior and boundary of B.

Geometry A covers geometry B is TRUE if the interior of A intersects with the boundary of B and there is no intersection between the exterior of A and the interior and boundary of B. This is shown in the polygon - line and polygon - point examples in Figure C.9, “Examples of Covers Relationship”.

Geometry A covers geometry B is TRUE if the boundary of A intersects the interior of B and there is no intersection between the exterior of A the interior and boundary of B. This is shown in the line - point example in Figure C.9, “Examples of Covers Relationship”.

Geometry A covers geometry B is TRUE if the boundary of A intersects the boundary of B and there is no intersection between the exterior of A and the interior and boundary of B.

Figure C.9. Examples of Covers Relationship

Geometry A covered by geometry B is TRUE if the interior of A intersects with the interior of B and there is no intersection between the interior and boundary of A and the exterior of B.

Geometry A covered by geometry B is TRUE if the interior of A intersects with the boundary of B and there is no intersection between the interior and boundary of A and the exterior of B.

Geometry A covered by geometry B is TRUE if the boundary of A intersects with the interior of B and there is no intersection between the interior and boundary of A and the exterior of B.

Geometry A covered by geometry B is TRUE if the boundary of A intersects with the boundary of B and there is no intersection between the interior and boundary of A and the exterior of B.

Overlaps only compares geometries of the same spatial dimension and checks that the intersection set of both geometries results in a different geometry of the same spatial dimension. For example, A overlaps B if the intersection of A and B's interior points is not an empty set and the intersection of A's interior points and B's exterior points is not an empty set and the intersection of B's interior points and A's exterior points is not an empty set.

The following table shows how relations of polygon to polygon, multi-point to multi-point, and multi-polygon to multi-polygon are interpreted. A overlaps B is TRUE if the interior and exterior of A intersects the interior and exterior of B. This is shown in the polygon - polygon example in Figure C.10, “Examples of Overlaps Relationship”.

The following table shows how relations of line string to line string and multi-line string to multi-line string are interpreted. Geometry A overlaps geometry B if the interior of A intersects the interior of B as a 1-dimensional geometry (a line string), the exterior of A intersects the interior of B, and there is no intersection between the interior of A with the exterior of B. This is shown in the line - line example in Figure C.10, “Examples of Overlaps Relationship”. Overlaps is FALSE if the intersection of the interiors results in a 0-dimensional geometry (a point).

Figure C.10. Examples of Overlaps Relationship

The anti-meridian, the boundary between the 180th and -180th meridians, is one area which special attention needs to be paid when using non-collection geometries, such as line strings, polygons, and envelopes. Non-collection geometries are not allowed to span the anti-meridian; they must be split on the anti-meridian and grouped into geometry collections. Each member geometry needs to include coordinates up to and including the anti-meridian boundary coordinates. Geometries that are not separated into regions which do not span the anti-meridian are interpreted strictly in 2-dimensional linear space and will be interpreted as if they span the opposite meridian (the prime meridian).

Take for instance a polygon defined by the following geometry OGC Well-Known Text (WKT):

POLYGON((150 -20,150 25,-150 25,-150 0))

Based solely on these coordinates it would be interpreted to span the area from -150 to 150 longitude. The figure below depicts how the above polygon would be interpreted. As you can see it crosses the prime meridian, which are the left and right edges of the figure below, and not the anti-meridian as we are intending.

Figure C.11. Polygon Trying to Span the Anti-meridian

In order to span the anti-meridian, the polygon described above must be split into a multi-polygon representing the discrete areas between 150 and 180 longitude and between -180 and -150 longitude. To do this a segment running along the anti-meridian on both sides must be present in the coordinate values. This is shown in the following multi-polygon WKT:

MULTIPOLYGON(((150 -20,150 25,180 25,180 -20)),((-180 -20,-180 25,-150 25, -150 -20)))

The figure below depicts the above multi-polygon with boundary coordinates highlighted. As you can see it spans the area up to and including the anti-meridian on both sides, giving the correct spatial coverage.

Figure C.12. Polygon Separated into Multi-Polygon

The same restriction applies also to line strings and envelopes, point geometries cannot cross the anti-meridian so they are exempt. Line strings must be split into multi-line strings; envelopes must be represented as a wrapped envelope, a two-part envelope, which is created using the Envelope.createEnvelope() method. Refer to the discussion on wrapped envelope geometries in Section C.1, “Geometry Object Model” for more details on creating them.

Polygons or envelopes based on geodetic coordinates which need to span polar regions also have special considerations. Since geometries are 2-dimensional and interpreted linearly, these geometries must be created with coordinates representing the boundaries of the longitudinal and latitudinal axes of the coordinate system.

Consider the following figure which depicts a geodetic area encompassing the north pole, from about 70 degrees north latitude up to 90 degrees north latitude. This figure shows the earth as a sphere and how the area would appear as viewed from directly over the pole.

Figure C.13. Region Encompassing the North Pole

To properly represent an area encompassing a pole like the one described in the above figure, the geometry's coordinate array must include coordinate pairs with the minimum and maximum longitudinal (X) axis values coupled with the maximum or minimum latitudinal (Y) axis values, depending on the pole being encompassed.

In the above figure, the north pole is a single point at 90 degrees which encompassing all longitudinal axis values. In order to accurately represent this area in a 2-dimensional geometry, that single point must be turned into a segment. This can be done by using the minimum and maximum longitude values coupled with the maximum latitude value (e.g. a segment with coordinates of -180,90 to 180,90). The other segments of the polygon run along both sides of the anti-meridian boundary down to the minimum latitude with a final segment spanning the longitudinal axis on the minimum latitude. This creates a band which spans the entire longitudinal axis and spans from 70 degrees north latitude up to 90 degrees north latitude. The coordinates needed to represent this polygon are shown in the following OGC Well-Known Text (WKT):

POLYGON((-180 80,-180 90,180 90,180 80))

The figure below depicts how the geometry defined above would look in the Plate Carrée projection for reference. As you can see in this projection, the single point of the pole is actually represented by a segment spanning the entire longitudinal axis. The boundary coordinates discussed above are highlighted.

Figure C.14. Polygon with Boundary Coordinates

The following additional examples in OGC Well-known text show special or unusual cases. These are included to illustrate how the coordinates of a polygon need to be constructed to be interpreted correctly with longitude/latitude data.