Skip Headers
Oracle® Application Server MapViewer User's Guide
10g Release 2 (10.1.2)
B14036-02
  Go To Documentation Library
Home
Go To Product List
Solution Area
Go To Table Of Contents
Contents
Go To Index
Index

Previous
Previous
Next
Next
 

1 Introduction to OracleAS MapViewer

Oracle Application Server MapViewer (OracleAS MapViewer) is a programmable tool for rendering maps using spatial data managed by Oracle Spatial or Oracle Locator (also referred to as Locator). OracleAS MapViewer provides tools that hide the complexity of spatial data queries and cartographic rendering, while providing customizable options for more advanced users. These tools can be deployed in a platform-independent manner and are designed to integrate with map-rendering applications.

This chapter contains the following major sections:

1.1 Overview of OracleAS MapViewer

OracleAS MapViewer includes the following main components:

The rendering engine connects to the Oracle database through Java Database Connectivity (JDBC). It also loads the map metadata (such as map definitions, styling rules, and symbology) from the database, and applies it to the retrieved spatial data.

The XML API provides high-level application developers with a convenient interface for submitting a map request to OracleAS MapViewer and handling the map response.

In addition to these components, the Map Definition Tool, an unsupported tool available through the Oracle Technology Network, simplifies the process of creating and managing map, theme, and symbology metadata in a spatial database. For information about the Map Definition Tool, see Chapter 7.

The primary benefit of OracleAS MapViewer is its integration with Oracle Spatial and Oracle Locator. The current release of OracleAS MapViewer supports only two-dimensional vector geometries. OracleAS MapViewer is not a full-featured Web map server or spatial application server.

1.1.1 Basic Flow of Action with OracleAS MapViewer

With OracleAS MapViewer, the basic flow of action involves two steps, whether the client requests a map or some OracleAS MapViewer administrative action.

For a map request:

  1. The client requests a map, passing in the map name, data source, center location, map size, and, optionally, other data to be plotted on top of a map.

  2. The server returns the map image (or a URL for the image) and the minimum bounding rectangle (MBR) of the map, and the status of the request.

For an OracleAS MapViewer administrative request:

  1. The client requests an OracleAS MapViewer administrative action, passing in the specific type of request and appropriate input values.

  2. The server returns the status of the request and the requested information.

Figure 1-1 shows the basic flow of action with OracleAS MapViewer.

Figure 1-1 Basic Flow of Action with OracleAS MapViewer

Description of Figure 1-1  follows
Description of "Figure 1-1 Basic Flow of Action with OracleAS MapViewer"

1.1.2 OracleAS MapViewer Architecture

Figure 1-2 illustrates the architecture of OracleAS MapViewer.

Figure 1-2 OracleAS MapViewer Architecture

Description of Figure 1-2  follows
Description of "Figure 1-2 OracleAS MapViewer Architecture"

As shown in Figure 1-2:

  • OracleAS MapViewer is part of the Oracle Application Server middle tier.

  • OracleAS MapViewer includes a rendering engine.

  • OracleAS MapViewer can communicate with a client Web browser or application using the HTTP protocol.

  • OracleAS MapViewer performs spatial data access (reading and writing Oracle Spatial and Oracle Locator data) through JDBC calls to the database.

  • The database includes Oracle Spatial or Oracle Locator, as well as mapping metadata.

1.2 Getting Started with OracleAS MapViewer

To get started using OracleAS MapViewer, follow these steps:

  1. Either before or after you install and deploy OracleAS MapViewer, read Chapter 2 to be sure you understand important terms and concepts.

  2. Ensure that you have the prerequisite software (see Section 1.3).

  3. Install (if necessary) and deploy OracleAS MapViewer (see Section 1.4).

  4. Use OracleAS MapViewer for some basic tasks, as described in Section 1.7.

  5. Optionally, use the Map Definition Tool (described in Chapter 7) to familiarize yourself with styles, themes, and maps, and the options for each.

1.3 Prerequisite Software for OracleAS MapViewer

To use OracleAS MapViewer, you must have the following Java packages and Oracle products, with the release number listed or a later release:

OracleAS MapViewer also supports the headless AWT mechanism in J2SE SDK 1.4, which enables OracleAS MapViewer to run on Linux or UNIX systems without setting any X11 DISPLAY variable. To enable AWT headless mode on Linux or UNIX systems, specify the following in the command line to start OracleAS MapViewer:

-Djava.awt.headless=true

1.4 Installing and Deploying OracleAS MapViewer

This section describes how to install (if necessary) and deploy OracleAS MapViewer to run in the middle tier. OracleAS MapViewer runs as an OC4J Web application and receives map requests from a client.

If you want to use GeoRaster themes or network themes for network analysis, then before you follow any procedure in this section, you must ensure that certain library files are in the Java CLASSPATH definition. For example, if the files are not already in the $ORACLE_HOME/lbs/mapviewer/web/WEB-INF/lib directory, you can add them there.

You can deploy OracleAS MapViewer either in a full Oracle Application Server environment or after a standalone installation of OC4J. Choose the procedure that applies to your needs:

1.4.1 Deploying OracleAS MapViewer in an Oracle Application Server Environment

If you have already successfully installed Oracle Application Server, you can deploy the OracleAS MapViewer application using the Oracle Enterprise Manager interface.

For all Oracle Application Server installation types except the J2EE and Web Cache installation type and the Infrastructure installation type, the following files are placed in the $ORACLE_HOME/lbs directory:

  • mapviewer.ear

  • lib/sdovis.jar

  • lib/sdoapi.jar

  • lib/sdoutl.jar


Note:

