Adding a WMS Map Theme

You can add a WMS map theme to the current map request. The WMS map theme is the result of a GetMap request, and it becomes an image layer in the set of layers (themes) rendered by the map visualization component.

To add a WMS map theme, use the WMS-specific features of the XML API (see XML API for Adding a WMS Map Theme).

XML API for Adding a WMS Map Theme

To add a WMS map theme to the current map request using the map visualization component XML API, use the <wms_getmap_request> element in a <theme> element.

For better performance, the <wms_getmap_request> element should be used only to request a map image from a Web Map Server (WMS) implementation. That is, the <service_url> element in a <wms_getmap_request> element should specify a WMS implementation, not a map visualization component instance. If you want to specify a map visualization component instance (for example, specifying <service_url> with a value of http://mapviewer.mycorp.com:8888/mapviewer/wms), consider using a MapViewer predefined theme or a JDBC theme in the <themes> element instead of using a <wms_getmap_request> element.

The following example shows the general format of the <wms_getmap_request> element within a <theme> element, and it includes some sample element values and descriptive comments:

<themes>
  <theme>
     <wms_getmap_request isBackgroundTheme="true">
           <!-- The wms_getmap_request theme is rendered in the order it
                 appears in the theme list unless isBackgroundTheme is "true".
           -->
          <service_url> http://wms.mapsrus.com/mapserver </service_url>
          <version> 1.1.1 </version>
            <!-- version is optional. Default value is "1.1.1".
            -->
          <layers> Administrative+Boundaries,Topography,Hydrography </layers>
           <!- layers is a comma-delimited list of names.
              If layer names contain spaces, use '+' instead of a space -->
           <!- styles is optional. It is a comma-delimited list, and it must
              have the same number of  names as the layer list, if specified.
              If style names contain spaces, use '+' instead of a space -->
          <styles/>
          <srs> EPSG:4326 </srs>
          <format> image/png </format>
          <transparent> true </transparent>
          <bgcolor> 0xffffff </bgcolor>
          <exceptions> application/vnd.ogc.se_inimage </exceptions>
          <vendor_specific_parameters>
               <!-- one or more <vsp> elements each containing
                     a <name> <value> pair  -->
               <vsp>
                    <name> datasource </name>
                    <value> mvdemo </value>
                 </vsp>
          <vendor_specific_parameters>
     <wms_getmap_request>
  </theme>
</themes>

The following attribute and elements are available with the <wms_getmap_request> element:

The isBackgroundTheme attribute specifies whether or not this theme should be rendered before the vector layers. The default value is false.
The <service_url> element specifies the URL (without the service parameters) for the WMS service. Example: http://my.webmapserver.com/wms
The <version> element specifies the WMS version number. The value must be one of the following: 1.0.0, 1.1.0, 1.1.1 (the default), or 1.3.0.
The <layers> element specifies a comma-delimited list of layer names to be included in the map request.
The <styles> element specifies a comma-delimited list of style names to be applied to the layer names in layers.
The <srs> element specifies the coordinate system (spatial reference system) name. The default value is EPSG:4326.
The <format> element specifies the format for the resulting map image. The default value is image/png.
The <transparent> element specifies whether or not the layer or layers being added should be transparent in the resulting map image. The default value is false. To make the layer or layers transparent, specify true.
The <bgcolor> element specifies the RGB value for the map background color. Use hexadecimal notation for the value, for example, 0xAE75B1. The default value is 0xFFFFFF (that is, white).
The <exceptions> element specifies the format for server exceptions. The default value is application/vnd.ogc.se_inimage.
The <vendor_specific_parameters> element contains one or more <vsp> elements, each of which contains a <name> element specifying the parameter name and a <value> element specifying the parameter value.

Example: Adding a WMS Map Theme (XML API) shows the <wms_getmap_request> element in a map request.

Example: Adding a WMS Map Theme (XML API)

<?xml version="1.0" standalone="yes"?>
<map_request
  title="Raster WMS Theme and Vector Data"
  datasource="mvdemo" srid="0"
  width="500"
  height="375"
  bgcolor="#a6caf0"
  antialiase="true"
  mapfilename="wms_georaster" format="PNG_URL">
  <center size="185340.0">
    <geoFeature>
      <geometricProperty typeName="center">
        <Point>
          <coordinates>596082.0,8881079.0</coordinates>
        </Point>
      </geometricProperty>
    </geoFeature>
  </center>
  <themes>
    <theme name="WMS_TOPOGRAPHY" user_clickable="false"  >
       <wms_getmap_request isBackgroundTheme="true">
         <service_url> http://wms.mapservers.com:8888/mapserver/wms </service_url>
         <layers> TOPOGRAPHY </layers>
         <srs> EPSG:29190 </srs>
         <format> image/png </format>
         <bgcolor> 0xa6caf0 </bgcolor>
         <transparent> true </transparent>
         <vendor_specific_parameters>
           <vsp>
              <name> ServiceType </name>
              <value> mapserver </value>
           </vsp>
         </vendor_specific_parameters>
       </wms_getmap_request>
    </theme>
    <theme name="cl_theme" user_clickable="false">
       <jdbc_query  spatial_column="geom" render_style="ltblue"
         jdbc_srid="82279" datasource="mvdemo"
         asis="false">select geom from classes where vegetation_type = 'forests'
       </jdbc_query>
     </theme>
  </themes>
  <styles>
    <style name="ltblue">
      <svg width="1in" height="1in">
       <g class="color"
          style="stroke:#000000;stroke-opacity:250;fill:#33ffff;fill-opacity:100">
          <rect width="50" height="50"/>
       </g>
      </svg>
    </style>
  </styles>
</map_request>

Predefined WMS Map Theme Definition

The predefined XML definition for a WMS theme uses the same structure of the parameters in XML API for Adding a WMS Map Theme, and adds the optional capabilities_url attribute, which is used by Map Builder when editing a WMS theme. If the capabilities_url attribute is defined, Map Builder will issue a GetCapabilities request to populate some UI elements in the editor page. Example: Creating a Predefined WMS Theme shows how to create a predefined WMS theme in the metadata. The base table and base column names can be any values, and in this example 'WMS' is used for both.

Example: Creating a Predefined WMS Theme

INSERT INTO user_sdo_themes  VALUES (
  'PRED_WMS_THEME',
  'WMS data',
  'WMS',
  'WMS',   '<?xml version="1.0" standalone="yes"?>
   <styling_rules theme_type="wms">
     <service_url> http://sampleserver1b.arcgisonline.com/arcgis/services/Specialty/ESRI_StateCityHighway_USA/MapServer/WMSServer </service_url>
     <layers> 0,1,2 </layers>
     <version> 1.3.0 </version>
     <srs> CRS:84 </srs>
     <format> image/png </format>
     <bgcolor> 0xA6CAF0 </bgcolor>
     <transparent> false </transparent>
     <styles> +,+,+ </styles>
     <exceptions> xml </exceptions>
     <capabilities_url> http://sampleserver1.arcgisonline.com/ArcGIS/services/Specialty/ESRI_StateCityHighway_USA/MapServer/WMSServer? </capabilities_url>
   </styling_rules>');

Authentication with WMS Map Themes

For a WMS server that requires authentication for access to the WMS data, the following must be included in the theme definition:

<user> element specifying the user name
<password> element specifying the user password

If you use the Map Builder tool to create a WMS map theme, the password value will be automatically encrypted. Figure: Using Map Builder to Specify Authentication with a WMS Theme shows the use of the Map Builder tool to create a WMS theme with authentication information. In this figure, the Authentication option is checked (enabled), and User and Password are specified.

Figure: Using Map Builder to Specify Authentication with a WMS Theme

Description of the illustration wms_auth.gif

Example: WMS Theme with Authentication Specified shows how to create a WMS theme that includes authentication information.

Example: WMS Theme with Authentication Specified

<?xml version="1.0" standalone="yes"?>
<styling_rules theme_type="wms">
    <service_url> http://localhost:7001/mapviewer/wms </service_url>
    <user> wmsuser </user>
    <password> ******* </password>
    <layers> THEME_DEMO_STATES </layers>
    <version> 1.1.1 </version>
    <srs> EPSG:4326 </srs>
    <format> image/png </format>
    <bgcolor> 0xA6CAF0 </bgcolor>
    <transparent> true </transparent>
    <exceptions> application/vnd.ogc.se_xml </exceptions>
    <vendor_specific_parameters>
        <vsp>
            <name> datasource </name>
            <value> mvdemo </value>
    </vsp>
  </vendor_specific_parameters>
    <capabilities_url> http://localhost:7001/mapviewer/wms? </capabilities_url>
</styling_rules>

Customizing GetCapabilities Responses: Additional Options

The main map visualization component configuration file has a section to customize some information for GetCapabilities responses (see Customizing WMS GetCapabilities Responses). However only a limited number of properties that can be defined in that main map visualization component configuration file, and no customization can be done for several attributes that a layer can have in GetCapabilities response.

Effective with Release 12.1.3, a WMS configuration file (wmsConfig.xml) has been added to the map visualization component. Any settings defined in this WMS configuration file will override similar WMS settings defined in the main map visualization component configuration file.

The wmsConfig.xml can include the following.

Custom WMS Capabilities Parameters (`<custom_parameters>` Element)

The following attributes are available with the <custom_parameters> element:

The host attribute specifies the host part of the service request URL that the client should use for future WMS requests made to this map visualization component server.
The port attribute specifies the port part of the service request URL that the client should use for future WMS requests made to this map visualization component server.
The protocol attribute specifies the protocol part of the service request URL that the client should use for future WMS requests made to this map visualization component server.
The default_datasource attribute specifies the base data source to be used for retrieving the capabilities response. If this attribute is not defined, the data source WMS is used, and that data source must exist in this map visualization component server.
The public_datasources attribute specifies which data source contents are to be listed in the getCapabilities response. If this attribute is not defined, all data source contents that exist in server will be listed.
The use_text_xml attribute by default uses standard text/xml even for getCapabilities. If this attribute is set to false, then the OGC 1.1.1 specification is used (for example, application/vnd.ogc.wms_xml).

For example:

<custom_parameters
        host="www.my_corp.com" port="80" protocol="http"
        default_datasource="mvdemo"
        public_datasources="mvdemo, wms">
</custom_parameters>

Custom WMS Capabilities Service Attributes (`<service_attributes>` Element)

The <service attributes> element overrides any of these values defined in main map visualization component configuration file. For example:

<service_attributes>
 <title>
     WMS interface provided by OracleFMW MapViewer
 </title>
 <abstract>
     This WMS service is for demonstration.
 </abstract>
 <keyword_list>
    <keyword>Oracle</keyword>
    <keyword>MapViewer</keyword>
    <keyword>Spatial and Graph</keyword>
 </keyword_list>
 <online_resource>
     http://localhost:7001/mapviewer/wms
 </online_resource>
 <contact_information>
    <ContactPersonPrimary>
       <ContactPerson>John Doe</ContactPerson>
       <ContactOrganization>My Corp.</ContactOrganization>
    </ContactPersonPrimary>
    <ContactPosition>Sr. Manager</ContactPosition>
    <ContactAddress>
       <AddressType>US Street</AddressType>
       <Address>1 MyCorp drv</Address>
       <City>Nashua</City>
       <StateOrProvince>NH</StateOrProvince>
       <PostCode>03062</PostCode>
       <Country>USA</Country>
    </ContactAddress>
    <ContactVoiceTelephone>18001122333</ContactVoiceTelephone>
    <ContactFacsimileTelephone></ContactFacsimileTelephone>
    <ContactElectronicMailAddress>jdoe@my_corp.com</ContactElectronicMailAddress>
 </contact_information>
 <Fees>None</Fees>
 <AccessConstraints>None whatsoever</AccessConstraints>
</service_attributes>

Custom WMS Layer Attributes (`<layer_attributes>` Element)

The WMS OGC specification defines several attributes for Layers. The layer attribute list includes abstract, keyword list, SRS list, style, attribution, and others.

The <layer_attributes> element lets you define custom attributes for map visualization component metadata (base maps and themes). WMS Layers are associated with map visualization component themes and base maps. All Layer attributes are optional, and if defined they will complement the GetCapabilities response. Example: Custom WMS Layer Attributes shows a <layer_attributes> element with custom parameters for a base map and for a theme. In this example, for the base map DEMO_MAP the custom element <abstract> is defined, while for the theme THEME_DEMO_STATES the custom elements <abstract>, <keywordlist>, <srs>, and <style> are defined. In the <metadata> element, use the value theme for map visualization component themes and the value basemap for map visualization component base maps in the type attribute. If the type attribute is not defined or value is not equal to theme or basemap, then theme is used by default. Example: GetCapabilities Response with Custom Attributes shows part of a GetCapabilities response that includes these custom attributes.

Example: Custom WMS Layer Attributes

<layer_attributes>
  <datasource name="mvdemo">
    <metadata name="DEMO_MAP"  type="basemap">
           <abstract>Collection of US States</abstract>
    </metadata>
     <metadata name="THEME_DEMO_STATES"  type="theme"
            queryable="1" cascaded="0" opaque="1" noSubsets="0"
            fixedWidth="500" fixedHeight="400">

        <abstract>US States</abstract>

        <keywordlist>keyword1,keyword2,keyword3</keywordlist>

        <srs>EPSG:4203,EPSG:20248</srs>

        <style>
           <title>Style title</title>
           <name>Style name</name>
           <abstract>Style abstract</abstract>
           <stylesheeturl>
              <format>Stylesheet format</format>
              <onlineresource>
                 <href>http://www.yoururl.com/styledata.html</href>
                 <type>simple</type>
              </onlineresource>
           </stylesheeturl>
           <styleurl>
              <format>Styles format</format>
              <onlineresource>
                 <href>http://www.yoururl.com/style.html</href>
                 <type>simple</type>
              </onlineresource>
           </styleurl>
           <legendurl>
             <format>Legend format</format>
             <width>500</width>
             <height>500</height>
             <onlineresource>
                <href>http://www.yoururl.com/legendurl.html</href>
                <type>simple</type>
             </onlineresource>
           </legendurl>
         </style>
   ...

    </metadata>
  </datasource>
</layer_attributes>

Example: GetCapabilities Response with Custom Attributes

<Layer>
  <Name>DEMO_MAP</Name>
  <Title>Basemap DEMO_MAP</Title>
  <Abstract>Collection of US States</Abstract>
  <SRS>EPSG:4326</SRS>
  <LatLonBoundingBox maxy="90.0" maxx="180.0" miny="-90.0" minx="-180.0"/>
  <Layer fixedHeight="400" fixedWidth="500" noSubsets="0" opaque="1" cascaded="0" queryable="1">
    <Name>THEME_DEMO_STATES</Name>
    <Title>THEME_DEMO_STATES</Title>
    <Abstract>US States</Abstract>
    <KeywordList>
      <Keyword>keyword1</Keyword>
      <Keyword>keyword2</Keyword>
      <Keyword>keyword3</Keyword>
    </KeywordList>
    <SRS>EPSG:4326</SRS>
    <SRS>EPSG:4203</SRS>
    <SRS>EPSG:20248</SRS>
    <BoundingBox resy="5.0E-8" resx="5.0E-8" maxy="71.33268128071118" maxx="180.0" miny="-14.605189123107024" minx="-180.0" SRS="EPSG:4326"/>
    <BoundingBox resy="5.0E-8" resx="5.0E-8" maxy="2.06926736125942E7" maxx="5.5812377162013E7" miny="-1.54158038049741E9" minx="-5.74425799715062E8" SRS="EPSG:4203"/>
    <BoundingBox resy="5.0E-8" resx="5.0E-8" maxy="2.06929693795843E7" maxx="6.15958436393193E7" miny="-1.74609707025816E9" minx="-6.32398501646291E8" SRS="EPSG:20248"/>
    <Style>
      <Name>Style name</Name>
      <Title>Style title</Title>
      <Abstract>Style abstract</Abstract>
      <LegendURL height="500" width="500">
        <Format>Legend format</Format>
        <OnlineResource xlink:href="http://www.yoururl.com/legendurl.html" xlink:type="simple"/>
      </LegendURL>
      <StyleSheetURL>
        <Format>Stylesheet format</Format>
        <OnlineResource xlink:href="http://www.yoururl.com/styledata.html" xlink:type="simple"/>
      </StyleSheetURL>
      <StyleURL>
        <Format>Stylesheet format</Format>
        <OnlineResource xlink:href="http://www.yoururl.com/style.html" xlink:type="simple"/>
      </StyleURL>
    </Style>
    <ScaleHint max="1.5E8" min="0.0"/>
  </Layer>
...
</Layer>

Custom WMS Feature Information (`<get_feature_info>` Element)

The following attributes, available with the <get_feature_info> element, can be used define the default radius (value and unit) for predefined map visualization component themes:

The name attribute specifies the name of the predefined theme.
The datasource attribute specifies map visualization component data source.
The radius attribute specifies the default radius value for theme to be used in within_radius GetFeatureInfo requests when the radius parameter is not defined.
The unit attribute specifies default radius unit (default is m for meters).