Administering the Map Visualization Component

This topic introduces the map visualization component Administration page and some administrative and configuration tasks that you can perform, such as adding new data sources, managing map tile layers used by Oracle Maps, and setting logging levels.

Logging in to the Map Visualization Component Administration Page

After you have verified that the map visualization component is running properly, it is suggested that you log in to the map visualization component Administration page. To do this, go first to the map visualization component Welcome page, which is typically http://<host>:<port>/mapviewer, where <host> and <port> should be replaced by the correct value for your installation.

Click the Admin link at the top right to display the map visualization component Administration page.

You can use this administration page to perform administrative tasks, such as clearing cached data, creating tile layers, managing tile layers, and restarting the server (use the Monitoring link to restart).

Configuring the Map Visualization Component

If the default configuration settings for running the map visualization component are not adequate, you can configure the map visualization component by editing the visualization component configuration file, mapViewerConfig.xml, which is located in the $MAPVIEWER_HOME/WEB-INF/conf directory. To modify this file, you can use a text editor, or you can use the map visualization component Administration page.

After you modify this file, you must restart the container to have the changes take effect; however, you can instead use the map visualization component Administration page to restart only the map visualization component servlet (instead of the entire Java EE instance, which may have other applications deployed and running) if you installed the map visualization component with a standalone Glassfish instance.

The map visualization component configuration file defines the following information in XML format:

All path names in the mapViewerConfig.xml file are relative to the directory in which the file is stored, unless otherwise specified.

Example: Sample Map Visualization Component Configuration File

Example: Sample Map Visualization Component Configuration File shows a sample mapViewerConfig.xml file.

<?xml version="1.0" ?>
<!-- This is the configuration file for the map visualization component. -->
<!-- Note: All paths are resolved relative to this directory (where
           this config file is located), unless specified as an absolute
           path name.
 -->

