== FDO WMS Stylized Layer Descriptor Support ==

=== Overview ===

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

=== SLD Support in the FDO WMS Provider ===

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

==== !FdoWmsOvRemoteOwsType ====

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

To 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 WCS though more may be allowed in the future. 

The !RemoteOwsType is to be used in conjunction with the Raster Definition’s !RemoteOwsUrl property which specifies the URL of the OWS service. 

The following is the FDO API C++ definition of the !RemoteOwsType.

{{{
/// \brief
/// The FdoWmsOvRemoteOWSType enumeration identifies the 
/// optional source of the feature data to be used for a 
/// user-defined WMS layer symbolization. The WMS Styled 
/// Layer Descriptor (SLD) is able to reference feature 
/// data in a remote Web Coverage Server or a remote Web 
/// Feature Server.
enum FdoWmsOvRemoteOwsType {

    FdoWmsOvRemoteOwsType_Default = 0,  /// Default (Unknown)
    FdoWmsOvRemoteOwsType_WFS,          /// Remote Web Feature Server
    FdoWmsOvRemoteOwsType_WCS           /// Remote Web Coverage Server
};
}}}

==== !FdoWmsOvRasterDefinition ====

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

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

The following is the C++ definition of the methods to be appended to the !FdoWmsOvRasterDefinition class.

{{{
/// \brief
/// The FdoWmsOvRasterDefinition class defines the 
/// physical overrides for a raster property in a WMS FDO schema.
class FdoWmsOvRasterDefinition : public FdoPhysicalElementMapping
{
public:
…
…
    /// \brief
    /// Gets the optional Styled Layer Descriptor (SLD) that 
    /// will be used to stylize a set of WMS layers. 
    /// 
    /// \remarks
    /// The Styled Layer Descriptor definition already contains 
    /// references to a set of WMS layers and styles. If an SLD is
    /// used, adding layers to the layer collection associated 
    /// to the this Raster Definition becomes optional. If layers
    /// are not explicity set, then all layers identified in the SLD
    /// are rendered with all defined styles. If layers are set, then
    /// only the layers present in the layers collection are rendered 
    /// and the SLD is used as a style library.
    ///
    /// The SLD is typically either a URL reference to an XML file 
    /// in the form of http://myclient.com/mysld.xml, or an XML string
    /// containing the explicity SLD definition encoded in CGI or XML.
    /// 
    /// \return
    /// Returns the WMS Styled Layer Descriptor.
    /// 
    FDOWMS_API FdoString* GetSld(void) const;

    /// \brief
    /// Sets the optional Styled Layer Descriptor (SLD) that 
    /// will be used to stylize a set of WMS layers. 
    /// 
    /// \remarks
    /// The Styled Layer Descriptor definition already contains 
    /// references to a set of WMS layers and styles. If an SLD is
    /// used, adding layers to the layer collection associated 
    /// to the this Raster Definition becomes optional. If layers
    /// are not explicity set, then all layers identified in the SLD
    /// are rendered with all defined styles. If layers are set, then
    /// only the layers present in the layers collection are rendered 
    /// and the SLD is used as a style library.
    ///
    /// The SLD is typically either a URL reference to an XML file 
    /// in the form of http://myclient.com/mysld.xml, or an XML string
    /// containing the explicity SLD definition encoded in CGI or XML.
    /// 
    /// \return
    /// Returns nothing.
    /// 
    FDOWMS_API void SetSld(FdoString* value);

    /// \brief
    /// Gets the specification version for the 
    /// Styled Layer Descriptor (SLD). 
    /// 
    /// \remarks
    /// If the SLD version is not set, requests to the WMS
    /// server will default to using "1.1.0".
    ///
    /// \return
    /// Returns the WMS Styled Layer Descriptor.
    /// 
    FDOWMS_API FdoString* GetSldVersion(void) const;

    /// \brief
    /// Sets the specification version for the 
    /// Styled Layer Descriptor (SLD). 
    /// 
    /// \remarks
    /// If the SLD version is not set, requests to the WMS
    /// server will default to using "1.1.0".
    ///
    /// \return
    /// Returns nothing.
    /// 
    FDOWMS_API void SetSldVersion(FdoString* value);

    /// \brief
    /// Gets the remote OWS type of the service that will be used 
    /// as the default source for the feature/coverage data 
    /// used to generate the WMS GetMap response.
    /// 
    /// \remarks
    /// The presently allowed values for the OWS type are WFS and WCS, 
    /// though more may be allowed in the future.
    ///
    /// \return
    /// Returns the remote OWS type.
    /// 
    FDOWMS_API FdoWmsOvRemoteOwsType GetRemoteOwsType(void) const;

    /// \brief
    /// Sets the remote OWS type of the service that will be used 
    /// as the default source for the feature/coverage data 
    /// used to generate the WMS GetMap response.
    /// 
    /// \remarks
    /// The presently allowed values for the OWS type are WFS and WCS, 
    /// though more may be allowed in the future.
    ///
    /// \return
    /// Returns nothing.
    /// 
    FDOWMS_API void SetRemoteOwsType(FdoWmsOvRemoteOwsType value);

    /// \brief
    /// Gets the URL of the remote OWS service that will be used 
    /// as the default source for the feature/coverage data 
    /// used to generate the WMS GetMap response.
    /// 
    /// \return
    /// Returns the remote OWS URL.
    /// 
    FDOWMS_API FdoString* GetRemoteOwsUrl(void) const;

    /// \brief
    /// Sets the URL of the remote OWS service that will be used 
    /// as the default source for the feature/coverage data 
    /// used to generate the WMS GetMap response.
    /// 
    /// \return
    /// Returns nothing.
    /// 
    FDOWMS_API void SetRemoteOwsUrl(FdoString* value);

…
…
};
}}}

