Add an optional force_new parameter to topology.ST_AddFace to force creation of a...

git-svn-id: http://svn.osgeo.org/postgis/trunk@7268 b70326c6-7e19-0410-871a-916f4a2858ee

diff --git a/doc/extras_topology.xml b/doc/extras_topology.xml
index 0a2ae2d6be28f89e6c0ff8ad8aafc61bb67b3b58..209cc0f07e826fa352058cc0e27f55fb9e8f113e 100644 (file)
--- a/doc/extras_topology.xml
+++ b/doc/extras_topology.xml
@@ -689,8 +689,9 @@ edgeid
                        <refnamediv>
                                <refname>AddFace</refname>
                        
-                               <refpurpose>Register a polygon as a topology face in the specified topology schema and returns the faceid of new face. 
-                                   If face already exists the id of the existing face is returned. Edges of the polygon must already exist otherwise an error is thrown.</refpurpose>
+                               <refpurpose>
+Registers a face primitive to a topology and get it's identifier.
+        </refpurpose>
                        </refnamediv>
                
                        <refsynopsisdiv>
@@ -699,6 +700,7 @@ edgeid
                                        <funcdef>integer <function>AddFace</function></funcdef>
                                        <paramdef><type>varchar </type> <parameter>toponame</parameter></paramdef>
                                        <paramdef><type>geometry </type> <parameter>apolygon</parameter></paramdef>
+                                       <paramdef choice="opt"><type>boolean </type> <parameter>force_new=false</parameter></paramdef>
                                        </funcprototype>
                                </funcsynopsis>
                        </refsynopsisdiv>
@@ -708,14 +710,33 @@ edgeid
             
                 <para>
 Registers a face primitive to a topology and get it's identifier.
+                </para>
+
+                <para>
 For a newly added face, the edges forming its boundaries and the ones 
 contained in the face will be updated to have correct values in the
 left_face and right_face fields.
 Isolated nodes contained in the face will also be updated to have a correct
 containing_face field value.
-               </para>
+                </para>
+
                 <para>The target topology is assumed to be valid (containing no self-intersecting edges). An exception is raised if: The polygon boundary is not fully defined by existing edges or the polygon overlaps an existing face.</para>
-                <note><para>If the <varname>apolygon</varname> geometry already exists as a face the face id of the existing face is returned.</para></note>
+
+                <para>
+If the <varname>apolygon</varname> geometry already exists as a face, then:
+if <varname>force_new</varname> is false (the default) the
+face id of the existing face is returned;
+if <varname>force_new</varname> is true a new id will be assigned to
+the newly registered face.
+                </para>
+
+               <note><para>
+When a new registration of an existing face is performed (force_new=true),
+no action will be taken to resolve dangling references to the existing
+face in the edge, node an relation tables, nor will the MBR field of the
+existing face record be updated. It is up to the caller to deal with that.
+                </para></note>
+
                 <note><para>The <varname>apolygon</varname> geometry must have the same <varname>srid</varname> as defined for the topology otherwise an invalid spatial reference sys error will be thrown.</para></note>
                 
                 <!-- use this format if new function -->

diff --git a/topology/sql/populate.sql b/topology/sql/populate.sql
index 1f1abc26d16384eaf1c91759e82e94cc9288218c..f861843f7a5db609c7d168d5875451d662fd6d98 100644 (file)
--- a/topology/sql/populate.sql
+++ b/topology/sql/populate.sql
@@ -300,13 +300,22 @@ LANGUAGE 'plpgsql' VOLATILE;
 
 --{
 --
--- AddFace(atopology, poly)
+-- AddFace(atopology, poly, [<force_new>=true])
 --
 -- Add a face primitive to a topology and get it's identifier.
--- Returns an existing face at the same location, if any.
+-- Returns an existing face at the same location, if any, unless
+-- true is passed as the force_new argument
 --
 -- For a newly added face, its edges will be appropriately
--- linked (marked as left-face or right-face).
+-- linked (marked as left-face or right-face), and any contained
+-- edges and nodes would also be marked as such.
+--
+-- When forcing re-registration of an existing face, no action will be
+-- taken to deal with the face being substituted. Which means
+-- a record about the old face and any record in the relation table
+-- referencing the existing face will remain untouched, effectively
+-- leaving the topology in a possibly invalid state.
+-- It is up to the caller to deal with that.
 --
 -- The target topology is assumed to be valid (containing no
 -- self-intersecting edges).
@@ -316,7 +325,7 @@ LANGUAGE 'plpgsql' VOLATILE;
 --  o The polygon overlaps an existing face.
 --
 -- 
-CREATE OR REPLACE FUNCTION topology.AddFace(atopology varchar, apoly geometry)
+CREATE OR REPLACE FUNCTION topology.AddFace(atopology varchar, apoly geometry, force_new boolean DEFAULT FALSE)
        RETURNS int
 AS
 $$
@@ -480,8 +489,12 @@ BEGIN
   END IF;
 
   IF faceid IS NOT NULL AND faceid != 0 THEN
-    RAISE DEBUG 'Face already known as %', faceid;
-    RETURN faceid;
+    IF NOT force_new THEN
+      RAISE DEBUG 'Face already known as %, not forcing a new face', faceid;
+      RETURN faceid;
+    ELSE
+      RAISE DEBUG 'Face already known as %, forcing a new face', faceid;
+    END IF;
   END IF;
 
   --

diff --git a/topology/test/regress/addface.sql b/topology/test/regress/addface.sql
index 1566209b97ccf5ca995892a7b6f77032d0940ce7..5369d946d4d9c6351668d3d21b9b3b605b313ad6 100644 (file)
--- a/topology/test/regress/addface.sql
+++ b/topology/test/regress/addface.sql
@@ -40,6 +40,13 @@ SELECT face_id, Box2d(mbr) from tt.face ORDER by face_id;
 -- Check linking
 SELECT edge_id, left_face, right_face from tt.edge ORDER by edge_id;
 
+-- Force re-registration of an existing face
+SELECT 'f1-force',  topology.addFace('tt', 'POLYGON((0 0, 0 10, 10 10, 10 0, 0 0))', true);
+
+-- re-check added faces and linking
+SELECT face_id, Box2d(mbr) from tt.face ORDER by face_id;
+SELECT edge_id, left_face, right_face from tt.edge ORDER by edge_id;
+
 SELECT topology.DropTopology('tt');
 
 -- Test topology with MixedCase

diff --git a/topology/test/regress/addface_expected b/topology/test/regress/addface_expected
index b6e370474af4bb0a1228093bfb96d6efdabf1136..bf506ef10adf429cabceb6809507663b134caba4 100644 (file)
--- a/topology/test/regress/addface_expected
+++ b/topology/test/regress/addface_expected
@@ -22,6 +22,19 @@ f2|2
 6|0|2
 7|0|2
 8|0|2
+f1-force|3
+0|
+1|BOX(0 0,10 10)
+2|BOX(10 0,20 10)
+3|BOX(0 0,10 10)
+1|3|0
+2|3|2
+3|0|3
+4|0|3
+5|0|0
+6|0|2
+7|0|2
+8|0|2
 Topology 'tt' dropped
 t
 MiX-e1|1