C.3 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
- Predefined WMS Map Theme Definition
- Authentication with WMS Map Themes
- Customizing GetCapabilities Responses: Additional Options
Parent topic: OGC WMS Support in the Map Visualization Component
C.3.1 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 isfalse
. -
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), or1.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 inlayers
. -
The
<srs>
element specifies the coordinate system (spatial reference system) name. The default value isEPSG:4326
. -
The
<format>
element specifies the format for the resulting map image. The default value isimage/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 isfalse
. To make the layer or layers transparent, specifytrue
. -
The
<bgcolor>
element specifies the RGB value for the map background color. Use hexadecimal notation for the value, for example,0xAE75B1
. The default value is0xFFFFFF
(that is, white). -
The
<exceptions>
element specifies the format for server exceptions. The default value isapplication/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 C-5 shows the <wms_getmap_request>
element in a map request.
Example C-5 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>
Parent topic: Adding a WMS Map Theme
C.3.2 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 C-6 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 C-6 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>');
Parent topic: Adding a WMS Map Theme
C.3.3 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 passwordIf you use the Map Builder tool to create a WMS map theme, the password value will be automatically encrypted. Figure C-1 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 C-1 Using Map Builder to Specify Authentication with a WMS Theme
Description of "Figure C-1 Using Map Builder to Specify Authentication with a WMS Theme"
Example C-7 shows how to create a WMS theme that includes authentication information.
Example C-7 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>
Parent topic: Adding a WMS Map Theme
C.3.4 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)
- Custom WMS Capabilities Service Attributes (<service_attributes> Element)
- Custom WMS Layer Attributes (<layer_attributes> Element)
- Custom WMS Feature Information (<get_feature_info> Element)
Parent topic: Adding a WMS Map Theme
C.3.4.1 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 sourceWMS
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 standardtext/xml
even for getCapabilities. If this attribute is set tofalse
, 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>
C.3.4.2 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>
C.3.4.3 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 C-8 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 C-9 shows part of a GetCapabilities response that includes these custom attributes.
Example C-8 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 C-9 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>
C.3.4.4 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 inwithin_radius
GetFeatureInfo requests when theradius
parameter is not defined. -
The
unit
attribute specifies default radius unit (default ism
for meters).
For example:
<get_feature_info> <theme name="theme_demo_states" datasource="mvdemo" radius="500" unit="km" /> </get_feature_info>