16 Oracle Spatial Data Cartridge

bufferPolygon

Syntax

Purpose

This com.oracle.cep.cartridge.spatial.Geometry method returns a new com.oracle.cep.cartridge.spatial.Geometry object which is the buffered version of the input oracle.spatial.geometry.JGeometry polygon.

This method takes the following arguments:

• polygon: an oracle.spatial.geometry.JGeometry polygon.

• distance: the distance value used for this buffer as a double.

  This value is assumed to be in the same unit as the Unit of Projection for projected geometry. If the geometry is geodetic, this buffer width should be in meters.

This method obtains parameters from the Oracle Spatial data cartridge application context. Consequently, you must use the spatial link name to associate the method call with the Oracle Spatial data cartridge application context:

com.oracle.cep.cartridge.spatial.Geometry.bufferPolygon@spatial(geom, 1300)

For more information, see Section 16.1.4, "Oracle Spatial Data Cartridge Application Context".

Examples

Example 16-11 shows how to use the bufferPolygon method. Because this bufferPolygon call depends on the Oracle Spatial data cartridge application context, it uses the spatial link name.

<view id="LocGeomStream" schema="customerId curLoc">
    select 
        customerId, 
        com.oracle.cep.cartridge.spatial.Geometry.bufferPolygon@spatial(geom, 13) 
    from 
        CustomerLocStream
</view>

createElemInfo

Syntax

Purpose

This com.oracle.cep.cartridge.spatial.Geometry method returns a single element info value as an int[] from the given arguments.

This method takes the following arguments:

• soffset: the offset, as an int, within the ordinates array where the first ordinate for this element is stored.

  SDO_STARTING_OFFSET values start at 1 and not at 0. Thus, the first ordinate for the first element will be at SDO_GEOMETRY.Ordinates(1). If there is a second element, its first ordinate will be at SDO_GEOMETRY.Ordinates(n * 3 + 2), where n reflects the position within the SDO_ORDINATE_ARRAY definition.

• etype: the type of the element as an int.

  The Oracle Spatial data cartridge supports SDO_ETYPE values 1, 1003, and 2003 are considered simple elements (not compound types). They are defined by a single triplet entry in the element info array. These types are:

  • 1: point.

  • 1003: exterior polygon ring (must be specified in counterclockwise order).

  • 2003: interior polygon ring (must be specified in clockwise order).

  These types are further qualified by the SDO_INTERPRETATION.

  Note:

  You cannot mix 1-digit and 4-digit SDO_ETYPE values in a single geometry.

• interp: the interpretation as an int.

  For an SDO_ETYPE that is a simple element (1, 1003, or 2003) the SDO_INTERPRETATION attribute determines how the sequence of ordinates for this element is interpreted. For example, a polygon boundary may be made up of a sequence of connected straight line segments.

  If a geometry consists of more than one element, then the last ordinate for an element is always one less than the starting offset for the next element. The last element in the geometry is described by the ordinates from its starting offset to the end of the ordinates varying length array.

  Table 16-5 describes the relationship between SDO_ETYPE and SDO_INTERPREATION.

  Table 16-5 SDO_ETYPE and SDO_INTERPRETATION

  SDO_ETYPE	SDO_INTERPRETATION	Description
  0	Any numeric value	Used to model geometry types not supported by Oracle Spatial.
  1	1	Point type.
  1	0	Orientation for an oriented point.
  1003 or 2003	1	Simple polygon whose vertices are connected by straight line segments. You must specify a point for each vertex; and the last point specified must be exactly the same point as the first (within the tolerance value), to close the polygon. For example, for a 4-sided polygon, specify 5 points, with point 5 the same as point 1.

  
  

Examples

Example 16-12 shows how to use the createElemInfo method.

<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>

createGeometry

Syntax

Purpose

This com.oracle.cep.cartridge.spatial.Geometry method returns a new 2D oracle.cep.cartridge.spatial.Geometry object.