If you install and deploy OracleAS MapViewer with a standalone installation of OC4J, as described in Section 1.4.2, the mapviewer.ear file that you download already also includes the sdovis.jar, sdoapi.jar, and sdoutl.jar files.

The rest of this section describes how to deploy OracleAS MapViewer using the Oracle Enterprise Manager interface. The main steps are the following:

  1. Select or create an OC4J instance.

  2. Deploy the mapviewer.ear file.

  3. If sdovis.jar, sdoapi.jar, and sdoutl.jar exist as separate files (that is, if you did not download a mapviewer.ear file that already includes these files), add the directory for these files to the library path.

  4. Configure a secure administrator user for OracleAS MapViewer.

In your Web browser, go to the Oracle Enterprise Manager Application Server page, and either navigate to the OC4J instance where you want to deploy OracleAS MapViewer or create a new OC4J instance for the deployment. Click the Applications tab, and click the Deploy EAR file button to start a wizard that takes you through the deployment steps. Figure 1-3 shows the introductory page for this wizard.

Figure 1-3 Deploying OracleAS MapViewer: Wizard Introduction Page

Description of Figure 1-3  follows
Description of "Figure 1-3 Deploying OracleAS MapViewer: Wizard Introduction Page"

For J2EE Application, specify the complete path for the mapviewer.ear file.

For Application Name, specify mapviewer.

For Parent Application, accept the value default.

Press Continue to go to the next page of the wizard.

1.4.1.1 URL Mappings for the Web Modules Page

For URL Binding, specify /mapviewer.

Click Finish to go directly to the Summary page.

1.4.1.2 Summary Page

Review the information on the Summary page. If you need to make any changes, go back to the appropriate screen. If the information is correct, click Deploy.

Oracle Enterprise Manager deploys mapviewer.ear, modifies some XML files, creates a URL binding in the Oracle HTTP listener, and displays a screen with information about deployed applications. Figure 1-4 shows part of this page.

Figure 1-4 Deployed Applications

Description of Figure 1-4  follows
Description of "Figure 1-4 Deployed Applications"

1.4.1.3 Pages for Completing the Deployment

After you click Deploy on the Summary page, you must perform some steps to associate the sdovis.jar, sdoapi.jar, and sdoutl.jar files with OracleAS MapViewer. This section presents these steps.


Note:

The sdovis.jar, sdoapi.jar, and sdoutl.jar files contain the core rendering library for OracleAS MapViewer. These files are not packaged as part of the mapviewer.ear file, because some other Oracle Application Server components require their functions. Therefore, the sdovis.jar, sdoapi.jar, and sdoutl.jar files must be accessible even if OracleAS MapViewer is never deployed (that is, even if the mapviewer.ear file is never unpacked).

  1. In the Deployed Applications section of the page shown in Figure 1-4, click the button (in the Select column) next to mapviewer (in the Name column).

  2. Click Edit.

  3. On the next page, in the Administration section, under Properties, click General.

  4. On the next page, in the Library Paths section, click Add Another Row.

  5. In the box for the added row, type the path for the sdovis.jar file, which is in the $ORACLE_HOME/lbs/lib directory.

    For example: D:\oracle\ora_Bl\lbs\lib\sdovis.jar

  6. Click Apply.

  7. Repeat Steps 4 to 6 to add rows for the sdoapi.jar file and for the sdoutl.jar file.

  8. Restart the OC4J instance by clicking Restart on the OC4J instance page.

  9. If the target database is Oracle9i Release 9.0.1 or earlier, run SQL scripts to create the OracleAS MapViewer metadata views and predefined styles (see Section 1.4.2.3).

  10. Verify that the deployment was successful (see Section 1.4.2.4).

1.4.1.4 Configuring a Secure Administrator User for OracleAS MapViewer

Starting with Oracle Application Server MapViewer Release 9.0.4, you must configure an administrator user for OracleAS MapViewer in order to access the OracleAS MapViewer Admin page. This user must be given the OracleAS MapViewer map_admin_role security role. Follow these steps to configure the administrator user for OracleAS MapViewer.

  1. Go to the OC4J instance running OracleAS MapViewer, select the mapviewer application, and click the Security link shown in Figure 1-5.

    Figure 1-5 OracleAS MapViewer Administration Security Link

    Description of Figure 1-5  follows
    Description of "Figure 1-5 OracleAS MapViewer Administration Security Link"

  2. On the Security page, click the Add User button (shown in Figure 1-6) to add a user for OracleAS MapViewer.

    Figure 1-6 OracleAS MapViewer Security Page: Add User Button

    Description of Figure 1-6  follows
    Description of "Figure 1-6 OracleAS MapViewer Security Page: Add User Button"

  3. On the Security: Add User page (shown in Figure 1-7), specify the user name, a description, and password (twice, to confirm the password) for the new security user being created for OracleAS MapViewer, and then click OK.

    Figure 1-7 OracleAS MapViewer Security: Add User Page

    Description of Figure 1-7  follows
    Description of "Figure 1-7 OracleAS MapViewer Security: Add User Page"

  4. On the Security page, click the Map Role to Principals button (shown in Figure 1-8) to map this new user to the OracleAS MapViewer security role map_admin_role.

    Figure 1-8 OracleAS MapViewer Security Page: Map Role to Principals Button

    Description of Figure 1-8  follows
    Description of "Figure 1-8 OracleAS MapViewer Security Page: Map Role to Principals Button"

  5. On the Role page for map_admin_role, under Map Role to Users, select the newly created user (shown in Figure 1-9) to be mapped to the map_admin_role role, and then click Apply.

    Figure 1-9 Mapping the OracleAS MapViewer Administrator User to the map_admin_role Role

    Description of Figure 1-9  follows
    Description of "Figure 1-9 Mapping the OracleAS MapViewer Administrator User to the map_admin_role Role"