<MapperConfig>

  <!-- ****************************************************************** -->
  <!-- ************************ Logging Settings ************************ -->
  <!-- ****************************************************************** -->

  <!-- Uncomment the following to modify logging. Possible values are:
       log_level = "fatal"|"error"|"warn"|"info"|"debug"|"finest"
                 default: info) ;
       log_thread_name = "true" | "false" ;
       log_time = "true" | "false" ;
       one or more log_output elements.
  -->
  <!--
    <logging log_level="info" log_thread_name="false"
             log_time="true">
       <log_output name="System.err" />
       <log_output name="../log/mapviewer.log" />
    </logging>
  -->

  <!-- ****************************************************************** -->
  <!-- ********************** Map Image Settings ************************ -->
  <!-- ****************************************************************** -->

  <!-- Uncomment the following only if you want generated images to
       be stored in a different directory, or if you want to customize
       the life cycle of generated image files.

       By default, all maps are generated under
       $ORACLE_HOME/lbs/mapviewer/web/images.

       Images location-related attributes:
       file_prefix: image file prefix, default value is "omsmap"
       url:  the URL at which images can be accessed. It must match the 'path'
             attribute below. Its default value is "%HOST_URL%/mapviewer/images"
       path: the corresponding path in the server where the images are
             saved; default value is "%ORACLE_HOME%/lbs/mapviewer/web/images"

       Images life cycle-related attributes:
       life: the life period of generated images, specified in minutes.
             If not specified or if the value is 0, images saved on disk will
             never be deleted.
       recycle_interval:  this attribute specifies how often the recycling
             of generated map images will be performed. The unit is minute.
             The default interval (when not specified or if the value is 0)
             is 8*60, or 8 hours.

   -->
  <!--
   <save_images_at  file_prefix="omsmap"
                   url="http://mypc.mycorp.com:8888/mapviewer/images"
                   path="../web/images"
   />
  -->

  <!-- ****************************************************************** -->
  <!-- ********************* IP Monitoring Settings ********************* -->
  <!-- ****************************************************************** -->

  <!-- Uncomment the following to enable IP filtering for administrative
        requests.
    Note:
    - Use <ips> and <ip_range> to specify which IPs (and ranges) are allowed.
      Wildcard form such as 20.* is also accepted. Use a comma-delimited
      list in <ips>.

    - Use <ips_exclude> and <ip_range_exclude> for IPs and IP ranges
      prohibited from accessing eLocation.

    - If an IP falls into both "allowed" and "prohibited" categories, it is
      prohibited.

    - If you put  "*" in an <ips> element, then all IPs are allowed, except
      those specified in <ips_exclude> and <ip_range_exclude>.
      On the other hand, if you put "*" in an <ips_exclude> element, no one
      will be able to access the map visualization component (regardless of whether an IP is in
      <ips> or <ip_range>).

    - You can have multiple <ips>, <ip_range>, <ips_exclude>, and
      <ip_range_exclude> elements under <ip_monitor>.

    - If no <ip_monitor> element is present in the XML configuration
      file, then no IP filtering will be performed (all allowed).

    - The way the map visualization component determines if an IP is allowed is:

          if(IP filtering is not enabled) then allow;
          if(IP is in exclude-list) then not allow;
          else if(IP is in allow-list) then allow;
          else not allow;
   -->

  <!--
     <ip_monitor>
          <ips> 138.1.17.9, 138.1.17.21, 138.3.*, 20.* </ips>
          <ip_range> 24.17.1.3 - 24.17.1.20 </ip_range>
          <ips_exclude> 138.3.29.* </ips_exclude>
          <ip_range_exclude>20.22.34.1 - 20.22.34.255</ip_range_exclude>
     </ip_monitor>
   -->

  <!-- ****************************************************************** -->
  <!-- ********************** Web Proxy Setting  ************************ -->
  <!-- ****************************************************************** -->
  <!-- Uncomment and modify the following to specify the web proxy setting.
       This is only needed for passing background image URLs to
       the map visualization component in map requests or for setting a logo image URL, if
       such URLs cannot be accessed without the proxy.
   -->

  <!--
    <web_proxy host="www-proxy.my_corp.com"  port="80" />
  -->

  <!-- ****************************************************************** -->
  <!-- *********************** Security Configuration ******************* -->
  <!-- ****************************************************************** -->
  <!-- Here you can set various security related configurations of the map visualization component.
  -->

  <security_config>
    <disable_direct_info_request> false </disable_direct_info_request>
  </security_config>

  <!-- ****************************************************************** -->
  <!-- *********************** Global Map Configuration ***************** -->
  <!-- ****************************************************************** -->
  <!-- Uncomment and modify the following to specify systemwide parameters
       for generated maps. You can specify your copyright note, map title, and
       an image to be used as a custom logo shown on maps. The logo image must
       be accessible to this map visualization component and in either GIF or JPEG format.
       Notes:
         - To disable a global note or title, specify an empty string ("") for
            the text attribute of <note> and <title> element.
         - position specifies a relative position on the map where the
                  logo, note, or title  will be displayed. Possible values are
                  NORTH, EAST, SOUTH, WEST, NORTH_EAST, SOUTH_EAST,
                  SOUTH_WEST, NORTH_WEST, and CENTER.
         - image_path specifies a file path or a URL (starts with "http://")
                    for the image.

       <rendering> element attributes:
       - Local geodetic data adjustment: If allow_local_adjustment="true",
         The map visualization component automatically performs local data
         "flattening" with geodetic data if the data window is less than
         3 decimal degrees. Specifically, the map visualization component performs a simple
         mathematical transformation of the coordinates using a tangential
         plane at the current map request center.
         If allow_local_adjustment="false" (default), no adjustment is
         performed.
       - Automatically applies a globular map projection (geodetic data only):
         If use_globular_projection="true", The map visualization component will
         apply a globular projection on the fly to geometries being displayed.
         If use_globular_projection="false" (the default), The map visualization component does no map
         projection to geodetic geometries. This option has no effect on
         non-geodetic data.
   -->

  <!--
    <global_map_config>
        <note text="Copyright 2009, Oracle Corporation"
              font="sans serif"
              position="SOUTH_EAST"/>
        <title  text="MapViewer Demo"
                font="Serif"
                position="NORTH" />
        <logo image_path="C:\images\a.gif"
              position="SOUTH_WEST" />

        <rendering allow_local_adjustment="false"
                   use_globular_projection="false" />
    </global_map_config>
  -->

  <!-- ****************************************************************** -->
  <!-- ****************** Spatial Data Cache Setting  ******************* -->
  <!-- ****************************************************************** -->
  <!-- Uncomment and modify the following to customize the spatial data cache
       used by the map visualization component. The default is 64 MB for in-memory cache.

       To disable the cache, set max_cache_size to 0.

       max_cache_size:  Maximum size of in-memory spatial cache of the map visualization component.
                        Size must be specified in megabytes (MB).
       report_stats:    If you would like to see periodic output of cache
                        statistics, set this attribute to true. The default
                        is false.
   -->

  <!--
    <spatial_data_cache   max_cache_size="64"
                          report_stats="false"
    />
  -->

  <!-- ****************************************************************** -->
  <!-- ****************** Custom WMS Capabilities Info ****************** -->
  <!-- ****************************************************************** -->
  <!-- Uncomment and modify the following tag if you want the map visualization component to
       use the following information in its getCapabilities response.
       Note: all attributes and elements of <wms_config> are optional.
  -->
  <!--
  <wms_config host="www.my_corp.com" port="80">
    <title>
        WMS 1.1 interface for Oracle Map visualization component
    </title>
    <abstract>
        This WMS service is provided through the map visualization component.
    </abstract>
    <keyword_list>
       <keyword>bird</keyword>
       <keyword>roadrunner</keyword>
       <keyword>ambush</keyword>
    </keyword_list>
    <sdo_epsg_mapfile>
      ../config/epsg_srids.properties
    </sdo_epsg_mapfile>
  </wms_config>
  -->

  <!-- ****************************************************************** -->
  <!-- **************** Custom Non-Spatial Data Provider **************** -->
  <!-- ****************************************************************** -->
  <!-- Uncomment and add as many custom non-spatial data provider as
       needed here, each in its own <ns_data_provider> element.
       You must provide the id and full class name here. Optionally you
       can also specify any number of global parameters, which the map visualization component
       will pass to the data provider implementation during initialization.
       The name and value of each parameter is interpreted only by the
       implementation.
  -->

  <!-- this is the default data provider that comes with the map visualization component;
       refer to the documentation on how to use it.

  <ns_data_provider
    id="defaultNSDP"
    class="oracle.sdovis.NSDataProviderDefault"
  />
  -->

  <!-- this is a sample NS data provider with prameters:
  <ns_data_provider
    id="myProvider1" class="com.mycorp.bi.NSDataProviderImpl" >

    <parameters>
      <parameter name="myparam1" value="value1" />
      <parameter name="p2"       value="v2"     />
    </parameters>

  </ns_data_provider>
  -->

  <!-- ****************************************************************** -->
  <!-- *******************  Map Tile Server Setting  ******************* -->
  <!-- ****************************************************************** -->
  <!-- Uncomment and modify the following to customize the map tile server.

       <tile_storage> specifies the default root directory under which the
       cached tile images are to be stored if the cache instance configuration
       does not specify the root directory for the cache instance. If the
       default root directory is not set or not valid, the default root
       direcotry will be set to be $MAPVIEWER_HOME/web/tilecache

          default_root_path:  The default root directory under which the cached
                              tile images are stored.
  -->

  <!--
     <map_tile_server>
       <tile_storage default_root_path="/scratch/tilecachetest/"/>
    </map_tile_server>
  -->

  <!-- ****************************************************************** -->
  <!-- ******************** Predefined Data Sources  ******************** -->
  <!-- ****************************************************************** -->
  <!-- Uncomment and modify the following to predefine one or more data
       sources.
       Note: You must precede the jdbc_password value with a '!'
             (exclamation point), so that when the map visualization component starts the next
             time, it will encrypt and replace the clear text password.
  -->

  <!--
  <map_data_source name="mvdemo"
                   jdbc_host="elocation.example.com"
                   jdbc_sid="orcl"
                   jdbc_port="1521"
                   jdbc_user="<user>"
                   jdbc_password="<password_for_user>"
                   jdbc_mode="thin"
                   number_of_mappers="3"
   />
   -->

