Oracle® Application Server 10g MapViewer User's Guide 10g (9.0.4) Part Number B10559-01 |
|
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.
MapViewer includes the following main components:
The rendering engine connects to the Oracle database through Java Database Connectivity (JDBC). It also loads the map metadata (such as map definitions, styling rules, and symbology) from the database, and applies it to the retrieved spatial data.
The XML API provides high-level application developers with a convenient interface for submitting a map request to 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, regardless of whether or not the client requests a map or some MapViewer administrative action.
For a map request:
For a MapViewer administrative request:
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:
To get started using MapViewer, follow these steps:
To use MapViewer, you must have the following Java packages and Oracle products, with the release number listed or a later release:
http://otn.oracle.com
)
MapViewer also supports the headless AWT mechanism in JDK 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.
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 successfully installed Oracle Application Server, you can deploy the MapViewer application using the Oracle Enterprise Manager interface.
Start Oracle Enterprise Manager, navigate to the OC4J instance where you want to deploy MapViewer, and select Deploy Application to start a wizard that takes you through the deployment steps. Figure 1-3 shows part of the introductory page for this wizard.
For J2EE Application, specify the complete path for the mapviewer.ear
file.
For Application, specify: mapviewer
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
file with MapViewer. This section presents these steps.
sdovis.jar
file, which is in the $ORACLE_HOME
/lbs/lib
directory.
For example: D:\oracle\ora_Bl\lbs\lib\sdovis.jar
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:
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.
To start MapViewer automatically each time OC4J is restarted, edit the OC4J configuration files, as follows.
$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>
$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:
Auto-unpacking D:\Oracle\Ora817\lbs\mapviewer.ear... done. Auto-unpacking D:\Oracle\Ora817\lbs\mapviewer\web.war... done. Installed mapviewer... [oracle.spatial.mapserver.core.MapperPool, WARN] destroying all mapper instances. [oracle.spatial.mapserver.oms, INFO] *** Oracle Spatial MapViewer is successfully started. *** [oracle.spatial.mapserver.core.MapRecycleThread, Tue Oct 23 15:46:07 EDT 2001,#Thread-3, INFO] cleansing old maps
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 a later release, 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 a previous release, 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(ServletRequestDispatche r.java:501) at com.evermind.server.http.ServletRequestDispatcher.forwardInternal(ServletRequest Dispatcher.java:170) at com.evermind.server.http.HttpRequestHandler.processRequest(HttpRequestHandler.ja va: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 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/conf
directory. After you modify this file, you must restart OC4J to have the changes take effect.
The MapViewer configuration file defines the following information in XML format:
<logging>
element (see Section 1.5.1)
<save_images_at>
element (see Section 1.5.2)
<ip_monitor>
element (see Section 1.5.3)
<web_proxy>
element (see Section 1.5.4)
<global_map_config>
element (see Section 1.5.5)
<spatial_data_cache>
element (see Section 1.5.6)
<custom_image_renderer>
element (see Appendix B)
<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.
<?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" Image 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 emptry 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 2003, 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 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). max_disk_cache_size: Maximum size of disk-based cache for MapViewer. Size must be specified in megabytes (MB). disk_cache_path: Temporary disk path where the spooled objects will be located. Default is the "../cache" directory. --> <!-- <spatial_data_cache max_cache_size="64" max_disk_cache_size="512" disk_cache_path="../cache" /> --> <!-- ****************************************************************** --> <!-- ******************** 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 runtime 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:
log_level
attribute controls the levels of information that are recorded in the log, which in turn affects 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.
log_thread_name
attribute controls whether or not to include the name of the thread that encountered and logged the event.
log_time
attribute controls whether or not the current time is included when a logging event occurs.
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.2) 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:
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
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
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.
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.
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.
<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:
<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.
Syntax notes for the <ip_monitor>
element:
<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.
<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.
<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:
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:
text
attribute specifies the title string.
font
attribute specifies a font. The font must exist on the system where MapViewer is running.
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:
text
attribute specifies the note string.
font
attribute specifies a font. The font must exist on the system where MapViewer is running.
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:
image_path
attribute must specify a valid file path name, or a URL starting with http://
.
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.10. 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 memory cache and disk cache that MapViewer uses for spatial geometry objects by using the <spatial_data_cache>
element. For example:
<spatial_data_cache max_cache_size="64" max_disk_cache_size="512" disk_cache_path="/var/tmp" />
You can specify the following information as attributes of the <spatial_data_cache>
element:
max_cache_size
attribute specifies the maximum number of megabytes (MB) of in-memory cache.
Default value: 64
max_disk_cache_size
attribute specifies the maximum number of megabytes (MB) of disk cache.
Default value: 512
disk_cache_path
attribute specifies the temporary disk path where the spooled cache will be located.
Default value: location specified for the Java environment variable java.io.tmpdir
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 need to specify the max_cache_size
attribute value as 0
(zero).
Every map request must have a name
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" />
You can specify the following information as attributes of the <map_data_source>
element:
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.
jdbc_host
, jdbc_sid
, jdbc_port
, and jdbc_user
parameters specify the database connection information and the database user name.
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.
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.
number_of_mappers
attribute identifies the number of map renderers to be created (that is, the number of requests that MapViewer can process at the same time) for this data source. Each map renderer typically uses from 5 MB to 30 MB of memory, depending on the volume of spatial data retrieved and processed during any map generation. 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. The maximum number of mappers for a single data source is 64.
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://otn.oracle.com
), you have a file named mvdemo.zip
, which includes an Oracle 8.1.7 export file mvdemo.dmp
. Follow these steps:
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
copymeta.sql
(included in the mvdemo.zip
file) to set up the mapping metadata for the user SCOTT.
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:
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
<?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>
This page contains forms that you can use for a variety of other tasks, such as:
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.6.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-5 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.6.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.
|
![]() Copyright © 2001, 2003 Oracle Corporation. All Rights Reserved. |
|