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)
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
See Also:
-
Usage Notes for the SDO_TOPO.RELATE function
Parent topic: Topology Application Programming Interface
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.
See Also:
Oracle Spatial Java API Reference for detailed reference information about the Topology Data Model classes, as well as some usage information about the Java APIParent topic: Topology Application Programming Interface