</MapperConfig>

This map visualization component configuration topic includes the following subtopics.

Specifying Logging Information

The map visualization component provides a flexible logging mechanism to record runtime information and events. You can configure the granularity, volume, format, and destination of the log output. You can also configure the maximum size of log files as well as automatic log file rotation.

There are two ways to configure the map visualization component’s logging: container-controlled logging, and using the <logging> element in the configuration file.

Container-Controlled Logging

If the <logging> element in the mapViewerConfig.xml file is commented out or missing, the map visualization component uses container-controlled logging, specifically using the following loggers:

Using the <logging> Element

If the <logging> element in the mapViewerConfig.xml file is in use (that is, if the <logging> element is not commented out or missing), The map visualization component uses that information instead of using container-controlled logging. The <logging> element can have the following attributes and subelements:

Specifying Map File Storage and Life Cycle Information

Map image file information is specified in the <save_images_at> element. By default, images are stored in the $ORACLE_HOME /lbs/mapviewer/web/images directory. You do not need to modify the <save_images_at> element unless you want to specify a different directory for storing images.

A mapping client can request that the map visualization component send back the URL for an image file instead of the actual map image data, by setting the format attribute of the <map_request> element to GIF_URL or PNG_URL. In this case, the map visualization component saves the requested map image as a file on the host system where the map visualization component is running and sends a response containing the URL of the image file back to the map client.

You can specify the following map image file information as attributes of the <save_images_at> element:

Specifying a Web Proxy

Sometimes the map visualization component server needs to make HTTP connections to external web servers, such as to obtain a background image through a URL or to contact an external WMS server to fetch its map images. In such cases, if there is a firewall between the map visualization component server and the target web server, you may need to specify the HTTP proxy information to the map visualization component so that it will not be blocked by the firewall. The following example specifies web proxy information:

<web_proxy host="www-proxy.mycorp.com" port="80" />

If the web proxy requires authentication, you can specify the user and password attributes. If the password value is preceded by the exclamation mark (!) character, the password value will be encrypted on the first loading of the configuration file. For example:

<web_proxy host="www-proxy.mycorp.com" port="80" user="<user>" password="<password_for_user>" />

Specifying Global Map Configuration Options

You can specify the following global “look and feel” options for the display of each map generated by the map visualization component:

To specify any of these options, use the <global_map_config> element. For example:

<global_map_config>
    <note text="Copyright (c) 2009, Example Corporation"
              font="sans serif"
              position="SOUTH_EAST"/>
    <title  text="Map Courtesy of Example Corp."
              font="Serif"
              position="NORTH"/>
    <logo image_path="C:\images\a.gif"
              position="SOUTH_WEST"/>

    <rendering allow_local_adjustment="false"
               use_globular_projection="false"/>
</global_map_config>

Set the map title through the <title> element of the <global_map_config> element. You can also set the map title in an individual map request by specifying the title attribute with the <map_request> element, and in this case, the title in the map request is used instead of the global title in the map visualization component configuration file. Note the following information about the attributes of the <title> element:

Set the map note through the <note> element of the <global_map_config> element. Note the following information about the attributes of the <note> element:

Set the map logo through the <logo> element of the <global_map_config> element. The map logo image must be in either JPEG or GIF format. The image can be stored in a local file system where the map visualization component instance will have access to it, or it can be obtained from the web by specifying its URL. To specify a map logo, uncomment the <map_logo> element in the map visualization component configuration file and edit its attributes as needed.

Note the following information about the attributes of the <logo> element:

If the logo image is obtained through a URL that is outside your firewall, you may need to set the web proxy in order for the map visualization component to retrieve the logo image. For information about specifying a web proxy, see Specifying a Web Proxy.

If you also specify a map legend, be sure that its position is not the same as any position for a map title, note, or logo. (Map legends are explained in Map Legend. The default position for a map legend is SOUTH_WEST.)

To have the map visualization component automatically project geodetic data to a local non-geodetic coordinate system before displaying it if the map data window is less than 3 decimal degrees, specify allow_local_adjustment="true" in the <rendering> element.

To have the map visualization component automatically apply a globular map projection (that is, a map projection suitable for viewing the world, and specifically the azimuthal equidistant projection for the map visualization component), specify use_globular_projection="true" in the <rendering> element. This option applies to geodetic data only.

Customizing the Spatial Data Cache

You can customize the in-memory cache that the map visualization component uses for spatial data by using the <spatial_data_cache> element. For example:

<spatial_data_cache   max_cache_size="64"
                      report_stats="true"
/>

You can specify the following information as attributes of the <spatial_data_cache> element:

