2 Editing Topologies

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 topology objects. 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 procedure. The following procedures set an updatable TopoMap object to be read-only:

• SDO_TOPO_MAP.COMMIT_TOPO_MAP

• SDO_TOPO_MAP.ROLLBACK_TOPO_MAP

• SDO_TOPO_MAP.CLEAR_TOPO_MAP

There can be no more than one updatable TopoMap object in a user session at any time. There can be multiple read-only TopoMap objects.

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

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 Section 1.6.5) 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;

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

Figure 2-1 shows the recommended process for editing topology objects 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 the illustration topo_editing_plsql.gif

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

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

2. 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 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 topology objects in the session. (They can also improve performance for queries that use a read-only TopoMap object.)

3. 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 topology objects.

   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.

4. Update the topology by calling the SDO_TOPO_MAP.UPDATE_TOPO_MAP procedure.

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

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

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

2.1.5 Process for Editing Using the Java API

Figure 2-2 shows the recommended process for editing topology objects using the client-side Java API, which is introduced in Section 1.8.1 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 the illustration topo_editing_java.gif

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

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

2. 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 topology objects during the database connection.

3. 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 topology objects.

   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.

4. Update the topology by calling the updateTopology method of the TopoMap class.

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

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

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

2.1.6 Error Handling for Topology Editing

This section discusses the following conditions:

• Input parameter errors

• All exceptions

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

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

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

2.2.1 Adding a Node

Adding a non-isolated node adds the node to an edge at a point that is currently on the edge. This operation also splits the edge, causing the original edge to be divided into two edges. Spatial automatically adjusts the definition of the original edge and creates a new edge (assigning it an ID value that is unique among edges in the topology).

To add a non-isolated node, use the SDO_TOPO_MAP.ADD_NODE function. To add an isolated node, use the SDO_TOPO_MAP.ADD_ISOLATED_NODE function.

Figure 2-3 shows the addition of a node (N3) on edge E1.

Figure 2-3 Adding a Non-Isolated Node

Description of the illustration add_node.gif

As a result of the operation shown in Figure 2-3:

• Edge E1 is redefined to be between the original edge's start point and the point at the added node (N3).

• Edge E2 is created. Its start point is the point at node N3, and its end point is the end point of the original edge.

Any linear features that were defined on the original edge are automatically redefined to be on both resulting edges. For example, if a street named Main Street had been defined on the original edge E1 in Figure 2-3, then after the addition of node N3, Main Street would be defined on both edges E1 and E2.

2.2.2 Moving a Node

Moving a non-isolated node to a new position causes the ends of all edges that are attached to the node to move with the node. You must specify the vertices for all edges affected by the moving of the node; each point (start or end) that is attached to the node must have the same coordinates as the new location of the node, and the other end points (not the moved node) of each affected edge must remain the same.

To move a non-isolated node, use the SDO_TOPO_MAP.MOVE_NODE procedure. To move an isolated node, use the SDO_TOPO_MAP.MOVE_ISOLATED_NODE procedure.

Figure 2-4 shows the original topology before node N1 is moved.

Figure 2-4 Topology Before Moving a Non-Isolated Node

Description of the illustration move_node_1.gif

Figure 2-5 shows two cases of the original topology after node N1 is moved. In one case, no reshaping occurs; that is, all edges affected by the movement are specified as straight lines. In the other case, reshaping occurs; that is, one or more affected edges are specified as line segments with multiple vertices.

Figure 2-5 Topology After Moving a Non-Isolated Node

Description of the illustration move_node_2b.gif

In both cases shown in Figure 2-5:

• The topology does not change. That is, the number of nodes, edges, and faces does not change, and the relationships among the nodes, edges, and faces do not change.

• All features defined on the nodes, edges, and faces retain their definitions.

Any isolated nodes and edges might remain in the same face or be moved to a different face as a result of a move operation on a non-isolated node. The SDO_TOPO_MAP.MOVE_NODE procedure has two output parameters, moved_iso_nodes and moved_iso_edges, that store the ID numbers of any isolated nodes and edges that were moved to a different face as a result of the operation.