This method takes the following arguments:

• gtype: the geometry type as an int.

  For more information, see Table 16-2.

• eleminfo: the geometry element info as an int[].

  For more information, see "createElemInfo".

• ordinates: the geometry ordinates as a double[].

• srid: the optional SDO_SRID of the geometry as an int.

  If you omit the srid parameter, then this method obtains parameters from the Oracle Spatial data cartridge application context. Consequently, you must use the spatial link name to associate the method call with the Oracle Spatial data cartridge application context:

  com.oracle.cep.cartridge.spatial.Geometry.createGeometry@spatial(gtype, eleminfo, ordinates)
  

  For more information, see Section 16.1.4, "Oracle Spatial Data Cartridge Application Context".

Examples

Example 16-13 shows how to use the createGeometry method. Because this createGeometry call does not include the srid argument, it uses the spatial link name to associate the method call with the Oracle Spatial data cartridge application context.

<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>

createLinearPolygon

Syntax

Purpose

This com.oracle.cep.cartridge.spatial.Geometry method returns a new com.oracle.cep.cartridge.spatial.Geometry object which is a 2D simple linear polygon without holes. If the coordinate array does not close itself (the last coordinate is not the same as the first) then this method copies the first coordinate and appends this coordinate value to the end of the input coordinates array.

To create a simple linear polygon without holes, use the following arguments:

• coords: the coordinates of the linear polygon as a double[].

• srid: the optional SRID of the geometry as an int.

  If you omit the srid parameter, then this method obtains parameters from the Oracle Spatial data cartridge application context. Consequently, you must use the spatial link name to associate the method call with the Oracle Spatial data cartridge application context:

  com.oracle.cep.cartridge.spatial.Geometry.createLinearPolygon@spatial(coords)
  

  For more information, see Section 16.1.4, "Oracle Spatial Data Cartridge Application Context".

Examples

Example 16-14 shows how to use the createLinearPolygon method. Because this createLinearPolygon method call does not include the srid argument, it must use the spatial link name to associate the method call with the Oracle Spatial data cartridge application context.

<view id="LocGeomStream" schema="customerId curLoc">
    select 
        customerId, 
        com.oracle.cep.cartridge.spatial.Geometry.createLinearPolygon@spatial(coords) 
    from 
        CustomerLocStream
</view>

createPoint

Syntax

Purpose

This com.oracle.cep.cartridge.spatial.Geometry method returns a new com.oracle.cep.cartridge.spatial.Geometry object which is a 3D point.

This method takes the following arguments:

• x: the x coordinate of the lower left as a double.

• y: the y coordinate of the lower left as a double.

• srid: the optional SRID of the geometry as an int.

  If you omit the srid parameter, then this method obtains parameters from the Oracle Spatial data cartridge application context. Consequently, you must use the spatial link name to associate the method call with the Oracle Spatial data cartridge application context:

  com.oracle.cep.cartridge.spatial.Geometry.createPoint@spatial(x, y)
  

  For more information, see Section 16.1.4, "Oracle Spatial Data Cartridge Application Context".

Examples

Example 16-15 shows how to use the createPoint method. Because this createPoint call includes the srid argument, it does not need to use the spatial link name.

<view id="LocGeomStream" schema="customerId curLoc">
    select 
        customerId, 
        com.oracle.cep.cartridge.spatial.Geometry.createPoint@spatial(lng, lat) 
    from 
        CustomerLocStream
</view>

createRectangle

Syntax

Purpose

This com.oracle.cep.cartridge.spatial.Geometry method returns a new com.oracle.cep.cartridge.spatial.Geometry object which is a 2D rectangle.

This method takes the following arguments:

• x1: the x coordinate of the lower left as a double.

• y1: the y coordinate of the lower left as a double.

• x2: the x coordinate of the upper right as a double.

• y2: the y coordinate of the upper right as a double.