The spatial data cache is always enabled by default, even if the element is commented out in the configuration file. To completely disable the caching of spatial data, you must specify the max_cache_size attribute value as 0 (zero).

Note: The disk-based spatial cache, which was supported in the previous release, is no longer supported, because performance tests have shown that disk-based spatial caching was often less efficient than fetching spatial objects directly from the database when needed (that is, in cases where the cached objects frequently did not need to be retrieved again after caching).

For detailed information about the caching of predefined themes, see Caching of Predefined Themes.

Specifying the Security Configuration

You can use the <security_config> element to specify whether the map visualization component should reject <info_request> elements in requests. An <info_request> element is a type of request from a client that asks the map visualization component to execute a simple SQL statement and return the result rows in plain text or XML format. This request is often used by the map visualization component applications to identify features displayed on a map, or to run simple spatial search queries.

However, if the map visualization component data source information is exposed, malicious attackers might be able to abuse this capability and obtain sensitive information. To prevent this from happening, you can make sure the map visualization component always connects to a database schema that has very limited access rights and hosts only non-sensitive information, and you can also reject all <info_request> requests by specifying the <security_config> element as follows:

<security_config>
  <disable_direct_info_request> true </disable_direct_info_request>
</security_config>

Note, however, that this setting affects some map visualization component features. For example, the identify() method of the map visualization component Java API will no longer work, and applications will need to implement their own identify() method through other means.

You can also define remote URLs that the map visualization component built-in proxy servlet is allowed to communicate with. Use commas to separate such URLs. You can end a URL with the * (asterisk) wildcard character to allow multiple URLs that start with a path. The following example specifies one remote URL:

<security-config>
    ...
    <proxy_enabled_hosts>
      foo.com:8080/mapviewer
    </proxy_enabled_hosts>
    ...
</security-config>

To facilitate the map visualization component’s HTTPS (SSL) connection with external web sites that use self-signed certificates, you may register those certificates here. Use one entry for each server that requires an HTTPS connection. The following example shows an excerpt specifying one entry:

<security_config>
    ...
    <certificates>
        <entry>
           <host_name>fooserver.com</host_name>
           <keystore_file>/scratch/fooserver.jks</keystore_file>
           <key>123456</key>
        </entry>
    </certificates>
    ...
</security_config>

The subelements for each certificate’s <entry> element are the following.

The host_name attribute specifies the IP address or domain name of the server that requires an HTTPS connection.

The keystore_file attribute specifies the file containing a single self-signed certificate. After you obtain the certificate (typically a .pem file) from the server site, you can create a key store by using the Java keytool command. For example:

keytool -import -file fooserver.pem -alias fooserver -keystore fooserver.jks

The key attribute specifies the password that you provided when creating the key store file. (It is used to ensure the integrity of the key store file itself.)

Registering a Custom Spatial Provider

The map visualization component can render spatial data that is in an external (non-Oracle Spatial) native format, such as shapefile, if there is a spatial provider implementation registered for the format. For information about implementing an external spatial data provider (in connection with custom geometry themes), see Custom Geometry Themes.

To register an external spatial data provider, use the <s_data_provider> element, as shown in the following example:

<s_data_provider
  id="shapefileSDP"
  class="oracle.sdovis.ShapefileDataProvider"
  >
  <parameters>
    <parameter name="datadir" value="/temp/data" />
  </parameters>
</s_data_provider>

The class attribute specifies the name of the class that implements the external spatial data provider.

The <parameters> element specifies a set of initialization parameters that are used by the data provider during its initialization process. In this example, the shapefile provider has a data directory ("datadir") parameter that points to directory where the map visualization component can look for the data.

Registering Custom Nonspatial Data Providers

When generating thematic map layers, the map visualization component can dynamically join nonspatial attribute data (such as sales for each region) that originates from an external source with the base geometries (boundaries of all the regions) that are stored in the database. For information about thematic mapping using external attribute data from nonspatial data providers, see Thematic Mapping Using External Attribute Data.

To register a nonspatial data provider, use the <ns_data_provider> element, as shown in the following example:

<ns_data_provider id="testProvider"
                  class="com.mycorp.GetSalesData" >
  <parameters>
    <parameter name="bi_database" value="stadb
32.mycorp.com" />
    <parameter name="sid" value="bidata"  />
  </parameters>
</ns_data_provider>

The id attribute uniquely identifies a nonspatial data provider. Use this id value in any map request that involves the provider.

The class attribute specifies the name of the class that implements the nonspatial data provider.

The <parameters> element specifies a set of initialization parameters that are used by the nonspatial data provider during its initialization process.

Customizing SRS Mapping

You can use the <srs_mapping> element to specify an SDO to EPSG SRID mapping file, which define mappings between Oracle Spatial SDO_SRID values and EPSG codes. As explained in SDO to EPSG SRID Mapping File, each line in the specified mapping file must contain an SDO_SRID value and the corresponding EPSG code. The <srs_mapping> element can be used with WMS and WFS themes.

The following example uses the <srs_mapping> element to specify an SDO to EPSG SRID mapping file:

<srs_mapping>
  <sdo_epsg_mapfile>
    ../config/epsg_srids.properties
  </sdo_epsg_mapfile>
</srs_mapping>

Customizing WMS GetCapabilities Responses

The map visualization component can be used as an Open Geospatial Consortium WMS (Web Map Server) 1.1.1 compliant server. As such, a WMS client can send the map visualization component the GetCapabilities request. In response, the map visualization component will send back the list of themes that it hosts and other important information, such as the data provider’s name and a list of keywords that might of interest to the requesting client.

Note:

There is a separate WMS configuration file (wmsConfig.xml) that contains more information than is in the <wms_config> element in the map visualization component configuration file. It is recommended that you define any custom WMS configuration parameters in this separate WMS configuration file; any settings there will override any conflicting settings in the <wms_config> element in the map visualization component configuration file.

For more information about the wmsXonfig.xml file, see Customizing GetCapabilities Responses: Additional Options.

You can use the <wms_config> element to customize the descriptive information sent back to the client as part of the GetCapabilities response, as shown in the following example:

<wms_config host="www.my_corp.com" port="80"
            protocol="http" default_datasource="dsrc1"
            public_datasources="dsrc1,dsrc2">
  <title>
    WMS 1.1 interface for Oracle Application Server 10g MapViewer
  </title>
  <abstract>
    This WMS service is provided through Oracle MapViewer.
  </abstract>
  <keyword_list>
    <keyword>bird</keyword>
    <keyword>roadrunner</keyword>
    <keyword>ambush</keyword>
  </keyword_list>
  <sdo_epsg_mapfile>
    ../config/epsg_srids.properties
  </sdo_epsg_mapfile>
</wms_config>

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 used to retrieve 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 will be listed.

The <title> element specifies the service title to be included as part of the response.

The <abstract> element specifies the abstract to be included as part of the response.

The <keyword_list> element specifies a list of keywords that best describe the types of layers served by this map visualization component server.

The <sdo_epsg_mapfile> element specifies a text file that defines mappings from Oracle Spatial (SDO) SRID values to the corresponding EPSG SRID values that are typically used in most WMS requests and responses. For information about this mapping file, see SDO to EPSG SRID Mapping File.

Customizing WMTS GetCapabilities Responses

The map visualization component can be used as an Open Geospatial Consortium WMTS (Web Map Tile Service) 1.0.0 compliant server, enabling tile layers defined in the USER_SDO_CACHED_MAPS metadata view to be retrieved through WMTS requests. A WMTS client can send to the map visualization component the GetCapabilities request. In response, the map visualization component will send back the list of tile layers that it hosts and other important information, such as the data provider’s name and a list of keywords that might of interest to the requesting client. You can edit the WMTS configuration file, which is stored in the same folder as that for mapViewerConfig.xml with a name of wmtsConfig.xml, to provide such customized information.

In the wmtsConfig.xml file, you can use the <wmts_config> element to customize the descriptive information sent back to the client as part of the GetCapabilities response, as shown in the following example:

<wmts_config>
     <public_datasources>
        <public_datasource name="MVDEMO" include_all_tile_layers="true"/>
        <public_datasource name="ELOCATION">
          <tile_layers>
            <tile_layer name="WORLD_MAP"/>
          </tile_layers>
        </public_datasource>
    </public_datasources>
    <sdo_epsg_mapfile>
      ../config/epsg_srid.properties
    </sdo_epsg_mapfile>
   <ServiceAttributes>
    <ServiceIdentification>
        <Title>Web Map Tile Service by myCorp</Title>
        <Abstract> U.S. maps for state and county boundaries and big cities</Abstract>
        <Keywords>
           <Keyword>Maps,U.S. State Boundaries,Cities</Keyword>
        </Keywords>
    </ServiceIdentification>
    <ServiceProvider>
      <ProviderName>provider's name</ProviderName>
        <ProviderSite url="http://www.myCorp.com/mySite"/>
    </ServiceProvider>
  </ServiceAttributes>
</wmts_config>

The <public_datasources> element can contain <public_datasource> subelements, which specify which data sources’ tile layers to list in the WMTS GetCapabilities response. If this <public_datasources> element is not defined, all data sources’ tile layers will be listed; if this element is defined but contains no <public_datasource> subelement, then no tile layers from any data source will be listed in the response.

The <public_datasource> element must contain a name attribute, which indicates the name of the data source.

The include_all_tile_layers attribute is optional, and the default is false. When set to true, it indicates that all tile layers in that data source are to be listed in the response.

The <tile_layer> element must contain a name attribute, which indicates the name of the tile layer to be included in the response from the data source defined in its parent element.

The <sdo_epsg_mapfile> element specifies a text file that defines mappings from Oracle Spatial (SDO) SRID values to the corresponding EPSG SRID values that are typically used in most WMTS requests and responses. For information about this mapping file, see SDO to EPSG SRID Mapping File.

The <Title> element specifies the service title to be included as part of the response.

The <Abstract> element specifies the abstract to be included as part of the response.

The <Keywords> element specifies a collection of keywords (from its <Keyword> subelements) that best describe the types of layers served by this map visualization component server.

More information can be found in the comments in the wmtsConfig.xml file.

Configuring the Map Tile Server for Oracle Maps

The Oracle Maps feature of the map visualization component can pre-generate base map image tiles and cache them through the map tile server. You can use the <map_tile_server> element to provide configuration information to the map tile server, such as default location for map tile file storage, and logging information, as shown in the following example:

<map_tile_server>
   <tile_storage default_root_path="/scratch/tilecache/" />
   <logging log_level="finest" log_thread_name="false" log_time="true">
      <log_output name="System.err"/>
   </logging>
</map_tile_server>

The <tile_storage> element specifies the default root directory where all map image tiles generated by this map visualization component server will be stored.

The <logging> element specifies logging information specific to the map tile server.

Defining Permanent Map Data Sources

Every map request must have a data source attribute that specifies a map data source, which is a database user with geospatial data. You can predefine available map data sources by using the <map_data_source> element. For instance, the following example defines a map data source by specifying the JDBC connection details:

<map_data_source name="mvdemo"
                 jdbc_host="mapsrus.example.com"
                 jdbc_sid="orcl"
                 jdbc_port="1521"
                 jdbc_user="<user>"
                 jdbc_password="<password_for_user>"
                 jdbc_mode="thin"
                 number_of_mappers="5"
                 allow_jdbc_theme_based_foi="true"
                 plsql_package="web_user_info"
/>

You can specify the following information as attributes of the <map_data_source> element:

Data Sources

A data source corresponds to a database schema or user.

Before you can draw any spatial data in a database schema, you must first define (create) a data source for the schema:

Each map request must specify a data source. You can, however, specify a different data source for individual themes added to the map request. This makes it easy to aggregate data stored across different database schemas. If a theme has no specified data source, it is associated with the data source of the map request. A base map (and thus the themes included in it) is always associated with the data source. When a theme is processed, all of its underlying data, as well as the styles referenced in its definition, must be accessible from the data source or sources associated with the theme.

Each data source has associated renderers (sometimes called mappers or map makers), the number of which is determined by the number_of_mappers attribute in the <map_data_source> element. This attribute (described in Defining Permanent Map Data Sources) affects the number of database connections created for each data source when map requests are processed. The number of renderers specified in a data source also is the maximum number of concurrent requests that can be processed for that data source. Each additional renderer requires only a small amount of memory, so the main potential disadvantage of specifying a large number of renderers (such as 100) is that the underlying CPU resource might be strained if too many map requests are allowed to come through, thus affecting the performance of the entire map visualization component server.

Each data source has its own internal metadata cache. The metadata cache holds the definitions of all accessed styles, as well as of all predefined themes that originate from the data source. This eliminates the need to query the database repeatedly for the definition of a style or predefined theme whenever it is needed.

Catalog Data Sources

A catalog data source gets all of its data from local files. The local directory where the data files are stored is relative to where the mapViewerConfig.xml file is stored. From another perspective, a catalog data source does not need the Oracle AI Database, because all necessary data (the spatial geometry data and its attributes, as well as the metadata for how to rend the spatial data, such as styles and themes) is stored in local files.

The following are the general steps for creating and using a catalog data source:

  1. Export the Necessary Metadata from an Oracle AI Database

  2. Export the Necessary Spatial Tables

  3. Edit the Map Visualization Component Configuration File to Add the Catalog Data Source

  4. Restart the Map Visualization Component Server

Export the Necessary Metadata from an Oracle AI Database

Before creating a catalog data source, you must use the Map Builder utility to export the metadata to USER_SDO_CACHED_MAPS.xml, USER_SDO_THEMES.xml, and USER_SDO_STYLES.xml files. The following considerations apply:

  1. In the Map Builder utility, select Tools, then Export Metadata to XML.

  2. Select a temporary directory to store the metadata.

  3. Accept the default prefix (USER_SDO_) for the table names.

  4. Select the tile layers, themes, and styles to export. (If you are not sure which styles are needed for the desired themes, you may export all styles.)

  5. Click OK to perform the export operation.

    The USER_SDO_CACHED_MAPS.xml, USER_SDO_THEMES.xml, and USER_SDO_STYLES.xml files are created in the specified directory.

Export the Necessary Spatial Tables

For a catalog data source, the spatial data sets are stored in GeoJSON files. One GeoJSON file corresponds to one spatial table is the database. To export spatial tables, you send requests to the map visualization component server.

For example, if a spatial table called OBIEE_COUNTRY is needed by a catalog data source theme (assume that the theme is also called OBIEE_COUNTRY) in the USER_SDO_THEMES.xml file, then this spatial table needs to be exported as a GeoJSON file. As a convention, you may name it with the same name as the name of the spatial table. In this case, it is named as OBIEE_CONTRY.json.

  1. Check the themes definition from the USER_SDO_THEMES.xml file. For example, if a theme named OBIEE_COUNTRY uses the OBIEE_COUNTRY spatial table, then the spatial table needs to be exported. The table’s columns and expected names must be identified, and the column names are the same as the name attributes in the theme definition. In the following example, the ISO_COUNTRY_CODE column is mapped as Country Code:

     <theme>
    <name>OBIEE_COUNTRY</name>
    <description><![CDATA[OBIEE Country]]></description>
    <base_table>OBIEE_COUNTRY</base_table>
    <geometry_column>GEOMETRY</geometry_column>
    <styling_rules><![CDATA[<?xml version="1.0" standalone="yes"?><styling_rules>
  <hidden_info>
    <field column="ISO_COUNTRY_CODE" name="Country Code"/>
    <field column="NAME" name="Country Name"/>
    <field column="NAME_INIT" name="Country Name (Init)"/>
  </hidden_info>
  <rule>
    <features style="C.AIRPORTS"> </features>
    <label column="NAME_LABEL" style="T.COUNTRY_NAME_10"> 1 </label>
  </rule>
</styling_rules>]]></styling_rules>
   </theme>
    . . .

  2. Identify the spatial table columns. In the following example, base table OBIEE_COUNTRY has the spatial geometry column named GEOMETRY:

    SQL> describe obiee_country
 Name                          Null?    Type

 ----------------------------- -------- ----------------------------
 NAME                                   VARCHAR2(255 CHAR)
 NAME_INIT                              VARCHAR2(1020 CHAR)
 OBIEE_LOWER                            VARCHAR2(1020 CHAR)
 ISO_COUNTRY_CODE                       VARCHAR2(5)
 SQKM                                   NUMBER(11)
 NAME_LABEL                             VARCHAR2(255 CHAR)

GEOMETRY                               MDSYS.SDO_GEOMETRY

  3. Create request strings to the map visualization component data server. For example, if OBIEE_COUNTRY is the base table, and if the map visualization component is running at localhost:8080, and if the data source name is my_ds_name with spatial data retrieval enabled, you can send a request string like the following:

    http://localhost:8080/ mapviewer/dataserver/my_ds_name?t=obiee_country&sql=select iso_country_code as id, iso_country_code as "country Code", name as "Country Name", name_init as "Country Name (Init)", name_label, geometry from obiee_country&id_col=id&simplify=true&threshold=90&include_label_box=true

    You can save the data set with a name OBIEE_COUNTRY.json in this case to the temporary folder where the exported metadata (the USER_SDO_CACHED_MAPS.xml, USER_SDO_THEMES.xml, and USER_SDO_STYLES.xml files) is stored.

Edit the Map Visualization Component Configuration File to Add the Catalog Data Source

Edit the mapViewerConfig.xml file and add the catalog data source. For example:

<map_data_source name="catalogds1"
   catalog_dir="../catalogs/datafolder1"
   private="true"
   number_of_mappers="3"
   allow_jdbc_theme_based_foi="true"
   editable="false"/>

For the preceding catalog data source definition, you must create the specified catalog_dir folder relative to where the mapViewerConfig.xml file is stored, and then copy all data files into the folder: that is, the three exported metadata files (USER_SDO_CACHED_MAPS.xml, USER_SDO_THEMES.xml, and USER_SDO_STYLES.xml) and all exported GeoJSON files, such as OBIEE_COUNTRY.json in this example.

Restart the Map Visualization Component Server

Restart the map visualization component server.

After the map visualization component server is restarted, all the exported tile layers and themes should be accessible from this catalog data source. For example, you should see a map image if you send a map request like the following:

http://localhost:8080/mapviewer/omserver?xml_request= <?xml version="1.0" standalone="yes"?> <map_request  datasource = "catalogds1" width="1024" height="768" format="PNG_STREAM"> <center size="200"> <geoFeature><geometricProperty typeName="center"> <Point> <coordinates>0, 0</coordinates> </Point> </geometricProperty></geoFeature> </center> <themes> <theme name="OBIEE_COUNTRY"> </theme> </themes> </map_request>

Configuring and Securing the Map Data Server for the HTML5 API

Themes can be streamed by default, and the only way to protect them is by adding authentication, that is, by adding a security constraint in the map visualization component web.xml file and by configuring the <mds_config> element in the configuration file to authorize access to various themes.

The Map Data Server (MDS) server component facilitates the streaming of geospatial data in vector format to the Oracle Maps API (described in Oracle Maps JavaScript API). The MDS provides a RESTful API for browser clients to request the vector data of any predefined or dynamic (JDBC) theme from a map visualization component server instance. The only way to secure or protect the access to this service is by adding a security constraint in the map visualization component web.xml deployment file, as in the following example:

