Topology Application Programming Interface

1.8 Topology Application Programming Interface

The Topology Data Model application programming interface (API) consists of the following.

PL/SQL functions and procedures in the SDO_TOPO package (described in SDO_TOPO Package Subprograms) and the SDO_TOPO_MAP package (described in SDO_TOPO_MAP Package Subprograms)
PL/SQL topology operators (described in Topology Operators)
Java API (described in Topology Data Model Java Interface)

Parent topic: Topology Data Model Overview

1.8.1 Topology Operators

With the Topology Data Model PL/SQL API, you can use the Oracle Spatial operators, except for the following:

SDO_RELATE (but you can use the SDO_RELATE convenience operators that do not use the mask parameter)
SDO_NN
SDO_NN_DISTANCE
SDO_WITHIN_DISTANCE

To use spatial operators with the Topology Data Model, you must understand the usage and reference information about spatial operators, which are documented in Oracle Spatial Developer's Guide. This topic describes only additional information or differences that apply to using spatial operators with topologies. Otherwise, unless this section specifies otherwise, the operator-related information in Oracle Spatial Developer's Guide applies to the use of operators with topology data.

When you use spatial operators with topologies, the formats of the first two parameters can be any one of the following:

Two topology geometry objects (type SDO_TOPO_GEOMETRY)

For example, the following statement finds all city streets features that have any interaction with a land parcel feature named P3. (This example uses definitions and data from Topology Built from Topology Data.)

SELECT c.feature_name FROM city_streets c, land_parcels l
  WHERE l.feature_name = 'P3' AND
    SDO_ANYINTERACT (c.feature, l.feature) = 'TRUE';
 
FEATURE_NAME                                                                    
------------------------------                                                  
R1

A topology geometry object (type SDO_TOPO_GEOMETRY) as the first parameter and a spatial geometry (type SDO_GEOMETRY) as the second parameter

For example, the following statement finds all city streets features that have any interaction with a geometry object that happens to be a polygon identical to the boundary of the land parcel feature named P3. (This example uses definitions and data from Topology Built from Spatial Geometries.)
```
SELECT c.feature_name FROM city_streets c
  WHERE SDO_ANYINTERACT (c.feature,
    SDO_GEOMETRY(2003, NULL, NULL, SDO_ELEM_INFO_ARRAY(1,1003,1),
      SDO_ORDINATE_ARRAY(35,6, 47,6, 47,14, 47,22, 35,22, 35,14, 35,6))) = 'TRUE';
 
FEATURE_NAME                                                                    
------------------------------                                                  
R1
```
A topology geometry object (type SDO_TOPO_GEOMETRY) as the first parameter and a topology object array object (type SDO_TOPO_OBJECT_ARRAY) as the second parameter

For example, the following statement finds all city streets features that have any interaction with an SDO_TOPO_OBJECT_ARRAY object that happens to be identical to the land parcel feature named P3. (This example uses definitions and data from Topology Built from Spatial Geometries.)
```
SELECT c.feature_name FROM city_streets c WHERE
  SDO_ANYINTERACT (c.feature,
   SDO_TOPO_OBJECT_ARRAY (SDO_TOPO_OBJECT (5, 3), SDO_TOPO_OBJECT (8, 3)))
   = 'TRUE';
 
FEATURE_NAME                                                                    
------------------------------                                                  
R1
```

Example 1-11 shows different topology operators checking for a specific relationship between city streets features and the land parcel named P3. The first statement shows the SDO_FILTER operator, and the remaining statements show the SDO_RELATE convenience operators that include the "mask" in the operator name. With the convenience operators in this example, only SDO_ANYINTERACT, SDO_OVERLAPBDYINTERSECT, and SDO_OVERLAPS return any resulting feature data. (As Figure 1-3 in Features shows, the only street feature to have any interaction with land parcel P3 is R1.) All statements in Example 1-11 use the format where the first two parameters are topology geometry objects.

Example 1-11 Topology Operators

-- SDO_FILTER
SELECT c.feature_name FROM city_streets c, land_parcels l
  WHERE l.feature_name = 'P3' AND
    SDO_FILTER (c.feature, l.feature) = 'TRUE';
 