After completing these steps, you can go to the OracleAS MapViewer Admin page to perform administrator operations, such as adding a data source. When you are prompted for the user name and password, enter the values that you specified on the Add User page.

After you have finished performing OracleAS MapViewer administrator operations, you should exit from the Web browser; otherwise, the Admin page login information will remain in the cache for your current browser session.

1.4.2 Installing OracleAS MapViewer with a Standalone Installation of OC4J

To install and deploy OracleAS MapViewer with a standalone installation of OC4J, you must have installed OC4J on your system.

Follow these steps to install and deploy OracleAS MapViewer with a standalone installation of OC4J:

  1. If you have not already installed Oracle Application Server Wireless, download the mapviewer.ear file to the $ORACLE_HOME/lbs directory. If this directory does not exist, create it.

    You can put the mapviewer.ear file in another directory; however, the instructions in this guide assume that the mapviewer.ear file is in the $ORACLE_HOME/lbs directory.

  2. Edit the OC4J configuration files (see Section 1.4.2.1).

  3. Restart OC4J (see Section 1.4.2.2).

  4. If the target database is Oracle9i Release 9.0.1 or earlier, run SQL scripts to create the OracleAS MapViewer metadata views and predefined styles (see Section 1.4.2.3).

  5. Verify that the deployment was successful (see Section 1.4.2.4).

  6. Check the OracleAS MapViewer administrator user account (see Section 1.4.2.5).

1.4.2.1 Editing the OC4J Configuration Files to Autostart OracleAS MapViewer

To start OracleAS MapViewer automatically each time OC4J is restarted, edit the OC4J configuration files, as follows.

  1. Edit $OC4J_HOME/config/default-web-site.xml (or http-web-site.xml if you downloaded an OC4J kit from the Oracle Technology Network), where $OC4J_HOME should be $ORACLE_HOME/j2ee/home. Add a <web-app> element inside the <web-site> element. For example:

    <web-app application="mapviewer" name="web" root="/mapviewer"
      load-on-startup="true"/> 
    
    

    The following example shows a sample default-web-site.xml file after the modification.

    <?xml version="1.0"?>
    <!DOCTYPE web-site PUBLIC "Oracle Application Server XML Web site" "http://xmlns.oracle.com/ias/dtds/web-site.dtd">
    
    <!-- Change the host name below to your own host name. Localhost will -->
    <!-- not work with clustering. -->
    <!-- Also add cluster-island attribute as below.
    <web-site host="localhost" port="8888" display-name="Default Oracle Application Server Java Web Site" cluster-island="1" >
    -->
    
    <web-site port="8888" display-name="Default Oracle Application Server Containers for J2EE Web Site">
      <!-- Uncomment the following line when using clustering -->
      <!-- <frontend host="your_host_name" port="80"/> -->
      <!-- The default web-app for this site, bound to the root -->
      <default-web-app application="default" name="defaultWebApp"/>
    
      <!-- Access Log, where requests are logged to -->
      
      <access-log path="../log/default-web-access.log"/>
      <web-app application="mapviewer" name="web" root="/mapviewer"
       load-on-startup="true"/>
    </web-site>
    
    
  2. Modify $OC4J_HOME/config/server.xml. Add an <application> element inside the <application-server> element. For example:

    <application name="mapviewer" path="$MAPVIEWER_EAR_PATH" auto-start="true"/>
    
    

    $MAPVIEWER_EAR_PATH should be the full path of the mapviewer.ear file.

    The following example shows a sample server.xml file after the modification.

    <?xml version="1.0"?>
    <!DOCTYPE application-server PUBLIC "Orion Application Server Config" "http://xmlns.oracle.com/ias/dtds/application-server.dtd">
    
    <application-server application-directory="../applications"
                        deployment-directory="../application-deployments">
      <rmi-config path="./rmi.xml"/>
      <!-- JMS-server config link, uncomment to activate the JMS service -->
      <jms-config path="./jms.xml"/>
      <log>
        <file path="../log/server.log"/>
      </log>
    	
      <global-application name="default" path="application.xml"/>
    
      <global-web-app-config path="global-web-application.xml"/>
      <!-- <web-site path="./secure-web-site.xml"/> -->
      <web-site path="./default-web-site.xml"/>
    
      <application name="mapviewer" path="D:\Oracle\Ora817\lbs\mapviewer.ear" 
       auto-start="true"/> 
    </application-server>
    

1.4.2.2 Restarting OC4J

If OC4J is already running, you should not need to restart it. Instead, after you save changes made to the OC4J configuration files, OC4J should automatically restart and "hot deploy" OracleAS MapViewer. In this case, you should see messages such as the following:

04/04/19 11:26:11 WARN [oracle.lbs.mapserver.core.MapperPool] destroying ALL mapmaker instances.
04/04/19 11:26:11 INFO [oracle.lbs.mapserver.core.MapperConfig] Map Recycling thread started.
04/04/19 11:26:11 INFO [oracle.lbs.mapserver.oms] *** Oracle MapViewer started. ***

If OC4J is not running, start OC4J after saving the changes that you made to the OC4J configuration files. OC4J should start to deploy OracleAS MapViewer.

While it is deploying OracleAS MapViewer, OC4J extracts the whole OracleAS MapViewer directory structure from mapviewer.ear into the $ORACLE_HOME/lbs/mapviewer directory.

1.4.2.3 Running SQL Scripts, If Necessary

If all target databases are running Oracle9i Release 9.2 or later, skip this step and go to the next section. A target database is a database with Oracle Spatial or Oracle Locator (Release 8.1.6 or later) installed and from which you want OracleAS MapViewer to be able to render maps.