==== Update to !FdoWmsOverride.xsd ==== 

The following are the XSD definitions of the types to be appended to the !FdoWmsOvRasterDefinition class.

===== !RasterDefinitionType =====

The !RasterDefinitionType will be enhanced to support the new SLD and OWS !GetMap parameters.

{{{
<xs:complexType name="RasterDefinitionType" abstract="false">
    <xs:complexContent>
        <xs:extension base="fdo:SchemaMappingElement">
            <xs:sequence>
                <xs:element name="Format" type="RasterFormatType"/>
                <xs:element name="Transparent" type="xs::boolean"/>
                <xs:element name="BackgroundColor" type="xs::string"/>
                <xs:element name="Time" type="xs::string"/>
                <xs:element name="Elevation" type="xs::string"/>
                <xs:element name="SpatialContext" type="xs::string"/>
                <xs:element name="Layer" 
                            type="LayerDefinitionType" 
                            minOccurs="0" 
                            maxOccurs="unbounded"/>
                <xs:element name="SLD" type="xs:string"/>
                <xs:element name="SLDVersion" type="xs::string"/>
                <xs:element name="RemoteOWSType" type="RemoteOwsType"/>
                <xs:element name="RemoteOWSUrl" type="xs::string"/>
            </xs:sequence>
        </xs:extension>
    </xs:complexContent>
</xs:complexType>
}}}


===== !RemoteOwsType =====

The !RemoteOwsType will be added to support the OWS remote service types.

{{{
<xs:simpleType name="RemoteOwsType">
    <xs:annotation>
        <xs:documentation>
            The RemoteOwsType enumeration identifies the 
            optional source of the feature data to be used for a 
            user-defined WMS layer symbolization. The WMS Styled 
            Layer Descriptor (SLD) is able to reference feature 
            data in a remote Web Coverage Server or a remote Web 
            Feature Server.
        </xs:documentation>
    </xs:annotation>
    <xs:restriction base="xs:token">
        <xs:enumeration value="Default"/>
        <xs:enumeration value="WFS"/>
        <xs:enumeration value="WCS"/>
    </xs:restriction>
</xs:simpleType>
}}}

==== WMS !SchemaMapping Configuration Example ====

The following C++/XML excerpts demonstrate how a WMS schema mapping XML element would be generated as a result of using the parameters listed above.

===== WMS !SchemaMapping C++ Sample =====

{{{
FdoWmsOvPhysicalSchemaMapping* OverridesTest::CreateSchemaOverridesWithSLD()
{
    FdoWmsOvPhysicalSchemaMappingP config;
    try {
        config = FdoWmsOvPhysicalSchemaMapping::Create();
        config->SetName(L"WorldMap");
        FdoWmsOvClassesP classes = config->GetClasses();

        FdoWmsOvClassDefinitionP classDefn = FdoWmsOvClassDefinition::Create();
        classDefn->SetName(L"Wind");

        FdoWmsOvRasterDefinitionP rasterDefn = FdoWmsOvRasterDefinition::Create();
        rasterDefn->SetName(L"Raster");

        rasterDefn->SetFormatType(FdoWmsOvFormatType_Png);
        rasterDefn->SetTransparent(true);
        rasterDefn->SetBackgroundColor(L"0xFFFFFF");
        rasterDefn->SetTimeDimension(L"TIME=current");
        rasterDefn->SetElevationDimension(L"ELEVATION=0");
        rasterDefn->SetSpatialContextName(L"EPSG:4326");
        rasterDefn->SetSld(L"http://myclientsite.com/mySLD.xml");
        rasterDefn->SetSldVersion(L"1.1.0");
        rasterDefn->SetRemoteOwsType(FdoWmsOvRemoteOwsType_WFS);
        rasterDefn->SetRemoteOwsUrl(L"http://anothersite.com/WFS");

        classDefn->SetRasterDefinition(rasterDefn);
        classes->Add(classDefn);
    }
    catch (FdoException* e) 
    {
        throw (e);
    }

    return FDO_SAFE_ADDREF(config.p);
}
}}}