FEATURE_NAME                                                                    
------------------------------                                                  
R1                                                                              
 
-- SDO_RELATE convenience operators
SELECT c.feature_name FROM city_streets c, land_parcels l
  WHERE l.feature_name = 'P3' AND
    SDO_ANYINTERACT (c.feature, l.feature) = 'TRUE';
 
FEATURE_NAME                                                                    
------------------------------                                                  
R1                                                                              
 
SELECT c.feature_name FROM city_streets c, land_parcels l
  WHERE l.feature_name = 'P3' AND
    SDO_CONTAINS (c.feature, l.feature) = 'TRUE';
 
no rows selected
 
SELECT c.feature_name FROM city_streets c, land_parcels l
  WHERE l.feature_name = 'P3' AND
    SDO_COVEREDBY (c.feature, l.feature) = 'TRUE';
 
no rows selected
 
SELECT c.feature_name FROM city_streets c, land_parcels l
  WHERE l.feature_name = 'P3' AND
    SDO_COVERS (c.feature, l.feature) = 'TRUE';
 
no rows selected
 
SELECT c.feature_name FROM city_streets c, land_parcels l
  WHERE l.feature_name = 'P3' AND
    SDO_EQUAL (c.feature, l.feature) = 'TRUE';
 
no rows selected
 
SELECT c.feature_name FROM city_streets c, land_parcels l
  WHERE l.feature_name = 'P3' AND
    SDO_INSIDE (c.feature, l.feature) = 'TRUE';
 
no rows selected
 
SELECT c.feature_name FROM city_streets c, land_parcels l
  WHERE l.feature_name = 'P3' AND
    SDO_ON (c.feature, l.feature) = 'TRUE';
 
no rows selected
 
SELECT c.feature_name FROM city_streets c, land_parcels l
  WHERE l.feature_name = 'P3' AND
    SDO_OVERLAPBDYINTERSECT (c.feature, l.feature) = 'TRUE';
 
FEATURE_NAME                                                                    
------------------------------                                                  
R1                                                                              
 
SELECT c.feature_name FROM city_streets c, land_parcels l
  WHERE l.feature_name = 'P3' AND
    SDO_OVERLAPBDYDISJOINT (c.feature, l.feature) = 'TRUE';
 
no rows selected
 
SELECT c.feature_name FROM city_streets c, land_parcels l
  WHERE l.feature_name = 'P3' AND
    SDO_OVERLAPS (c.feature, l.feature) = 'TRUE';
 
FEATURE_NAME                                                                    
------------------------------                                                  
R1                                                                              
 
SELECT c.feature_name FROM city_streets c, land_parcels l
  WHERE l.feature_name = 'P3' AND
    SDO_TOUCH (c.feature, l.feature) = 'TRUE';
 
no rows selected

1.8.2 Topology Data Model Java Interface

Note:

Effective with Oracle Database Release 23ai, the Oracle Spatial Topology Data Model APIs are compiled with JDK 11 as the OJVM in the database supports JDK11. However, the APIs will continue to be supported on JDK8 for backwards compatibility. When using the API, ensure that all the related JAR files are consistent with the JDK version (JDK 8 or JDK 11) that is being used. See RDBMS and JDK Version Compatibility for Oracle JDBC Drivers for more information on the JDBC drivers that are supported for the different JDK versions.

The Java client interface for the Topology Data Model consists of the following classes:

TopoMap: class that stores edges, nodes, and faces, and provides methods for adding and deleting elements while maintaining topological consistency both in the cache and in the underlying database tables
Edge: class for an edge
Face: class for a face
Node: class for a node
Point2DD: class for a point
CompGeom: class for static computational geometry methods
InvalidTopoOperationException: class for the invalid topology operation exception
TopoValidationException: class for the topology validation failure exception
TopoEntityNotFoundException: class for the entity not found exception
TopoDataException: class for the invalid input exception

The Spatial Java class libraries are in .jar files under the <ORACLE_HOME>/md/jlib/ directory.