Oracle® Application Server MapViewer User's Guide
10g Release 2 (10.1.2) Part No. B14036-01 |
|
![]() Previous |
![]() Next |
Oracle Application Server MapViewer (or simply, MapViewer) is a programmable tool for rendering maps using spatial data managed by Oracle Spatial or Oracle Locator (also referred to as Locator). 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:
Section 1.5, "Configuring MapViewer" (for advanced users)
Section 1.6, "High Availability and MapViewer" (for advanced users)
MapViewer includes the following main components:
A rendering engine (Java class library) that provides cartographic rendering capabilities (map renderer)
An Extensible Markup Language (XML) API that provides a programmable interface to MapViewer
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 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 MapViewer is its integration with Oracle Spatial and Oracle Locator. The current release of MapViewer supports only two-dimensional vector geometries. MapViewer is not a full-featured Web map server or spatial application server.
With MapViewer, the basic flow of action involves two steps, whether the client requests a map or some MapViewer administrative action.
For a map request:
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.
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 a MapViewer administrative request:
The client requests a MapViewer administrative action, passing in the specific type of request and appropriate input values.
The server returns the status of the request and the requested information.
Figure 1-1 shows the basic flow of action with MapViewer.
Figure 1-2 illustrates the architecture of MapViewer.
As shown in Figure 1-2:
MapViewer is part of the Oracle Application Server middle tier.
MapViewer includes a rendering engine.
MapViewer can communicate with a client Web browser or application using the HTTP protocol.
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.
To get started using MapViewer, follow these steps:
Either before or after you install and deploy MapViewer, read Chapter 2 to be sure you understand important terms and concepts.
Ensure that you have the prerequisite software (see Section 1.3).
Install (if necessary) and deploy MapViewer (see Section 1.4).
Use MapViewer for some basic tasks, as described in Section 1.7.
Optionally, use the Map Definition Tool (described in Chapter 7) to familiarize yourself with styles, themes, and maps, and the options for each.
To use MapViewer, you must have the following Java packages and Oracle products, with the release number listed or a later release:
Oracle Application Server 10g release 2 (10.1.2), or a standalone version of Oracle Application Server Containers for J2EE (OC4J) release 9.0.4 or later, which is available from the Oracle Technology Network at
Oracle Spatial or Oracle Locator (release 8.1.6 or later)
Oracle Client (release 8.1.7 or later), if you need to use JDBC Oracle Call Interface (OCI) features
J2SE SDK (Java 2 Platform Standard Edition, Software Development Kit from Sun Microsystems) 1.4 or later, with SDK 1.4.2_04 the recommended Java version for this release of MapViewer
MapViewer also supports the headless AWT mechanism in J2SE SDK 1.4, which enables 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 MapViewer:
-Djava.awt.headless=true
This section describes how to install (if necessary) and deploy MapViewer to run in the middle tier. 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.
To view GeoRaster data (described in Section 2.3.6), ensure that the Java Advanced Imaging (JAI) library files (jai_core.jar
and jai_codec.jar
) are in the MapViewer library path. These files are included in a full Oracle Application Server or Oracle Database (release 10g) installation. You can also get these files from the Sun Microsystems Web site.
To perform network analysis, such as shortest-path and within-cost analysis (see Section 2.3.7.2), and to view the results of the analysis on a map, ensure that the network model library file (sdonm.jar
) is in the MapViewer library path. This file is included in the Oracle Spatial installation for Oracle Database release 10g.
You can deploy MapViewer either in a full Oracle Application Server environment or after a standalone installation of OC4J. Choose the procedure that applies to your needs:
If you have already installed Oracle Application Server and want to deploy MapViewer, follow the instructions in Section 1.4.1.
If you have not installed Oracle Application Server but have installed OC4J and now want to install and deploy MapViewer, follow the instructions in Section 1.4.2.
If you have already successfully installed Oracle Application Server, you can deploy the 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:
Note: If you install and deploy MapViewer with a standalone installation of OC4J, as described in Section 1.4.2, themapviewer.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 MapViewer using the Enterprise Manager interface. The main steps are the following:
Select or create an OC4J instance.
Deploy the mapviewer.ear
file.
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.
Configure a secure administrator user for MapViewer.
In your Web browser, go to the Oracle Application Server Enterprise Manager site, and either navigate to the OC4J instance where you want to deploy 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 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.
For URL Binding, specify /mapviewer
.
Click Finish to go directly to the 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.
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 MapViewer. This section presents these steps.
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).
Click Edit.
On the next page, in the Administration section, under Properties, click General.
On the next page, in the Library Paths section, click Add Another Row.
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
Click Apply.
Repeat Steps 4 to 6 to add rows for the sdoapi.jar
file and for the sdoutl.jar
file.
Restart the OC4J instance by clicking Restart on the OC4J instance page.
If the release of the target Oracle Database is 9.0.1 or earlier, run SQL scripts to create the MapViewer metadata views and predefined styles (see Section 1.4.2.3).
Verify that the deployment was successful (see Section 1.4.2.4).
Starting with MapViewer release 9.0.4, you must configure an administrator user for MapViewer in order to access the MapViewer Admin page. This user must be given the MapViewer map_admin_role
security role. Follow these steps to configure the administrator user for MapViewer.
Go to the OC4J instance running MapViewer, select the mapviewer application, and click the Security link shown in Figure 1-5.
On the Security page, click the Add User button (shown in Figure 1-6) to add a user for MapViewer.
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 MapViewer, and then click OK.
On the Security page, click the Map Role to Principals button (shown in Figure 1-8) to map this new user to the MapViewer security role map_admin_role
.
Figure 1-8 MapViewer Security Page: Map Role to Principals Button
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 MapViewer Administrator User to the map_admin_role Role
After completing these steps, you can go to the 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 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.
To install and deploy MapViewer with a standalone installation of OC4J, you must have installed OC4J on your system.
Follow these steps to install and deploy MapViewer with a standalone installation of OC4J:
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.
Edit the OC4J configuration files (see Section 1.4.2.1).
Restart OC4J (see Section 1.4.2.2).
If the release of the target Oracle Database is 9.0.1 or earlier, run SQL scripts to create the MapViewer metadata views and predefined styles (see Section 1.4.2.3).
Verify that the deployment was successful (see Section 1.4.2.4).
Check the MapViewer administrator user account (see Section 1.4.2.5).
To start MapViewer automatically each time OC4J is restarted, edit the OC4J configuration files, as follows.
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 WebSite" 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>
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>
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" 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 MapViewer.
While it is deploying MapViewer, OC4J extracts the whole MapViewer directory structure from mapviewer.ear
into the $ORACLE_HOME
/lbs/mapviewer
directory.
If all target databases are running Oracle Database 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 MapViewer to be able to render maps.
For each target database that is running Oracle Database release 9.0.1 or earlier, run SQL scripts to create the 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 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 MapViewer metadata objects.
To test if the MapViewer servlet has started correctly, point your browser to that OC4J instance. For example, if MapViewer is installed on a system named mapserver.xyzabc.com
and the HTTP port is 8888, enter the following URL to invoke the 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(ServletRequestDispatcher.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 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 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 MapViewer server to fail because it 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.
Check the MapViewer administrator user account to ensure that it is set up correctly with the map_admin_role
role, and that you can, therefore, perform MapViewer administrative operations. When you deploy MapViewer to a standalone instance of OC4J, you can use the user name and password of the standalone instance to log in to the MapViewer Admin page. (The 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:
Go to the OC4J j2ee/home
directory.
Type the same installation command as before (java -jar oc4j.jar -install
).
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 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.
Note: Most readers should skip this section, because after the installation, MapViewer is configured to run using the default settings. This section is intended for advanced users who need to customize the MapViewer configuration. |
If the default configuration settings for running MapViewer are not adequate, you can configure MapViewer by editing the 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 MapViewer Admin page.
After you modify this file, you must restart OC4J to have the changes take effect; however, you can instead use the MapViewer Admin page to restart only the MapViewer servlet (instead of the entire OC4J instance, which may have other applications deployed and running) if either of the following applies:
You installed MapViewer with a standalone OC4J instance.
The MapViewer OC4J instance with Oracle Application Server is configured to have only one OC4J process running (the default) and not to be clustered (that is, not to be in an island).
If you deployed MapViewer to an OC4J instance with multiple processes (thus with multiple physical JVMs on the same host), or if you deployed to an OC4J instance that is in a clustered island (with multiple OC4J instances running on multiple hosts), you must restart the OC4J instance itself for the changes to the MapViewer configuration file to take effect in all MapViewer servers. In the latter case (clustered OC4J instances), you may also need to modify the MapViewer configuration file in the MapViewer directory hierarchy for each host's OC4J instance in the cluster. For more information about repository-based middle-tier clustering, see Oracle Application Server High Availability Guide.
The MapViewer configuration file defines the following information in XML format:
Logging information, defined in the <logging>
element (see Section 1.5.1)
Map image file information, defined in the <save_images_at>
element (see Section 1.5.2)
Administrative request restrictions, defined in the <ip_monitor>
element (see Section 1.5.3)
Web proxy information for accessing external information across a firewall, defined in the <web_proxy>
element (see Section 1.5.4)
Global map "look and feel" configuration, defined in the <global_map_config>
element (see Section 1.5.5)
Internal spatial data cache settings, defined in the <spatial_data_cache>
element (see Section 1.5.6)
Custom image renderer registration, defined in the <custom_image_renderer>
element (see Appendix C)
Permanent map data sources, defined in the <map_data_source>
element (see Section 1.5.7)
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 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>
Logging information is specified in the <logging>
element.
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 fatal 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.
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 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, MapViewer saves the requested map image as a file on the host system where 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 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 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 MapViewer checks for possible files to delete.
Default: MapViewer never deletes the generated map images.
The recycle_interval
attribute specifies the number of minutes between times when 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)
In addition to map requests, 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 MapViewer users are permitted to make administrative requests.
However, if you want to restrict the ability to submit administrative requests, you can edit the 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 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.
If a map request contains the bgimage
(background image) attribute specifying a URL for an image, the image might be behind a firewall that MapViewer cannot directly access. To allow 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"/>
You can specify the following global "look and feel" options for the display of each map generated by 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 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 MapViewer is running.
The position
attribute provides a positioning hint to 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 MapViewer is running.
The position
attribute provides a positioning hint to 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 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 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 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 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 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 MapViewer automatically apply a globular map projection (that is, a map projection suitable for viewing the world, and specifically the azimuthal equidistant projection for MapViewer), specify use_globular_projection="true"
in the <rendering>
element. This option applies to geodetic data only.
You can customize the in-memory cache that 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 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.
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 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 MapViewer next restarts, it will automatically obfuscate and replace the clear text password.
The jdbc_mode
attribute tells MapViewer which 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 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 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, 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 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). 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 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 MapViewer configuration file, you must start the OC4J instance with the -userThreads
option. 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 MapViewer Admin page, you can use the container_ds
attribute regardless of whether you started the OC4J instance with the -userThreads
option.
Note: This section is intended for advanced users who want to take full advantage of the high availability features of Oracle Application Server with 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, MapViewer users can benefit from the high availability features more effectively than in previous releases.
You can safely deploy 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 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 MapViewer is deployed to an OC4J instance with multiple processes, each process has a MapViewer server running inside it. These 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 MapViewer servers. Each MapViewer server generates map image files according to a unique naming scheme, with the names coordinated when the different MapViewer servers are first started (that is, when the containing OC4J instance is started). This avoids the possibility of two MapViewer servers generating map files in the same sequence with the same file names.
OC4J instances in different Oracle Application Server installations can be clustered into an island. This provides a middle-tier fail-safe option. 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 MapViewer server running on host A. 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 MapViewer servers running on different hosts. You must configure the map file storage information (see Section 1.5.2) for each 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 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 MapViewer instance (as explained in the preceding paragraph), so that each 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.
To get started using MapViewer quickly, you can load a supplied set of demonstration data to which styles have been applied. If you have downloaded the entire MapViewer kit from OTN (http://www.oracle.com/technology
), you have a file named mvdemo.zip
, which includes the Oracle export file mvdemo.dmp
. Follow these steps:
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
Run the SQL script copymeta.sql
(included in the mvdemo.zip
file) to set up the mapping metadata for the user SCOTT
.
Define a data source for user SCOTT
in MapViewer, as explained in Section 1.7.1.
Optionally, use the supplied example JSP file described in Section 1.7.2.
Before you can use 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 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:
After starting MapViewer, go to a 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 MapViewer. For example:
http://mapserver.xyzabc.com:8888/mapviewer
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>
Edit the name and the JDBC-related information to reflect your environment.
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 MapViewer metadata cache for a specific data source
Many of these tasks use MapViewer administrative requests, which are described in Chapter 6.
The directory $ORACLE_HOME
/lbs/mapviewer/web/demo
contains a simple JavaServer Pages (JSP) file named mapclient.jsp
that demonstrates how to interact with 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 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.
The 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 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 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 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.