A node cannot be moved if, as a result of the move, any of the following would happen:

• Any edges attached to the node would intersect any other edge. For example, assume that the original topology shown in Figure 2-5 had included another edge E20 that passed just above and to the right of node N1. If the movement of node N1 would cause edge E3, E4, E6, E8, or E9 to intersect edge E20, the move operation is not performed.

• The node would be moved to a face that does not currently bound the node. For example, if the movement of node N1 would place it outside the original topology shown in Figure 2-5, the move operation is not performed.

• The node would be moved to the opposite side of an isolated face. This is not allowed because the move would change the topology by changing one or more of the following: the relationship or ordering of edges around the face, and the left and right face for each edge. Figure 2-6 shows a node movement (flipping node N1 from one side of isolated face F1 to the other side) that would not be allowed.

  Figure 2-6 Node Move Is Not Allowed

  
  Description of the illustration flip_node.gif
  
  

2.2.2.1 Additional Examples of Allowed and Disallowed Node Moves

This section provides additional examples of node movement operations that are either allowed or not allowed. All refer to the topology shown in Figure 2-7.

Figure 2-7 Topology for Node Movement Examples

Description of the illustration node_moves_several.gif

In the topology shown in Figure 2-7:

• Attempts will be made to move node N1 to points P1, P2, P3, and P4. (These points are locations but are not existing nodes.)

• The edges have no shape points, either before or after the move operation.

• New vertices are specified for the edges E1, E2, E3, and E4, but the ID values of the start and end points for the edges remain the same.

When the following node move operations are attempted using the topology shown in Figure 2-7, the following results occur:

• Moving node N1 to point P1: Not allowed, because one or more of the four attached edges would intersect edge E5. (Edge E3 would definitely intersect edge E5 if the move were allowed.)

• Moving node N1 to point P2: Allowed.

• Moving node N1 to point P3: Allowed. However, this operation causes the isolated node N2 to change from face F2 to face F1, and this might cause the application to want to roll back or disallow the movement of node N1. Similarly, if the movement of a node would cause any isolated edges or faces to change from one face to another, the application might want to roll back or disallow the node move operation.

• Moving node N1 to point P4: Not allowed, because the node must be moved to a point in a face that bounds the original (current) position of the node.

2.2.3 Removing a Node

Removing a non-isolated node deletes the node and merges the edges that were attached to the node into a single edge. (Spatial applies complex rules, which are not documented, to determine the ID value and direction of the resulting edge.)

To remove a non-isolated or isolated node, use the SDO_TOPO_MAP.REMOVE_NODE procedure.

Figure 2-8 shows the removal of a node (N1) that is attached to edges E1 and E2.

Figure 2-8 Removing a Non-Isolated Node

Description of the illustration delete_node.gif

As a result of the operation shown in Figure 2-8:

• Edge E1 is redefined to consist of the line segments that had represented the original edges E1 and E2.

• Edge E2 is deleted.

Any linear features that were defined on both original edges are automatically redefined to be on the resulting edge. For example, if a street named Main Street had been defined on the original edges E1 and E2 in Figure 2-8, then after the removal of node N1, Main Street would be defined on edge E1.

A node cannot be removed if one or more of the following are true:

• A point feature is defined on the node. For example, if a point feature named Metropolitan Art Museum had been defined on node N1 in Figure 2-8, node N1 cannot be removed. Before you can remove the node in this case, you must remove the definition of any point features on the node.

• A linear feature defined on either original edge is not also defined on both edges. For example, if a linear feature named Main Street had been defined on edge E1 but not edge E2 in Figure 2-8, node N1 cannot be removed.

2.3.1 Adding an Edge

Adding a non-isolated edge adds the edge to a face. It also splits the face, causing the original face to be divided into two faces. Spatial automatically adjusts the definition of the original face and creates a new face (assigning it an ID value that is unique among faces in the topology).

To add an edge, use the SDO_TOPO_MAP.ADD_EDGE procedure. You must specify existing nodes as the start and end nodes of the added edge.