<security-constraint>
<web-resource-collection>
. . .
<url-pattern>/dataserver/*</url-pattern>
</web-resource-collection>
<auth-constraint>
<role-name>map_admin_role</role-name>
</auth-constraint>
</security-constraint>

The preceding example adds a security constraint to any incoming URL with the relative path /dataserver/ in it. Because the MDS servlet responds only to URLs with /dataserver in its path, this constraint effectively protects all access to the MDS. This means that any application or web client accessing the Map Data Server will require proper authentication, and only those users with the role map_admin_role will be granted access. (For more information on how to secure a Java EE servlet such as MDS, check the Java EE and WebLogic Server documentation.)

Access to any predefined or dynamic (JDBC) theme’s vector data is blocked by default, regardless of whether you added a security constraint on the MDS URL patterns. In other words, for example, even if the /dataserver/* URLs are protected and an HTML5 application has passed authentication, it still cannot access a theme’s data without proper authorization. When an Oracle Maps HTML5 application attempts to load or display a theme without proper authorization, the error message typically contains a statement like “This data source does not allow streaming access.”

To grant access to a data source’s themes, you must explicitly configure the <mds_config> element in the configuration file.

Example: Configuring the mds.xml File

Example: Configuring the mds.xml File shows an <mds_config> element in which two map visualization component data sources, mvdemo and my-data, are configured such that certain themes of theirs can be streamed to clients.

<mds_config>

<data_source name="mvdemo">
<allow_predefined_themes>true</allow_predefined_themes>
<deny>my_secret_theme</deny>
<allow_dynamic_themes>true</allow_dynamic_themes>
</data_source>

<data_source name="my-data">
<allow_predefined_themes>false</allow_predefined_themes>
<allow>
<theme>public_points_theme</theme>
<theme>office_locations*</theme>
</allow>
<allow_dynamic_themes>false</allow_dynamic_themes>
</data_source>

</mds_config>

In Example: Configuring the mds.xml File:

If you modify the <mds_config> element, you must restart the deployed map visualization component instance for the modifications to take effect.

Creating a Map Visualization Component Data Source Using a JDBC Container

You can create a JDBC data source using a container defined data source in the map visualization component configuration file. However, to establish database connections to the newly created container data source, you must restart the map visualization component after performing the instructions in the following sections.

Create a JDBC Data Source in a Map Visualization Component Container

You can use Oracle Enterprise Manager 12c or later to create a data source that connects to the Oracle AI Database.

The following steps show how to create GridLink data source. (These are followed by steps showing how to create a Multi data source.)

  1. Log in to Enterprise Manager and in the Target Navigation pane, click the server instance that contains the map visualization component server.

    In Figure: Selecting the Server Instance, clicking map_viewer1 under WebLogic Domain causes the map_viewer1 server information to appear in the main area of the window.

    Figure: Selecting the Server Instance

    Description of the illustration mv_serv_instance.jpg

  2. Click WebLogic Server and select JDBC Data Sources, as shown in Figure: Displaying JDBC Data Sources.

    Figure: Displaying JDBC Data Sources

    Description of the illustration display_jdbc_ds.jpg

  3. Under JDBC Data Sources, click Create and select GridLink Data Source, as shown in Figure: Creating a GridLink Data Source.

    Figure: Creating a GridLink Data Source

    Description of the illustration create_gridlink_ds.jpg

  4. Enter any necessary information in the Creating New JDBC Data Source wizard. For example, to create a container data source named jdbc/mvdemo:

    1. Data Source Properties: Specify Data Source Name as mvdemo, Driver Service Name as Oracle Driver (Thin XA) for GridLink Connections Versions: Any, and JNDI Name as jdbc/mvdemo.

    2. Connection Properties: Generate the URL for database user mvdemo on the appropriate host.

    3. Transaction Properties: Accept the displayed transaction properties.

    4. ONS Properties: Accept the displayed transaction properties, or make any changes as needed.

    5. Select Targets: Select (check) map_viewer1 under Name to deploy the JDBC data source on the desired server.

    6. Review: Review the properties for the new data source to be created. If you need to make any changes, go back and make them and then return to this page.

To create a Multi data source instead of a GridLink data source as in the preceding instructions, adapt the steps as appropriate. For example:

  1. Log in to Enterprise Manager and in the Target Navigation pane, click the server instance that contains the map visualization component server.

    In Figure: Selecting the Server Instance, clicking map_viewer1 under WebLogic Domain causes the map_viewer1 server information to appear in the main area of the window.

    Figure: Selecting the Server Instance

    Description of the illustration mv_serv_instance.jpg

  2. Click WebLogic Server and select JDBC Data Sources, as shown in Figure: Displaying JDBC Data Sources.

    Figure: Displaying JDBC Data Sources

    Description of the illustration display_jdbc_ds.jpg

  3. Under JDBC Data Sources, click Create and select Multi Data Source, as shown in Figure: Creating a Multi Data Source.

    Figure: Creating a Multi Data Source

    Description of the illustration create_multi_ds.jpg

  4. Enter any necessary information. For example:

    1. Data Source Properties: Specify Data Source Name as mvdemo, JNDI Name as jdbc/mvdemo, and Algorithm Type as Failover.

    2. Select Targets: Select (check) map_viewer1 under Name .

    3. Select Data Source Type: Accept the default values (non-XA Driver).

    4. Click Create New Data Source.

    5. Specify properties for the first data source node, such as: Name: mvdemo-rac0, JNDI Name: jdbc/mvdemo-rac0, Database Type: Oracle.

    6. For Database Driver, select Oracle's Driver (Thin) for Oracle RAC Service-Instance connections: Versions: Any.

    7. Accept the default values (Supports Global Transactions and One-Phase Commit).

    8. Define the connection properties for Node 1. Provide values for Service Name, Database Name, Host Name, Port, Database User Name, Password, and Protocol.

    9. Verify the properties and click Test Configuration. If it succeeds, click Next.

    10. Select (check) the server in which the map visualization component is deployed (map_viewer1), and click Finish.

    11. On the next page, click Create a New Data Source to create and configure the second node.

    12. Specify properties for the second data source node, such as: Name: mvdemo-rac1, JNDI Name: jdbc/mvdemo-rac1, Database Type: Oracle.

    13. For Database Driver, select Oracle's Driver (Thin) for Oracle RAC Service-Instance connections: Versions: Any.

    14. Accept the default values (Supports Global Transactions and One-Phase Commit).

    15. Define the connection properties for Node 2. Provide values for Service Name, Database Name, Host Name, Port, Database User Name, Password, and Protocol.

    16. Verify the properties and click Test Configuration. If it succeeds, click Next.

    17. Select (check) the server in which the map visualization component is deployed (map_viewer1), and click Finish.

    18. If you need to add more nodes, click Create a New Data Source and create each in the same way as before.

Create a Map Visualization Component Data Source

After creating a container data source in the map visualization component container (explained in Create a JDBC Data Source in a Map Visualization Component Container), create a new map visualization component data source that enables it to connect to the Oracle AI Database by adding the container_ds attribute in the map visualization component data source. For example:

<map_data_source  name="mvdemo"
                  container_ds="jdbc/mvdemo"
                  number_of_mappers="7" />

In the preceding example:

For more information about these attributes, see Defining Permanent Map Data Sources.

Creating a Map Visualization Component Data Source Using Oracle Service Name

As an alternative to creating a JDBC container data source for use with the container_ds attribute in the map visualization component configuration file (as explained in Creating a Map Visualization Component Data Source Using a JDBC Container), you can create a map visualization component data source directly in the map visualization component configuration file by specifying the Oracle AI Database connection parameters. (This type of connection works only with Oracle Database Release 11.2 and later.) For example:

<map_data_source name="mvdemo"
         jdbc_host="hostname.example.com"
         jdbc_sid="//srv.mycompany.com"
         jdbc_port="1521"
         jdbc_user="mvdemo"
         jdbc_password="<password_for_mvdemo>"
         jdbc_mode="thin"
         number_of_mappers="8"
         allow_jdbc_theme_based_foi="true"
         editable="false"
/>

In the preceding example:

For more information about the attributes in this example, see Defining Permanent Map Data Sources.

In order to have the newly created map visualization component data source take effect, you must restart the map visualization component. Once restarted, the map visualization component obtains the necessary database connections directly using the connection parameters.

Performing Map Visualization Component Administrative Tasks

Besides knowing how to configure the map visualization component, you should also know how to perform other important administrative tasks using the map visualization component administration page. To log in to this page, see the instructions in Logging in to the Map Visualization Component Administration Page.

The tasks you can do as a map visualization component administrator include the following: