| Oracle® Application Server MapViewer User's Guide Release 10.1.3.1 B14036-03 |
|
 Previous |
 Next |
| Oracle® Application Server MapViewer User's Guide Release 10.1.3.1 B14036-03 |
|
Previous |
Next |
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:
Section 1.6, "High Availability and OracleAS MapViewer" (for advanced users)
OracleAS MapViewer is shipped as part of Oracle Application Server. Its main deliverable is a J2EE application that can be deployed to a J2EE container, such as that for Oracle Application Server. OracleAS MapViewer includes the following main components:
A core rendering engine (Java library) named SDOVIS that performs cartographic rendering. A servlet is provided to expose the rendering functions to Web applications.
A suite of application programming interfaces (APIs) that allow programmable access to MapViewer features. These APIs include XML, Java, PL/SQL, and an AJAX-based JavaScript API.
A graphical Map builder tool that enables you to create map symbols, define spatial data rendering rules, and create and edit MapViewer objects.
Oracle Map, which includes Map Cache and FOI (Feature of Interest) servers that facilitate the development of interactive geospatial Web applications.
The core rendering engine connects to the Oracle database through Java Database Connectivity (JDBC). It also reads the map metadata (such as map definitions, styling rules, and symbologies created through the Map Builder tool) from the database, and applies the metadata to the retrieved spatial data during rendering operations.
The XML API provides application developers with a versatile interface for submitting a map request to OracleAS MapViewer and retrieving the map response. The JavaBean-based API and the PL/SQL API provide access to MapViewer's rendering capabilities. The JavaScript API enables you to create highly interactive web applications that use the Oracle Maps feature of MapViewer.
The Map Builder tool simplifies the process of creating and managing map, theme, and symbology metadata in a spatial database. For information about this tool, see Chapter 7.
Oracle Maps, built on core MapViewer features, uses a Map Cache server that caches map image tiles, and a Feature of Interest (FOI) server that streams live data out of a database to be displayed as interactive features on a map. You can use the AJAX-based JavaScript API with Oracle Maps to provide sophisticated mapping solutions. Oracle Maps also allows for advanced customization and querying capabilities.
The primary benefit of OracleAS MapViewer is its integration with Oracle Spatial, Oracle Locator, and the Oracle Fusion middleware. The current release of OracleAS MapViewer supports two-dimensional vector geometries stored in Oracle Spatial, as well as data in the Oracle Spatial topology and network data models. Oracle MapViewer is also an Open Geospatial Consortium (OGC)-compliant Web Map Service (WMS) server.
With OracleAS MapViewer, the basic flow of action follows a two-step request/response model, whether the client requests a map or some OracleAS 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 an OracleAS MapViewer administrative request:
The client requests an OracleAS 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 OracleAS MapViewer.
Figure 1-1 Basic Flow of Action with OracleAS MapViewer
Figure 1-2 illustrates the architecture of OracleAS MapViewer.
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.
To get started using OracleAS MapViewer, follow these steps:
Either before or after you install and deploy OracleAS 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 OracleAS MapViewer (see Section 1.4).
Use OracleAS MapViewer for some basic tasks. For example, create an Oracle Maps application (see Chapter 8.
Optionally, use the Map Builder tool (described in Chapter 7) to familiarize yourself with styles, themes, and maps, and the options for each, and optionally to preview spatial data.
To use OracleAS 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 3 (10.1.3) or later, or a standalone version of Oracle Application Server Containers for J2EE (OC4J) Release 10.1.3 or later, which is available from the Oracle Technology Network at
Oracle Database with Spatial or Locator (Release 9i or later)
Oracle Client (Release 9i or later), if you need to use JDBC Oracle Call Interface (OCI) features. Note that in general, the JDBC thin driver is recommended for use with MapViewer, in which case Oracle Client is not required.
Java SDK 1.5 or later
OracleAS MapViewer also supports the headless AWT mechanism in J2SE SDK, 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
This section describes how to install (if necessary) and deploy OracleAS MapViewer to run in the middle tier. As mentioned previously, OracleAS MapViewer runs as a J2EE Web application and listens for incoming map requests on the container's HTTP port.
You can deploy OracleAS MapViewer either in a full Oracle Application Server environment or to a standalone installation of OC4J. Choose the procedure that applies to your needs:
If you have already installed Oracle Application Server 10.1.3 or later, and want to deploy OracleAS MapViewer to that instance, follow the instructions in Section 1.4.1.
If you have not installed Oracle Application Server but have installed the OC4J standalone kit and now want to install and deploy OracleAS MapViewer, follow the instructions in Section 1.4.2. OC4J standalone is a small footprint J2EE container and Web server provided by Oracle.
Alternatively, you can download the latest MapViewer Quick Start kit from the MapViewer page on the Oracle Technology Network (OTN). This kit includes a standalone OC4J with MapViewer already deployed and configured. It takes only minutes to get MapViewer running, and is convenient for testing and basic development.
Regardless of where and how MapViewer is deployed, the application server (or standalone OC4J) will create a home directory for MapViewer during deployment. This directory is typically located under the following directory:
$ORACLE_HOME/j2ee/<oc4j_instance_name>/applications
$ORACLE_HOME is the top directory of either the Application Server or standalone OC4J install. The value for <oc4j_instance_name> is typically home if deployed to standalone OC4J, or the name of the target OC4J instance if deployed to a full OracleAS installation. This MapViewer directory is typically named mapviewer (or the same as the context path under which MapViewer is deployed), and has many subdirectories. You may wish to familiarize yourself with some of the subdirectories in case you want to perform debugging, administration, or manual configuration.
The following are the main subdirectories of a MapViewer deployment:
/mapviewer
sql/
web/
fsmc/
WEB-INF/
lib/
conf/
log/
mapcache/
classes/
admin/
The /mapviewer/sql directory contains several SQL scripts that are necessary for installing the MapViewer PL/SQL API package into the database. The /mapviewer/web/fsmc directory contains the JavaScript API library and several tutorials for Oracle Maps. The /mapviewer/web/WEB-INF directory and its subdirectories contain libraries and MapViewer administration and configuration files.
If you want to use GeoRaster themes to view GeoRaster data, after successfully deploying MapViewer you may need to ensure that certain JAI (Java Advanced Imaging) library files are in the MapViewer Java classpath. The library files are jai_core.jar, jai_codec.jar, and jai_imageio.jar, and they can be found in a full Oracle Application Server or Oracle Database installation, usually under the directory for Oracle interMedia files. You can copy them into the MapViewer WEB-INF/lib directory.
If you have already successfully installed Oracle Application Server version 10.1.3 or later, you can deploy the OracleAS MapViewer using the Oracle Enterprise Manager Server Control web interface. The main steps are the following:
Select an OC4J instance as the target for deploying MapViewer. You can select an existing OC4J instance, or create a new instance specifically for MapViewer. It is suggested that you create a new instance for MapViewer, but it is not required.
Locate the mapviewer.ear file. This file is either shipped with the Oracle Application Server software or, for version 10.1.3.1, can be downloaded from OTN.
Deploy the mapviewer.ear file to the selected OC4J instance using the Server Control web interface, or use Oracle Application Server command-line admin tool to deploy MapViewer (or any other J2EE application). For information about using the admin tool, see the Oracle Application Server Administration Guide.
To start deploying MapViewer, navigate to the OracleAS Server Control page and select the desired OC4J instance, as shown in Figure 1-3, where the default home OC4J instance is selected.
Click Deploy to display a page (shown in Figure 1-4) in which you enter the location of the mapviewer.ear file (a directory named tmp in this figure).
Figure 1-4 Specifying the mapviewer.ear Location
Click Next to display a page (shown in Figure 1-5) in which you specify the name of the application.
Figure 1-5 Specifying the Application Name
For Application Name, specify mapviewer. The Context Root will be set to /mapviewer by default. Do not change the context root value unless absolutely necessary.
Click Next to display the Deployment Setting page. You usually do not need to change any of the settings on this page.
Click Deploy on the Deployment Setting page to start the deployment of MapViewer. If the deployment is successful, the Confirmation page is displayed indicating that deployment of the application was successful.
After you complete the deployment, see Section 1.4.3.
To install and deploy OracleAS MapViewer with a standalone installation of OC4J, you must have installed OC4J on your system. The standalone OC4J installation kit is a single zip file that you can download from OTN. It contains the Oracle Container for J2EE and also a lightweight Web server. After you unzip this file, you can start the OC4J instance up by entering the command java –jar oc4j.jar from the $OC4J_HOME/j2ee/home directory, where $OC4J_HOME is the top directory into which you unzipped the installation file.
Note that you must have the Java 1.5 SDK installation, not the JRE installation, in your environment path in order for OC4J to start up and function properly.
Because standalone OC4J version 10.1.3 (or later) comes with its own Server Control Web interface, the deployment of MapViewer is almost exactly as described in Section 1.4.1 once you log into its Server Control Web page. The only difference is that you will not be able to choose a different OC4J instance, because you are running in a single standalone OC4J instance.
After you complete the deployment, see Section 1.4.3.
After successfully deploying MapViewer to Oracle Application Server or standalone OC4J, you may want to verify whether it is actually working, as described in Section 1.4.3.1. It's also a good idea to become familiar with its web interface, particularly its administration pages.
You must also run at least one, and perhaps several, SQL scripts, as explained in Section 1.4.3.2.
To test if the OracleAS MapViewer server has started correctly, point your browser to that OC4J instance. For example, if OracleAS MapViewer is installed on a system named www.xyzabc.com and the HTTP port is 8888, enter the following URL to invoke the OracleAS MapViewer server with a simple get-version request:
http://www.xyzabc.com:8888/mapviewer/omserver?getv=t
If MapViewer is running correctly, it should immediately send back a response text string indicating the version and build number, such as the following:
Ver10131_B060225
The actual version and build number will reflect the version that you installed.
If the server 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 server 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 and MapViewer is attempting to connect to these databases). In this case, you can wait at least a few seconds and try the preceding 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 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 deployed the mapviewer.ear file to an incompatible version of Oracle Application Server or standalone OC4J. Note that MapViewer 10.1.3.1 must be deployed to Application Server (or standalone OC4J) 10.1.3 or later. It will not work properly with earlier versions of Oracle Application Server or OC4J.
This section describes SQL scripts, one or more of which you must run while connected as the MDSYS user. For each script that you run, you must run it on each target Oracle database from which MapViewer will render spatial data.
MapViewer uses a set of system views to store necessary mapping metadata in a target database. 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. MapViewer requires following system views:
USER_SDO_MAPS
USER_SDO_THEMES
USER_SDO_STYLES
USER_SDO_CACHED_MAPS
The USER_SDO_CACHED_MAPS view is used by the Oracle Maps feature. It stores definitions of map tile cache instances. You must create this view manually by running the following script while connected as the MDSYS user:
$MV_HOME/web/WEB-INF/admin/mcsdefinition.sql
If the target database is release 9.2 or later, the other three views (USER_SDO_MAPS, USER_SDO_THEMES, and USER_SDO_STYLES) are created and populated automatically. However, if the target database has a release number lower than 9.2, you must manually create and populate these views by running the following scripts while connected as the MDSYS user:
$MV_HOME/web/WEB-INF/admin/mapdefinition.sql
$MV_HOME/web/WEB-INF/admin/defaultstyles.sql
This section introduces the MapViewer Administration page and some administrative and configuration tasks that you can perform, such as adding new data sources, managing map cache instances used by Oracle Maps, and setting logging levels.
After you have verified that MapViewer is running properly, it is suggested that you log in to the MapViewer Administration page. To do this, go first to the MapViewer Welcome page, which is typically http://<host>:<port>/mapviewer, where <host> and <port> should be replaced by the correct value for your installation. Figure 1-6 shows the MapViewer Welcome page
Click the Admin icon at the top right or text link at the bottom. A login prompt is displayed, asking for user name and password for the MapViewer administration page.
User Name: Enter oc4jadmin.
Password: Enter the password that you use to log into the Server Control page of the OracleAS or OC4J standalone installation.
After you log in, the MapViewer administration page is displayed, as shown in Figure 1-7.
You can use this page to perform administrative tasks, such as configuring MapViewer to your site's specific requirements, adding predefined data sources so that MapViewer will automatically connect to the specified target database whenever it is started, and managing map cache instances. For detailed about configuration tasks, see Section 1.5.2; for information about administrative tasks, see Section 1.5.3.
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:
You installed OracleAS MapViewer with a standalone OC4J instance.
The OracleAS 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 OracleAS 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 OracleAS MapViewer configuration file to take effect in all OracleAS MapViewer servers. In the latter case (clustered OC4J instances), you may also need to modify the OracleAS MapViewer configuration file in the OracleAS 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 OracleAS MapViewer configuration file defines the following information in XML format:
Logging information, defined in the <logging> element (see Section 1.5.2.1)
Map image file information, defined in the <save_images_at> element (see Section 1.5.2.2)
Administrative request restrictions, defined in the <ip_monitor> element (see Section 1.5.2.3)
Web proxy information for accessing external information across a firewall, defined in the <web_proxy> element (see Section 1.5.2.4)
Global map "look and feel" configuration, defined in the <global_map_config> element (see Section 1.5.2.5)
Internal spatial data cache settings, defined in the <spatial_data_cache> element (see Section 1.5.2.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.2.12)
Security configurations, defined in the <security_config> element
WMS services configurations, defined in the <wms_config> element
External attribute data provider registration, defined in <ns_data_provider> elements
Map cache server configurations, defined in the <map_cache_server> element
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 OracleAS MapViewer. -->
<!-- Note: All paths are resolved relative to this directory (where
this config file is located), unless specified as an absolute
path name.
-->
<MapperConfig>
<!-- ****************************************************************** -->
<!-- ************************ Logging Settings ************************ -->
<!-- ****************************************************************** -->
<!-- Uncomment the following to modify logging. Possible values are:
log_level = "fatal"|"error"|"warn"|"info"|"debug"|"finest"
default: info) ;
log_thread_name = "true" | "false" ;
log_time = "true" | "false" ;
one or more log_output elements.
-->
<!--
<logging log_level="info" log_thread_name="false"
log_time="true">
<log_output name="System.err" />
<log_output name="../log/mapviewer.log" />
</logging>
-->
<!-- ****************************************************************** -->
<!-- ********************** Map Image Settings ************************ -->
<!-- ****************************************************************** -->
<!-- Uncomment the following only if you want generated images to
be stored in a different directory, or if you want to customize
the life cycle of generated image files.
By default, all maps are generated under
$ORACLE_HOME/lbs/mapviewer/web/images.
Images location-related attributes:
file_prefix: image file prefix, default value is "omsmap"
url: the URL at which images can be accessed. It must match the 'path'
attribute below. Its default value is "%HOST_URL%/mapviewer/images"
path: the corresponding path in the server where the images are
saved; default value is "%ORACLE_HOME%/lbs/mapviewer/web/images"
Images life cycle-related attributes:
life: the life period of generated images, specified in minutes.
If not specified or if the value is 0, images saved on disk will
never be deleted.
recycle_interval: this attribute specifies how often the recycling
of generated map images will be performed. The unit is minute.
The default interval (when not specified or if the value is 0)
is 8*60, or 8 hours.
-->
<!--
<save_images_at file_prefix="omsmap"
url="http://mypc.mycorp.com:8888/mapviewer/images"
path="../web/images"
/>
-->
<!-- ****************************************************************** -->
<!-- ********************* IP Monitoring Settings ********************* -->
<!-- ****************************************************************** -->
<!-- Uncomment the following to enable IP filtering for administrative
requests.
Note:
- Use <ips> and <ip_range> to specify which IPs (and ranges) are allowed.
Wildcard form such as 20.* is also accepted. Use a comma-delimited
list in <ips>.
- Use <ips_exclude> and <ip_range_exclude> for IPs and IP ranges
prohibited from accessing eLocation.
- If an IP falls into both "allowed" and "prohibited" categories, it is
prohibited.
- If you put "*" in an <ips> element, then all IPs are allowed, except
those specified in <ips_exclude> and <ip_range_exclude>.
On the other hand, if you put "*" in an <ips_exclude> element, no one
will be able to access 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" />
-->
<!-- ****************************************************************** -->
<!-- *********************** Security Configuration ******************* -->
<!-- ****************************************************************** -->
<!-- Here you can set various security related configurations of MapViewer.
-->
<security_config>
<disable_direct_info_request> false </disable_direct_info_request>
</security_config>
<!-- ****************************************************************** -->
<!-- *********************** Global Map Configuration ***************** -->
<!-- ****************************************************************** -->
<!-- Uncomment and modify the following to specify systemwide parameters
for generated maps. You can specify your copyright note, map title, and
an image to be used as a custom logo shown on maps. The logo image must
be accessible to this 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> element.
- position specifies a relative position on the map where the
logo, note, or title will be displayed. Possible values are
NORTH, EAST, SOUTH, WEST, NORTH_EAST, SOUTH_EAST,
SOUTH_WEST, NORTH_WEST, and CENTER.
- image_path specifies a file path or a URL (starts with "http://")
for the image.
<rendering> element attributes:
- Local geodetic data adjustment: If allow_local_adjustment="true",
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
apply a globular projection on the fly 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 Corporation"
font="sans serif"
position="SOUTH_EAST"/>
<title text="MapViewer Demo"
font="Serif"
position="NORTH" />
<logo image_path="C:\\images\\a.gif"
position="SOUTH_WEST" />
<rendering allow_local_adjustment="false"
use_globular_projection="false" />
</global_map_config>
-->
<!-- ****************************************************************** -->
<!-- ****************** Spatial Data Cache Setting ******************* -->
<!-- ****************************************************************** -->
<!-- Uncomment and modify the following to customize the spatial data cache
used by MapViewer. The default is 64 MB for in-memory cache.
To disable the cache, set max_cache_size to 0.
max_cache_size: Maximum size of in-memory spatial cache of MapViewer.
Size must be specified in megabytes (MB).
report_stats: If you would like to see periodic output of cache
statistics, set this attribute to true. The default
is false.
-->
<!--
<spatial_data_cache max_cache_size="64"
report_stats="false"
/>
-->
<!-- ****************************************************************** -->
<!-- ******************** Custom 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" />
-->
<!-- ****************************************************************** -->
<!-- ****************** Custom WMS Capabilities Info ****************** -->
<!-- ****************************************************************** -->
<!-- Uncomment and modify the following tag if you want MapViewer to
use the following information in its getCapabilities response.
Note: all attributes and elements of <wms_config> are optional.
-->
<!--
<wms_config host="www.my_corp.com" port="80">
<title>
WMS 1.1 interface for Oracle Application Server 10g MapViewer
</title>
<abstract>
This WMS service is provided through Oracle MapViewer.
</abstract>
<keyword_list>
<keyword>bird</keyword>
<keyword>roadrunner</keyword>
<keyword>ambush</keyword>
</keyword_list>
<sdo_epsg_mapfile>
../config/epsg_srids.properties
</sdo_epsg_mapfile>
</wms_config>
-->
<!-- ****************************************************************** -->
<!-- **************** Custom Non-Spatial Data Provider **************** -->
<!-- ****************************************************************** -->
<!-- Uncomment and add as many custom non-spatial data provider as
needed here, each in its own <ns_data_provider> element.
You must provide the id and full class name here. Optionally you
can also specify any number of global parameters, which MapViewer
will pass to the data provider implementation during initialization.
The name and value of each parameter is interpreted only by the
implementation.
-->
<!-- this is the default data provider that comes with MapViewer; please
refer to the MapViewer User's Guide for instructions on how to use it.
<ns_data_provider
id="defaultNSDP"
class="oracle.sdovis.NSDataProviderDefault"
/>
-->
<!-- this is a sample NS data provider with prameters:
<ns_data_provider
id="myProvider1" class="com.mycorp.bi.NSDataProviderImpl" >
<parameters>
<parameter name="myparam1" value="value1" />
<parameter name="p2" value="v2" />
</parameters>
</ns_data_provider>
-->
<!-- ****************************************************************** -->
<!-- ******************* Map Cache Server Setting ******************* -->
<!-- ****************************************************************** -->
<!-- Uncomment and modify the following to customize the map cache server.
<cache_storage> specifies the default root directory under which the
cached tile images are to be stored if the cache instance configuration
does not specify the root directory for the cache instance. If the
default root directory is not set or not valid, the default root
direcotry will be set to be $MAPVIEWER_HOME/web/mapcache
default_root_path: The default root directory under which the cached
tile images are stored.
<logging> specifies the logging options for map cache server.
-->
<!--
<map_cache_server>
<cache_storage default_root_path="/scratch/mapcachetest/"/>
<logging log_level="finest" log_thread_name="false" log_time="true">
<log_output name="System.err"/>
<log_output name="../log/mapcacheserver.log"/>
</logging>
</map_cache_server>
-->
<!-- ****************************************************************** -->
<!-- ******************** Predefined Data Sources ******************** -->
<!-- ****************************************************************** -->
<!-- Uncomment and modify the following to predefine one or more data
sources.
Note: You must precede the jdbc_password value with a '!'
(exclamation point), so that when 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.
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.
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)
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 7 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.
Sometimes the MapViewer server needs to make HTTP connections to external Web servers, such as to obtain a background image through a URL or to contact an external WMS server to fetch its map images. In such cases, if there is a firewall between the MapViewer server and the target Web server, you may need to specify the HTTP proxy information to MapViewer so that it will not be blocked by the firewall. The following example specifies Web proxy information:
<web_proxy host="www-proxy.mycorp.com" port="80" />
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.2.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.
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.
You can use the <security_config> element to specify whether MapViewer should reject <info_request> elements in requests. An <info_request> element is a type of request from a client that asks MapViewer to execute a simple SQL statement and return the result rows in plain text or XML format. This request is often used by MapViewer applications written in JSP to identify features displayed on a map, or to run simple spatial search queries.
However, if the MapViewer data source information is exposed, malicious attackers might be able to abuse this capability and obtain sensitive information. To prevent this from happening, you can make sure MapViewer always connects to a database schema that has very limited access rights and hosts only non-sensitive information, and you can also reject all <info_request> requests by specifying the <security_config> element as follows:
<security_config> <disable_direct_info_request> true </disable_direct_info_request> </security_config>
Note, however, that this setting affects some Mapviewer features. For example, the identify() method of the MapViewer Java API will no longer work, and applications will need to implement their own identify() method through other means.
MapViewer can display images stored in a database BLOB through its image theme capability. When the image data stored in the BLOB is in a format unknown to MapViewer, such as ECW, you can register a custom image renderer so that MapViewer can use it to display such images. For information about creating and registering a custom image renderer, see Appendix C.
To s[pecify a custom image renderer, use the <custom_image_renderer> element, as shown in the following example:
<custom_image_renderer image_format="ECW"
impl_class="com.my_corp.image.ECWRenderer" />
The image_format attribute specifies the image format name with which this custom image renderer should be associated.
The impl_class attribute specifies the name of the class that implements the custom image renderer.
MapViewer can be used as an Open Geospatial Consortium WMS (Web Map Server) 1.1.1 compliant server. As such, a WMS client can send MapViewer the GetCapabilities request. In response, MapViewer will send back the list of themes that it hosts and other important information, such as the data provider's name and a list of keywords, that might of interest to the requesting client.
You can use the <wms_config> element to customize the descriptive information sent back to the client as part of the GetCapabilities response, as shown in the following example:
<wms_config>
<title>
WMS 1.1 interface for Oracle Application Server 10g MapViewer
</title>
<abstract>
This WMS service is provided through Oracle MapViewer.
</abstract>
<keyword_list>
<keyword>bird</keyword>
<keyword>roadrunner</keyword>
<keyword>ambush</keyword>
</keyword_list>
<sdo_epsg_mapfile>
../config/epsg_srids.properties
</sdo_epsg_mapfile>
</wms_config>
The host attribute specifies the host part of the service request URL that the client should use for future WMS requests made to this MapViewer server.
The port attribute specifies the port part of the service request URL that the client should use for future WMS requests made to this MapViewer server.
The <title> element specifies the service title to be included as part of the response.
The <abstract> element specifies the abstract to be included as part of the response.
The <keyword_list> element specifies a list of keywords that best describe the types of layers served by this MapViewer server.
The <sdo_epsg_mapfile> element specifies a text file that defines mappings from Oracle Spatial (SDO) SRID values to the corresponding EPSG SRID values that are typically used in most WMS requests and responses. For information about this mapping file, see Section D.1.3.
When generating thematic map layers, MapViewer can dynamically join nonspatial attribute data (such as sales for each region) that originates from an external source with the base geometries (boundaries of all the regions) that are stored in the database. For information about thematic mapping using external attribute data from nonspatial data providers, see Section 2.3.3.1.
To register a nonspatial data provider, use the <ns_data_provider> element, as shown in the following example:
<ns_data_provider id="testProvider"
class="com.mycorp.GetSalesData" >
<parameters>
<parameter name="bi_database" value="stadb32.mycorp.com" />
<parameter name="sid" value="bidata" />
</parameters>
</ns_data_provider>
The id attribute uniquely identifies a nonspatial data provider. Use this id value in any map request that involves the provider.
The class attribute specifies the name of the class that implements the nonspatial data provider.
The <parameters> element specifies a set of initialization parameters that are used by the nonspatial data provider during its initialization process.
The Oracle Maps feature of MapViewer can pre-generate base map image tiles and cache them through the map cache server. You can use the <map_cache_server> element to provide configuration information to the map cache server, such as default location for map tile file storage, and logging information, as shown in the following example:
<map_cache_server>
<cache_storage default_root_path="/scratch/mapcache/" />
<logging log_level="finest" log_thread_name="false" log_time="true">
<log_output name="System.err"/>
<log_output name="../log/mapcacheserver.log"/>
</logging>
</map_cache_server>
The <cache_storage> element specifies the default root directory where all map image tiles generated by this MapViewer server will be stored.
The <logging> element specifies logging information specific to the map cache server.
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"
allow_jdbc_theme_based_foi="true"
/>
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.
The allow_jdbc_theme_based_foi attribute lets you specify whether to allow JDBC theme-based FOI requests to be performed against this data source. A JDBC theme-based FOI request is based on a dynamic SQL query constructed by the JavaScript client application.
By default, such FOI requests are not allowed unless you set this attribute to true. Due to the potential security threat, JDBC theme-based FOI requests should be used with caution. You should only allow JDBC theme-based FOI requests on database connections that are granted very low privilege and contain only data that you want to expose. See Section 8.3.1.3 for more information about JDBC theme-based FOI requests
Besides knowing how to configure MapViewer, you should also know how to perform other important administrative tasks using the MapViewer administration page. To log in to this page, see the instructions in Section 1.5.1.
The tasks you can do as a MapViewer administrator include the following:
Editing the configuration file
Click Manage MapViewer, then Configuration.
Creating dynamic data sources
Click Manage MapViewer, then Datasources. Enter the appropriate parameters, then click Submit.
Refreshing the list of data sources
Click Manage MapViewer, then Datasources. Click Refresh.
Clearing cached definitions of MapViewer styles, themes, and base maps
Click Manage MapViewer, then Datasources. Select the data source, then click Purge Cached Metadata.
Clearing cached geometry data for predefined themes
Click Manage MapViewer, then Geometry Cache. Under Purge Cached Geometries, select the data source and theme, and click Submit.
Creating map cache instances for Oracle Maps
Click Manage Map Caches, then Create. Select Internal or External for the map source type, and click Continue.
Internal map source: Enter the map cache name, then select the data source and base map. Also define parameters for cache storage (where tiles will be stored), zoom levels, minimum and maximum scale, spatial reference ID (SRID), data bounding box (MBR), and tile size and format. Click Submit to create the map cache instance. You can also define the map cache properties in XML by clicking XML.
External map source: Enter the map cache name, then select the data source. To provide access to the external source, define parameters such as the map service URL, the request method (GET or POST), the proxy information (if needed), the java adapter class name and its location on the server, and additional adapter properties. Also define parameters for cache storage (where tiles will be stored), zoom levels, minimum and maximum scale, spatial reference ID (SRID), data bounding box (MBR), and tile size and format. Click Submit to create the map cache instance. You can also define the map cache properties in XML by clicking XML.
Managing map cache instances for Oracle Maps
Click Manage Map Caches, then Manage. Then do any of the following:
To refresh map caches, click Refresh.
To edit a map cache instance, under Existing Map Cache Instances, select the data source. At the cache level, you can delete the cache, view cache details, and place the cache offline or online. At the tile level, you can perform operations such as clearing, prefetching, and refreshing the tiles, specifying the zoom level, and specifying the bounding box.
To check the status of a request, enter the request ID and click Submit.
|
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.
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.
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.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.