For each target database that is running Oracle9i Release 9.0.1 or earlier, run SQL scripts to create the OracleAS MapViewer metadata views and predefined styles. While you are connected to the database as the MDSYS user, you must run the first of the following SQL scripts, and it is recommended that you run the second script:

$ORACLE_HOME/lbs/mapviewer/admin/mapdefinition.sql
$ORACLE_HOME/lbs/mapviewer/admin/defaultstyles.sql

The second script (defaultstyles.sql) inserts some styles and themes and a base map into the OracleAS MapViewer metadata views. You can use these styles and themes in applications, and you can also use them as models when you create your own OracleAS MapViewer metadata objects.

1.4.2.4 Verifying That the Deployment Was Successful

To test if the OracleAS MapViewer servlet has started correctly, point your browser to that OC4J instance. For example, if OracleAS MapViewer is installed on a system named mapserver.xyzabc.com and the HTTP port is 8888, enter the following URL to invoke the OracleAS MapViewer servlet without sending it a request:

http://mapserver.xyzabc.com:8888/mapviewer/omserver

You should use an XML-enabled Web browser, such as Internet Explorer 5.0 or a later version, to see the XML response.

If the servlet has been started and initialized correctly, it generates a response, which will probably be a message such as the following:

<?xml version="1.0" encoding="UTF-8" ?>
<oms_error>Message:[oms] empty or null xml map request string. Wed Oct 24 12:22:03
EDT 2001 Machine Node Name: mapserver Severity: 0 Description: at
oracle.spatial.mapserver.oms.getXMLDocument(oms.java:379) at
oracle.spatial.mapserver.oms.doPost(oms.java:151) at
oracle.spatial.mapserver.oms.doGet(oms.java:119) at
javax.servlet.http.HttpServlet.service(HttpServlet.java:195) at
javax.servlet.http.HttpServlet.service(HttpServlet.java:309) at
javax.servlet.http.HttpServlet.service(HttpServlet.java:336) at
com.evermind.server.http.ServletRequestDispatcher.invoke(ServletRequestDispatcher.
java:501) at
com.evermind.server.http.ServletRequestDispatcher.forwardInternal(ServletRequestDi
spatcher.java:170) at
com.evermind.server.http.HttpRequestHandler.processRequest(HttpRequestHandler.java
:576) at
com.evermind.server.http.HttpRequestHandler.run(HttpRequestHandler.java:189) at
com.evermind.util.ThreadPoolThread.run(ThreadPoolThread.java:62)</oms_error>

The preceding display indicates that the servlet has been started and initialized correctly. The apparent errors in the display are normal at this point, because no request was specified in the URL.

If the servlet has not been started and initialized correctly, there will be no response, or the message 500 internal server error will be displayed.

If the response message includes wording like MapServer is not ready. Please try again later, it could mean that the OracleAS MapViewer servlet is initializing, but the process will take some additional time (for example, because the system is slow or because multiple predefined data sources are specified in the configuration file). In this case, you can wait at least a few seconds and try the request again. However, if you continue to get this response message, there may be a problem with the deployment. Check for any error messages, either in the OC4J console for a standalone OC4J deployment or in the redirected output/errors log file of the OC4J instance (using the Oracle Enterprise Manager site) for a full Oracle Application Server deployment. The following are common causes of this problem:

  • On a UNIX or Linux operating system, the Java virtual machine (JVM) was not started with the –Djava.awt.headless=true option, and no DISPLAY environment variable is set. This causes the OracleAS MapViewer server to fail because the server accesses the Java graphics library, which on UNIX and Linux systems relies on the X11 windowing system.

  • You are using the mapviewer.ear file from a full Oracle Application Server installation, but you forgot to add the sdovis.jar, sdoapi.jar, and sdoutl.jar files to the OC4J instance's library path, or you did not specify the correct locations for these JAR files.

1.4.2.5 Checking the OracleAS MapViewer Administrator User Account

Check the OracleAS MapViewer administrator user account to ensure that it is set up correctly with the map_admin_role role, and that you can, therefore, perform OracleAS MapViewer administrative operations. When you deploy OracleAS MapViewer to a standalone instance of OC4J, you can use the user name and password of the standalone instance to log in to the OracleAS MapViewer Admin page. (The OracleAS MapViewer script WEB_INF/orion-web.xml script sets this up.)

The user name is typically admin. The password is the one that you specified when you installed the OC4J instance (that is, at the prompt after you typed java -jar oc4j.jar -install). If you have forgotten the password, you can set a new password as follows:

  1. Go to the OC4J j2ee/home directory.

  2. Type the same installation command as before (java -jar oc4j.jar -install).

  3. Specify a new password at the prompt.

If you enter the correct password but are still prompted for login information, the problem might be caused by an automatically generated deployment descriptor (in $OC4J_HOME/application-deployments/mapviewer/web/orion-web.xml) from an earlier version of OracleAS MapViewer. If this is the cause of the problem, delete the orion-web.xml file from that directory, and redeploy the current version of the mapviewer.ear file.

1.5 Configuring OracleAS MapViewer


Note:

Most readers should skip this section, because after the installation, OracleAS MapViewer is configured to run using the default settings. This section is intended for advanced users who need to customize the OracleAS MapViewer configuration.

If the default configuration settings for running OracleAS MapViewer are not adequate, you can configure OracleAS MapViewer by editing the OracleAS MapViewer configuration file, mapViewerConfig.xml, which is located in the $ORACLE_HOME/lbs/mapviewer/web/WEB-INF/conf directory. To modify this file, you can use a text editor, or you can use the OracleAS MapViewer Admin page.

After you modify this file, you must restart OC4J to have the changes take effect; however, you can instead use the OracleAS MapViewer Admin page to restart only the OracleAS MapViewer servlet (instead of the entire OC4J instance, which may have other applications deployed and running) if either of the following applies:

The OracleAS MapViewer 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 1-1 shows a sample mapViewerConfig.xml file.

Example 1-1 Sample OracleAS MapViewer Configuration File

<?xml version="1.0" ?>
<!-- This is the configuration file for Oracle Application Server MapViewer. -->
<!-- Note: All paths are resolved relative to this directory (where this
           configuration 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://system3.my_corp.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 MapViewer (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 MapViewer 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
       MapViewer 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" />
  -->


  <!-- ****************************************************************** -->
  <!-- *********************** 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 MapViewer 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> elements.
         - 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",
         MapViewer automatically performs local data
         "flattening" with geodetic data if the data window is less than
         3 decimal degrees. Specifically, MapViewer 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", MapViewer will dynamically
         apply a globular projection to geometries being displayed. 
         If use_globular_projection="false" (the default), MapViewer does no map 
         projection to geodetic geometries. This option has no effect on 
         non-geodetic data.
   -->

  <!--
    <global_map_config>
        <note text="Copyright 2004, Oracle. All rights reserved." 
              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 MapViewer. The default is 64 MB for in-memory cache and 512 MB
       for disk spooling of spatial data. The disk cache path is determined by
       MapViewer by default.

       To disable the cache, set max_cache_size to 0.

       max_cache_size:  Maximum size of in-memory spatial cache of MapViewer.
                        Size must be specified in megabytes (MB).
   -->

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


  <!-- ****************************************************************** -->
  <!-- ******************** Custom Image Renderers ********************** -->
  <!-- ****************************************************************** -->
  <!-- Uncomment and add as many custom image renderers as needed here, 
       each in its own  <custom_image_renderer> element. The "image_format"
       attribute specifies the format of images that are to be custom 
       rendered using the class with full name specified in "impl_class". 
       You are responsible for placing the implementation classes in the
       MapViewer's classpath.
  -->
  <!-- 
  <custom_image_renderer image_format="ECW" 
                         impl_class="com.my_corp.image.ECWRenderer" />
  -->

  
  <!-- ****************************************************************** -->
  <!-- ******************** 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 MapViewer starts the next
             time, it will encrypt and replace the clear text password. 
  -->

  <!-- 
  <map_data_source name="mvdemo"
                   jdbc_host="elocation.us.oracle.com"
                   jdbc_sid="orcl"
                   jdbc_port="1521"
                   jdbc_user="scott"
                   jdbc_password="!tiger" 
                   jdbc_mode="thin"
                   number_of_mappers="3"
   />
   -->

</MapperConfig>

1.5.1 Specifying Logging Information

Logging information is specified in the <logging> element.

OracleAS MapViewer provides a flexible logging mechanism to record run-time information and events. You can configure the volume, format, and destination of the log output.

You can specify the following information as attributes or subelements of the <logging> element:

  • The log_level attribute controls the levels of information that are recorded in the log, which in turn affect the log output volume. Set the log_level attribute value to one of the following, listed from most restrictive logging to least restrictive logging: FATAL, ERROR, WARN, INFO, DEBUG, and FINEST. The FATAL level outputs the least log information (only unrecoverable events are logged), and the other levels are progressively more inclusive, with the FINEST level causing the most information to be logged. For production work, a level of WARN or more restrictive (ERROR or FATAL) is recommended; however, for debugging you may want to set a less restrictive level.

  • The log_thread_name attribute controls whether or not to include the name of the thread that encountered and logged the event.

  • The log_time attribute controls whether or not the current time is included when a logging event occurs.

  • The log_output subelement identifies output for the logging information. By default, log records are written to the system error console. You can change this to the system output console or to one or more files, or some combination. If you specify more than one device through multiple log_output subelements, the logging records are sent to all devices, using the same logging level and attributes.

1.5.2 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 OracleAS MapViewer 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 (described in Section 3.2.1.1) to GIF_URL or PNG_URL. In this case, OracleAS MapViewer saves the requested map image as a file on the host system where OracleAS MapViewer 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:

  • The file_prefix attribute identifies the map image file prefix. A map image file name will be a fixed file prefix followed by a serial number and the image type suffix. For example, if the map image file prefix is omsmap, a possible GIF map image file could be omsmap1.gif.

    Default value: file_prefix=omsmap

  • The url attribute identifies the map image base URL, which points to the directory under which all map image files are saved on the OracleAS MapViewer host. The map image URL sent to the mapping client is the map image base URL plus the map image file name. For example, if the map image base URL is http://dev04.abcxyz.com:1521/mapviewer/images, the map image URL for omsmap1.gif will be http://dev04.abcxyz.com:1521/mapviewer/images/omsmap1.gif.

    Default value: url=$HOST_URL/mapviewer/images

  • The path attribute identifies the path of the directory where all map image files are saved on the OracleAS MapViewer host system. This directory must be accessible by HTTP and must match the map image URL. Map image files saved in the directory specified by the path attribute should be accessible from the URL specified by the url attribute.

  • The life attribute specifies the number of minutes that a generated map image is guaranteed to stay on the file system before the image is deleted. If the life attribute is specified, the recycle_interval attribute controls how frequently OracleAS MapViewer checks for possible files to delete.

    Default: OracleAS MapViewer never deletes the generated map images.

  • The recycle_interval attribute specifies the number of minutes between times when OracleAS MapViewer checks to see if it can delete any image files that have been on the file system longer than the number of minutes for the life attribute value.

    Default value: 480 (8 hours)

1.5.3 Restricting Administrative (Non-Map) Requests

In addition to map requests, OracleAS MapViewer accepts administrative (non-map) requests, such as requests to list all data sources and to add and delete data sources. (Chapter 6 describes the administrative requests.) By default, all OracleAS MapViewer users are permitted to make administrative requests.

However, if you want to restrict the ability to submit administrative requests, you can edit the OracleAS MapViewer configuration file to allow administrative requests only from users with specified IP addresses.

To restrict administrative requests to users at specified IP addresses, add the <ip_monitor> element to the OracleAS MapViewer configuration file (or uncomment and modify an existing element, if one is commented out). Example 1-2 shows a sample <ip_monitor> element excerpt from a configuration file.

Example 1-2 Restricting Administrative Requests

<MapperConfig>
   . . .
   <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>
   . . .
</MapperConfig>

In Example 1-2:

  • The following IP addresses are explicitly included as able to submit administrative requests (unless excluded by an <ips_exclude> element): 138.1.17.9, 138.1.17.21, all that start with 138.3., all that start with 20., and all in the range (inclusive) of 24.17.1.3 to 24.17.1.20.

  • The following IP addresses are explicitly excluded from submitting administrative requests: all starting with 138.3.29., and all in the range (inclusive) of 20.22.34.1 to 20.22.34.255.

  • All other IP addresses that are not explicitly included cannot submit administrative requests.

Syntax notes for the <ip_monitor> element:

  • Use <ips> and <ip_range> elements to specify which IP addresses (and ranges) are allowed. Asterisk wildcards (such as 20.*) are acceptable. Use a comma-delimited list for addresses.

  • Use <ips_exclude> and <ip_range_exclude> elements to exclude IP addresses and address ranges from submitting administrative requests. If an address falls into both the included and excluded category, it is excluded.

  • If you specify the asterisk wildcard in an <ips> element, all associated IP addresses are included except any specified in <ips_exclude> and <ip_range_exclude> elements.

1.5.4 Specifying a Web Proxy for Background Image URLs

If a map request contains the bgimage (background image) attribute specifying a URL for an image, the image might be behind a firewall that OracleAS MapViewer cannot directly access. To allow OracleAS MapViewer to access background images in these cases, use the <web_proxy> element to identify the host name and port number for proxy access. For example:

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

1.5.5 Specifying Global Map Configuration Options

You can specify the following global "look and feel" options for the display of each map generated by OracleAS MapViewer:

  • Title

  • Note (such as a copyright statement or a footnote)

  • Logo (custom symbol or corporate logo)

  • Local geodetic data adjustment

  • Splitting geometries along the 180 meridian

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

<global_map_config>
    <note text="Copyright (c) 2003, XYZ Corporation"
              font="sans serif"
              position="SOUTH_EAST"/>
    <title  text="Map Courtesy of XYZ 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 OracleAS MapViewer configuration file. Note the following information about the attributes of the <title> element:

  • The text attribute specifies the title string.

  • The font attribute specifies a font. The font must exist on the system where OracleAS MapViewer is running.

  • The position attribute provides a positioning hint to OracleAS MapViewer when determining where the map title will be drawn on a map. Possible values are: NORTH, EAST, SOUTH, WEST, NORTH_EAST, SOUTH_EAST, SOUTH_WEST, NORTH_WEST, and CENTER.

    Default value: NORTH

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:

  • The text attribute specifies the note string.

  • The font attribute specifies a font. The font must exist on the system where OracleAS MapViewer is running.

  • The position attribute provides a positioning hint to OracleAS MapViewer when determining where the map note will be drawn on a map. Possible values are: NORTH, EAST, SOUTH, WEST, NORTH_EAST, SOUTH_EAST, SOUTH_WEST, NORTH_WEST, and CENTER.

    Default value: SOUTH_EAST

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 OracleAS MapViewer 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 OracleAS MapViewer configuration file and edit its attributes as needed.

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

  • The image_path attribute must specify a valid file path name, or a URL starting with http://.

  • The position attribute provides a positioning hint to OracleAS MapViewer when determining where the map logo will be drawn on a map. Possible values are: NORTH, EAST, SOUTH, WEST, NORTH_EAST, SOUTH_EAST, SOUTH_WEST, NORTH_WEST, and CENTER.

    Default value: SOUTH_WEST

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 OracleAS MapViewer to retrieve the logo image. For information about specifying a Web proxy, see Section 1.5.4.

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 Section 2.4.2 and Section 3.2.11. The default position for a map legend is SOUTH_WEST.)

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

1.5.6 Customizing the Spatial Data Cache

You can customize the in-memory cache that OracleAS MapViewer 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 max_cache_size attribute specifies the maximum number of megabytes (MB) of in-memory cache.

    Default value: 64

  • The report_stats attribute, if set to true, instructs the OracleAS MapViewer server to periodically (every 5 minutes) output cache statistics, such as the number of objects cached, the total size of cache objects, and data relating to the efficiency of the internal cache structure. The statistics are provided for each data source and for each predefined theme. They can help you to determine the optimal setting of the in-memory cache. For example, if you want to pin all geometry data for certain themes in the memory cache, you need to specify a max_cache_size value that is large enough to accommodate these themes.

    Default value: false

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 Section 2.3.1.2.

1.5.7 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 example:

<map_data_source name="mvdemo"
                 jdbc_host="mapsrus.us.oracle.com"
                 jdbc_sid="orcl"
                 jdbc_port="1521"
                 jdbc_user="scott"
                 jdbc_password="!tiger"
                 jdbc_mode="thin"
                 number_of_mappers="5"
                 max_connections="100"
/>

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

  • The name attribute specifies a unique data source name to OracleAS MapViewer. You must specify the data source name in all map requests that identify a data source.

  • The jdbc_host, jdbc_sid, jdbc_port, and jdbc_user attributes specify the database connection information and the database user name. (As an alternative to specifying these attributes and the jdbc_password and jdbc_mode attributes, you can specify the container_ds attribute, described later in this section.)

  • The jdbc_password attribute specifies the database user's login password. It must be prefixed with an exclamation point (!) when you specify the password for the first time. When OracleAS MapViewer next restarts, it will automatically obfuscate and replace the clear text password.

  • The jdbc_mode attribute tells OracleAS MapViewer which Oracle JDBC driver to use when connecting to the database. The default is thin (for the "thin" driver). The other possible value is oci8, which requires that you also have the Oracle Database client installed on the same host on which OracleAS MapViewer is running.

  • The number_of_mappers attribute identifies the maximum number of map renderers available (and thus the maximum number of map requests that OracleAS MapViewer can process in parallel for the data source) for this data source. Any unprocessed map requests are queued and eventually processed. For example, if the value is 3, OracleAS MapViewer will be able to process at most three mapping requests concurrently. If a fourth map request comes while three requests are being processed, it will wait until OracleAS MapViewer has finished processing one of the current requests.

    Specifying a large number_of_mappers value (such as 30 or 50) does not cause additional static memory to be used, and it does not affect the total number of database connections that will remain open. However, specifying a large value does cause some additional overhead operations, which might affect server performance at times of peak loads. The maximum number of mappers for a single data source is 64.

  • The max_connections attribute specifies the maximum number of database connections or sessions open for the data source at any given time. In most cases you should not specify this attribute, and accept the default value of 100.

    If you specify a value that is too small, the effect on performance can be significant. For example, if you specify max_connections="5" for a map request with 12 predefined themes, 12 connections will still be created temporarily to meet the demand, but 7 of them will be closed immediately upon the completion of the request (leaving only 5 open connections). OracleAS MapViewer will then dynamically create database connections whenever it needs more than 5 to meet the demand when processing map requests, because the number of permanently open database connections will never exceed the specified max_connections attribute value. Specifying a value that is too small will almost certainly increase the time it takes to process a map request, because opening a new database connection involves significant processing overhead.

  • The container_ds attribute lets you specify the J2EE container name (from the ejb-location attribute value) instead of specifying the jdbc_host, jdbc_sid, jdbc_port, jdbc_user, jdbc_password, and jdbc_mode attributes. For example, assume that the <data_source> element in the data-source.xml file for the standalone OC4J instance contains ejb-location="jdbc/OracleDS". In this case, instead of using the example at the beginning of this section, you can define the permanent OracleAS MapViewer data source as follows:

    <map_data_source name="mvdemo"
                     container_ds="jdbc/OracleDS"
                     number_of_mappers="5"
                     max_connections="100"
    />
    
    

    To use the container_ds attribute in the OracleAS MapViewer configuration file, you must start the OC4J instance with the -userThreads option. OracleAS MapViewer processes its configuration file in a separate user thread; if the -userThreads option is not specified, the container's context information is not available to user threads. However, if you are dynamically defining a data source through the OracleAS MapViewer Admin page, you can use the container_ds attribute regardless of whether you started the OC4J instance with the -userThreads option.

