This chapter provides a reference and guide to using the Oracle Spatial cartridge, which extends Oracle Continuous Query Language (Oracle CQL) to provide advanced spatial features for location-enabled applications.
You can use Oracle Spatial types, methods, fields, and constructors in Oracle CQL queries and views as you would Oracle CQL native types when you create Oracle Event Processing applications.
This chapter includes the following sections:
Oracle Spatial is an Oracle Database option that provides advanced spatial features to support high-end geographic information systems (GIS) and location-enabled business intelligence solutions (LBS).
Oracle Spatial is an optional data cartridge that enables you to write Oracle CQL queries and views that seamlessly interact with Oracle Spatial classes in your Oracle Event Processing application.
With Oracle Spatial, you can configure Oracle CQL queries that perform the most important geographic domain operations such as storing spatial data, performing proximity and overlap comparisons on spatial data, and integrating spatial data with the Oracle Event Processing server by providing the ability to index on spatial data.
To use Oracle Spatial, you require a working knowledge of the Oracle Spatial API. For more information about Oracle Spatial, see:
Product overview: http://www.oracle.com/in/products/database/options/spatial/index.html
Oracle Spatial documentation: http://www.oracle.com/pls/db112/portal.portal_db?selected=7&frame=#oracle_spatial_and_location_information
Oracle Spatial Java API reference: http://download.oracle.com/docs/cd/E11882_01/appdev.112/e11829/toc.htm
This section describes:
Oracle Spatial uses the cartridge ID com.oracle.cep.cartrdiges.spatial and registers the server-scoped reserved link name spatial.
Use the spatial link name to associate an Oracle Spatial method call with the Oracle Spatial application context.
For more information, see:
Oracle Spatial is based on the Oracle Spatial Java API. Oracle Spatial exposes Oracle Spatial functionality in the com.oracle.cep.cartridge.spatial.Geometry class. Oracle Spatial functionality that is not in the Oracle Spatial Java API is not accessible from Oracle Spatial.
Using Oracle Spatial, your Oracle CQL queries can access the Oracle Spatial functionality that Table 4-1 describes.
Table 4-1 Oracle Spatial Scope
| Oracle Spatial Feature | Scope |
|---|---|
|
Geometry Types |
The following geometry types from the Oracle Spatial Java API:
The following geometry operations:
For more information, see: |
|
Coordinate Systems |
For more information, see Ordinates and Coordinate Systems and the SDO_SRID. |
|
Geometric Index |
For more information, see Geometric Index. |
|
Geometric Relation Operators |
For more information, see Geometric Relation Operators. |
|
Geometric Filter Operators |
For more information, see Geometric Filter Operators. |
|
Geometry API |
For a complete list of the methods that |
|
Geometric Aggregations |
For more information, see Geometric Aggregations. |
For more information on how to access these Oracle Spatial features using Oracle Spatial, see Using Oracle Spatial.
The Oracle Spatial data model consists of geometries. A geometry is an ordered sequence of vertices. The semantics of the geometry are determined by its type. Oracle Spatial enables you to access the following Oracle Spatial types directly in Oracle CQL queries and views:
SDO_GTYPES: Oracle Spatial supports the following geometry types:
2D points
2D simple polygons
2D rectangles
3D points
3D lines
3D rectangles
3D polygons
Table 4-2 describes the geometry types from the com.oracle.cep.cartridge.spatial.Geometry class that you can use.
Table 4-2 Oracle Spatial Geometry Types
| Geometry Type | Description |
|---|---|
|
|
Point geometry type that contains one point. |
|
|
Curve geometry type that contains one line string that can contain straight or circular arc segments, or both.
|
|
|
Polygon geometry type that contains one polygon. Polygon or surface geometry type that contains one polygon with or without holes or one surface consisting of one or more polygons. In a three-dimensional polygon, all points must be on the same plane. |
|
|
Collection geometry type that is a heterogeneous collection of elements.
|
|
|
Multipoint geometry type that has one or more points. |
|
|
Multiline or multicurve geometry type that has one or more line strings.
|
|
|
Multipolygon or multisuraface geometry type that can have multiple, disjoint polygons (more than one exterior boundary) or surfaces.
|
|
|
Solid geometry that consists of multiple surfaces and is completely enclosed in a three-dimensional space. Can be a cuboid or a frustum. |
|
|
Multisolid geometry that consists of multiple, disjoint solids (more than one exterior boundary).
|
SDO_ELEMENT_INFO: You can create the Element Info array using:
com.oracle.cep.cartridge.spatial.Geometry.createElemInfo static method
einfogenerator function
For more information, see Element Info Array.
ORDINATES: You can create the ordinates using the Oracle Spatial ordsgenerator function.
For more information, see Ordinates and Coordinate Systems and the SDO_SRID.
For more information, see:
The Element Info attribute is defined using a varying length array of numbers. This attribute specifies how to interpret the ordinates stored in the Ordinates attribute.
Oracle Spatial provides the following helper function for generating Element Info attribute values:
com.oracle.cep.cartridge.spatial.Geometry.createElemInfo(int SDO_STARTING_OFFSET, int SDO_ETYPE , int SDO_INTERPRETATION)
You can also use the einfogenerator function.
For more information, see:
Table 4-3 lists the coordinate systems that Oracle Spatial supports by default and the SDO_SRID value that identifies each coordinate system.
Table 4-3 Oracle Spatial Coordinate Systems
| Coordinate System | SDO_SRID | Description |
|---|---|---|
|
Cartesian |
0 |
Cartesian coordinates are coordinates that measure the position of a point from a defined origin along axes that are perpendicular in the represented space. |
|
Geodetic (WGS84) |
8307 |
Geodetic coordinates (sometimes called geographic coordinates) are angular coordinates (longitude and latitude), closely related to spherical polar coordinates, and are defined relative to a particular Earth geodetic datum. This is the default coordinate system in Oracle Spatial. |
You can specify the SDO_SRID value as an argument to each Oracle Spatial method and constructor you call or you can configure the SDO_SRID in the Oracle Spatial application context once and use com.oracle.cep.cartridge.spatial.Geometry methods without having to set the SDO_SRID as an argument each time. Using the application context, you can also specify any coordinate system that Oracle Spatial supports.
Note:
If you use a com.oracle.cep.cartridge.spatial.Geometry method that does not take an SDO_SRID value, then you must use the Oracle Spatial application context. For example, the following method call causes a runtime exception:
com.oracle.cep.cartridge.spatial.Geometry.createPoint(lng, lat)
Instead, you must use the spatial link name to associate the method call with the Oracle Spatial application context:
com.oracle.cep.cartridge.spatial.Geometry.createPoint@spatial(lng, lat)
If you use a Geometry method that takes an SDO_SRID value, then the use of the spatial link name is optional. For example, both the following method calls are valid:
com.oracle.cep.cartridge.spatial.Geometry.createPoint(8307, lng, lat) com.oracle.cep.cartridge.spatial.Geometry.createPoint@spatial(lng, lat)
For more information, see Oracle Spatial Application Context.
Ordinates define the array of coordinates for a geometry using a double array. Oracle Spatial provides the ordsgenerator helper function for generating the array of coordinates. For syntax, see ordsgenerator.
For more information, see:
Oracle Spatial uses a spatial index to implement the primary filter. The purpose of the spatial index is to quickly create a subset of the data and reduce the processing burden on the secondary filter.
A spatial index, like any other index, provides a mechanism to limit searches, but in this case the mechanism is based on spatial criteria such as intersection and containment.
Oracle Spatial uses R-Tree indexing for the default indexing mechanism. A spatial R-tree index can index spatial data of up to four dimensions. An R-tree index approximates each geometry by a single rectangle that minimally encloses the geometry (called the Minimum Bounding Rectangle, or MBR)
For more information, see: Geometric Filter Operators.
Oracle Spatial supports the following Oracle Spatial geometric relation operators:
You can use any of these operators in either the Oracle CQL query projection clause or where clause.
When you use a geometric relation operator in the where clause of an Oracle CQL query, Oracle Spatial enables Rtree indexing on the relation specified in the where clause.
Oracle Spatial supports only geometric relations between point and other geometry types.
For more information, see How to Use Geometry Relation Operators.
Oracle Spatial supports the following Oracle Spatial geometric filter operators:
These filter operators perform primary filtering and so they may only appear in an Oracle CQL query where clause.
These filter operators use the spatial index to identify the set of spatial objects that are likely to interact spatially with the given object.
For more information, see:
The geometry aggregation operator MBR may only appear in an Oracle CQL query projection clause.
For more information, see, How to Use Geometry Aggregate Operators.
Oracle Spatial is based on the Oracle Spatial Java API. Oracle Spatial exposes Oracle Spatial functionality in the com.oracle.cep.cartridge.spatial.Geometry class. This Geometry class also extends oracle.spatial.geometry.J3D_Geometry. Oracle Spatial supports 2D and 3D geometries and automatically zero-pads the Z coordinates for J3D_Geometry methods.
Oracle Spatial functionality inaccessible from the Geometry class (or not conforming to the scope and geometry types that Oracle Spatial supports) is inaccessible from Oracle Spatial.
This section describes:
For more information, see:
Note:
To simplify Oracle Spatial type names, you can use Aliases described in Oracle CQL Language Reference for Oracle Event Processing.
Table 4-4 lists the public methods that the Geometry class provides.
Table 4-4 Oracle Spatial Geometry Methods
| Type | Method |
|---|---|
|
Buffers |
|
|
Circles |
|
|
Conversions |
|
|
Distance |
|
|
Element information |
|
|
Geometries |
|
|
Linear line and multi line strings |
|
|
Linear polygons |
|
|
Minimum Bounding Rectangle (MBR) |
|
|
Points |
|
|
Rectangles |
|
|
Type and type conversion |
Note:
Geometry class methods are case sensitive and you must use them in the case shown.
The following JGeometry public methods are applicable to Oracle Spatial:
double area(double tolerance): returns the total planar surface area of a 2D geometry.
double length(double tolerance): returns the perimeter of a 2D geometry. All edge lengths are added.
double[] getMBR(): returns the Minimum Bounding Rectangle (MBR) of this geometry. It returns a double array containing the minX, minY, maxX, and maxY value of the MBR for 2D.
For more information, see:
The Oracle Spatial cartridge supports one data type: com.oracle.cep.cartridge.spatial.Geometry.
The Geometry class extends oracle.spatial.geometry.J3D_Geometry and supports all the public methods, fields, and constructors that J3D_Geometry and its parent class oracle.spatial.geometry.JGeometry provide.
For a complete list of the methods that com.oracle.cep.cartridge.spatial.Geometry provides, see Geometry API.
You can define an application context for an instance of Oracle Spatial and propagate this application context at runtime. This allows you to associate specific Oracle Spatial application defaults (such as an SDO_SRID) with a particular Oracle Spatial instance.
Before you can define an Oracle Spatial application context, edit your Oracle Event Processing application EPN assembly file to add the required namespace and schema location entries:
<?xml version="1.0" encoding="UTF-8"?>
<beans xmlns="http://www.springframework.org/schema/beans"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:osgi="http://www.springframework.org/schema/osgi"
xmlns:wlevs="http://www.bea.com/ns/wlevs/spring"
xmlns:spatial="http://www.oracle.com/ns/ocep/spatial/"
xsi:schemaLocation="
http://www.springframework.org/schema/beans
http://www.springframework.org/schema/beans/spring-beans.xsd
http://www.springframework.org/schema/osgi
http://www.springframework.org/schema/osgi/spring-osgi.xsd
http://www.bea.com/ns/wlevs/spring
http://www.bea.com/ns/wlevs/spring/spring-wlevs-v11_1_1_6.xsd"
http://www.oracle.com/ns/ocep/spatial
http://www.oracle.com/ns/ocep/spatial/ocep-spatial.xsd">
The following example shows how to create a spatial context named SpatialGRS80 in an EPN assembly file using the Geodetic Reference System 1980 (GRS80) coordinate system.
<spatial:context id="SpatialGRS80" srid="4269" sma="6378137" rof="298.25722101" />
The following example shows how to reference a spatial:context in an Oracle CQL query. In this case, the query uses link name SpatialGRS80 (defined in the above example) to propagate this application context to Oracle Spatial. The spatial:context attribute settings of SpatialGRS80 are applied to the createPoint method call.
<view id="createPoint">
select com.oracle.cep.cartridge.spatial.Geometry.createPoint@SpatialGRS80(
lng, lat)
from CustomerPos[NOW]
</view>
This section describes common use-cases that highlight how you can use Oracle Spatial in your Oracle Event Processing applications, including:
For more information, see Geometry API.
This procedure describes how to access Oracle Spatial geometry types SDO_GTYPE, SDO_ELEMENT_INFO, and ORDINATES using Oracle Spatial in an Oracle CQL query.
To access the geometry types that the Oracle Spatial Java API supports:
You can use Oracle Spatial to create a geometry in an Oracle CQL query by invoking:
static methods in com.oracle.cartridge.spatial.Geometry
methods in oracle.spatial.geometry.JGeometry that conform to the scope and geometry types that Oracle Spatial supports.
constructor methods in oracle.spatial.geometry.J3D_Geometry
static methods from oracle.spatial.geometry.J3D_Geometry
For more information, see Geometry API.
Using a Static Method in the Oracle Spatial Geometry Class
The following example shows how to create a point geometry using a static method in com.oracle.cartridge.spatial.Geometry. In this case, you must use a link (@spatial) to identify the data cartridge that provides this class. The advantage of using this approach is that the Oracle Spatial application context is applied to set the SRID and other Oracle Spatial options, either by default or based on an application context you configure (see Oracle Spatial Application Context).
<view id="CustomerPosGeom">
select com.oracle.cep.cartridge.spatial.Geometry.createPoint@spatial(
lng, lat) as geom
from CustomerPos[NOW]
</view>
Using an Oracle Spatial J3D_Geometry Constructor
The following example shows how to create a geometry using a constructor method in oracle.spatial.geometry.J3D_Geometry. In this case, you do not use a link (@spatial) because J3D_Geometry is just a Java class. The disadvantage of this approach compared with using com.oracle.cartridge.spatial.Geometry is that you must set the SRID because no application context is available.
<view id="CustomerPosGeom">
select oracle.spatial.geometry.J3D_Geometry(
oracle.spatial.geometry.GTYPE_POINT, srid, x, y, z) as geom
from CustomerPos[NOW]
</view>
Using a Static Method in the Oracle Spatial J3D_Geometry
The following example shows how to create a geometry using a static method in oracle.spatial.geometry.J3D_Geometry.
<view id="CustomerPosGeom">
select oracle.spatial.geometry.J3D_Geometry.createArc@spatial(
x1, y1, x2, y2, x3, y3) as geom
from CustomerPos[NOW]
</view>
For more information, see Geometry Types.
Using Oracle Spatial, you can access the public member functions and public member fields of Oracle Spatial classes directly in Oracle CQL.
Oracle Spatial functionality inaccessible from the Geometry class (or not conforming to the scope and geometry types that Oracle Spatial supports) is inaccessible from Oracle Spatial.
In the following example, the view ShopGeom creates an Oracle Spatial geometry called geom. The view shopMBR calls JGeometry static method getMBR which returns a double[] as stream element mbr. The query qshopMBR accesses this double[] using regular Java API.
<view id="ShopGeom">
select com.oracle.cep.cartridge.spatial.Geometry.createGeometry@spatial(
com.oracle.cep.cartridge.spatial.Geometry.GTYPE_POLYGON,
com.oracle.cep.cartridge.spatial.Geometry.createElemInfo(1, 1003, 1),
ordsgenerator@spatial(
lng1, lat1, lng2, lat2, lng3, lat3,
lng4, lat4, lng5, lat5, lng6, lat6
)
) as geom
from ShopDesc
</view>
<view id="shopMBR">
select geom.getMBR() as mbr
from ShopGeom
</view>
<query id="qshopMBR">
select mbr[0], mbr[1], mbr[2], mbr[3]
from shopMBR
</query>
For more information, see:
Using Oracle Spatial, you can access the following Oracle Spatial geometry relation operators in either the WHERE or SELECT clause of an Oracle CQL query:
In the following example, the view op_in_where uses the CONTAIN geometry relation operator in the WHERE clause: in this case, Oracle Spatial uses R-Tree indexing. The view op_in_proj uses CONTAIN in the SELECT clause.
<view id="op_in_where">
RStream(
select
loc.customerId,
shop.shopId
from
LocGeomStream[NOW] as loc,
ShopGeomRelation as shop
where
CONTAIN@spatial(shop.geom, loc.curLoc, 5.0d) = true
)
</view>
<view id="op_in_proj">
RStream(
select
loc.customerId,
shop.shopId,
CONTAIN@spatial(shop.geom, loc.curLoc, 5.0d)
from
LocGeomStream[NOW] as loc,
ShopGeomRelation as shop
)
</view>
For more information, see Geometric Relation Operators.
Using Oracle Spatial, you can access the following Oracle Spatial geometry filter operators in the WHERE clause of an Oracle CQL query:
In the following example, the view filter uses the FILTER geometry filter operator in the WHERE clause.
<view id="filter">
RStream(
select loc.customerId, shop.shopId
from LocGeomStream[NOW] as loc, ShopGeomRelation as shop
where FILTER@spatial(shop.geom, loc.curLoc, 5.0d) = true
)
</view>
For more information, see Geometric Filter Operators.
Using the Oracle Spatial data cartridge, you can access the following Oracle Spatial aggregate operators in the SELECT clause of an Oracle CQL query:
MBR
In the following example, the view vaggrmbr uses the MBR geometry aggregate operator in the SELECT clause. The query qaggrmbr access the double[] returned by the MBR geometry aggregate operator directly using standard Java API.
<view id="vaggrmbr">
select MBR@spatial1(shop.geom) as mbr
from ShopGeomRelation as shop
</view>
<query id="qaggrmbr">
select mbr[0], mbr[1], mbr[2], mbr[3], mbr[4], mbr[5], mbr[6]
from vaggrmbr
</query>
For more information, see Geometric Filter Operators.
When you create an Oracle CQL query using the default Oracle Spatial application context, the default SRID will be set to CARTESIAN.
The following example shows, the createPoint method call uses the default link (@spatial). This guarantees that the default Oracle Spatial application context is applied.
<view id="createPoint">
select com.oracle.cep.cartridge.spatial.Geometry.createPoint@spatial(
lng, lat)
from CustomerPos[NOW]
</view>
For more information, see:
This procedure describes how to use the Oracle Spatial application context to specify a geodetic coordinate system other than the default Cartesian geodetic coordinate system in an Oracle CQL query:
For more information, see:
To use other geodetic coordinates: