| Oracle® Spatial Topology and Network Data Models 10g Release 1 (10.1) Part Number B10828-01 |
|
|
View PDF |
| Oracle® Spatial Topology and Network Data Models 10g Release 1 (10.1) Part Number B10828-01 |
|
|
View PDF |
The MDSYS.SDO_TOPO_MAP package contains subprograms (functions and procedures) that constitute part of the PL/SQL application programming interface (API) for the Spatial topology data model. This package contains subprograms related to editing topologies. These subprograms use a TopoMap object, either one that you previously created or that Spatial creates implicitly.
To use the subprograms in this chapter, you must understand the conceptual information about topology in Chapter 1, as well as the information about editing topologies in Chapter 2.
The rest of this chapter provides reference information on the SDO_TOPO_MAP subprograms, listed in alphabetical order.
Format
SDO_TOPO_MAP.ADD_EDGE(
topology IN VARCHAR2,
node_id1 IN NUMBER,
node_id2 IN NUMBER,
geom IN SDO_GEOMETRY
) RETURN NUMBER;
Description
Adds an edge to a topology, and returns the edge ID of the added edge.
Parameters
Name of the topology to which to add the edge, or null if you are using an updatable TopoMap object (see Section 2.1.2). Must not exceed 20 characters.
Node ID of the start node for the edge to be added.
Node ID of the end node for the edge to be added.
SDO_GEOMETRY object (line or contiguous line string geometry) representing the edge to be added.
Usage Notes
Spatial automatically assigns an edge ID to the added edge and inserts the appropriate entry in the <topology-name>_EDGE$ table. If the addition of the edge affects the face table information, Spatial automatically updates the appropriate entries in the <topology-name>_FACE$ table.
If node_id1 and node_id2 are the same value, a loop edge is created.
For information about adding and deleting nodes and edges, see Chapter 2.
This function is equivalent to using the addEdge method of the TopoMap class of the client-side Java API (described in Section 1.8.1).
Examples
The following example adds an edge connecting node N3 to node N4 in the current updatable TopoMap object. (The example refers to definitions and data from Section 1.11.)
CALL SDO_TOPO_MAP.ADD_EDGE(null, 3, 4,
SDO_GEOMETRY(2002, NULL, NULL, SDO_ELEM_INFO_ARRAY(1, 2, 1),
SDO_ORDINATE_ARRAY(25,35, 20,37)))
INTO :res_number;
Call completed.
SQL> PRINT res_number;
RES_NUMBER
----------
29
Format
SDO_TOPO_MAP.ADD_ISOLATED_NODE(
topology IN VARCHAR2,
face_id IN NUMBER,
point IN SDO_GEOMETRY
) RETURN NUMBER;
or
SDO_TOPO_MAP.ADD_ISOLATED_NODE(
topology IN VARCHAR2,
point IN SDO_GEOMETRY
) RETURN NUMBER;
Description
Adds an isolated node (that is, an island node) to a topology, and returns the node ID of the added isolated node.
Parameters
Name of the topology to which to add the isolated node, or null if you are using an updatable TopoMap object (see Section 2.1.2). Must not exceed 20 characters.
Face ID of the face on which the isolated node is to be added. (An exception is raised if the specified point is not on the specified face.)
SDO_GEOMETRY object (point geometry) representing the isolated node to be added.
Usage Notes
Spatial automatically assigns a node ID to the added node and inserts the appropriate entry in the <topology-name>_NODE$ table. Spatial also updates the <topology-name>_FACE$ table to include an entry for the added isolated node.
If you know the ID of the face on which the isolated node is to be added, you can specify the face_id parameter. If you specify this parameter, there are two benefits:
Validation: The function checks to see if the point is on the specified face, and raises an exception if it is not. Otherwise, the function checks to see if the point is on any face in the topology, and raises an exception if it is not.
Performance: The function checks only if the point is on the specified face. Otherwise, it checks potentially all faces in the topology to see if the point is on any face.
To add a non-isolated node, use the SDO_TOPO_MAP.ADD_NODE function.
For information about adding and deleting nodes and edges, see Chapter 2.
This function is equivalent to using the addIsolatedNode method of the TopoMap class of the client-side Java API (described in Section 1.8.1).
Examples
The following example adds an isolated node to the right of isolated node N4 on face F2, and it returns the node ID of the added node. It uses the current updatable TopoMap object. (The example refers to definitions and data from Section 1.11.)
DECLARE
result_num NUMBER;
BEGIN
result_num := SDO_TOPO_MAP.ADD_ISOLATED_NODE(null, 2,
SDO_GEOMETRY(2001, NULL, SDO_POINT_TYPE(22,37,NULL), NULL, NULL));
DBMS_OUTPUT.PUT_LINE('Result = ' || result_num);
END;
/
Result = 24
PL/SQL procedure successfully completed.
Format
SDO_TOPO_MAP.ADD_LOOP(
topology IN VARCHAR2,
node_id IN NUMBER,
geom IN SDO_GEOMETRY
) RETURN NUMBER;
Description
Adds an edge that loops and connects to the same node, and returns the edge ID of the added edge.
Parameters
Name of the topology to which to add the edge, or null if you are using an updatable TopoMap object (see Section 2.1.2). Must not exceed 20 characters.
Node ID of the node to which to add the edge that will start and end at this node.
SDO_GEOMETRY object (line string geometry) representing the edge to be added. The start and end points of the line string must be the same point representing node_id.
Usage Notes
This function creates a new edge, as well as a new face consisting of the interior of the loop. If the edge is added at an isolated node, the edge is an isolated edge. Spatial automatically updates the <topology-name>_EDGE$ and <topology-name>_FACE$ tables as needed.
For information about adding and deleting nodes and edges, see Chapter 2.
This function is equivalent to using the addLoop method of the TopoMap class of the client-side Java API (described in Section 1.8.1).
Examples
The following example adds an edge loop starting and ending at node N4, and it returns the edge ID of the added edge. It uses the current updatable TopoMap object. (The example refers to definitions and data from Section 1.11.)
CALL SDO_TOPO_MAP.ADD_LOOP(null, 4,
SDO_GEOMETRY(2002, NULL, NULL, SDO_ELEM_INFO_ARRAY(1, 2, 1),
SDO_ORDINATE_ARRAY(20,37, 20,39, 25,39, 20,37)))
INTO :res_number;
Call completed.
SQL> PRINT res_number;
RES_NUMBER
----------
30
Format
SDO_TOPO_MAP.ADD_NODE(
topology IN VARCHAR2,
edge_id IN NUMBER,
point IN SDO_GEOMETRY,
coord_index IN NUMBER,
is_new_shape_point IN VARCHAR2
) RETURN NUMBER;
Description
Adds a non-isolated node to a topology to split an existing edge, and returns the node ID of the added node.
Parameters
Name of the topology to which to add the node, or null if you are using an updatable TopoMap object (see Section 2.1.2). Must not exceed 20 characters.
Edge ID of the edge on which the node is to be added.
SDO_GEOMETRY object (point geometry) representing the node to be added. The point must be an existing shape point or be on the line segment connecting two consecutive shape points.
The index (position) of the array position in the edge coordinate array on or after which the node is to be added. Each vertex (node or shape point) has a position in the edge coordinate array. The start point (node) is index (position) 0, the first point after the start point is 1, and so on. (However, the coord_index value cannot be the index of the last vertex.) For example, if the edge coordinates are (2,2, 5,2, 8,3) the index of the second vertex (5,2) is 1.
TRUE if the added node is to be a new shape point following the indexed vertex (coord_index value) of the edge; FALSE if the added node is exactly on the indexed vertex.
A value of TRUE lets you add a node at a new point, breaking an edge segment at the coordinates specified in the point parameter. A value of FALSE causes the coordinates in the point parameter to be ignored, and causes the node to be added at the existing shape point associated with the coord_index value.
Usage Notes
Spatial automatically assigns a node ID to the added node and inserts the appropriate entry in the <topology-name>_NODE$ table. Spatial also creates a new edge and inserts the appropriate entry in the <topology-name>_EDGE$ table.
To add an isolated node (that is, an island node), use the SDO_TOPO_MAP.ADD_ISOLATED_NODE function.
For information about adding and deleting nodes and edges, see Chapter 2.
This function is equivalent to using the addNode method of the TopoMap class of the client-side Java API (described in Section 1.8.1).
Examples
The following example adds a non-isolated node to the right of node N2 on edge E2, and it returns the node ID of the added node. It uses the current updatable TopoMap object. (The example refers to definitions and data from Section 1.11.)
DECLARE
result_num NUMBER;
BEGIN
result_num := SDO_TOPO_MAP.ADD_NODE(null, 2,
SDO_GEOMETRY(2001, NULL, SDO_POINT_TYPE(27,30,NULL), NULL, NULL),
0, 'TRUE');
DBMS_OUTPUT.PUT_LINE('Result = ' || result_num);
END;
/
Result = 26
PL/SQL procedure successfully completed.
Format
SDO_TOPO_MAP.CHANGE_EDGE_COORDS(
topology IN VARCHAR2,
edge_id IN NUMBER,
geom IN SDO_GEOMETRY);
or
SDO_TOPO_MAP.CHANGE_EDGE_COORDS(
topology IN VARCHAR2,
edge_id IN NUMBER,
geom IN SDO_GEOMETRY,
moved_iso_nodes OUT SDO_NUMBER_ARRAY,
moved_iso_edges OUT SDO_NUMBER_ARRAY,
allow_iso_moves IN VARCHAR2);
Description
Changes the coordinates and related information about an edge.
Parameters
Name of the topology containing the edge, or null if you are using an updatable TopoMap object (see Section 2.1.2). Must not exceed 20 characters.
Edge ID of the edge whose coordinates are to be changed.
SDO_GEOMETRY object (line or contiguous line string geometry) representing the modified edge. The start and end points of the modified edge must be the same as for the original edge.
Output parameter in which, if the allow_iso_moves parameter value is TRUE, Spatial stores the node ID values of any isolated nodes that have moved to a different face as a result of this procedure. If the allow_iso_moves parameter value is FALSE, Spatial stores the node ID values of any isolated nodes that did not move but that would have moved to a different face if the allow_iso_moves parameter value had been TRUE.
Output parameter in which, if the allow_iso_moves parameter value is TRUE, Spatial stores the edge ID values of any isolated edges that have moved to a different face as a result of this procedure. If the allow_iso_moves parameter value is FALSE, Spatial stores the edge ID values of any isolated edges that did not move but that would have moved to a different face if the allow_iso_moves parameter value had been TRUE.
TRUE causes Spatial to allow an edge coordinates change operation that would cause any isolated nodes or edges to be in a different face, and to adjust the containing face information for such isolated nodes and edges; FALSE causes Spatial not to allow an edge coordinates change operation that would cause any isolated nodes or edges to be in a different face.
If you use the format that does not include the allow_iso_moves parameter, Spatial allows edge move operations that would cause any isolated nodes or edges to be in a different face, and it adjusts the containing face information for such isolated nodes and edges.
Usage Notes
If this procedure modifies a boundary between faces, Spatial automatically performs the following operations and updates the topology data model tables as needed: reassigning island nodes and faces, and adjusting the MBRs of the faces on both sides.
This procedure modifies the information about the specified edge in the <topology-name>_EDGE$ table (described in Section 1.5.1).
You cannot use this procedure to change the start point or the end point, or both, of the specified edge. To do any of these operations, you must delete the edge, delete the node or nodes for the start or end point (or both) to be changed, add the necessary new node or nodes, and add the edge.
For information about editing topology objects, see Chapter 2.
This procedure is equivalent to using the changeEdgeCoords method of the TopoMap class of the client-side Java API (described in Section 1.8.1).
Examples
The following example changes the coordinates of edge E1. (It changes only the third point, from 16,38 to 16,39.) It uses the current updatable TopoMap object. (The example refers to definitions and data from Section 1.11.)
CALL SDO_TOPO_MAP.CHANGE_EDGE_COORDS(null, 1,
SDO_GEOMETRY(2002, NULL, NULL, SDO_ELEM_INFO_ARRAY(1, 2, 1),
SDO_ORDINATE_ARRAY(8,30, 16,30, 16,39, 3,38, 3,30, 8,30)));
Format
SDO_TOPO_MAP.CLEAR_TOPO_MAP(
topo_map IN VARCHAR2);
Description
Clears all objects and changes in the cache associated with a TopoMap object.
Parameters
Name of the TopoMap object. (TopoMap objects are explained in Section 2.1.1.)
Usage Notes
If the TopoMap object is updatable, this procedure changes it to be read-only.
For information about using an in-memory cache to edit topology objects, see Section 2.1.
Contrast this procedure with the SDO_TOPO_MAP.UPDATE_TOPO_MAP procedure, which applies the changes in the cache associated with the TopoMap object to the topology. You cannot call the SDO_TOPO_MAP.CLEAR_TOPO_MAP procedure if you previously used the SDO_TOPO_MAP.UPDATE_TOPO_MAP procedure on the specified TopoMap object.
This procedure is equivalent to using the clearCache method of the TopoMap class of the client-side Java API (described in Section 1.8.1).
Examples
The following example clears the cache associated with the TopoMap object named CITY_DATA_TOPOMAP, which is associated with the topology named CITY_DATA. (The example refers to definitions and data from Section 1.11.)
CALL SDO_TOPO_MAP.CLEAR_TOPO_MAP('CITY_DATA_TOPOMAP');
Format
SDO_TOPO_MAP.COMMIT_TOPO_MAP;
Description
Updates the topology to reflect changes made to the current updatable TopoMap object, commits all changes to the database, and makes the TopoMap object read-only.
Parameters
None.
Usage Notes
Use this procedure when you are finished with a batch of edits to a topology and you want to commit all changes to the database. After the commit operation completes, you cannot edit the TopoMap object. To make further edits to the topology, you must either clear the cache (using the SDO_TOPO_MAP.CLEAR_TOPO_MAP procedure) or create a new TopoMap object (using the SDO_TOPO_MAP.CREATE_TOPO_MAP procedure), and then load the topology into the TopoMap object for update (using the SDO_TOPO_MAP.LOAD_TOPO_MAP function).
Contrast this procedure with the SDO_TOPO_MAP.UPDATE_TOPO_MAP procedure, which leaves the TopoMap object available for editing operations and which does not perform a commit operation (and thus does not end the database transaction).
To roll back all TopoMap object changes, use the SDO_TOPO_MAP.ROLLBACK_TOPO_MAP procedure.
For information about using an in-memory cache to edit topology objects, see Section 2.1.
This procedure is equivalent to using the commitDB method of the TopoMap class of the client-side Java API (described in Section 1.8.1).
Examples
The following example commits to the database all changes to the current updatable TopoMap object, and prevents further editing of the TopoMap object.
EXECUTE SDO_TOPO_MAP.COMMIT_TOPO_MAP;
Format
SDO_TOPO_MAP.CREATE_EDGE_INDEX(
topo_map IN VARCHAR2);
Description
Creates an internal R-tree index (or rebuilds the index if one already exists) on the edges in the cache associated with a TopoMap object.
Parameters
Name of the TopoMap object. (TopoMap objects are explained in Section 2.1.1.)
Usage Notes
You can cause Spatial to create in-memory R-tree indexes to be built on the edges and faces in the specified TopoMap object. These indexes use some memory resources and take some time to create; 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. If the TopoMap object is updatable and if you are performing many editing operations, you should probably rebuild the indexes periodically; however, if the TopoMap object will not be updated, create the indexes when or after loading the read-only topoMap object or after calling the SDO_TOPO_MAP.COMMIT_TOPO_MAP procedure.
Compare this procedure with the SDO_TOPO_MAP.CREATE_FACE_INDEX procedure, which creates an internal R-tree index (or rebuilds the index if one already exists) on the faces in the cache associated with a TopoMap object.
This procedure is equivalent to using the createEdgeIndex method of the TopoMap class of the client-side Java API (described in Section 1.8.1).
Examples
The following example creates an internal R-tree index (or rebuilds the index if one already exists) on the edges in the cache associated with the TopoMap object named CITY_DATA_TOPOMAP, which is associated with the topology named CITY_DATA. (The example refers to definitions and data from Section 1.11.)
CALL SDO_TOPO_MAP.CREATE_EDGE_INDEX('CITY_DATA_TOPOMAP');
Format
SDO_TOPO_MAP.CREATE_FACE_INDEX(
topo_map IN VARCHAR2);
Description
Creates an internal R-tree index (or rebuilds the index if one already exists) on the faces in the cache associated with a TopoMap object.
Parameters
Name of the TopoMap object. (TopoMap objects are explained in Section 2.1.1.)
Usage Notes
You can cause Spatial to create in-memory R-tree indexes to be built on the edges and faces in the specified TopoMap object. These indexes use some memory resources and take some time to create; 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. If the TopoMap object is updatable and if you are performing many editing operations, you should probably rebuild the indexes periodically; however, if the TopoMap object will not be updated, create the indexes when or after loading the read-only topoMap object or after calling the SDO_TOPO_MAP.COMMIT_TOPO_MAP procedure.
Compare this procedure with the SDO_TOPO_MAP.CREATE_EDGE_INDEX procedure, which creates an internal R-tree index (or rebuilds the index if one already exists) on the edges in the cache associated with a TopoMap object.
This procedure is equivalent to using the createFaceIndex method of the TopoMap class of the client-side Java API (described in Section 1.8.1).
Examples
The following example creates an internal R-tree index (or rebuilds the index if one already exists) on the faces in the cache associated with the TopoMap object named CITY_DATA_TOPOMAP, which is associated with the topology named CITY_DATA. (The example refers to definitions and data from Section 1.11.)
CALL SDO_TOPO_MAP.CREATE_FACE_INDEX('CITY_DATA_TOPOMAP');
Format
SDO_TOPO_MAP.CREATE_TOPO_MAP(
topology IN VARCHAR2,
topo_map IN VARCHAR2,
number_of_edges IN NUMBER DEFAULT 100,
number_of_nodes IN NUMBER DEFAULT 80,
number_of_faces IN NUMBER DEFAULT 30);
Description
Creates a TopoMap object cache associated with an existing topology.
Parameters
Name of the topology. Must not exceed 20 characters.
Name of the TopoMap object. (TopoMap objects are explained in Section 2.1.1.)
An estimate of the maximum number of edges that will be in the TopoMap object at any given time. If you do not specify this parameter, a default value of 100 is used.
An estimate of the maximum number of nodes that will be in the TopoMap object at any given time. If you do not specify this parameter, a default value of 80 is used.
An estimate of the maximum number of faces that will be in the TopoMap object at any given time. If you do not specify this parameter, a default value of 30 is used.
Usage Notes
The number_of_edges, number_of_nodes, and number_of_faces parameters let you improve the performance and memory usage of the procedure when you have a good idea of the approximate number of edges, nodes, or faces (or any combination) that will be placed in the cache associated with the specified TopoMap object. Spatial initially allocates memory cache for the specified or default number of objects of each type, and incrementally increases the allocation later if more objects need to be accommodated.
You can create more than one TopoMap object in a user session; however, there can be no more than one updatable TopoMap object at any given time in a user session.
For information about using an in-memory cache to edit topology objects, see Section 2.1.
Using this procedure is equivalent to calling the constructor of the TopoMap class of the client-side Java API (described in Section 1.8.1).
Examples
The following example creates a TopoMap object named CITY_DATA_TOPOMAP and its associated cache, and it associates the TopoMap object with the topology named CITY_DATA. (The example refers to definitions and data from Section 1.11.)
CALL SDO_TOPO_MAP.CREATE_TOPO_MAP('CITY_DATA', 'CITY_DATA_TOPOMAP');
Format
SDO_TOPO_MAP.DROP_TOPO_MAP(
topo_map IN VARCHAR2);
Description
Deletes a TopoMap object from the current user session.
Parameters
Name of the TopoMap object. (TopoMap objects are explained in Section 2.1.1.)
Usage Notes
This procedure rolls back any uncommitted changes if the TopoMap object is updatable (that is, performs the equivalent of an SDO_TOPO_MAP.ROLLBACK_TOPO_MAP operation). It clears the cache associated with the TopoMap object, and removes the TopoMap object from the session.
For information about using an in-memory cache to edit topology objects, see Section 2.1.
Using this procedure is equivalent to setting the variable of the TopoMap object to a null value in a client-side Java application. (The client-side Java API is described in Section 1.8.1.)
Examples
The following example drops the TopoMap object named CITY_DATA_TOPOMAP. (The example refers to definitions and data from Section 1.11.)
CALL SDO_TOPO_MAP.DROP_TOPO_MAP('CITY_DATA_TOPOMAP');
Format
SDO_TOPO_MAP.GET_CONTAINING_FACE(
topology IN VARCHAR2,
topo_map IN VARCHAR2,
point IN SDO_GEOMETRY
) RETURN NUMBER;
Description
Returns the face ID number of the face that contains the specified point.
Parameters
Name of the topology that contains the face and the point, or a null value, as explained in Section 2.1.3. Must not exceed 20 characters.
Name of the TopoMap object, or a null value, as explained in Section 2.1.3. (TopoMap objects are explained in Section 2.1.1.)
Geometry object specifying the point.
Usage Notes
The topology or topo_map parameter should specify a valid name, as explained in Section 2.1.3.
This function determines, from the faces in the specified TopoMap object (including any island faces), which one face (if any) contains the specified point in its open set. (The open set of a face consists of all points inside, but not on the boundary of, the face.) If the point is exactly on the boundary of a face, the function returns a value of 0 (zero).
If the entire topology has been loaded into the TopoMap object and if the point is not in any finite face in the cache, this function returns a value of -1 (for the universal face). If a window from the topology has been loaded into the TopoMap object and if the point is not in any finite face in the cache, this function returns a value of -1 (for the universal face) if the point is inside the window and a value of 0 (zero) if the point is outside the window.
This function is equivalent to using the getContainingFace method of the TopoMap class of the client-side Java API (described in Section 1.8.1).
Examples
The following example returns the face ID number of the face that contains the point at (22, 37) in the CITY_DATA_TOPOMAP TopoMap object. (The example refers to definitions and data from Section 1.11.)
SELECT SDO_TOPO_MAP.GET_CONTAINING_FACE(null, 'CITY_DATA_TOPOMAP', SDO_GEOMETRY(2001, NULL, SDO_POINT_TYPE(22,37,NULL), NULL, NULL)) FROM DUAL;
SDO_TOPO_MAP.GET_CONTAINING_FACE(NULL,'CITY_DATA_TOPOMAP',SDO_GEOMETRY(2001,NULL,SDO
--------------------------------------------------------------------------------
2
Format
SDO_TOPO_MAP.GET_EDGE_ADDITIONS() RETURN SDO_NUMBER_ARRAY;
Description
Returns an array of edge ID numbers of edges that have been added to the current updatable TopoMap object.
Parameters
None.
Usage Notes
This function returns the edge ID numbers of edges in the current updatable TopoMap object that have been added since the object was most recently loaded (using SDO_TOPO_MAP.LOAD_TOPO_MAP), updated (using SDO_TOPO_MAP.UPDATE_TOPO_MAP), cleared (using SDO_TOPO_MAP.CLEAR_TOPO_MAP), committed (using SDO_TOPO_MAP.COMMIT_TOPO_MAP), or rolled back (using SDO_TOPO_MAP.ROLLBACK_TOPO_MAP). If there have been no additions during that time, the function returns an empty SDO_NUMBER_ARRAY object.
This function is equivalent to using the getEdgeAdditions method of the TopoMap class of the client-side Java API (described in Section 1.8.1).
Examples
The following example returns the edge ID numbers of edges that have been added to the current updatable TopoMap object.
SELECT SDO_TOPO_MAP.GET_EDGE_ADDITIONS FROM DUAL; GET_EDGE_ADDITIONS -------------------------------------------------------------------------------- SDO_NUMBER_ARRAY(28, 29, 30, 32)
Format
SDO_TOPO_MAP.GET_EDGE_CHANGES() RETURN SDO_NUMBER_ARRAY;
Description
Returns an array of edge ID numbers of edges that have been changed (modified) in the current updatable TopoMap object.
Parameters
None.
Usage Notes
This function returns the edge ID numbers of edges in the current updatable TopoMap object that have been changed since the object was most recently loaded (using SDO_TOPO_MAP.LOAD_TOPO_MAP), updated (using SDO_TOPO_MAP.UPDATE_TOPO_MAP), cleared (using SDO_TOPO_MAP.CLEAR_TOPO_MAP), committed (using SDO_TOPO_MAP.COMMIT_TOPO_MAP), or rolled back (using SDO_TOPO_MAP.ROLLBACK_TOPO_MAP). If there have been no changes during that time, the function returns an empty SDO_NUMBER_ARRAY object.
This function is equivalent to using the getEdgeChanges method of the TopoMap class of the client-side Java API (described in Section 1.8.1).
Examples
The following example returns the edge ID numbers of edges that have been changed in the current updatable TopoMap object.
SELECT SDO_TOPO_MAP.GET_EDGE_CHANGES FROM DUAL; GET_EDGE_CHANGES -------------------------------------------------------------------------------- SDO_NUMBER_ARRAY(3, 2, 1)
Format
SDO_TOPO_MAP.GET_EDGE_COORDS(
topology IN VARCHAR2,
topo_map IN VARCHAR2,
edge_id IN NUMBER
) RETURN SDO_NUMBER_ARRAY;
Description
Returns an array with the coordinates of the start node, shape points, and end node for the specified edge.
Parameters
Name of the topology that contains the edge, or a null value, as explained in Section 2.1.3. Must not exceed 20 characters.
Name of the TopoMap object, or a null value, as explained in Section 2.1.3. (TopoMap objects are explained in Section 2.1.1.)
Edge ID value of the edge.
Usage Notes
The topology or topo_map parameter should specify a valid name, as explained in Section 2.1.3.
This function is equivalent to using the getEdgeCoords method of the TopoMap class of the client-side Java API (described in Section 1.8.1).
Examples
The following example returns the coordinates of the start node, shape points, and end node for the edge whose edge ID value is 1. The returned array contains coordinates for six points. (The example refers to definitions and data from Section 1.11.)
SELECT SDO_TOPO_MAP.GET_EDGE_COORDS(null, 'CITY_DATA_TOPOMAP', 1) FROM DUAL; SDO_TOPO_MAP.GET_EDGE_COORDS(NULL,'CITY_DATA_TOPOMAP',1) -------------------------------------------------------------------------------- SDO_NUMBER_ARRAY(8, 30, 16, 30, 16, 38, 3, 38, 3, 30, 8, 30)
Format
SDO_TOPO_MAP.GET_EDGE_DELETIONS() RETURN SDO_NUMBER_ARRAY;
Description
Returns an array of edge ID numbers of edges that have been deleted from the current updatable TopoMap object.
Parameters
None.
Usage Notes
This function returns the edge ID numbers of edges in the current updatable TopoMap object that have been deleted since the object was most recently loaded (using SDO_TOPO_MAP.LOAD_TOPO_MAP), updated (using SDO_TOPO_MAP.UPDATE_TOPO_MAP), cleared (using SDO_TOPO_MAP.CLEAR_TOPO_MAP), committed (using SDO_TOPO_MAP.COMMIT_TOPO_MAP), or rolled back (using SDO_TOPO_MAP.ROLLBACK_TOPO_MAP). If there have been no deletions during that time, the function returns an empty SDO_NUMBER_ARRAY object.
This function is equivalent to using the getEdgeDeletions method of the TopoMap class of the client-side Java API (described in Section 1.8.1).
Examples
The following example returns the edge ID numbers of edges that have been deleted from the current updatable TopoMap object. In this case, the return of an empty SDO_NUMBER_ARRAY object indicates that no edges have been deleted.
SELECT SDO_TOPO_MAP.GET_EDGE_DELETIONS FROM DUAL; GET_EDGE_DELETIONS -------------------------------------------------------------------------------- SDO_NUMBER_ARRAY()
Format
SDO_TOPO_MAP.GET_EDGE_NODES(
topology IN VARCHAR2,
topo_map IN VARCHAR2,
edge_id IN NUMBER
) RETURN SDO_NUMBER_ARRAY;
Description
Returns an array with the ID numbers of the start and end nodes on the specified edge.
Parameters
Name of the topology that contains the edge, or a null value, as explained in Section 2.1.3. Must not exceed 20 characters.
Name of the TopoMap object, or a null value, as explained in Section 2.1.3. (TopoMap objects are explained in Section 2.1.1.)
Edge ID value of the edge.
Usage Notes
The topology or topo_map parameter should specify a valid name, as explained in Section 2.1.3.
If the edge starts and ends at a node, the ID number of the node is the first and last number in the array.
This function has no exact equivalent method in the TopoMap class of the client-side Java API (described in Section 1.8.1). The getEdge method returns a Java edge object of the oracle.spatial.topo.Edge class.
Examples
The following example returns the ID numbers of the nodes on the edge whose edge ID value is 1. The returned array contains two nodes ID numbers, both of them 1, because the specified edge starts and ends at the node with node ID 1 and has a loop edge. (The example refers to definitions and data from Section 1.11.)
SELECT SDO_TOPO_MAP.GET_EDGE_NODES(null, 'CITY_DATA_TOPOMAP', 1) FROM DUAL; SDO_TOPO_MAP.GET_EDGE_NODES(NULL,'CITY_DATA_TOPOMAP',1) -------------------------------------------------------------------------------- SDO_NUMBER_ARRAY(1, 1)
Format
SDO_TOPO_MAP.GET_FACE_ADDITIONS() RETURN SDO_NUMBER_ARRAY
Description
Returns an array of face ID numbers of faces that have been added to the current updatable TopoMap object.
Parameters
None.
Usage Notes
This function returns the face ID numbers of faces in the current updatable TopoMap object that have been added since the object was most recently loaded (using SDO_TOPO_MAP.LOAD_TOPO_MAP), updated (using SDO_TOPO_MAP.UPDATE_TOPO_MAP), cleared (using SDO_TOPO_MAP.CLEAR_TOPO_MAP), committed (using SDO_TOPO_MAP.COMMIT_TOPO_MAP), or rolled back (using SDO_TOPO_MAP.ROLLBACK_TOPO_MAP). If there have been no additions during that time, the function returns an empty SDO_NUMBER_ARRAY object.
This function is equivalent to using the getFaceAdditions method of the TopoMap class of the client-side Java API (described in Section 1.8.1).
Examples
The following example returns the face ID numbers of faces that have been added to the current updatable TopoMap object.
SELECT SDO_TOPO_MAP.GET_FACE_ADDITIONS FROM DUAL; GET_FACE_ADDITIONS -------------------------------------------------------------------------------- SDO_NUMBER_ARRAY(11)
Format
SDO_TOPO_MAP.GET_FACE_CHANGES() RETURN SDO_NUMBER_ARRAY;
Description
Returns an array of face ID numbers of faces that have been changed (modified) in the current updatable TopoMap object.
Parameters
None.
Usage Notes
This function returns the face ID numbers of faces in the current updatable TopoMap object that have been changed since the object was most recently loaded (using SDO_TOPO_MAP.LOAD_TOPO_MAP), updated (using SDO_TOPO_MAP.UPDATE_TOPO_MAP), cleared (using SDO_TOPO_MAP.CLEAR_TOPO_MAP), committed (using SDO_TOPO_MAP.COMMIT_TOPO_MAP), or rolled back (using SDO_TOPO_MAP.ROLLBACK_TOPO_MAP). If there have been no changes during that time, the function returns an empty SDO_NUMBER_ARRAY object.
This function is equivalent to using the getFaceChanges method of the TopoMap class of the client-side Java API (described in Section 1.8.1).
Examples
The following example returns the face ID numbers of faces that have been changed in the current updatable TopoMap object.
SELECT SDO_TOPO_MAP.GET_FACE_CHANGES FROM DUAL; GET_FACE_CHANGES -------------------------------------------------------------------------------- SDO_NUMBER_ARRAY(2, 1, -1)
Format
SDO_TOPO_MAP.GET_FACE_DELETIONS() RETURN SDO_NUMBER_ARRAY;
Description
Returns an array of face ID numbers of faces that have been deleted from the current updatable TopoMap object.
Parameters
None.
Usage Notes
This function returns the face ID numbers of faces in the current updatable TopoMap object that have been deleted since the object was most recently loaded (using SDO_TOPO_MAP.LOAD_TOPO_MAP), updated (using SDO_TOPO_MAP.UPDATE_TOPO_MAP), cleared (using SDO_TOPO_MAP.CLEAR_TOPO_MAP), committed (using SDO_TOPO_MAP.COMMIT_TOPO_MAP), or rolled back (using SDO_TOPO_MAP.ROLLBACK_TOPO_MAP). If there have been no deletions during that time, the function returns an empty SDO_NUMBER_ARRAY object.
This function is equivalent to using the getFaceDeletions method of the TopoMap class of the client-side Java API (described in Section 1.8.1).
Examples
The following example returns the face ID numbers of faces that have been deleted from the current updatable TopoMap object. In this case, the return of an empty SDO_NUMBER_ARRAY object indicates that no faces have been deleted.
SELECT SDO_TOPO_MAP.GET_FACE_DELETIONS FROM DUAL; GET_FACE_DELETIONS -------------------------------------------------------------------------------- SDO_NUMBER_ARRAY()
Format
SDO_TOPO_MAP.GET_NEAREST_EDGE(
topology IN VARCHAR2,
topo_map IN VARCHAR2,
point IN SDO_GEOMETRY
) RETURN NUMBER;
Description
Returns the edge ID number of the edge that is nearest (closest to) the specified point.
Parameters
Name of the topology that contains the edge and the point, or a null value, as explained in Section 2.1.3. Must not exceed 20 characters.
Name of the TopoMap object, or a null value, as explained in Section 2.1.3. (TopoMap objects are explained in Section 2.1.1.)
Geometry object specifying the point.
Usage Notes
The topology or topo_map parameter should specify a valid name, as explained in Section 2.1.3.
The nearest edge is determined from the representation of the topology in the database, using the spatial index. If there are changed, added, or deleted edges in the instance and the database has not been updated to reflect those changes, the result may not reflect the true situation in the TopoMap object cache.
If multiple edges are equally close to the point, one of the edge ID values is returned.
This function is equivalent to using the getNearestEdge method of the TopoMap class of the client-side Java API (described in Section 1.8.1).
Examples
The following example returns the edge ID number of the edge that is closest to the point at (8, 8) in the CITY_DATA_TOPOMAP TopoMap object. (The example refers to definitions and data from Section 1.11.)
SELECT SDO_TOPO_MAP.GET_NEAREST_EDGE(null, 'CITY_DATA_TOPOMAP',
SDO_GEOMETRY(2001, NULL, SDO_POINT_TYPE(8,8,NULL), NULL, NULL))
FROM DUAL;
SDO_TOPO_MAP.GET_NEAREST_EDGE(NULL,'CITY_DATA_TOPOMAP',SDO_GEOMETRY(2001,NULL,SD
--------------------------------------------------------------------------------
22
Format
SDO_TOPO_MAP.GET_NEAREST_NODE(
topology IN VARCHAR2,
topo_map IN VARCHAR2,
point IN SDO_GEOMETRY
) RETURN NUMBER;
Description
Returns the node ID number of the node that is nearest (closest to) the specified point.
Parameters
Name of the topology that contains the node and the point, or a null value, as explained in Section 2.1.3. Must not exceed 20 characters.
Name of the TopoMap object, or a null value, as explained in Section 2.1.3. (TopoMap objects are explained in Section 2.1.1.)
Geometry object specifying the point.
Usage Notes
The topology or topo_map parameter should specify a valid name, as explained in Section 2.1.3.
The nearest node is determined from the representation of the topology in the database, using the spatial index. If there are changed, added, or deleted nodes in the instance and the database has not been updated to reflect those changes, the result may not reflect the true situation in the TopoMap object cache.
If multiple edges are equally close to the point, one of the edge ID values is returned.
This function is equivalent to using the getNearestNode method of the TopoMap class of the client-side Java API (described in Section 1.8.1).
Examples
The following example returns the node ID number of the node that is closest to the point at (8, 8) in the CITY_DATA_TOPOMAP TopoMap object. (The example refers to definitions and data from Section 1.11.)
SELECT SDO_TOPO_MAP.GET_NEAREST_NODE(null, 'CITY_DATA_TOPOMAP',
SDO_GEOMETRY(2001, NULL, SDO_POINT_TYPE(8,8,NULL), NULL, NULL))
FROM DUAL;
SDO_TOPO_MAP.GET_NEAREST_NODE(NULL,'CITY_DATA_TOPOMAP',SDO_GEOMETRY(2001,NULL,SD
--------------------------------------------------------------------------------
8
Format
SDO_TOPO_MAP.GET_NODE_ADDITIONS() RETURN SDO_NUMBER_ARRAY;
Description
Returns an array of node ID numbers of nodes that have been added to the current updatable TopoMap object.
Parameters
None.
Usage Notes
This function returns the node ID numbers of nodes in the current updatable TopoMap object that have been added since the object was most recently loaded (using SDO_TOPO_MAP.LOAD_TOPO_MAP), updated (using SDO_TOPO_MAP.UPDATE_TOPO_MAP), cleared (using SDO_TOPO_MAP.CLEAR_TOPO_MAP), committed (using SDO_TOPO_MAP.COMMIT_TOPO_MAP), or rolled back (using SDO_TOPO_MAP.ROLLBACK_TOPO_MAP). If there have been no additions during that time, the function returns an empty SDO_NUMBER_ARRAY object.
This function is equivalent to using the getNodeAdditions method of the TopoMap class of the client-side Java API (described in Section 1.8.1).
Examples
The following example returns the node ID numbers of nodes that have been added to the current updatable TopoMap object.
SELECT SDO_TOPO_MAP.GET_NODE_ADDITIONS FROM DUAL; GET_NODE_ADDITIONS -------------------------------------------------------------------------------- SDO_NUMBER_ARRAY(24, 25, 26, 27, 28)
Format
SDO_TOPO_MAP.GET_NODE_CHANGES() RETURN SDO_NUMBER_ARRAY;
Description
Returns an array of node ID numbers of nodes that have been changed (modified) in the current updatable TopoMap object.
Parameters
None.
Usage Notes
This function returns the node ID numbers of nodes in the current updatable TopoMap object that have been changed since the object was most recently loaded (using SDO_TOPO_MAP.LOAD_TOPO_MAP), updated (using SDO_TOPO_MAP.UPDATE_TOPO_MAP), cleared (using SDO_TOPO_MAP.CLEAR_TOPO_MAP), committed (using SDO_TOPO_MAP.COMMIT_TOPO_MAP), or rolled back (using SDO_TOPO_MAP.ROLLBACK_TOPO_MAP). If there have been no changes during that time, the function returns an empty SDO_NUMBER_ARRAY object.
This function is equivalent to using the getNodeChanges method of the TopoMap class of the client-side Java API (described in Section 1.8.1).
Examples
The following example returns the node ID numbers of nodes that have been changed in the current updatable TopoMap object.
SELECT SDO_TOPO_MAP.GET_NODE_CHANGES FROM DUAL; GET_NODE_CHANGES -------------------------------------------------------------------------------- SDO_NUMBER_ARRAY(2, 4)
Format
SDO_TOPO_MAP.GET_NODE_COORD(
topology IN VARCHAR2,
topo_map IN VARCHAR2,
node_id IN NUMBER
) RETURN SDO_POINT_TYPE;
Description
Returns an SDO_POINT_TYPE object with the coordinates of the specified node.
Parameters
Name of the topology that contains the node, or a null value, as explained in Section 2.1.3. Must not exceed 20 characters.
Name of the TopoMap object, or a null value, as explained in Section 2.1.3. (TopoMap objects are explained in Section 2.1.1.)
Node ID value of the node.
Usage Notes
The topology or topo_map parameter should specify a valid name, as explained in Section 2.1.3.
This function is equivalent to using the getNodeCoord method of the TopoMap class of the client-side Java API (described in Section 1.8.1).
Examples
The following example returns the coordinates of the node whose node ID value is 14. (The example refers to definitions and data from Section 1.11.)
SELECT SDO_TOPO_MAP.GET_NODE_COORD(null, 'CITY_DATA_TOPOMAP', 14) FROM DUAL; SDO_TOPO_MAP.GET_NODE_COORD(NULL,'CITY_DATA_TOPOMAP',14)(X, Y, Z) -------------------------------------------------------------------------------- SDO_POINT_TYPE(21, 14, NULL)
Format
SDO_TOPO_MAP.GET_NODE_DELETIONS() RETURN SDO_NUMBER_ARRAY;
Description
Returns an array of node ID numbers of nodes that have been deleted from the current updatable TopoMap object.
Parameters
None.
Usage Notes
This function returns the node ID numbers of nodes in the current updatable TopoMap object that have been deleted since the object was most recently loaded (using SDO_TOPO_MAP.LOAD_TOPO_MAP), updated (using SDO_TOPO_MAP.UPDATE_TOPO_MAP), cleared (using SDO_TOPO_MAP.CLEAR_TOPO_MAP), committed (using SDO_TOPO_MAP.COMMIT_TOPO_MAP), or rolled back (using SDO_TOPO_MAP.ROLLBACK_TOPO_MAP). If there have been no deletions during that time, the function returns an empty SDO_NUMBER_ARRAY object.
This function is equivalent to using the getNodeDeletions method of the TopoMap class of the client-side Java API (described in Section 1.8.1).
Examples
The following example returns the node ID numbers of nodes that have been deleted from the current updatable TopoMap object. In this case, the return of an empty SDO_NUMBER_ARRAY object indicates that no nodes have been deleted.
SELECT SDO_TOPO_MAP.GET_NODE_DELETIONS FROM DUAL; GET_NODE_DELETIONS -------------------------------------------------------------------------------- SDO_NUMBER_ARRAY()
Format
SDO_TOPO_MAP.GET_NODE_STAR(
topology IN VARCHAR2,
topo_map IN VARCHAR2,
node_id IN NUMBER
) RETURN SDO_NUMBER_ARRAY;
Description
Returns an SDO_NUMBER_ARRAY object with the edge ID numbers, in clockwise order, of the edges that are connected to the specified node.
Parameters
Name of the topology that contains the node, or a null value, as explained in Section 2.1.3. Must not exceed 20 characters.
Name of the TopoMap object, or a null value, as explained in Section 2.1.3. (TopoMap objects are explained in Section 2.1.1.)
Node ID value of the node.
Usage Notes
The node star of a node is the edges that are connected to the node.
The topology or topo_map parameter should specify a valid name, as explained in Section 2.1.3.
This function is equivalent to using the getNodeStar method of the TopoMap class of the client-side Java API (described in Section 1.8.1).
Examples
The following example returns the node star of the node whose node ID value is 14. (The example refers to definitions and data from Section 1.11.)
SELECT SDO_TOPO_MAP.GET_NODE_STAR(null, 'CITY_DATA_TOPOMAP', 14) FROM DUAL; SDO_TOPO_MAP.GET_NODE_STAR(NULL,'CITY_DATA_TOPOMAP',14) -------------------------------------------------------------------------------- SDO_NUMBER_ARRAY(19, -10, -20, -9)
Format
SDO_TOPO_MAP.GET_TOPO_NAME(
topo_map IN VARCHAR2
) RETURN VARCHAR2;
Description
Returns the name of the topology associated with the specified TopoMap object.
Parameters
Name of the TopoMap object. (TopoMap objects are explained in Section 2.1.1.)
Usage Notes
This function is equivalent to using the getTopoName method of the TopoMap class of the client-side Java API (described in Section 1.8.1).
Examples
The following example returns the name of the topology associated with the TopoMap object named CITY_DATA_TOPOMAP. (The example refers to definitions and data from Section 1.11.)
SELECT SDO_TOPO_MAP.GET_TOPO_NAME('CITY_DATA_TOPOMAP') FROM DUAL;
SDO_TOPO_MAP.GET_TOPO_NAME('CITY_DATA_TOPOMAP')
--------------------------------------------------------------------------------
CITY_DATA
Format
SDO_TOPO_MAP.LIST_TOPO_MAPS() RETURN VARCHAR2;
Description
Returns a comma-delimited list of entries for each TopoMap object currently active in the session, or an empty string if there are no currently active TopoMap objects.
Parameters
None.
Usage Notes
Each entry in the comma-delimited list contains the following information: the name of the TopoMap object, the name of the topology associated with the TopoMap object, and either updatable if the TopoMap object can be updated (that is, edited) or read-only if the TopoMap object cannot be updated.
For more information about TopoMap objects, including updatable and read-only status, see Section 2.1.1.
To remove a TopoMap object from the session, use the SDO_TOPO_MAP.DROP_TOPO_MAP procedure.
Examples
The following example lists the Topomap object name, topology name, and whether the object is updatable or read-only for each TopoMap object currently active in the session. (The example refers to definitions and data from Section 1.11.)
SELECT SDO_TOPO_MAP.LIST_TOPO_MAPS FROM DUAL; LIST_TOPO_MAPS -------------------------------------------------------------------------------- (CITY_DATA_TOPOMAP, CITY_DATA, updatable)
Format
SDO_TOPO_MAP.LOAD_TOPO_MAP(
topo_map IN VARCHAR2,
allow_updates IN VARCHAR2,
build_indexes IN VARCHAR2 DEFAULT 'TRUE'
) RETURN VARCHAR2;
or
SDO_TOPO_MAP.LOAD_TOPO_MAP(
topo_map IN VARCHAR2,
xmin IN NUMBER,
ymin IN NUMBER,
xmax IN NUMBER,
ymax IN NUMBER,
allow_updates IN VARCHAR2,
build_indexes IN VARCHAR2 DEFAULT 'TRUE'
) RETURN VARCHAR2;
Description
Loads an entire topology or a window (rectangular portion) of a topology into a TopoMap object; returns the string TRUE if topology objects were loaded into the cache, and FALSE if no topology objects were loaded into the cache.
Parameters
Name of the TopoMap object. (TopoMap objects are explained in Section 2.1.1.)
Lower-left X coordinate value for the window (rectangular portion of the topology) to be loaded.
See the Usage Notes and Figure 4-1 for information about which topology objects are loaded when you specify a window.
Lower-left Y coordinate value for the window (rectangular portion of the topology) to be loaded.
Upper-right X coordinate value for the window (rectangular portion of the topology) to be loaded.
Upper-right Y coordinate value for the window (rectangular portion of the topology) to be loaded.
TRUE makes the TopoMap object updatable; that is, it allows topology editing operations to be performed on the TopoMap object. FALSE makes the TopoMap object read-only; that is, it does not allow topology editing operations to be performed on the TopoMap object.
There can be no more than one updatable TopoMap object active in a user session.
TRUE (the default) builds in-memory R-tree indexes for edge and face data; FALSE does not build in-memory R-tree indexes for edge and face data. The indexes improve the performance of editing operations, especially with large topologies.
Usage Notes
You must create the TopoMap object (using the SDO_TOPO_MAP.CREATE_TOPO_MAP procedure) before you load data into it.
You cannot use this function if the TopoMap object already contains data. If the TopoMap object contains any data, you must do one of the following before calling this function: commit the changes (using the SDO_TOPO_MAP.COMMIT_TOPO_MAP procedure) and clear the cache (using the SDO_TOPO_MAP.CLEAR_TOPO_MAP procedure), or roll back the changes (using the SDO_TOPO_MAP.ROLLBACK_TOPO_MAP procedure).
For information about using an in-memory cache to edit topology objects, see Section 2.1.
This function is equivalent to using the loadTopoMap method of the TopoMap class of the client-side Java API (described in Section 1.8.1).
If you specify a window using the xmin, ymin, xmax, and ymax parameters, all topology objects that are inside or on the window, all faces and edges that overlap the window, and all edges whose definitions depend on a face inside or partially within the window are loaded. For example, if an isolated node is on a face that is in the window, or if an edge has a left or right face that is in the window, it is loaded. Consider the topology and the window (shown by a dashed line) in Figure 4-1.
With the window shown in Figure 4-1:
Face F1 is loaded because it is partially in the window.
The following edges are loaded: E3, E4, E5, E6, E7, E8, E9, E10, E11, E12, E13, E14, E16.
Edges E1, E2, and E15 are not loaded, because their definitions do not refer to any face within the window (here, face F1).
The following nodes are loaded: N5, N6, N7, N8, N9, N10, N11, N16, N19, N20.
Non-isolated nodes N1, N2, N3, N4, N12, N13, N14, N15, N17, and N18 are not loaded, because they are not inside or on the window boundary.
Examples
The following example loads all CITY_DATA topology elements into its associated TopoMap object for editing (not read-only) and builds the in-memory R-tree indexes by default. It returns a result indicating that the operation was successful and that some topology objects were loaded into the cache. (The example refers to definitions and data from Section 1.11.)
CALL SDO_TOPO_MAP.LOAD_TOPO_MAP('CITY_DATA_TOPOMAP', 'TRUE') INTO :res_varchar;
Call completed.
PRINT res_varchar;
RES_VARCHAR
--------------------------------------------------------------------------------
TRUE
Format
SDO_TOPO_MAP.MOVE_EDGE(
topology IN VARCHAR2,
edge_id IN NUMBER,
s_node_id IN NUMBER,
t_node_id IN NUMBER,
edge_coords IN SDO_NUMBER_ARRAY);
or
SDO_TOPO_MAP.MOVE_EDGE(
topology IN VARCHAR2,
edge_id IN NUMBER,
s_node_id IN NUMBER,
t_node_id IN NUMBER,
edge_coords IN SDO_NUMBER_ARRAY,
moved_iso_nodes OUT SDO_NUMBER_ARRAY,
moved_iso_edges OUT SDO_NUMBER_ARRAY,
allow_iso_moves IN VARCHAR2);
Description
Moves a non-isolated edge.
Parameters
Name of the topology in which to move the edge, or null if you are using an updatable TopoMap object (see Section 2.1.2). Must not exceed 20 characters.
Edge ID of the edge to be moved.
An array of coordinates of the resulting moved edge, from start point to end point.
Node ID of the source node, which identifies the point (start node or end node of the edge) affected by the move, before the move occurs. For example, if the end point of edge E19 is to be moved from node N17 to node N16, the s_node_id value is the node ID number for node N17.
Node ID of the target node, which identifies the point affected by the move, after the move occurs. For example, if the end point of edge E19 is to be moved from node N17 to node N16, the t_node_id value is the node ID number for node N16.
Output parameter in which, if the allow_iso_moves parameter value is TRUE, Spatial stores the node ID values of any isolated nodes that have moved to a different face as a result of this procedure. If the allow_iso_moves parameter value is FALSE, Spatial stores the node ID values of any isolated nodes that did not move but that would have moved to a different face if the allow_iso_moves parameter value had been TRUE.
Output parameter in which, if the allow_iso_moves parameter value is TRUE, Spatial stores the edge ID values of any isolated edges that have moved to a different face as a result of this procedure. If the allow_iso_moves parameter value is FALSE, Spatial stores the edge ID values of any isolated edges that did not move but that would have moved to a different face if the allow_iso_moves parameter value had been TRUE.
TRUE causes Spatial to allow an edge move operation that would cause any isolated nodes or edges to be in a different face, and to adjust the containing face information for such isolated nodes and edges; FALSE causes Spatial not to allow an edge move operation that would cause any isolated nodes or edges to be in a different face.
If you use the format that does not include the allow_iso_moves parameter, Spatial allows an edge move operation that would cause any isolated nodes or edges to be in a different face, and it adjusts the containing face information for such isolated nodes and edges.
Usage Notes
For information about moving edges, see Section 2.3.2.
This function is equivalent to using the moveEdge method of the TopoMap class of the client-side Java API (described in Section 1.8.1).
Examples
The following example moves the edge with edge ID value 19, and it displays the edge coordinates before and after the move. The edge move operation moves the end point of the edge from the node with node ID value 17 to the node with node ID value 16. (The edge being moved is E19 in Figure 1-2 in Section 1.2; and the edge is being changed from going vertically up to node N17, to going diagonally up and left to node N16. The example refers to definitions and data from Section 1.11.)
-- Get coordinates of edge E19. SELECT SDO_TOPO_MAP.GET_EDGE_COORDS(null, 'CITY_DATA_TOPOMAP', 19) FROM DUAL; SDO_TOPO_MAP.GET_EDGE_COORDS(NULL,'CITY_DATA_TOPOMAP',19) -------------------------------------------------------------------------------- SDO_NUMBER_ARRAY(21, 14, 21, 22) -- Move edge E19: from N14 -> N17 to N14 -> N16. The 3rd and 4th parameters -- identify N17 and N16. CALL SDO_TOPO_MAP.MOVE_EDGE(null, 19, 17, 16, SDO_NUMBER_ARRAY(21,14, 9,22)); Call completed. -- Get coordinates of edge E19 after the move. SELECT SDO_TOPO_MAP.GET_EDGE_COORDS(null, 'CITY_DATA_TOPOMAP', 19) FROM DUAL; SDO_TOPO_MAP.GET_EDGE_COORDS(NULL,'CITY_DATA_TOPOMAP',19) -------------------------------------------------------------------------------- SDO_NUMBER_ARRAY(21, 14, 9, 22)
Format
SDO_TOPO_MAP.MOVE_ISOLATED_NODE(
topology IN VARCHAR2,
node_id IN NUMBER,
point IN SDO_GEOMETRY;
Description
Moves an isolated (island) node.
Parameters
Name of the topology in which to move the node, or null if you are using an updatable TopoMap object (see Section 2.1.2). Must not exceed 20 characters.
Node ID of the node to be moved.
SDO_GEOMETRY object (point geometry) representing the location to which the isolated node is to be moved.
Usage Notes
For information about moving nodes, see Section 2.2.2.
This procedure is equivalent to using the moveIsolatedNode method of the TopoMap class of the client-side Java API (described in Section 1.8.1).
Examples
The following example adds an isolated node and then moves it. (The example refers to definitions and data from Section 1.11.)
CALL SDO_TOPO_MAP.ADD_ISOLATED_NODE(null, 2, SDO_GEOMETRY(2001, NULL, SDO_POINT_TYPE(22,38,NULL), NULL, NULL)) INTO :res_number; -- Move the just-added isolated node (from 20,38 to 22,39). CALL SDO_TOPO_MAP.MOVE_ISOLATED_NODE( null, :res_number, SDO_GEOMETRY(2001, NULL, SDO_POINT_TYPE(22,39,NULL), NULL, NULL));
Format
SDO_TOPO_MAP.MOVE_NODE(
topology IN VARCHAR2,
node_id IN NUMBER,
edges_coords IN SDO_EDGE_ARRAY;
or
SDO_TOPO_MAP.MOVE_NODE(
topology IN VARCHAR2,
node_id IN NUMBER,
edges_coords IN SDO_EDGE_ARRAY,
moved_iso_nodes OUT SDO_NUMBER_ARRAY,
moved_iso_edges OUT SDO_NUMBER_ARRAY,
allow_iso_moves IN VARCHAR2);
Description
Moves a non-isolated node and its attached edges.
Parameters
Name of the topology in which to move the node, or null if you are using an updatable TopoMap object (see Section 2.1.2). Must not exceed 20 characters.
Node ID of the node to be moved.
An array of arrays, of type SDO_EDGE_ARRAY (described in Section 1.6.5). Each inner array consists of coordinates of each resulting attached edge, from start point to end point. The outer array consists of the attached edge arrays, starting with the start edge of the node to be moved and proceeding in clockwise order (with the sequence of the edges as would be obtained in a call to the SDO_TOPO_MAP.GET_NODE_STAR function).
The array for each edge must include the start and end points. Any loops that connect twice at the moved node must be specified twice in the array.
Output parameter in which, if the allow_iso_moves parameter value is TRUE, Spatial stores the node ID values of any isolated nodes that have moved to a different face as a result of this procedure. If the allow_iso_moves parameter value is FALSE, Spatial stores the node ID values of any isolated nodes that did not move but that would have moved to a different face if the allow_iso_moves parameter value had been TRUE.
Output parameter in which, if the allow_iso_moves parameter value is TRUE, Spatial stores the edge ID values of any isolated edges that have moved to a different face as a result of this procedure. If the allow_iso_moves parameter value is FALSE, Spatial stores the edge ID values of any isolated edges that did not move but that would have moved to a different face if the allow_iso_moves parameter value had been TRUE.
TRUE causes Spatial to allow a node move operation that would cause any isolated nodes or edges to be in a different face, and to adjust the containing face information for such isolated nodes and edges; FALSE causes Spatial not to allow a node move operation that would cause any isolated nodes or edges to be in a different face.
If you use the format that does not include the allow_iso_moves parameter, Spatial allows a node move operation that would cause any isolated nodes or edges to be in a different face, and it adjusts the containing face information for such isolated nodes and edges.
Usage Notes
For information about moving nodes, see Section 2.2.2.
This procedure is equivalent to using the moveNode method of the TopoMap class of the client-side Java API (described in Section 1.8.1).
Examples
The following example moves node N3 and adjusts the coordinates of the only attached edge. (The example refers to definitions and data from Section 1.11.)
-- Move node N3 to right: from 25,35 to 26,35. -- E3 is changed from 25,30 -> 25,35 to 25,30 -> 26,35. CALL SDO_TOPO_MAP.MOVE_NODE(null, 3, SDO_EDGE_ARRAY(SDO_NUMBER_ARRAY(25,30, 26,35)));
Format
SDO_TOPO_MAP.REMOVE_EDGE(
topology IN VARCHAR2,
edge_id IN NUMBER);
Description
Removes an edge from a topology.
Parameters
Name of the topology from which to remove the edge, or null if you are using an updatable TopoMap object (see Section 2.1.2). Must not exceed 20 characters.
Edge ID of the edge to be removed.
Usage Notes
Spatial automatically updates the appropriate entries in the <topology-name>_EDGE$ and <topology-name>_FACE$ tables.
For information about removing an edge from a topology, see Section 2.3.3.
Examples
The following example removes the edge with edge ID value 99 from the current updatable TopoMap object.
CALL SDO_TOPO_MAP.REMOVE_EDGE(null, 99);
Format
SDO_TOPO_MAP.REMOVE_NODE(
topology IN VARCHAR2,
node_id IN NUMBER);
Description
Removes a node from a topology.
Parameters
Name of the topology from which to remove the node, or null if you are using an updatable TopoMap object (see Section 2.1.2). Must not exceed 20 characters.
Node ID of the node to be removed.
Usage Notes
Spatial automatically updates the appropriate entries in the <topology-name>_NODE$ and <topology-name>_EDGE$ tables, and in the <topology-name>_FACE$ table if necessary.
For information about removing a node from a topology, see Section 2.2.3.
Examples
The following example removes the node with node ID value 500 from the current updatable TopoMap object.
CALL SDO_TOPO_MAP.REMOVE_NODE(null, 500);
Format
SDO_TOPO_MAP.ROLLBACK_TOPO_MAP;
Description
Rolls back all changes to the database that were made using the current updatable TopoMap object, discards any changes in the object, clears the object's cache structure, and makes the object read-only.
Parameters
None.
Usage Notes
Use this procedure when you are finished with a batch of edits to a topology and you want to discard (that is, not commit) all changes to the database and in the cache. After the rollback operation completes, you cannot edit the TopoMap object. To make further edits to the topology, you can load the topology into the same TopoMap object for update (using the SDO_TOPO_MAP.LOAD_TOPO_MAP procedure), or you can create a new TopoMap object (using the SDO_TOPO_MAP.CREATE_TOPO_MAP procedure) and load the topology into that TopoMap object for update.
To commit all TopoMap object changes, use the SDO_TOPO_MAP.COMMIT_TOPO_MAP procedure.
For information about using an in-memory cache to edit topology objects, see Section 2.1.
This procedure is equivalent to using the rollbackDB method of the TopoMap class of the client-side Java API (described in Section 1.8.1).
Examples
The following example rolls back from the database all changes associated with the current updatable TopoMap object.
EXECUTE SDO_TOPO_MAP.ROLLBACK_TOPO_MAP;
Format
SDO_TOPO_MAP.UPDATE_TOPO_MAP;
Description
Updates the topology to reflect edits made to the current updatable TopoMap object.
Parameters
None.
Usage Notes
Use this procedure to update the topology periodically during an editing session, as explained in Section 2.1.4. The TopoMap object remains open for further editing operations. The updates are not actually committed to the database until you call the SDO_TOPO_MAP.COMMIT_TOPO_MAP procedure.
This procedure performs a level-0 validation of the TopoMap object before it updates the topology. (See the explanation of the level parameter for the SDO_TOPO_MAP.VALIDATE_TOPO_MAP function.)
If you caused in-memory R-tree indexes to be created when you loaded the TopoMap object (by specifying or accepting the default value of TRUE for the build_indexes parameter with the SDO_TOPO_MAP.LOAD_TOPO_MAP function), you can rebuild these indexes 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.
Contrast this procedure with the SDO_TOPO_MAP.CLEAR_TOPO_MAP procedure, which clears the cache associated with a specified TopoMap object and makes the object read-only.
To commit all TopoMap object changes, use the SDO_TOPO_MAP.COMMIT_TOPO_MAP procedure.
For information about using an in-memory cache to edit topology objects, see Section 2.1.
This procedure is equivalent to using the updateTopology method of the TopoMap class of the client-side Java API (described in Section 1.8.1).
Examples
The following example updates the topology associated with the current updatable TopoMap object to reflect changes made to that object.
EXECUTE SDO_TOPO_MAP.UPDATE_TOPO_MAP;
Format
SDO_TOPO_MAP.VALIDATE_TOPO_MAP(
topo_map IN VARCHAR2,
level IN NUMBER DEFAULT 1
) RETURN VARCHAR2;
Description
Performs a first-order validation of a TopoMap object, and optionally (by default) checks the computational geometry also; returns the string TRUE if the structure of the topology objects in TopoMap object is consistent, and raises an exception if the structure of the topology objects in TopoMap object is not consistent.
Parameters
Name of the TopoMap object. (TopoMap objects are explained in Section 2.1.1.)
A value of 0 checks for the following conditions as part of a first-order validation:
All faces are closed, and none have infinite loops.
All previous and next edge pointers are consistent.
All edges meet at nodes.
Each island node is associated with a face.
All edges on a face boundary are associated with the face.
A value of 1 (the default) checks for all conditions associated with a value of 0, plus the following conditions related to computational geometry:
Each island is inside the boundary of its associated face.
No edge intersects itself or another edge.
Start and end coordinates of edges match coordinates of nodes.
Node stars are properly ordered geometrically.
Usage Notes
This function checks the consistency of all pointer relationships among edges, nodes, and faces. You can use this function to validate an updatable TopoMap object before you update the topology (using the SDO_TOPO_MAP.UPDATE_TOPO_MAP procedure) or to validate a read-only TopoMap object before issuing queries.
This function is equivalent to using the validateCache method of the TopoMap class of the client-side Java API (described in Section 1.8.1).
Examples
The following example validates the topology in the TopoMap object named CITY_DATA_TOPOMAP, and it returns a result indicating that the topology is valid. (The example refers to definitions and data from Section 1.11.)
CALL SDO_TOPO_MAP.VALIDATE_TOPO_MAP('CITY_DATA_TOPOMAP') INTO :res_varchar;
Call completed.
PRINT res_varchar;
RES_VARCHAR
--------------------------------------------------------------------------------
TRUE
Format
SDO_TOPO_MAP.VALIDATE_TOPOLOGY(
topology IN VARCHAR2,
) RETURN VARCHAR2;
or
SDO_TOPO_MAP.VALIDATE_TOPOLOGY(
topology IN VARCHAR2,
prevent_updates IN VARCHAR2,
level IN NUMBER DEFAULT 1
) RETURN VARCHAR2;
or
SDO_TOPO_MAP.VALIDATE_TOPOLOGY(
topology IN VARCHAR2,
xmin IN NUMBER,
ymin IN NUMBER,
xmax IN NUMBER,
ymax IN NUMBER,
prevent_updates IN VARCHAR2,
level IN NUMBER DEFAULT 1
) RETURN VARCHAR2;
Description
Loads an entire topology or a window (rectangular portion) of a topology into a TopoMap object; returns the string TRUE if the structure of the topology is consistent, and raises an exception if the structure of the topology is not consistent.
Parameters
Name of the topology to be validated. Must not exceed 20 characters.
Lower-left X coordinate value for the window (rectangular portion of the topology) to be validated.
Lower-left Y coordinate value for the window (rectangular portion of the topology) to be validated.
Upper-right X coordinate value for the window (rectangular portion of the topology) to be validated.
Upper-right Y coordinate value for the window (rectangular portion of the topology) to be validated.
TRUE prevents other users from updating the topology while the validation is being performed; FALSE allows other users to update the topology while the validation is being performed. If you specify FALSE, any topology changes made by other users while the validation is being performed will not be considered by this function and will not affect the result.
A value of 0 checks for the following conditions:
All faces are closed, and none have infinite loops.
All previous and next edge pointers are consistent.
All edges meet at nodes.
Each island node is associated with a face.
All edges on a face boundary are associated with the face.
A value of 1 (the default) checks for all conditions associated with a value of 0, plus the following conditions related to computational geometry:
Each island is inside the boundary of its associated face.
No edge intersects itself or another edge.
Start and end coordinates of edges match coordinates of nodes.
Node stars are properly ordered geometrically.
Usage Notes
This function implicitly creates a TopoMap object, and removes the object after the validation is complete. (TopoMap objects are described in Section 2.1.1.)
Examples
The following example validates the topology named CITY_DATA, and it returns a result indicating that the topology is valid. (The example refers to definitions and data from Section 1.11.)
CALL SDO_TOPO_MAP.VALIDATE_TOPOLOGY('CITY_DATA') INTO :res_varchar;
Call completed.
PRINT res_varchar;
RES_VARCHAR
--------------------------------------------------------------------------------
TRUE
|
 Copyright © 2003 Oracle Corporation All Rights Reserved. |
|