Changes between Initial Version and Version 1 of FdoWMSSLDSupport


Ignore:
Timestamp:
Oct 18, 2007, 1:15:54 PM (17 years ago)
Author:
gregboone
Comment:

--

Legend:

Unmodified
Added
Removed
Modified

  • FdoWMSSLDSupport

    v1 v1  
     1
     2== FDO WMS Stylized Layer Descriptor Support ==
     3
     4=== Overview ===
     5
     6This document will explore the feasibility of enhancing the Feature Data Objects (FDO) SDK to add Stylized Layer Descriptors (SLD) support for Web Mapping Services (WMS). This document will explore means of implementing SLD support in the FDO WMS Provider, and alternately, the FDO API itself.
     7
     8=== SLD Support in the FDO WMS Provider ===
     9
     10The shortest WMS-SLD implementation path would involve implementing SLD support within the existing FDO WMS provider. The design solution would enable a user with the ability to specify an SLD URL, or an embedded SLD document, when creating a WMS !PhysicalSchemaMapping Override. The !PhysicalSchemaMapping Override would be written to an XML file and used as a WMS Configuration when connecting to a WMS service. The following sections outline the configuration API additions that would need to occur in order to add SLD support.
     11
     12==== !FdoWmsOvRemoteOwsType ====
     13
     14If a WMS is to symbolize features using a user-defined symbolization, it is necessary to identify the source of the feature data. The WMS-SLD specification is designed to permit a wide variety of implementations of WMS that support user-defined symbolization. For example a WMS might symbolize feature or coverage data stored in a remote Web Feature Server (WFS) or Web Coverage Server (WCS), or it might only be able to symbolize data from a specific default feature/coverage store.
     15
     16To support this option, a !RemoteOwsType enumeration will be added to the FDO WMS Overrides API and exposed as a property on the Raster Definition class. By setting the enumeration value, clients will be able to specify the source of the feature/coverage data. The presently allowed values are WFS and WMS though more may be allowed in the future.
     17
     18The !RemoteOwsType is to be used in conjunction with the Raster Definition’s !RemoteOwsUrl property which specifies the URL of the OWS service.
     19
     20The following is the FDO API C++ definition of the !RemoteOwsType.
     21
     22{{{
     23/// \brief
     24/// The FdoWmsOvRemoteOWSType enumeration identifies the
     25/// optional source of the feature data to be used for a
     26/// user-defined WMS layer symbolization. The WMS Styled
     27/// Layer Descriptor (SLD) is able to reference feature
     28/// data in a remote Web Coverage Server or a remote Web
     29/// Feature Server.
     30enum FdoWmsOvRemoteOwsType {
     31
     32    FdoWmsOvRemoteOwsType_Default = 0,  /// Default (Unknown)
     33    FdoWmsOvRemoteOwsType_WFS,          /// Remote Web Feature Server
     34    FdoWmsOvRemoteOwsType_WCS           /// Remote Web Coverage Server
     35};
     36}}}
     37
     38==== !FdoWmsOvRasterDefinition ====
     39
     40In order to add SLD support to the FDO WMS Overrides API, the ability to set the SLD and OWS URL will be added to the !FdoWmsOvRasterDefinition class. The newly added properties will be serialized and de-serialized to/from XML as a part of the !ReadXml/!WriteXml process. These properties are considered optional and if not set, will not be serialized.
     41
     42If the SLD/OWS properties are de-serialized from XML as a part of the FDO WMS Provider connection process, the values will be used to help construct the appropriate WMS GetMap Request for the referenced FDO feature class definition.
     43
     44The following is the C++ definition of the methods to be appended to the !FdoWmsOvRasterDefinition class.
     45
     46{{{
     47/// \brief
     48/// The FdoWmsOvRasterDefinition class defines the
     49/// physical overrides for a raster property in a WMS FDO schema.
     50class FdoWmsOvRasterDefinition : public FdoPhysicalElementMapping
     51{
     52public:
     53…
     54…
     55    /// \brief
     56    /// Gets the optional Styled Layer Descriptor (SLD) that
     57    /// will be used to stylize a set of WMS layers.
     58    ///
     59    /// \remarks
     60    /// The Styled Layer Descriptor definition already contains
     61    /// references to a set of WMS layers and styles. If an SLD is
     62    /// used, adding layers to the layer collection associated
     63    /// to the this Raster Definition becomes optional. If layers
     64    /// are not explicity set, then all layers identified in the SLD
     65    /// are rendered with all defined styles. If layers are set, then
     66    /// only the layers present in the layers collection are rendered
     67    /// and the SLD is used as a style library.
     68    ///
     69    /// The SLD is typically either a URL reference to an XML file
     70    /// in the form of http://myclient.com/mysld.xml, or an XML string
     71    /// containing the explicity SLD definition encoded in CGI or XML.
     72    ///
     73    /// \return
     74    /// Returns the WMS Styled Layer Descriptor.
     75    ///
     76    FDOWMS_API FdoString* GetSld(void) const;
     77
     78    /// \brief
     79    /// Sets the optional Styled Layer Descriptor (SLD) that
     80    /// will be used to stylize a set of WMS layers.
     81    ///
     82    /// \remarks
     83    /// The Styled Layer Descriptor definition already contains
     84    /// references to a set of WMS layers and styles. If an SLD is
     85    /// used, adding layers to the layer collection associated
     86    /// to the this Raster Definition becomes optional. If layers
     87    /// are not explicity set, then all layers identified in the SLD
     88    /// are rendered with all defined styles. If layers are set, then
     89    /// only the layers present in the layers collection are rendered
     90    /// and the SLD is used as a style library.
     91    ///
     92    /// The SLD is typically either a URL reference to an XML file
     93    /// in the form of http://myclient.com/mysld.xml, or an XML string
     94    /// containing the explicity SLD definition encoded in CGI or XML.
     95    ///
     96    /// \return
     97    /// Returns nothing.
     98    ///
     99    FDOWMS_API void SetSld(FdoString* value);
     100
     101    /// \brief
     102    /// Gets the specification version for the
     103    /// Styled Layer Descriptor (SLD).
     104    ///
     105    /// \remarks
     106    /// If the SLD version is not set, requests to the WMS
     107    /// server will default to using "1.1.0".
     108    ///
     109    /// \return
     110    /// Returns the WMS Styled Layer Descriptor.
     111    ///
     112    FDOWMS_API FdoString* GetSldVersion(void) const;
     113
     114    /// \brief
     115    /// Sets the specification version for the
     116    /// Styled Layer Descriptor (SLD).
     117    ///
     118    /// \remarks
     119    /// If the SLD version is not set, requests to the WMS
     120    /// server will default to using "1.1.0".
     121    ///
     122    /// \return
     123    /// Returns nothing.
     124    ///
     125    FDOWMS_API void SetSldVersion(FdoString* value);
     126
     127    /// \brief
     128    /// Gets the remote OWS type of the service that will be used
     129    /// as the default source for the feature/coverage data
     130    /// used to generate the WMS GetMap response.
     131    ///
     132    /// \remarks
     133    /// The presently allowed values for the OWS type are WFS and WCS,
     134    /// though more may be allowed in the future.
     135    ///
     136    /// \return
     137    /// Returns the remote OWS type.
     138    ///
     139    FDOWMS_API FdoWmsOvRemoteOwsType GetRemoteOwsType(void) const;
     140
     141    /// \brief
     142    /// Sets the remote OWS type of the service that will be used
     143    /// as the default source for the feature/coverage data
     144    /// used to generate the WMS GetMap response.
     145    ///
     146    /// \remarks
     147    /// The presently allowed values for the OWS type are WFS and WCS,
     148    /// though more may be allowed in the future.
     149    ///
     150    /// \return
     151    /// Returns nothing.
     152    ///
     153    FDOWMS_API void SetRemoteOwsType(FdoWmsOvRemoteOwsType value);
     154
     155    /// \brief
     156    /// Gets the URL of the remote OWS service that will be used
     157    /// as the default source for the feature/coverage data
     158    /// used to generate the WMS GetMap response.
     159    ///
     160    /// \return
     161    /// Returns the remote OWS URL.
     162    ///
     163    FDOWMS_API FdoString* GetRemoteOwsUrl(void) const;
     164
     165    /// \brief
     166    /// Sets the URL of the remote OWS service that will be used
     167    /// as the default source for the feature/coverage data
     168    /// used to generate the WMS GetMap response.
     169    ///
     170    /// \return
     171    /// Returns nothing.
     172    ///
     173    FDOWMS_API void SetRemoteOwsUrl(FdoString* value);
     174
     175…
     176…
     177};
     178}}}
     179
     180==== Update to !FdoWmsOverride.xsd ====
     181
     182The following are the XSD definitions of the types to be appended to the !FdoWmsOvRasterDefinition class.
     183
     184===== !RasterDefinitionType =====
     185
     186The !RasterDefinitionType will be enhanced to support the new SLD and OWS !GetMap parameters.
     187
     188{{{
     189<xs:complexType name="RasterDefinitionType" abstract="false">
     190    <xs:complexContent>
     191        <xs:extension base="fdo:SchemaMappingElement">
     192            <xs:sequence>
     193                <xs:element name="Format" type="RasterFormatType"/>
     194                <xs:element name="Transparent" type="xs::boolean"/>
     195                <xs:element name="BackgroundColor" type="xs::string"/>
     196                <xs:element name="Time" type="xs::string"/>
     197                <xs:element name="Elevation" type="xs::string"/>
     198                <xs:element name="SpatialContext" type="xs::string"/>
     199                <xs:element name="Layer"
     200                            type="LayerDefinitionType"
     201                            minOccurs="0"
     202                            maxOccurs="unbounded"/>
     203                <xs:element name="SLD" type="xs:string"/>
     204                <xs:element name="SLDVersion" type="xs::string"/>
     205                <xs:element name="RemoteOWSType" type="RemoteOwsType"/>
     206                <xs:element name="RemoteOWSUrl" type="xs::string"/>
     207            </xs:sequence>
     208        </xs:extension>
     209    </xs:complexContent>
     210</xs:complexType>
     211}}}
     212
     213
     214===== !RemoteOwsType =====
     215
     216The !RemoteOwsType will be added to support the OWS remote service types.
     217
     218{{{
     219<xs:simpleType name="RemoteOwsType">
     220    <xs:annotation>
     221        <xs:documentation>
     222            The RemoteOwsType enumeration identifies the
     223            optional source of the feature data to be used for a
     224            user-defined WMS layer symbolization. The WMS Styled
     225            Layer Descriptor (SLD) is able to reference feature
     226            data in a remote Web Coverage Server or a remote Web
     227            Feature Server.
     228        </xs:documentation>
     229    </xs:annotation>
     230    <xs:restriction base="xs:token">
     231        <xs:enumeration value="Default"/>
     232        <xs:enumeration value="WFS"/>
     233        <xs:enumeration value="WMS"/>
     234    </xs:restriction>
     235</xs:simpleType>
     236}}}
     237
     238==== WMS !SchemaMapping Configuration Example ====
     239
     240The following C++/XML excerpts demonstrate how a WMS schema mapping XML element would be generated as a result of using the parameters listed above.
     241
     242===== WMS !SchemaMapping C++ Sample =====
     243
     244{{{
     245FdoWmsOvPhysicalSchemaMapping* OverridesTest::CreateSchemaOverridesWithSLD()
     246{
     247    FdoWmsOvPhysicalSchemaMappingP config;
     248    try {
     249        config = FdoWmsOvPhysicalSchemaMapping::Create();
     250        config->SetName(L"WorldMap");
     251        FdoWmsOvClassesP classes = config->GetClasses();
     252
     253        FdoWmsOvClassDefinitionP classDefn = FdoWmsOvClassDefinition::Create();
     254        classDefn->SetName(L"Wind");
     255
     256        FdoWmsOvRasterDefinitionP rasterDefn = FdoWmsOvRasterDefinition::Create();
     257        rasterDefn->SetName(L"Raster");
     258
     259        rasterDefn->SetFormatType(FdoWmsOvFormatType_Png);
     260        rasterDefn->SetTransparent(true);
     261        rasterDefn->SetBackgroundColor(L"0xFFFFFF");
     262        rasterDefn->SetTimeDimension(L"TIME=current");
     263        rasterDefn->SetElevationDimension(L"ELEVATION=0");
     264        rasterDefn->SetSpatialContextName(L"EPSG:4326");
     265        rasterDefn->SetSld(L"http://myclientsite.com/mySLD.xml");
     266        rasterDefn->SetSldVersion(L"1.1.0");
     267        rasterDefn->SetRemoteOwsType(FdoWmsOvRemoteOwsType_WFS);
     268        rasterDefn->SetRemoteOwsUrl(L"http://anothersite.com/WFS");
     269
     270        classDefn->SetRasterDefinition(rasterDefn);
     271        classes->Add(classDefn);
     272    }
     273    catch (FdoException* e)
     274    {
     275        throw (e);
     276    }
     277
     278    return FDO_SAFE_ADDREF(config.p);
     279}
     280}}}
     281
     282===== WMS !SchemaMapping XML Sample =====
     283
     284{{{
     285<?xml version="1.0" encoding="UTF-8" ?>
     286<SchemaMapping provider="OSGeo.WMS.3.3" name="WorldMap" xmlns="http://fdo.osgeo.org/schemas">
     287    <complexType name="WindType">
     288        <RasterDefinition name="Raster">
     289            <Format>PNG</Format>
     290            <Transparent>true</Transparent>
     291            <BackgroundColor>0xFFFFFF</BackgroundColor>
     292            <Time>TIME=current</Time>
     293            <Elevation>ELEVATION=100</Elevation>
     294            <SpatialContext>EPSG:4326</SpatialContext>
     295            <SLD>http://myclientsite.com/mySLD.xml</SLD>
     296            <SLDVersion>1.1.0</SLDVersion>
     297            <RemoteOWSType>WFS</RemoteOWSType>
     298            <RemoteOWSUrl>http://anothersite.com/WFS</RemoteOWSUrl>
     299        </RasterDefinition>
     300    </complexType>
     301</SchemaMapping>
     302}}}
     303
     304==== Support POST Request Encoding ====
     305
     306HTTP supports two request methods: GET and POST. One or both of these methods may be defined for a particular OGC Web Service type and offered by a service instance, and the use of the Online Resource URL differs in each case. The basic WMS specification defines HTTP GET (mandatory) and HTTP POST (optional) for invoking operations.
     307The FDO WMS Provider currently supports only the GET specification. If SLD support is to be fully implemented within the provider then POST processing will also need to be supported. If only GET request methods are used to embed inline SLD documents in the service requests, there may be difficulties if the WMS provider generates excessively long URLs.
     308
     309NOTE: POST processing is technically superior to GET processing but there has been a general lack of vendor support in the past for XML-POST GetMap-request methods. POST processing will only be used if the WMS service supports POST processing.
     310
     311Here are two examples of SLD !GetMap Requests using GET and POST processing:
     312
     313===== GET Encoding Example =====
     314
     315{{{
     316http://yourfavoritesite.com/WMS?
     317    REQUEST=GetMap&
     318    BBOX=0.0,0.0,1.0,1.0&
     319    SLD_BODY=%3C%3Fxml+version%3D%221.0%22+encoding%3D%22UTF-8%22%3F%3E%3CStyledLayerDescriptor+version
     320             %3D%221.1.0%22%3E%3CNamedLayer%3E%3CName%3ERivers%3C%2FName%3E%3CNamedStyle%3E%3CName
     321             %3ECenterLine%3C%2FName%3E%3C%2FNamedStyle%3E%3C%2FNamedLayer%3E%3CNamedLayer%3E%3CName
     322             %3ERoads%3C%2FName%3E%3CNamedStyle%3E%3CName%3ECenterLine%3C%2FName%3E%3C%2FNamedStyle
     323             %3E%3C%2FNamedLayer%3E%3CNamedLayer%3E%3CName%3EHouses%3C%2FName%3E%3CNamedStyle%3E%3CName
     324             %3EOutline%3C%2FName%3E%3C%2FNamedStyle%3E%3C%2FNamedLayer%3E%3C%2FStyledLayerDescriptor
     325             %3E WIDTH=400&
     326    HEIGHT=400&
     327    FORMAT=PNG
     328}}}
     329 
     330===== POST Encoding Example =====
     331
     332{{{
     333<GetMap xmlns="http://www.opengis.net/sld" xmlns:gml="http://www.opengis.net/gml"
     334xmlns:ogc="http://www.opengis.net/ogc"
     335xmlns:ows="http://www.opengis.net/ows"
     336xmlns:se="http://www.opengis.net/se" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
     337xsi:schemaLocation="http://www.opengis.net/sld GetMap.xsd" version="1.3.0">
     338    <StyledLayerDescriptor version="1.1.0">
     339        <NamedLayer>
     340            <se:Name>Rivers</se:Name>
     341            <NamedStyle>
     342                <se:Name>CenterLine</se:Name>
     343            </NamedStyle>
     344        </NamedLayer>
     345        <NamedLayer>
     346            <se:Name>Roads</se:Name>
     347            <NamedStyle>
     348                <se:Name>CenterLine</se:Name>
     349            </NamedStyle>
     350        </NamedLayer>
     351        <NamedLayer>
     352            <se:Name>Houses</se:Name>
     353            <NamedStyle>
     354                <se:Name>Outline</se:Name>
     355            </NamedStyle>
     356        </NamedLayer>
     357    </StyledLayerDescriptor>
     358    <CRS>EPSG:4326</CRS>
     359    <BoundingBox crs="http://www.opengis.net/gml/srs/epsg.xml#4326">
     360        <ows:LowerCorner>-180.0 -90.0</ows:LowerCorner>
     361        <ows:UpperCorner>180.0 90.0</ows:UpperCorner>
     362    </BoundingBox>
     363    <Output>
     364        <Size>
     365            <Width>1024</Width>
     366            <Height>512</Height>
     367        </Size>
     368        <wms:Format>image/jpeg</wms:Format>
     369        <Transparent>false</Transparent>
     370    </Output>
     371    <Exceptions>XML</Exceptions>
     372</GetMap>
     373}}}