• srid: the optional SRID of the geometry as an int.

  If you omit the srid parameter, then this method obtains parameters from the Oracle Spatial data cartridge application context. Consequently, you must use the spatial link name to associate the method call with the Oracle Spatial data cartridge application context:

  com.oracle.cep.cartridge.spatial.Geometry.createRectangle@spatial(x1, y1, x2, y2)
  

  For more information, see Section 16.1.4, "Oracle Spatial Data Cartridge Application Context".

Examples

Example 16-16 shows how to use the createRectangle method. Because this createRectangle method call does not include the srid argument, it must use the spatial link name to associate the method call with the Oracle Spatial data cartridge application context.

<view id="LocGeomStream" schema="customerId curLoc">
    select 
        customerId, 
        com.oracle.cep.cartridge.spatial.Geometry.createRectangle@spatial(x1, y1, x2, y2) 
    from 
        CustomerLocStream
</view>

distance

Syntax

Purpose

This com.oracle.cep.cartridge.spatial.Geometry method calculates the distance between two geometries as a double.

To calculate the distance between a given com.oracle.cep.cartridge.spatial.Geometry object and another, use the non-static distance method of the current Geometry object with the following arguments:

• g: the other com.oracle.cep.cartridge.spatial.Geometry object.

To calculate the distance between two com.oracle.cep.cartridge.spatial.Geometry objects, use the static distance method with the following arguments:

• g1: the first com.oracle.cep.cartridge.spatial.Geometry object.

• g2: the second com.oracle.cep.cartridge.spatial.Geometry object.

In both cases, this method obtains parameters from the Oracle Spatial data cartridge application context. Consequently, you must use the spatial link name to associate the method call with the Oracle Spatial data cartridge application context:

com.oracle.cep.cartridge.spatial.Geometry.distance@spatial(geom)
com.oracle.cep.cartridge.spatial.Geometry.distance@spatial(geom1, geom2)

For more information, see Section 16.1.4, "Oracle Spatial Data Cartridge Application Context".

Examples

Example 16-17 shows how to use the distance method. Because the distance method depends on the Oracle Spatial data cartridge application context, it must use the spatial link name.

<view id="LocGeomStream" schema="customerId curLoc">
    select 
        customerId, 
        com.oracle.cep.cartridge.spatial.Geometry.createRectangle(x1, y1, x2, y2, 8307) 
    from 
        CustomerLocStream
    where
        com.oracle.cep.cartridge.spatial.Geometry.distance@spatial(geom1, geom2) < 5
</view>

einfogenerator

Syntax

einfogenerator@spatial

Purpose

This function returns a single element info value as an int[] from the given arguments.

This function takes the following arguments:

• offset: the offset, as an int, within the ordinates array where the first ordinate for this element is stored.

  SDO_STARTING_OFFSET values start at 1 and not at 0. Thus, the first ordinate for the first element will be at SDO_GEOMETRY.Ordinates(1). If there is a second element, its first ordinate will be at SDO_GEOMETRY.Ordinates(n * 3 + 2), where n reflects the position within the SDO_ORDINATE_ARRAY definition.

• etype: the type of the element as an int.

  The Oracle Spatial data cartridge supports SDO_ETYPE values 1, 1003, and 2003 are considered simple elements (not compound types). They are defined by a single triplet entry in the element info array. These types are:

  • 1: point.

  • 1003: exterior polygon ring (must be specified in counterclockwise order).

  • 2003: interior polygon ring (must be specified in clockwise order).

  These types are further qualified by the SDO_INTERPRETATION.

  Note:

  You cannot mix 1-digit and 4-digit SDO_ETYPE values in a single geometry.

