1. Spatial Topology and Network Data Model Developer's Guide
  2. Network Data Model
  3. Network Data Model Overview
  4. Network Data Model Application Programming Interface

5.15 Network Data Model Application Programming Interface

The Oracle Spatial Network Data Model feature includes two client application programming interfaces (APIs): a PL/SQL interface provided by the SDO_NET package and a Java interface.

Both interfaces let you create and update network data, and the Java interface lets you perform network analysis. It is recommended that you use only PL/SQL or SQL to populate network tables and to create indexes, and that you mainly use Java for application development.

The following performance considerations apply to the PL/SQL and Java APIs:

  • If you plan to analyze or edit only nonspatial aspects of a spatial network, you can get better performance by setting the NETWORK_CATEGORY column value to LOGICAL in the USER_SDO_NETWORK_METADATA view (described in xxx_SDO_NETWORK_METADATA Views) before performing the analysis or editing, and then changing the value back to SPATIAL afterward.

    For example, you could use this technique when finding the shortest path between two nodes, because the shortest-path computation considers cost values. However, you could not use this technique when setting the spatial geometry object or the end measure value for a link.

  • If you do not plan to modify any network objects (that is, if you plan to perform only network analysis operations or to retrieve network information), you can get better performance by creating the network memory object as read-only (that is, by specifying that updates are not allowed).

Parent topic: Network Data Model Overview

5.15.1 Network Data Model PL/SQL Interface

The SDO_NET package provides subprograms for creating, accessing, and managing networks on a database server. Example 5-9 in Network Examples shows the use of SDO_NET functions and procedures.

The SDO_NET subprograms can be grouped into the following logical categories:

For reference information about each SDO_NET function and procedure, see SDO_NET Package Subprograms.

Parent topic: Network Data Model Application Programming Interface

5.15.2 Network Data Model Java Interface

Note:

Effective with Oracle Database Release 23ai, the Oracle Spatial Network 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 Network Data Model feature includes the load on demand Java interface. Complete reference information about this interface is provided in Oracle Spatial Java API Reference. The classes of the load on demand Java interface are in the oracle.spatial.network.lod package and its subpackages.

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

Parent topic: Network Data Model Application Programming Interface

5.15.2.1 Network Metadata and Data Management

You can use the Java API to perform network metadata and data management operations such as the following:

  • Insert, delete, and modify node and link data

  • Load a network from a database

  • Store a network in a database

  • Store network metadata in a database

  • Modify network metadata attributes

Parent topic: Network Data Model Java Interface

5.15.2.2 Network Analysis Using the Load on Demand Approach

You can use the oracle.spatial.network.lod.NetworkAnalyst class to perform network analysis operations, such as the following, using the load on demand approach:

  • Shortest path: typical transitive closure problems in graph theory. Given a start and an end node, find the shortest path.

  • Reachability: Given a node, find all nodes that can reach that node, or find all nodes that can be reached by that node.

  • Within-cost analysis: Given a target node and a cost, find all nodes that can be reached by the target node within the given cost.

  • Nearest-neighbors analysis: Given a target node and number of neighbors, find the neighbor nodes and their costs to go to the given target node.

  • Dynamic data input: Create and use a NetworkUpdate object with network update information.

  • User-defined link and node cost calculators: Define the method for computing the cost of a link or a node.

Parent topic: Network Data Model Java Interface

5.15.3 Network Data Model XML Interface

Note:

To efficiently and securely implement your customized network analysis, Oracle Spatial is deprecating the NDM XML API. Instead, use the Load On Demand (LOD) API. The LOD API provides customization interfaces that allow you to easily and securely implement your customization. In addition, you can also use the NDM Contraction Hierarchies REST API for high performance network analysis.

You can use the Network Data Model XML API to perform network analysis. Web service requests are supported through Oracle Spatial web services, which are described in Oracle Spatial Developer's Guide.

HTTP requests can be sent to the web service from Java, PLSQL, or .NET programs or simply from a HTML form. The SDO_NET.POST_XML function (described in SDO_NET Package Subprograms) enables PL/SQL users to call the web service.

The XML schema of the Network Data Model XML API is described in the following: $ORACLE_HOME/md/doc/sdondmxml.zip

Parent topic: Network Data Model Application Programming Interface

5.15.3.1 User-Specified Implementations

The XML API can take user-specified constraints, cost calculators, or even network analysis algorithm settings, by letting you specify the Java class that implements the LOD interfaces. For any implementation that requires input parameters, such as truck weight or height in a trucking constraint implementation, the Java class must implement the oracle.spatial.network.lod.XMLConfigurable interface, that is, it must implement the following two methods:

  • void init(Element parameter);

  • String getXMLSchema();

The init method lets you pass in the input parameter as an XML element, which must follow the schema returned from the getXMLSchema method.

The following XML code segment is an example of how to configure the shortest path algorithm for a shortest path analysis request:

<startPoint>
  <nodeID>123</nodeID>
</startPoint>
<endPoint>
  <nodeID>456</nodeID>
</endPoint>
<shortestPathAlgorithm>
  <className>oracle.spatial.network.lod.AStar</className>
  <parameters>
    <heuristicCostFunction>
      <className>oracle.spatial.network.lod.GeodeticCostFunction</className>
      <parameters>
        <userDataCategory>0</userDataCategory>
        <xCoordUserDataIndex>0</xCoordUserDataIndex>
        <yCoordUserDataIndex>1</yCoordUserDataIndex>
      </parameters>
    </heuristicCostFunction>
    <linkLevelSelector>
      <className>oracle.spatial.network.lod.DynamicLinkLevelSelector</className>
      <parameters>
        <maxLinkLevel>2</maxLinkLevel>
        <costThreshold linkLevel="1">40000</costThreshold>
        <numHighLevelNeighbors>8</numHighLevelNeighbors>
        <costMultiplier>1.5</costMultiplier>
        <costFunction>
          <className>oracle.spatial.network.lod.GeodeticCostFunction</className>
          <parameters>
            <userDataCategory>0</userDataCategory>
            <xCoordUserDataIndex>0</xCoordUserDataIndex>
            <yCoordUserDataIndex>1</yCoordUserDataIndex>
          </parameters>
        </costFunction>
      </parameters>
    </linkLevelSelector>
  </parameters>
</shortestPathAlgorithm>

More examples of the XML API are provided with the NDM tutorial (see Network Data Model Tutorial and Other Resources).

Parent topic: Network Data Model XML Interface