Figure 2-9 shows the addition of an edge (E7) between nodes N3 and N5 on face F3.

Figure 2-9 Adding a Non-Isolated Edge

Description of the illustration add_edge.gif

As a result of the operation shown in Figure 2-9, face F3 is redefined to be two faces, F1 and F3. (Spatial applies complex rules, which are not documented, to determine the ID values of the resulting faces.)

Any polygon features that were defined on the original face are automatically redefined to be on both resulting faces. For example, if a park named Walden State Park had been defined on the original face F3 in Figure 2-9, then after the addition of edge E7, Walden State Park would be defined on both faces F1 and F3.

2.3.2 Moving an Edge

Moving a non-isolated edge keeps the start or end point of the edge in the same position and moves the other of those two points to another existing node position. You must specify the source node (location before the move of the node to be moved), the target node (location after the move of the node being moved), and the vertices for the moved edge.

To move an edge, use the SDO_TOPO_MAP.MOVE_EDGE procedure.

Figure 2-10 shows the movement of edge E7, which was originally between nodes N3 and N5, to be between nodes N2 and N5.

Figure 2-10 Moving a Non-Isolated Edge

Description of the illustration move_edge.gif

As a result of the operation shown in Figure 2-10, faces F1 and F3 are automatically redefined to reflect the coordinates of their edges, including the new coordinates for edge E7.

Any isolated nodes and edges might remain in the same face or be moved to a different face as a result of a move operation on a non-isolated edge. The SDO_TOPO_MAP.MOVE_EDGE procedure has two output parameters, moved_iso_nodes and moved_iso_edges, that store the ID numbers of any isolated nodes and edges that were moved to a different face as a result of the operation.

An edge cannot be moved if, as a result of the move, any of the following would happen:

• The moved edge would intersect any other edge. For example, assume that the topology before the move, as shown in Figure 2-10, had included another edge (E10) that was between nodes N3 and N4. In this case, the movement of edge E7 would cause it to intersect edge E10, and therefore the move operation is not performed.

• The node would be moved to a face that does not currently bound the edge. For example, if the movement of edge E7 would place its terminating point at a node outside the faces shown in Figure 2-10 (F1 and F3), the move operation is not performed.

2.3.3 Removing an Edge

Removing a non-isolated edge deletes the edge and merges the faces that bounded the edge. (Spatial applies complex rules, which are not documented, to determine the ID value of the resulting face.)

To remove an edge, use the SDO_TOPO_MAP.REMOVE_EDGE procedure.

Figure 2-11 shows the removal of an edge (E7) that is bounded by faces F1 and F3.

Figure 2-11 Removing a Non-Isolated Edge

Description of the illustration delete_edge.gif

As a result of the operation shown in Figure 2-11:

• Face F1 is redefined to consist of the area of the original faces F1 and F3.

• Face F3 is deleted.

• The start and end nodes of the deleted edge (nodes N3 and N5) are not removed.

Any polygon features that were defined on both original faces are automatically redefined to be on the resulting face. For example, if a park named Adams Park had been defined on the original faces F1 and F3 in Figure 2-11, then after the removal of edge E7, Adams Park would be defined on face F1.

A non-isolated edge cannot be removed if one or more of the following are true:

• A linear feature is defined on the edge. For example, if a linear feature named Main Street had been defined on edge E7 in Figure 2-11, edge E7 cannot be removed. Before you can remove the edge in this case, you must remove the definition of any linear features on the edge.

• A polygon feature defined on either original face is not also defined on both faces. For example, if a linear feature named Adams Park had been defined on face F1 but not face F3 in Figure 2-11, edge E7 cannot be removed.

2.3.4 Updating an Edge

Updating an isolated edge means changing one or more coordinates of the edge, but without changing the start point and end point.

To update an edge, use the SDO_TOPO_MAP.CHANGE_EDGE_COORDS procedure.

An edge cannot be updated if, as a result of the operation, it would intersect any other edge. See the Usage Notes for the SDO_TOPO_MAP.CHANGE_EDGE_COORDS procedure for more information about updating an edge.