1.6 High Availability and OracleAS MapViewer


Note:

This section is intended for advanced users who want to take full advantage of the high availability features of Oracle Application Server with OracleAS MapViewer. You must have a strong understanding of high availability features, which are described in Oracle Application Server High Availability Guide.

With the current release of Oracle Application Server, OracleAS MapViewer users can benefit from the high availability features more effectively than in previous releases.

1.6.1 Deploying OracleAS MapViewer on a Multiprocess OC4J Instance

You can safely deploy OracleAS MapViewer in an OC4J instance of Oracle Application Server that has multiple processes. Oracle Application Server lets you configure the number of actual processes (JVMs) that can be started for each OC4J instance. On a multiprocessor host, starting multiple processes for a single OC4J can better utilize the system resources. (Releases of OracleAS MapViewer before 10g Release 2 (10.1.2) could not take advantage of this feature and thus could not be deployed on such OC4J instances.)

When OracleAS MapViewer is deployed to an OC4J instance with multiple processes, each process has an OracleAS MapViewer server running inside it. These OracleAS MapViewer servers all reside on the same host but in different Java processes. Map requests sent to this OC4J instance are automatically dispatched to the individual OracleAS MapViewer servers. Each OracleAS MapViewer server generates map image files according to a unique naming scheme, with the names coordinated when the different OracleAS MapViewer servers are first started (that is, when the containing OC4J instance is started). This avoids the possibility of two OracleAS MapViewer servers generating map files in the same sequence with the same file names.

1.6.2 Deploying OracleAS MapViewer on a Middle-Tier Cluster

OC4J instances in different Oracle Application Server installations can be clustered into an island. This provides a middle-tier fail-safe option. OracleAS MapViewer can be deployed to an OC4J island. You must take care, however, about how the generated image files on each host are named and referenced through URLs by client applications.

Consider the following sample scenario. When a map request is sent to the front Web server, it reaches the OracleAS MapViewer server running on host A. OracleAS MapViewer on host A then sends back the URL for the generated map image, and the client then sends a second request to fetch the actual image. This second request might be received by the OC4J container running on host B, which has no such image (or which will send back an incorrect image with the same name).