===== WMS !SchemaMapping XML Sample =====

{{{
<?xml version="1.0" encoding="UTF-8" ?>
<SchemaMapping provider="OSGeo.WMS.3.3" name="WorldMap" xmlns="http://fdo.osgeo.org/schemas">
    <complexType name="WindType">
        <RasterDefinition name="Raster">
            <Format>PNG</Format>
            <Transparent>true</Transparent>
            <BackgroundColor>0xFFFFFF</BackgroundColor>
            <Time>TIME=current</Time>
            <Elevation>ELEVATION=100</Elevation>
            <SpatialContext>EPSG:4326</SpatialContext>
            <SLD>http://myclientsite.com/mySLD.xml</SLD>
            <SLDVersion>1.1.0</SLDVersion>
            <RemoteOWSType>WFS</RemoteOWSType>
            <RemoteOWSUrl>http://anothersite.com/WFS</RemoteOWSUrl>
        </RasterDefinition>
    </complexType>
</SchemaMapping>
}}}

==== Support POST Request Encoding ====

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

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

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

Here are two examples of SLD !GetMap Requests using GET and POST processing:

===== GET Encoding Example =====

{{{
http://yourfavoritesite.com/WMS? 
    REQUEST=GetMap& 
    BBOX=0.0,0.0,1.0,1.0& 
    SLD_BODY=%3C%3Fxml+version%3D%221.0%22+encoding%3D%22UTF-8%22%3F%3E%3CStyledLayerDescriptor+version
             %3D%221.1.0%22%3E%3CNamedLayer%3E%3CName%3ERivers%3C%2FName%3E%3CNamedStyle%3E%3CName
             %3ECenterLine%3C%2FName%3E%3C%2FNamedStyle%3E%3C%2FNamedLayer%3E%3CNamedLayer%3E%3CName
             %3ERoads%3C%2FName%3E%3CNamedStyle%3E%3CName%3ECenterLine%3C%2FName%3E%3C%2FNamedStyle
             %3E%3C%2FNamedLayer%3E%3CNamedLayer%3E%3CName%3EHouses%3C%2FName%3E%3CNamedStyle%3E%3CName
             %3EOutline%3C%2FName%3E%3C%2FNamedStyle%3E%3C%2FNamedLayer%3E%3C%2FStyledLayerDescriptor
             %3E WIDTH=400&
    HEIGHT=400& 
    FORMAT=PNG
}}}
 
===== POST Encoding Example =====

{{{
<GetMap xmlns="http://www.opengis.net/sld" xmlns:gml="http://www.opengis.net/gml"
xmlns:ogc="http://www.opengis.net/ogc" 
xmlns:ows="http://www.opengis.net/ows"
xmlns:se="http://www.opengis.net/se" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://www.opengis.net/sld GetMap.xsd" version="1.3.0">
    <StyledLayerDescriptor version="1.1.0">
        <NamedLayer>
            <se:Name>Rivers</se:Name>
            <NamedStyle>
                <se:Name>CenterLine</se:Name>
            </NamedStyle>
        </NamedLayer>
        <NamedLayer>
            <se:Name>Roads</se:Name>
            <NamedStyle>
                <se:Name>CenterLine</se:Name>
            </NamedStyle>
        </NamedLayer>
        <NamedLayer>
            <se:Name>Houses</se:Name>
            <NamedStyle>
                <se:Name>Outline</se:Name>
            </NamedStyle>
        </NamedLayer>
    </StyledLayerDescriptor>
    <CRS>EPSG:4326</CRS>
    <BoundingBox crs="http://www.opengis.net/gml/srs/epsg.xml#4326">
        <ows:LowerCorner>-180.0 -90.0</ows:LowerCorner>
        <ows:UpperCorner>180.0 90.0</ows:UpperCorner>
    </BoundingBox>
    <Output>
        <Size>
            <Width>1024</Width>
            <Height>512</Height>
        </Size>
        <wms:Format>image/jpeg</wms:Format>
        <Transparent>false</Transparent>
    </Output>
    <Exceptions>XML</Exceptions>
</GetMap>
}}}

=== Full OGC WMS Support in the FDO API ===

Another option to the one listed above would be to add full OGC support to the FDO API. This would make OGC commands such as !GetCapabilities an integral part of the FDO API as opposed to an implementation detail of the WMS provider. 

Details on how this may be accomplished in the FDO API are being considered and will be added to this document when they become further developed.