Approaches for Editing Topology Data

2.1.1 TopoMap Objects

A TopoMap object is associated with an in-memory cache that is associated with a topology. If you explicitly create and use a cache for editing a topology, you must create a TopoMap object to be associated with a topology, load all or some of the topology into the cache, edit objects, periodically update the topology to write changes to the database, commit the changes made in the cache, and clear the cache.

Although this approach involves more steps than allowing Spatial to create and use the cache automatically, it is much faster and more efficient for most topology editing sessions, which typically affect hundreds or thousands of topological elements. It is the approach shown in most explanations and illustrations.

A TopoMap object can be updatable or read-only, depending on the value of the allow_updates parameter when you call the SDO_TOPO_MAP.LOAD_TOPO_MAP function or procedure:

With a read-only TopoMap object, topological elements (primitives) are loaded but not locked.
With an updatable TopoMap object, topological elements (primitives) are loaded and locked. If you specified a rectangular window for an updatable TopoMap object, you can edit only those topological elements inside the specified window. (The TopoMap object may also contain locked topological elements that you cannot edit directly, but that Oracle Spatial can modify indirectly as needed.)

For more information about what occurs when you use an updatable TopoMap object, see the Usage Notes for the SDO_TOPO_MAP.LOAD_TOPO_MAP function or procedure.

The following procedures set an updatable TopoMap object to be read-only:

Within a user session at any given time, there can be no more than one updatable TopoMap object. However, multiple different user sessions can work with updatable TopoMap objects based on the same topology, as long as their editing windows do not contain any topological elements that are in any other updatable TopoMap objects. There can be multiple read-only TopoMap objects within and across user sessions.

Two or more users can edit a topology at the same time as long as their editing windows (specified in the call to the SDO_TOPO_MAP.LOAD_TOPO_MAP function or procedure) do not overlap.

Parent topic: Approaches for Editing Topology Data

2.1.2 Specifying the Editing Approach with the Topology Parameter

For many SDO_TOPO_MAP package functions and procedures that edit topologies, such as SDO_TOPO_MAP.ADD_NODE or SDO_TOPO_MAP.MOVE_EDGE, you indicate the approach you are using for editing by specifying either a topology name or a null value for the first parameter, which is named topology:

If you specify a topology name, Spatial checks to see if an updatable TopoMap object already exists in the user session; and if one does not exist, Spatial creates an internal TopoMap object, uses that cache to perform the editing operation, commits the change (or rolls back changes to the savepoint at the beginning of the process if an exception occurred), and deletes the TopoMap object. (If an updatable TopoMap object already exists, an exception is raised.) For example, the following statement removes the node with node ID value 99 from the MY_TOPO topology:
```
CALL SDO_TOPO_MAP.REMOVE_NODE('MY_TOPO', 99);
```
If you specify a null value, Spatial checks to see if an updatable TopoMap object already exists in the user session; and if one does exist, Spatial performs the operation in the TopoMap object's cache. (If no updatable TopoMap object exists, an exception is raised.) For example, the following statement removes the node with node ID value 99 from the current updatable TopoMap object:
```
CALL SDO_TOPO_MAP.REMOVE_NODE(null, 99);
```

Parent topic: Approaches for Editing Topology Data

2.1.3 Using GET_xxx Topology Functions

Some SDO_TOPO_MAP package functions that get information about topologies have topology and topo_map as their first two parameters. Examples of such functions are SDO_TOPO_MAP.GET_EDGE_COORDS and SDO_TOPO_MAP.GET_NODE_STAR. To use these functions, specify a valid value for one parameter and a null value for the other parameter, as follows:

If you specify a valid topology parameter value, Spatial retrieves the information for the specified topology. It creates an internal TopoMap object, uses that cache to perform the operation, and deletes the TopoMap object. For example, the following statement returns the edge coordinates of the edge with an ID value of 1 from the CITY_DATA topology:
```
SELECT SDO_TOPO_MAP.GET_EDGE_COORDS('CITY_DATA', null, 1) FROM DUAL;
```
If you specify a null topology parameter value and a valid topo_map parameter value, Spatial uses the specified TopoMap object (which can be updatable or read-only) to retrieve the information for the specified topology. For example, the following statement returns the edge coordinates of the edge with an ID value of 1 from the CITY_DATA_TOPOMAP TopoMap object:
```
SELECT SDO_TOPO_MAP.GET_EDGE_COORDS(null, 'CITY_DATA_TOPOMAP', 1) FROM DUAL;
```
If you specify a null or invalid value for both the topology and topo_map parameters, an exception is raised.

Some SDO_TOPO_MAP package functions that get information about topology editing operations have no parameters. Examples of such functions are SDO_TOPO_MAP.GET_FACE_ADDITIONS and SDO_TOPO_MAP.GET_NODE_CHANGES. These functions use the current updatable TopoMap object. If no updatable TopoMap object exists, an exception is raised. For example, the following statement returns an SDO_NUMBER_ARRAY object (described in SDO_EDGE_ARRAY and SDO_NUMBER_ARRAY Types) with the node ID values of nodes that have been added to the current updatable TopoMap object:

SELECT SDO_TOPO_MAP.GET_NODE_ADDITIONS FROM DUAL;

Parent topic: Approaches for Editing Topology Data

2.1.4 Process for Editing Using Cache Explicitly (PL/SQL API)

Figure 2-1 shows the recommended process for editing topological elements using the PL/SQL API and explicitly using a TopoMap object and its associated cache.

Figure 2-1 Editing Topologies Using the TopoMap Object Cache (PL/SQL API)

Description of "Figure 2-1 Editing Topologies Using the TopoMap Object Cache (PL/SQL API)"

As Figure 2-1 shows, the basic sequence is as follows:

Create the TopoMap object, using the SDO_TOPO_MAP.CREATE_TOPO_MAP procedure.

This creates an in-memory cache for editing objects associated with the specified topology.
Load the entire topology or a rectangular window from the topology into the TopoMap object cache for update, using the SDO_TOPO_MAP.LOAD_TOPO_MAP function or procedure.

You can specify that in-memory R-tree indexes be built on the edges and faces that are being loaded. These indexes use some memory resources and take some time to create and periodically rebuild; however, they significantly improve performance if you edit a large number of topological elements in the session. (They can also improve performance for queries that use a read-only TopoMap object.)
Perform a number of topology editing operations (for example, add 1000 nodes).

Periodically, validate the cache by calling the SDO_TOPO_MAP.VALIDATE_TOPO_MAP function.

You can rebuild existing in-memory R-tree indexes on edges and faces in the TopoMap object, or create new indexes if none exist, by using the SDO_TOPO_MAP.CREATE_EDGE_INDEX and SDO_TOPO_MAP.CREATE_FACE_INDEX procedures. For best index performance, these indexes should be rebuilt periodically when you are editing a large number of topological elements.

If you want to discard edits made in the cache, call the SDO_TOPO_MAP.CLEAR_TOPO_MAP procedure. This procedure fails if there are any uncommitted updates; otherwise, it clears the data in the cache and sets the cache to be read-only.
Update the topology by calling the SDO_TOPO_MAP.UPDATE_TOPO_MAP procedure.
Repeat Steps 3 and 4 (editing objects, validating the cache, rebuilding the R-tree indexes, and updating the topology) as often as needed, until you have finished the topology editing operations.
Commit the topology changes by calling the SDO_TOPO_MAP.COMMIT_TOPO_MAP procedure. (The SDO_TOPO_MAP.COMMIT_TOPO_MAP procedure automatically performs the actions of the SDO_TOPO_MAP.UPDATE_TOPO_MAP procedure before it commits the changes.) After the commit operation, the cache is made read-only (that is, it is no longer updatable). However, if you want to perform further editing operations using the same TopoMap object, you can load it again and use it (that is, repeat Steps 2 through 5, clearing the cache first if necessary).

To perform further editing operations, clear the TopoMap object cache by calling the SDO_TOPO_MAP.CLEAR_TOPO_MAP procedure, and then go to Step 2.

If you want to discard all uncommitted topology changes, you can call the SDO_TOPO_MAP.ROLLBACK_TOPO_MAP procedure at any time. After the rollback operation, the cache is cleared.
Remove the TopoMap object by calling the SDO_TOPO_MAP.DROP_TOPO_MAP procedure.

This procedure removes the TopoMap object and frees any resources that it had used. (If you forget to drop the TopoMap object, it will automatically be dropped when the user session ends.) This procedure also rolls back any topology changes in the cache that have not been committed.

If the application terminates abnormally, all uncommitted changes to the database will be discarded.

If you plan to perform a very large number of topology editing operations, you can divide the operations among several editing sessions, each of which performs Steps 1 through 7 in the preceding list.

Parent topic: Approaches for Editing Topology Data

2.1.5 Process for Editing Using the Java API

Figure 2-2 shows the recommended process for editing topological elements using the client-side Java API, which is introduced in Topology Data Model Java Interface and is explained in the Javadoc-generated documentation. The Java API requires that you create and manage a TopoMap object and its associated cache.

Figure 2-2 Editing Topologies Using the TopoMap Object Cache (Java API)

Description of "Figure 2-2 Editing Topologies Using the TopoMap Object Cache (Java API)"

As Figure 2-2 shows, the basic sequence is as follows:

Create the TopoMap object, using a constructor of the TopoMap class, specifying a topology and a database connection.

This creates an in-memory cache for editing objects associated with the specified topology.
Load the entire topology or a rectangular window from the topology into the TopoMap object cache for update, using the loadTopology or loadWindow method of the TopoMap class.

You can specify that in-memory R-tree indexes be built on the edge and edge face that are being affected. These indexes use some memory resources and take some time to create and periodically rebuild; however, they significantly improve performance if you edit a large number of topological elements during the database connection.
Perform a number of topology editing operations (for example, add 1000 nodes), and update the topology by calling the updateTopology method of the TopoMap class.

Periodically, validate the cache by calling the validateCache method of the TopoMap class.

If you caused in-memory R-tree indexes to be created when you loaded the TopoMap object (in Step 2), you can periodically (for example, after each addition of 100 nodes) rebuild the indexes by calling the createEdgeIndex and createFaceIndex methods of the TopoMap class. For best index performance, these indexes should be rebuilt periodically when you are editing a large number of topological elements.

If you do not want to update the topology but instead want to discard edits made in the cache since the last update, call the clearCache method of the TopoMap class. The clearCache method fails if there are any uncommitted updates; otherwise, it clears the data in the cache and sets the cache to be read-only.
Update the topology by calling the updateTopology method of the TopoMap class.
Repeat Steps 3 and 4 (editing objects, validating the cache, rebuilding the R-tree indexes, and updating the topology) as often as needed, until you have finished the topology editing operations.
Commit the topology changes by calling the commitDB method of the TopoMap class. (The commitDB method automatically calls the updateTopology method before it commits the changes.) After the commit operation, the cache is made read-only (that is, it is no longer updatable). However, if you want to perform further editing operations using the same TopoMap object, you can load it again and use it (that is, repeat Steps 2 through 5, clearing the cache first if necessary).

To perform further editing operations, clear the TopoMap object cache by calling the clearCache method of the TopoMap class, and then go to Step 2.

If you want to discard all uncommitted topology changes, you can call the rollbackDB method of the TopoMap class at any time. After the rollback operation, the cache is cleared.
Remove the TopoMap object by setting the TopoMap object to null, which makes the object available for garbage collection and frees any resources that it had used. (If you forget to remove the TopoMap object, it will automatically be garbage collected when the application ends.)

If the application terminates abnormally, all uncommitted changes to the database will be discarded.

If you plan to perform a very large number of topology editing operations, you can divide the operations among several editing sessions, each of which performs Steps 1 through 7 in the preceding list.

Parent topic: Approaches for Editing Topology Data

2.1.6 Error Handling for Topology Editing

This section discusses the following conditions.

Parent topic: Approaches for Editing Topology Data

2.1.6.1 Input Parameter Errors

When an SDO_TOPO_MAP PL/SQL subprogram or a public method in the TopoMap Java class is called, it validates the values of the input parameters, and it uses or creates a TopoMap object to perform the editing or read-only operation. Whenever there is an input error, an oracle.spatial.topo.TopoDataException exception is thrown. Other errors may occur when the underlying TopoMap object performs an operation.

If the method is called from SQL or PL/SQL, the caller gets the following error message:

ORA-29532: Java call terminated by uncaught Java exception:
<specific error message text>

The following PL/SQL example shows how you can handle a TopoDataException exception:

DECLARE
  topo_data_error EXCEPTION;
  PRAGMA EXCEPTION_INIT(topo_data_error, -29532);
BEGIN
  sdo_topo_map.create_topo_map(null, null, 100, 100, 100);
EXCEPTION
  WHEN topo_data_error THEN
    DBMS_OUTPUT.PUT_LINE(SQLERRM);
END;/

The preceding example generates the following output:

ORA-29532: Java call terminated by uncaught Java exception:oracle.spatial.topo.TopoDataException: invalid TopoMap name

Parent topic: Error Handling for Topology Editing

2.1.6.2 All Exceptions

The following actions are performed automatically when any exception occurs in a call to any of the following SDO_TOPO_MAP PL/SQL subprograms or their associated methods in the TopoMap Java class: SDO_TOPO_MAP.ADD_EDGE (addEdge), SDO_TOPO_MAP.ADD_ISOLATED_NODE (addIsolatedNode), SDO_TOPO_MAP.ADD_LOOP (addLoop), SDO_TOPO_MAP.ADD_NODE (addNode), SDO_TOPO_MAP.ADD_POINT_GEOMETRY (addPointGeometry), SDO_TOPO_MAP.ADD_POLYGON_GEOMETRY (addPolygonGeometry), SDO_TOPO_MAP.CHANGE_EDGE_COORDS (changeEdgeCoords), SDO_TOPO_MAP.MOVE_ISOLATED_NODE (moveIsolatedNode), SDO_TOPO_MAP.MOVE_NODE (moveNode), SDO_TOPO_MAP.MOVE_EDGE (moveEdge), SDO_TOPO_MAP.REMOVE_EDGE (removeEdge), SDO_TOPO_MAP.REMOVE_NODE (removeNode), and SDO_TOPO_MAP.UPDATE_TOPO_MAP (updateTopology).

The transaction is rolled back.
The TopoMap object cache is cleared.
The TopoMap object is made read-only.

Parent topic: Error Handling for Topology Editing