There is no single best solution for this problem in all environments. One option is to have the hosts share common networked storage, so that the map images are deposited in the same virtual (networked) file system by different OracleAS MapViewer servers running on different hosts. You must configure the map file storage information (see Section 1.5.2) for each OracleAS MapViewer instance so that the images are deposited in different subdirectories or so that they have different file prefixes. Otherwise, the image files generated by the multiple OracleAS MapViewer servers might overwrite each other on the disk. By properly configuring the map file storage information, you ensure that each URL sent back to the client uniquely identifies the correct map on the network drive.

If you cannot use networked drives, consider using a load balancer. You may first need to configure the map file storage information for each OracleAS MapViewer instance (as explained in the preceding paragraph), so that each OracleAS MapViewer instance names its generated images using an appropriate scheme to ensure uniqueness. You can then specify rules in the load balancer to have it redirect image requests to a certain host if the URL matches a certain pattern, such as containing a specified map image file prefix.

1.7 Getting Started Using OracleAS MapViewer

To get started using OracleAS MapViewer quickly, you can load a supplied set of demonstration data to which styles have been applied. If you have downloaded the entire OracleAS MapViewer kit from the Oracle Technology Network, you have a file named mvdemo.zip, which includes the Oracle export file mvdemo.dmp. Follow these steps:

  1. Import the mvdemo.dmp file into your Oracle database under the supplied user SCOTT. (Do not import it under any other database user. The demo may fail if you import the file under a different user). Use the following command (and include the directory path in the FILE parameter if mvdemo.dmp is not in the current directory):

    imp SCOTT/TIGER FILE=mvdemo.dmp FULL=Y
    
    
  2. Run the SQL script copymeta.sql (included in the mvdemo.zip file) to set up the mapping metadata for the user SCOTT.

  3. Define a data source for user SCOTT in OracleAS MapViewer, as explained in Section 1.7.1.

  4. Optionally, use the supplied example JSP file described in Section 1.7.2.

1.7.1 Dynamically Defining OracleAS MapViewer Data Sources

Before you can use OracleAS MapViewer to render a map, you must have at least one map data source defined. A data source can be permanently defined in the mapViewerConfig.xml file, or it can be dynamically defined using the OracleAS MapViewer home page. The rest of this section explains how to define a data source dynamically.

To define a data source dynamically, follow these steps:

  1. After starting OracleAS MapViewer, go to an OracleAS MapViewer page for submitting administrative and other requests by visiting a URL that has the following format:

    http://hostname:port/mapviewer
    
    

    In the preceding format, hostname:port is the host name string and port number for OracleAS MapViewer. For example:

    http://mapserver.xyzabc.com:8888/mapviewer
    
    
  2. Examine the Add a data source form, which contains the following or similar text:

    <?xml version="1.0" standalone="yes"?>
    <non_map_request>
      <add_data_source 
            name="mvdemo" 
            jdbc_host="elocation.us.oracle.com"
            jdbc_port="1521"
            jdbc_sid="orcl"
            jdbc_user="scott"
            jdbc_password="tiger"
            jdbc_mode="thin"
            number_of_mappers="3"/>
    </non_map_request>
    
    
  3. Edit the name and the JDBC-related information to reflect your environment.

  4. Click Submit.

This page contains forms that you can use for a variety of other tasks, such as:

  • Removing a data source

  • Redefining a data source

  • Listing all existing data sources

  • Listing all maps defined in a data source

  • Listing all themes defined in a data source

  • Listing all themes defined in a data source that belong to a specific map

  • Clearing the OracleAS MapViewer metadata cache for a specific data source

Many of these tasks use OracleAS MapViewer administrative requests, which are described in Chapter 6.

1.7.2 Example JSP File That Uses OracleAS MapViewer

The directory $ORACLE_HOME/lbs/mapviewer/web/demo contains a simple JavaServer Pages (JSP) file named mapclient.jsp that demonstrates how to interact with OracleAS MapViewer. The mapclient.jsp file lets you submit map requests, and it displays the resulting map image. (This file is one of several JSP example files, as explained in Section 1.7.3.)

To run this example file, go to a URL that has the following format:

http://hostname:port/mapviewer/demo/mapclient.jsp

In the preceding format, hostname:port is the host name string and port number for OracleAS MapViewer. For example:

http://mapserver.xyzabc.com:8888/mapviewer/demo/mapclient.jsp

To submit a map request using this page, enter the necessary information in the text boxes above the Clear and Submit buttons (Title is optional), and click Submit.

A map is displayed reflecting the information you entered, and the Request/Response/Msg box contains the XML format of the map request and response. You can perform additional operations on the map display by clicking the other buttons on the page, such as Zm In and Zm Out for zoom operations.

Figure 1-10 shows this page displaying the result of a map request.

Figure 1-10 OracleAS MapViewer Example JSP Display

Description of Figure 1-10  follows
Description of "Figure 1-10 OracleAS MapViewer Example JSP Display"

1.7.3 Additional JSP Example Files

The OracleAS MapViewer home page (that is, the URL with the format http://hostname:port/mapviewer) contains a Demos link, which leads to JSP example files that can help you to develop applications that use OracleAS MapViewer. In addition to a link to the mapclient.jsp file (described in Section 1.7.2), there are links to pages for the following files:

  • jview.jsp visualizes the results of spatial queries issued against a specified data source. You can type in up to three separate queries that retrieve geometric data, and choose different styling for each query result.

  • mapinit.jsp shows how to use the OracleAS MapViewer client API to develop a simple interactive Web mapping application with a feature-identifying capability. That is, you can select Identify and then click the circle for a city to display data (from nonspatial columns) about that city.

  • tagmap.jsp shows how to use the OracleAS MapViewer JSP tag library and the client API together. It also shows how to generate a map legend and place it on the mapping page.