[mapserver-commits] r10589 - trunk/docs/en/development/rfc

Sun Oct 10 22:49:55 EDT 2010

Author: warmerdam
Date: 2010-10-10 19:49:55 -0700 (Sun, 10 Oct 2010)
New Revision: 10589

Modified:
   trunk/docs/en/development/rfc/ms-rfc-62.txt
Log:
various updates, particularly gml_types auto

Modified: trunk/docs/en/development/rfc/ms-rfc-62.txt
===================================================================

--- trunk/docs/en/development/rfc/ms-rfc-62.txt	2010-10-08 20:51:49 UTC (rev 10588)
+++ trunk/docs/en/development/rfc/ms-rfc-62.txt	2010-10-11 02:49:55 UTC (rev 10589)
@@ -17,6 +17,7 @@
 OGR outputs.  Control of output formats is managed via appropriate
 OUTPUTFORMAT declarations.
 
+
 WFS GetFeature Changes
 ~~~~~~~~~~~~~~~~~~~~~~
 
@@ -37,6 +38,7 @@
 generated by a call to msReturnTemplateQuery() which already supports output
 via the new template engine (RFC 36) as well as call outs for other renderers.
 
+
 outputFormatObj
 ~~~~~~~~~~~~~~~
 
@@ -49,6 +51,7 @@
 As well a new renderer value, MS_RENDER_WITH_OGR, will be added for OGR 
 output. 
 
+
 OGR OUTPUTFORMAT Declarations
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -90,6 +93,9 @@
   generally not suitable for use with FORM=zip which is already compressing
   the image.  "none" is the default.
 
+GEOMTYPE=None/Unknown/Point/LineString/Polygon/GeometryCollection/MultiPoint/MultiLineString/MultiPolygon
+  This sets the OGR geometry type of the output layer created.  It defaults
+  to "Unknown".  
 
 FILENAME=name
   Provides a name for the datasource created, default is "result.dat".  
@@ -132,17 +138,76 @@
 create an output layer for each map layer with an active, non-empty 
 query resultcache.  Those resultcache shapes will be written. 
 
-- The gml_include_items rules will be used to decide what attributes should
-  be written to the output layers. 
-- the gml field name aliasing mechanism will be supported for OGR output.
-- Layers will be created with a geometry type based on the type of the layer 
-  with POINT as wkbPoint, LINE as wkbLineString, and POLYGON as wkbPolygon.  
-- Currently all output fields will be created with a type of OFTString since
-  we do not have a mechanism to know the real types of source fields. 
+- The gml_include_items and gml_exclude_items rules will be used to decide 
+  what attributes should be written to the output layers. 
+- The gml field name aliasing mechanism will be supported for OGR output.
+- The gml_[item]_type metadata will be supported for OGR output. 
+- The gml_[item]_width (new) metadata will be supported for OGR output.
+- The gml_[item]_precision (new) metadata will be supported for OGR output.
+- When gml_[item]_type metadata is not available then all fields will be
+  created with a type of OFTString.
 - Some features, such as zip output, will only be supported with GDAL/OGR 1.8.
   These features will be made conditional on the GDAL/OGR version.
 
 
+Geometry Types Supported
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+In MapServer we have POINT, LINE and POLYGON layers which also allow for
+features with multiple points, lines or polygons.  However, in the OGC
+Simple Feature geometry model used by OGR a point and multipoint layer are
+quite distinct.  Likewise for a LineString and MultiLineString and 
+Polygon an MultiPolygon layer type.  When features written to a layer could
+be of distinct types like this the only way we can create the layer is as
+geometry type "wkbUnknown" - that is with no distinct geometry type. 
+
+Some drivers, such as the OGR shapefile driver will establish a specific
+geometry type based on the first geometry encountered and discard with an
+error features of an unsupported geometry type.  Some drivers support mixtures
+of geometry types.  
+
+The GEOMTYPE FORMATOPTION make it possible to force creation of the 
+layer with a particular geometry type. 
+
+
+Attribute Field Definitions
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+For OGR output it is highly desirable to be able to create the output fields
+with the appropriate datatype, width and precision to reflect the source
+feature definition.  In the past for GML output the gml_[item]_type metadata
+provided a mechanism for users to manually set the field type in generated
+GML as there was no supported mechanism to automatically discovered. 
+
+As a further step, for the OGR output mechanism it is planned to offer
+support for two new data items, gml_[item]_width and gml_[item]_precision
+which default the width and precision (number of decimal places) for 
+fields.
+
+It is not immediately planned to utilize the field width and precision
+information in the GML output though that may prove useful.  The width and
+precision metadata will be parsed by msGMLGetItems() and added into the 
+gmlItemObj structure.  Values of "0" indicate a value is not known.
+
+
+gml_types auto
+~~~~~~~~~~~~~~
+
+Setting the field type information for all fields in a layer is tedious
+and error prone.  So as a further extension it is intended to support a
+mechanism to automatically discover field type, width and precision for
+some data sources.  This will be requested by setting the "gml_types" 
+metadata item to a value of "auto".  This will be taken as a clue to 
+implementing layer types to set the various metadata items on the layer
+to define the fields type, width and precision when the GetItems layer
+method is called. 
+
+As part of the development effort for this RFC support for automatic 
+field definition discovered will be implemented for "OGR", "POSTGIS", 
+"ORACLE" and "SHAPEFILE" layers.   The maintainers of other feature 
+sources can implement support if and when it is convenient.
+
+
 Use of CPL Services
 ~~~~~~~~~~~~~~~~~~~
 
@@ -182,6 +247,9 @@
 - A prototype implementation has been developed (by Frank Warmerdam) and is
   working though it is not quite feature complete, and will need some refinement
   before it can be committed.
+- It is convenient to use the metadata and other structure originally 
+  intended to drive GML production but it does cause some confusion when 
+  "gml" metadata items are used to drive non-GML output.  
 
 
 Outstanding Issues
@@ -190,14 +258,32 @@
 - How do we alter msReturnTemplate() to support the WFS limit on number
   of features, and offset to the first feature?
 - What are the implications if queries in other circumstances than WFS
-  GetFeature pick an OGR output format?
-- Do we need to support multipoint, multilinestring and multipolygon generation?
-- Are there other mechanisms than gml_include_items we need to consult to 
-  decide on fields to write?
-- Do we want to introduce a mechanism to apply stronger typing to fields in
-  the output files?
+  GetFeature picking an OGR output format?
 
 
+Testing
+~~~~~~~
+
+The msautotest/wxs suite will be extended with a few tests of OGR output.
+This will likely revolve around producing text output formats so it will
+be easy to compare to previous results as we do with gml output.   Some
+advanced features, such as zipped output may not be convenient to add 
+regression testing for.
+
+
+Documentation
+~~~~~~~~~~~~~
+
+Documentation updates willb be required in the following documents:
+
+- WFS Server: extensive discussion of new gml items, and how OGR and templated
+  output is invoked and controlled.
+- MapFile Reference: Add information on OGR OUTPUTFORMAT declarations.
+- Ideally we ought to document the new "gml_types auto" stuff in the document
+  on how to write feature layer implementations, but the only document on this
+  is RFC 3 which does not seem to define what the functions are supposed to 
+  do for the most part.
+
 Voting history
 ~~~~~~~~~~~~~~
 