• interp: the interpretation as an int.

  For an SDO_ETYPE that is a simple element (1, 1003, or 2003) the SDO_INTERPRETATION attribute determines how the sequence of ordinates for this element is interpreted. For example, a polygon boundary may be made up of a sequence of connected straight line segments.

  If a geometry consists of more than one element, then the last ordinate for an element is always one less than the starting offset for the next element. The last element in the geometry is described by the ordinates from its starting offset to the end of the ordinates varying length array.

  Table 16-6 describes the relationship between SDO_ETYPE and SDO_INTERPREATION.

  Table 16-6 SDO_ETYPE and SDO_INTERPRETATION

  SDO_ETYPE	SDO_INTERPRETATION	Description
  0	Any numeric value	Used to model geometry types not supported by Oracle Spatial.
  1	1	Point type.
  1	0	Orientation for an oriented point.
  1003 or 2003	1	Simple polygon whose vertices are connected by straight line segments. You must specify a point for each vertex; and the last point specified must be exactly the same point as the first (within the tolerance value), to close the polygon. For example, for a 4-sided polygon, specify 5 points, with point 5 the same as point 1.

  
  

Examples

Example 16-18 shows how to use the oeinfogenerator function to create the element information for a geometry.

view id="ShopGeom">
    select  com.oracle.cep.cartridge.spatial.Geometry.createGeometry@spatial(
        com.oracle.cep.cartridge.spatial.Geometry.GTYPE_POLYGON,
        einfogenerator@spatial(1, 1003, 1),
        ordsgenerator@spatial(
            lng1, lat1, lng2, lat2, lng3, lat3,
            lng4, lat4, lng5, lat5, lng6, lat6
        ) 
    ) as geom
    from ShopDesc
</view>

get2dMbr

Syntax

Purpose

This com.oracle.cep.cartridge.spatial.Geometry method returns the MBR of a given Geometry as a double[][] that contains the following values:

• [0][0]: minX

• [0][1]: maxX

• [1][0]: minY

• [1][1]: maxY

This method takes the following arguments:

• geom: the com.oracle.cep.cartridge.spatial.Geometry object.

Examples

Example 16-19 shows how to use the get2dMbr method.

<view id="LocGeomStream" schema="customerId mbr">
    select 
        customerId, 
        com.oracle.cep.cartridge.spatial.Geometry.get2dMbr(geom)
    from 
        CustomerLocStream
    where
        com.oracle.cep.cartridge.spatial.Geometry.distance@spatial(geom1, geom2) < 5
</view>

ordsgenerator

Syntax

ordsgenerator@spatial

Purpose

This function returns the double array of 2D coordinates that Oracle Spatial requires.

This function takes the following arguments:

• x1, y1, ... xN, yN: a comma-separated list of double coordinate values.

Examples

Example 16-20 shows how to use the ordsgenerator function to create an Oracle Spatial double array out of six double coordinate values.

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>

to_Geometry

Syntax

Purpose

This com.oracle.cep.cartridge.spatial.Geometry method converts an oracle.spatial.geometry.JGeometry type to a 3D com.oracle.cep.cartridge.spatial.Geometry type. If the given geometry is already a Geometry type and a 3D geometry, then no conversion is done. If the given geometry is a 2D geometry, then the given geometry is converted to 3D by padding z coordinates.

This method takes the following arguments:

• geom: the oracle.spatial.geometry.JGeometry object to convert.

Examples

Example 16-21 shows how to use the to_Geometry method.

<view id="LocStream" schema="customerId loc">
    select 
        customerId, 
        com.oracle.cep.cartridge.spatial.Geometry.to_Geometry(geom) 
    from 
        CustomerLocStream
</view>

to_JGeometry

Syntax

Purpose

This com.oracle.cep.cartridge.spatial.Geometry method converts a com.oracle.cep.cartridge.spatial.Geometry object to an oracle.spatial.geometry.JGeometry 2D type.

This method takes the following arguments:

• g: the com.oracle.cep.cartridge.spatial.Geometry object to convert.

Examples

Example 16-22 shows how to use the to_JGeometry method.

<view id="LocStream" schema="customerId loc">
    select 
        customerId, 
        com.oracle.cep.cartridge.spatial.Geometry.to_JGeometry(geom) 
    from 
        CustomerLocStream
</view>