D OGC WMS Support in OracleAS MapViewer

D.1.1 Required Files

The following files are required for OracleAS MapViewer WMS support: WMSFilter.jar and classgen.jar.

• The servlet filter and its required classes are packaged in WMSFilter.jar. This should be located in the $MAPVIEWER_HOME/web/WEB-INF/lib directory.

• The servlet filter also requires classgen.jar, which is part of the XML Developer's Kit (XDK) for Java. A standalone OC4J installation usually does not have this file; however, an Oracle Database or full Oracle Application Server installation will already have this file.

  If your system does not already have the classgen.jar file, use a classgen.jar file from the same XDK for Java version as the one that ships with your standalone OC4J version. Place this file in the $MAPVIEWER_HOME/web/WEB-INF/lib directory or in a directory that is in the library path for OC4J.

  The classgen.jar and xmlparserv2.jar files must be from the same XDK release, because the classgen.jar file depends on the xmlparserv2.jar file. Also, the XDK release for both files must be OC4J 10.0.0.3 or later, and preferably 10.1.2 or later.

D.2.1 Supported GetMap Request Parameters

This section describes the supported GetMap request parameters and their interpretation by OracleAS MapViewer. (Parameters that are specific to OracleAS MapViewer and not mentioned in the WMS 1.1.1 specification are labeled OracleAS MapViewer-Only.) The supported parameters are in alphabetical order, with each in a separate subsection. Example D-2 shows a GetMap request.

http://localhost:8888/mapviewer/wms?REQUEST=GetMap&VERSION=1.1.1&FORMAT=image/gif&
SERVICE=WMS&BBOX=-121,37,-119,35&SRS=EPSG:4326&LAYERS=theme_demo_states,theme_
demo_counties,theme_demo_highways,theme_demo_cities&WIDTH=580&HEIGHT=500

The default data source for a GetMap request is WMS. That is, if you do not specify the DATASOURCE parameter in a GetMap request, it is assumed that a data source named WMS was previously created using the <add_data_source> element (described in Section 6.1.1) in an OracleAS MapViewer administrative request.

The following optional GetMap parameters are not supported in the current release of OracleAS MapViewer:

• TIME (time dimension)

• ELEVATION (elevation dimension)

• SLD and WFS URLs

The OracleAS MapViewer-only parameters must contain valid XML fragments. Because these are supplied in an HTTP GET request, they must be appropriately encoded using a URL encoding mechanism. For example, replace each space ( ) with %20 and each pound sign (#) with %23. The following example shows the use of such encoding:

http://localhost:8888/mapviewer/wms?request=GetMap&version=1.1.1&srs=none&bbox=-12
2,36,-121,37&width=600&height=400&format=image/png&layers=theme_us_
states&mvthemes=<themes><theme%20name="theme_us_counties"/><theme%20name="theme_
us_road1"/></themes>&legend_
request=<legend%20bgstyle="fill:%23ffffff;stroke:%23ff0000"%20profile="medium"%20p
osition="SOUTH_EAST"><column><entry%20style="v.rb1"%20tab="1"/></column></legend>&

REQUEST=GetMap&VERSION=1.1.1&BASEMAP=demo_
map&LAYERS=&WIDTH=500&HEIGHT=560&SRS=SDO:8307&BBOX=-122,36,-120,38.5&FORMAT=image/
png

<themes>
<theme name="THEME_DEMO_STATES"/>
<theme name="theme_demo_counties"/>
<theme name="THEME_demo_HIGHWAYS"/>
</themes>

D.2.2 Supported GetCapabilities Request and Response Features

A WMS GetCapabilities request to OracleAS MapViewer should specify only the following parameters:

• REQUEST=GetCapabilities

• VERSION=1.1.1

• SERVICE=WMS

For example:

http://localhost:8888/mapviewer/wms?REQUEST=GetCapabilities&VERSION=1.1.1&SERVICE=WMS

The response is an XML document conforming to the WMS Capabilities DTD available at

http://schemas.opengis.net/wms/1.1.1/WMS_MS_Capabilities.dtd

However, the current release of OracleAS MapViewer returns an XML document containing the <Service> and <Capability> elements with the following information:

• The <Service> element is mostly empty, with just the required value of OGC:WMS for the <Service.Name> element. Support for more informative service metadata is planned for a future release of OracleAS MapViewer.

• The <Capability> element has <Request>, <Exception>, and <Layer> elements.

• The <Request> element contains the GetCapabilities and GetMap elements that describe the supported formats and URL for an HTTP GET or POST operation.

• The <Exception> element defines the exception format. The Service Exception XML is the only supported format in this release. The <Exception> element returns an XML document compliant with the Service Exception DTD, but it does not report exceptions as specified in the implementation specification. The current release simply uses the CDATA section of a <ServiceException> element to return the OMSException returned by the OracleAS MapViewer server.

• The <Layer> element contains a nested set of <Layer> elements. The first (outermost) layer contains a name (WMS), a title (Oracle WebMapServer Layers by data source), and one <Layer> element for each defined data source. Each data source layer contains a <Layer> element for each defined base map and one entry for each valid theme (layer) not listed in any base map. Each base map layer contains a <Layer> element for each predefined theme in the base map.

  Themes that are defined in the USER_SDO_THEMES view, that have valid entries in the USER_SDO_GEOM_METADATA view for the base table and geometry column, and that are not used in any base map will be listed after the base maps for a data source. These themes will have no <ScaleHint> element. They will have their own <LatLonBoundingBox> and <BoundingBox> elements.

The Content-Type of the response is set to application/vnd.ogc.wms_xml, as required by the WMS implementation specification.

Because the list of layers is output by base map, a given layer or theme can appear multiple times in the GetCapabilities response. For example, the theme THEME_DEMO_STATES, which is part of the base maps named DEMO_MAP and DENSITY_MAP, appears twice in Example D-3, which is an excerpt (reformatted for readability) from a GetCapabilities response.

<Title>Oracle WebMapServer Layers by data source</Title>
<Layer>
 <Name>mvdemo</Name>
 <Title>Datasource mvdemo</Title>
   <Layer>
     <Name>DEMO_MAP</Name>
     <Title>Basemap DEMO_MAP</Title>
     <SRS>SDO:8307</SRS>
     <LatLonBoundingBox>-180,-90,180,90</LatLonBoundingBox>
. . .
   <Layer>
     <Name>DENSITY_MAP</Name>
     <Title>Basemap DENSITY_MAP</Title>
     <SRS>SDO:8307</SRS>
     <LatLonBoundingBox>-180,-90,180,90</LatLonBoundingBox>
       <Layer>
         <Name>THEME_DEMO_STATES</Name>
         <Title>THEME_DEMO_STATES</Title>
         <SRS>SDO:8307</SRS>
         <BoundingBox SRS="SDO:8307" minx="-180" miny="-90" maxx="180"
                      maxy="90" resx="0.5" resy="0.5"/>
         <ScaleHint min="50.0" max="4.0"/>
       </Layer>
. . .              
   </Layer>
   <Layer>
     <Name>IMAGE_MAP</Name>
     <Title>Basemap IMAGE_MAP</Title>
     <SRS>SDO:41052</SRS>
     <LatLonBoundingBox>-180,-90,180,90</ LatLonBoundingBox>
       <Layer>
         <Name>IMAGE_LEVEL_2</Name>
         <Title>IMAGE_LEVEL_2</Title>
         <SRS>SDO:41052</SRS>
         <BoundingBox SRS="SDO:41052" minx="200000" miny="500000" maxx="750000"
                    maxy="950000" resx="0.5" resy="0.5"/>
         <ScaleHint min="1000.0" max="0.0"/>
       </Layer>
. . .    
   </Layer>

In Example D-3, the innermost layer describes the IMAGE_LEVEL_2 theme. The <ScaleHint> element lists the min_scale and max_scale values, if any, for that theme in the base map definition. For example, the base map definition for IMAGE_MAP is as follows:

SQL> select definition from user_sdo_maps where name='IMAGE_MAP';
 
DEFINITION
------------------------------------------------------------------------
<?xml version="1.0" standalone="yes"?>
<map_definition>
  <theme name="IMAGE_LEVEL_2" min_scale="1000.0" max_scale="0.0"/>
  <theme name="IMAGE_LEVEL_8" min_scale="5000.0" max_scale="1000.0"/>
  <theme name="MA_ROAD3"/>
  <theme name="MA_ROAD2"/>
  <theme name="MA_ROAD1"/>
  <theme name="MA_ROAD0"/>
</map_definition>

In the innermost layer, the <SRS> and <BoundingBox> elements identify the SRID and the DIMINFO information for that theme's base table, as shown in the following Spatial metadata query:

SQL> select srid, diminfo from user_sdo_geom_metadata, user_sdo_themes 
  2  where name='IMAGE_LEVEL_2' and 
  3  base_table=table_name and
  4  geometry_column=column_name ;
 
      SRID
----------
DIMINFO(SDO_DIMNAME, SDO_LB, SDO_UB, SDO_TOLERANCE)
--------------------------------------------------------------------------------
     41052
SDO_DIM_ARRAY(SDO_DIM_ELEMENT('X', 200000, 500000, .5), SDO_DIM_ELEMENT('Y', 750
000, 950000, .5))

In Example D-3, the <Layer> element for a base map has an <SRS> element and a <LatLonBoundingBox> element. The <SRS> element is empty if all layers in the base map definition do not have the same SRID value specified in the USER_SDO_GEOM_METADATA view. If they all have the same SRID value (for example, 41052), the SRS element contains that value (for example, SDO:41052). The required <LatLonBoundingBox> element currently has default values (-180,-90,180,90). When this feature is supported by OracleAS MapViewer, this element will actually be the bounds specified in the DIMINFO column of the USER_SDO_GEOM_METADATA view for that layer, converted to geodetic coordinates if necessary and possible.

All layers are currently considered to be opaque and queryable. That is, all layers are assumed to be vector layers, and not GeoRaster, logical network, or image layers.

D.2.3 Supported GetFeatureInfo Request and Response Features

This section describes the supported GetFeatureInfo request parameters and their interpretation by OracleAS MapViewer. Example D-4 shows a GetFeatureInfo request.

http://localhost:8888/mapviewer/wms?REQUEST=GetFeatureInfo&VERSION=1.1.1&BBOX=0,-0
.0020,0.0040&SRS=EPSG:4326&LAYERS=cite:Lakes,cite:Forests&WIDTH=200&HEIGHT=100&INF
O_FORMAT=text/xml&QUERY_LAYERS=cite:Lakes,cite:Forests&X=60&Y=60

The response is an XML document and the Content-Type of the response is text/xml. Example D-5 is a response to the GetFeatureInfo request in Example D-4.

<?xml version="1.0" encoding="UTF-8" ?>
<GetFeatureInfo_Result>
  <ROWSET name="cite:Lakes">
    <ROW num="1">
      <ROWID>AAAK22AAGAAACUiAAA</ROWID>
    </ROW>
  </ROWSET>
  <ROWSET name="cite:Forests">
    <ROW num="1">
      <FEATUREID>109</FEATUREID>
    </ROW>
  </ROWSET>
</GetFeatureInfo_Result>

Most of the following sections describe parameters supported for a GetFeatureInfo request. (Parameters that are specific to OracleAS MapViewer and not mentioned in the WMS 1.1.1 specification are labeled OracleAS MapViewer-Only.) Section D.2.3.10 explains how to query attributes in a GetFeatureInfo request.

SELECT <info_columns> FROM <layer_table>
  WHERE SDO_RELATE(<geom_column>, 
    <query_point>, 'mask=ANYINTERACT')='TRUE'
  AND ROWNUM <= FEATURE_COUNT;

SQL> select styling_rules from user_sdo_themes where name='cite:Forests';
 
STYLING_RULES
--------------------------------------------------------------------------------
<?xml version="1.0" standalone="yes"?>
<styling_rules>
  <hidden_info>
          <field column="FID" name="FeatureId"/>
       </hidden_info>
  <rule>
    <features style="C.PARK FOREST">  </features>
    <label column="NAME" style="T.PARK NAME"> 1 </label>
  </rule>
</styling_rules>

D.3.1 XML API for Adding a WMS Map Theme

To add a WMS map theme to the current map request using the OracleAS MapViewer 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 an OracleAS MapViewer instance. If you want to specify an OracleAS MapViewer instance (for example, specifying <service_url> with a value of http://mapviewer.mycorp.com:8888/mapviewer/wms), consider using an OracleAS 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, or 1.1.1 (the default).

• 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 D-6 shows the <wms_getmap_request> element in a map request.

<?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>

D.3.2 JavaBean-Based API for Adding a WMS Map Theme

To add a WMS map theme to the current map request using the OracleAS MapViewer JavaBean-based API, use the addWMSMapTheme method.

This method should be used only to request a map image from a Web map server (WMS) implementation. That is, the serviceURL parameter should specify a WMS implementation, not an OracleAS MapViewer instance.

The addWMSMapTheme method has the following format:

addWMSMapTheme(String name, String serviceURL, String isBackgroundTheme,
               String version, String[] layers, String[] styles, 
               String srs, String format, String transparent,
               String bgcolor, String exceptions,
               Object[] vendor_specific_parameters
               );

The name parameter specifies the theme name.

The serviceURL parameter specifies the URL (without the service parameters) for the WMS service. Example: http://my.webmapserver.com/wms

The isBackgroundTheme parameter specifies whether or not this theme should be rendered before the vector layers. The default value is false.

The version parameter specifies the WMS version number. The value must be one of the following: 1.0.0, 1.1.0, or 1.1.1 (the default).

The layers parameter specifies a comma-delimited list of layer names to be included in the map request.

The styles parameter specifies a comma-delimited list of style names to applied to the layer names in layers.

The srs parameter specifies the coordinate system (spatial reference system) name. The default value is EPSG:4326.

The format parameter specifies the format for the resulting map image. The default value is image/png.

The transparent parameter 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 parameter 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 parameter specifies the format for server exceptions. The default value is application/vnd.ogc.se_inimage.

The vendor_specific_parameters parameter specifies a list of vendor-specific parameters. Each element in the object array is a String array with two strings: parameter name and value. Example: vsp = new Object[]{new String[]{"DATASOURCE", "mvdemo"}, //param 1 new String[]{"antialiasing", "true"} //param 2