Deprecated Feature: MapViewer JSP Library:
The MapViewer JSP library is deprecated, and will not be included in future releases of the documentation.Instead, you are encouraged to use the MapViewer Java API, which is more comprehensive and up to date. Moreover, if you prefer to use tags, consider using the GeoMap tags in the JDeveloper Application Development Framework (ADF).
This chapter explains how to submit requests to MapViewer using JavaServer Pages (JSP) tags in an HTML file. Through an XML-like syntax, the JSP tags provide a set of important (but not complete) MapViewer capabilities, such as setting up a map request, zooming, and panning, as well as identifying nonspatial attributes of user-clicked features.
Note:
The MapViewer JSP tag library will not work with Oracle9iAS Release 9.0.2 or the standalone OC4J Release 9.0.2. The minimum version required is Oracle9iAS Release 9.0.3 or the standalone OC4J Release 9.0.3.You can develop a location-based application by using any of the following approaches:
Using the XML API (see Chapter 3)
Using the JavaBean-based API (see Chapter 4)
Using JSP files that contain XML or HTML tags, or both, and that include custom Oracle-supplied JSP tags (described in this chapter)
Creating JSP files is often easier and more convenient than using the XML or JavaBean-based API, although the latter two approaches give you greater flexibility and control over the program logic. However, you can include calls to the Java API methods within a JavaServer Page, as is done with the call to the getMapTitle method in Example 5-1 in Section 5.3.
All MapViewer JSP tags in the same session scope share access to a single MapViewer bean.
This chapter contains the following major sections:
Before you can use MapViewer JSP tags, you must perform one or two steps, depending on whether or not the Web application that uses the tags will be deployed in the same OC4J instance that is running MapViewer.
If the Web application will be deployed in the same OC4J instance that is running MapViewer, skip this step and go to Step 2.
If the Web application will be deployed in a separate OC4J instance, you must copy the mvclient.jar file (located in the $MAPVIEWER/web/WEB-INF/lib directory) and the mvtaglib.tld file (located in the $MAPVIEWER/web/WEB-INF directory) to that OC4J instance's application deployment directory. Then you must define a <taglib> element in your application's web.xml file, as shown in the following example:
<taglib>
<taglib-uri>
http://xmlns.oracle.com/spatial/mvtaglib
</taglib-uri>
<taglib-location>
/WEB-INF/mvtaglib.tld
</taglib-location>
</taglib>
Import the tag library (as you must do with any JSP page that uses custom tags), by using the taglib directive at the top of the JSP page and before any other MapViewer tags. For example:
<%@ taglib uri="http://xmlns.oracle.com/spatial/mvtaglib"
prefix="mv" %>
The taglib directive has two parameters:
uri is the unique name that identifies the MapViewer tag library, and its value must be http://xmlns.oracle.com/spatial/mvtaglib, because it is so defined in the MapViewer web.xml initialization file.
prefix identifies the prefix for tags on the page that belong to the MapViewer tag library. Although you can use any prefix you want as long as it is unique in the JSP page, mv is the recommended prefix for MapViewer, and it is used in examples in this guide.
The following example shows the mv prefix used with the setParam tag:
<mv:setParam title="Hello World!" bgcolor="#ffffff" width="500" height="375" antialiasing="true"/>
The tags enable you to perform several kinds of MapViewer operations:
To create the MapViewer bean and place it in the current session, use the init tag, which must come before any other MapViewer JSP tags.
To set parameters for the map display and optionally a base map, use the setParam tag.
To add themes and a legend, use the addPredefinedTheme, addJDBCTheme, importBaseMap, and makeLegend tags.
To get information, use the getParam, getMapURL, and identify tags.
To submit the map request for processing, use the run tag.
This section provides detailed information about the Oracle-supplied JSP tags that you can use to communicate with MapViewer. Table 5-1 lists each tag and briefly describes the information specified by the tag.
Table 5-1 JSP Tags for MapViewer
| Tag Name | Explanation |
|---|---|
|
Creates the MapViewer bean and places it in the current session. Must come before any other MapViewer JSP tags. |
|
|
Specifies one or more parameters for the current map request. |
|
|
Adds a predefined theme to the current map request. |
|
|
Adds a dynamically defined theme to the map request. |
|
|
Adds the predefined themes that are in the specified base map to the current map request. |
|
|
Creates a legend (map inset illustration) drawn on top of the generated map. |
|
|
Gets the value associated with a specified parameter for the current map request. |
|
|
Gets the HTTP URL for the currently available map image, as generated by the MapViewer service. |
|
|
Gets nonspatial attribute (column) values associated with spatial features that interact with a specified point or rectangle on the map display, and optionally uses a marker style to identify the point or rectangle. |
|
|
Submits the current map request to the MapViewer service for processing. The processing can be to zoom in or out, to recenter the map, or to perform a combination of these operations. |
Except where noted, you can use JSP expressions to set tag attribute values at run time, using the following format:
<mv:tag attribute="<%= jspExpression %>" >
The following sections (in alphabetical order by tag name) provide reference information for all parameters available for each tag: the parameter name, a description, and whether or not the parameter is required. If a parameter is required, it must be included with the tag. If a parameter is not required and you omit it, a default value is used.
Short examples are provided in the reference sections for JSP tags, and a more comprehensive example is provided in Section 5.3.
The addJDBCTheme tag adds a dynamically defined theme to the map request. (It performs the same operation as the <jdbc_query> element, which is described in Section 3.2.9.)
Table 5-2 lists the addJDBCTheme tag parameters.
Table 5-2 addJDBCTheme Tag Parameters
| Parameter Name | Description | Required |
|---|---|---|
|
|
Name for the dynamically defined theme. Must be unique among all themes already added to the associated MapViewer bean. |
Yes |
|
|
The value to which the display must be zoomed in for the theme to be displayed, as explained in Section 2.4.1. If |
No |
|
|
The value beyond which the display must be zoomed in for the theme not to be displayed, as explained in Section 2.4.1. If |
No |
|
|
Column of type SDO_GEOMETRY containing geometry objects for the map display |
Yes |
|
|
Coordinate system (SDO_SRID value) of the data to be rendered. If you do not specify this parameter, a null coordinate system is assumed. |
No |
|
|
Name of the data source instance that contains information for connecting to the database |
YesFoot 1 |
|
|
Host name for connecting to the database |
YesFootref 1 |
|
|
Port name for connecting to the database |
YesFootref 1 |
|
|
SID for connecting to the database |
YesFootref 1 |
|
|
User name for connecting to the database |
YesFootref 1 |
|
|
Password for connecting to the database |
YesFootref 1 |
|
|
The Oracle JDBC driver ( |
No |
|
|
If set to |
No |
|
|
Name of the style to be used to render the spatial data retrieved for this theme. For point features the default is a red cross rotated 45 degrees, for lines and curves it is a black line 1 pixel wide, and for polygons it is a black border with a semitransparent dark gray interior. |
No |
|
|
Name of the text style to be used to draw labeling text on the spatial feature for this theme. If you specify |
No |
|
|
The column in the SELECT list of the supplied query that contains the labeling text for each feature (row). If |
No |
Footnote 1 You must specify either datasource or the combination of jdbc_host, jdbc_port, jdbc_sid, jdbc_user, and jdbc_password.
The following example creates a new dynamic theme named bigCities, to be executed using the mvdemo data source and specifying the LOCATION column as containing spatial data. Note that the greater-than (>) character in the WHERE clause is valid here.
<mv:addJDBCTheme name="bigCities" datasource="mvdemo"
spatial_column="location">
SELECT location, name FROM cities WHERE pop90 > 450000
</mv:addJDBCTheme>
The addPredefinedTheme tag adds a predefined theme to the current map request. (It performs the same operation as the <theme> element, which is described in Section 3.2.20.) The predefined theme is added at the end of the theme list maintained in the associated MapViewer bean.
Table 5-3 lists the addPredefinedTheme tag parameters.
Table 5-3 addPredefinedTheme Tag Parameters
| Parameter Name | Description | Required |
|---|---|---|
|
|
Name of the predefined theme to be added to the current map request. This theme must exist in the USER_SDO_THEMES view of the data source used by the associated MapViewer bean. |
Yes |
|
|
Name of the data source from which the theme will be loaded. If you do not specify this parameter, the default data source for the map request is used. |
No |
|
|
The value to which the display must be zoomed in for the theme to be displayed, as explained in Section 2.4.1. If |
No |
|
|
The value beyond which the display must be zoomed in for the theme not to be displayed, as explained in Section 2.4.1. If |
No |
The following example adds the theme named THEME_DEMO_CITIES to the current Map request:
<mv:addPredefinedTheme name="THEME_DEMO_CITIES"/>
The getMapURL tag gets the HTTP URL (uniform resource locator) for the currently available map image, as generated by the MapViewer service. This map image URL is kept in the associated MapViewer bean, and it does not change until after the run tag is used.
The getMapURL tag has no parameters.
The following example displays the currently available map image, using the getMapURL tag in specifying the source (SRC keyword value) for the image:
<IMG SRC="<mv:getMapURL/>" ALIGN="top">
The getParam tag gets the value associated with a specified parameter for the current map request.
Table 5-4 lists the getParam tag parameter.
Table 5-4 getParam Tag Parameter
| Parameter Name | Description | Required |
|---|---|---|
|
|
Name of the parameter whose value is to be retrieved. It must be one of the valid parameter names for the setParam tag. The parameter names are case-sensitive. (This attribute must have a literal value; it cannot take a JSP expression value.) |
Yes |
The following example displays the value of the title parameter for the current map request:
<P> The current map title is: <mv:getParam name="title"/> </P>
The identify tag gets nonspatial attribute (column) values associated with spatial features that interact with a specified point or rectangle on the map display, and it optionally uses a marker style to identify the point or rectangle. For example, if the user clicks on the map and you capture the X and Y coordinate values for the mouse pointer when the click occurs, you can retrieve values of nonspatial columns associated with spatial geometries that interact with the point. For example, if the user clicks on a point in Chicago, your application might display the city name, state abbreviation, and population of Chicago, and it might also display a "city" marker on the map near where the click occurred.
The attributes are returned in a String[][] array of string arrays, which is exposed by this tag as a scripting variable.
The list of nonspatial columns to fetch must be provided in the tag body, in a comma-delimited list, which the MapViewer bean uses to construct a SELECT list for its queries.
You can optionally associate a highlighting marker with each feature that is identified by using the style attribute and specifying a marker style. To display a new map that includes the highlighting markers, use the getMapURL tag.
Table 5-5 lists the identify tag parameters.
Table 5-5 identify Tag Parameters
| Parameter Name | Description | Required |
|---|---|---|
|
|
Name for the scripting variable through which the returned nonspatial attribute values will be exposed. The first array contains the column names. (This attribute must have a literal value; it cannot take a JSP expression value.) |
Yes |
|
|
Name of the MapViewer data source from which to retrieve the nonspatial information. |
No |
|
|
Name of the table containing the column identified in |
Yes |
|
|
Column of type SDO_GEOMETRY containing geometry objects to be checked for spatial interaction with the specified point or rectangle. (This attribute must have a literal value; it cannot take a JSP expression value.) |
Yes |
|
|
Coordinate system (SDO_SRID value) of the data in |
No |
|
|
The X ordinate value of the point; or the X ordinate value of the lower-left corner of the rectangle if |
Yes |
|
|
The Y ordinate value of the point; or the Y ordinate value of the lower-left corner of the rectangle if |
Yes |
|
|
The X ordinate value of the upper-right corner of the rectangle. |
No |
|
|
The Y ordinate value of the upper-right corner of the rectangle. |
No |
|
|
Name of the marker style to be used to draw a marker on features that interact with the specified point or rectangle. To display a new map that includes the highlighting markers, use the getMapURL tag. |
No |
The following example creates an HTML table that contains a heading row and one row for each city that has any spatial interaction with a specified point (presumably, the city where the user clicked). Each row contains the following nonspatial data: city name, population, and state abbreviation. The String[][] array of string arrays that holds the nonspatial information about the associated city or cities is exposed through the scripting variable named attrs. The scriptlet after the tag loops through the array and outputs the HTML table (which in this case will contain information about one city).
<mv:identify id="attrs" style="M.CYAN PIN"
table="cities" spatial_column="location"
x="100" y="200">
City, Pop90 Population, State_abrv State
</mv:identify>
<%
if(attrs!=null && attrs.length>0)
{
out.print("<CENTER> <TABLE border=\"1\">\n");
for(int i=0; i<attrs.length; i++)
{
if(i==0) out.print("<TR BGCOLOR=\"#FFFF00\">");
else out.print("<TR>\n");
String[] row = attrs[i];
for(int k=0; k<row.length; k++)
out.print("<TD>"+row[k]+"</TD>");
out.print("</TR>\n");
}
out.print("</TABLE></CENTER>");
}
%>
The importBaseMap tag adds the predefined themes that are in the specified base map to the current map request. (This has the same effect as using the setParam tag with the basemap attribute.)
Table 5-6 lists the importBaseMap tag parameter.
Table 5-6 importBaseMap Tag Parameter
| Parameter Name | Description | Required |
|---|---|---|
|
|
Name of the base map whose predefined themes are to be added at the end of the theme list for the current map request. This base map must exist in the USER_SDO_MAPS view of the data source used by the associated MapViewer bean. |
Yes |
The following example adds the predefined themes in the base map named demo_map at the end of the theme list for the current map request:
<mv:importBaseMap name="demo_map"/>
The init tag creates the MapViewer bean and places it in the current session. This bean is then shared by all other MapViewer JSP tags in the same session. The init tag must come before any other MapViewer JSP tags.
Table 5-7 lists the init tag parameters.
| Parameter Name | Description | Required |
|---|---|---|
|
|
The uniform resource locator (URL) of the MapViewer service. It must be in the form |
Yes |
|
|
Name of the MapViewer data source to be used when requesting maps and retrieving mapping data. If you have not already created the data source, you must do so before using the |
Yes |
|
|
Name that can be used to refer to the MapViewer bean created by this tag. (This attribute must have a literal value; it cannot take a JSP expression value.) |
Yes |
The following example creates a data source named mvdemo with an id value of mvHandle:
<mv:init url="http://mycompany.com:8888/mapviewer/omserver"
datasource="mvdemo" id="mvHandle"/>
The makeLegend tag accepts a user-supplied XML legend specification and creates a standalone map legend image. The legend image is generated by the MapViewer service, and a URL for that image is returned to the associated MapViewer bean. This tag exposes the URL as a scripting variable.
The body of the tag must contain a <legend> element. See Section 3.2.11 for detailed information about the <legend> element and its attributes.
Table 5-8 lists the makeLegend tag parameters.
Table 5-8 makeLegend Tag Parameters
| Parameter Name | Description | Required |
|---|---|---|
|
|
Name for the scripting variable that can be used to refer to the URL of the generated legend image. (This attribute must have a literal value; it cannot take a JSP expression value.) |
Yes |
|
|
Name of the MapViewer data source from which to retrieve information about styles specified in the legend request |
No |
|
|
Format of the legend image to be created on the server. If specified, must be |
No |
The following example creates a single-column legend with the id of myLegend, and it displays the legend image.
<mv:makeLegend id="myLegend">
<legend bgstyle="fill:#ffffff;stroke:#ff0000" profile="MEDIUM">
<column>
<entry text="Legend:" is_title="true"/>
<entry style="M.STAR" text="center point"/>
<entry style="M.CITY HALL 3" text="cities"/>
<entry is_separator="true"/>
<entry style="C.ROSY BROWN STROKE" text="state boundary"/>
<entry style="L.PH" text="interstate highway"/>
<entry text="County population density:"/>
<entry style="V.COUNTY_POP_DENSITY" tab="1"/>
</column>
</legend>
</mv:makeLegend>
<P> Here is the map legend: <IMG SRC="<%=myLegend%>"> </P>
The run tag submits the current map request to the MapViewer service for processing. The processing can be to zoom in or out, to recenter the map, or to perform a combination of these operations.
The run tag does not output anything to the JSP page. To display the map image that MapViewer generates as a result of the run tag, you must use the getMapURL tag.
Table 5-9 lists the run tag parameters.
| Parameter Name | Description | Required |
|---|---|---|
|
|
One of the following values to indicate the map navigation action to be taken: For If you do not specify an action, the map request is submitted for processing with no zooming or recentering, and with cropping only if |
No |
|
|
The X ordinate value of the point for recentering the map, or the X ordinate value of the lower-left corner of the rectangular area to which to crop the resulting image if |
No |
|
|
The Y ordinate value of the point for recentering the map, or the Y ordinate value of the lower-left corner of the rectangular area to which to crop the resulting image if |
No |
|
|
The X ordinate value of the upper-right corner of the rectangular area to which to crop the resulting image |
No |
|
|
The Y ordinate value of the upper-right corner of the rectangular area to which to crop the resulting image |
No |
|
|
Zoom factor: a number by which the current map size is multiplied (for |
No |
The following example requests a zooming in on the map display (with the default zoom factor of 2), and recentering of the map display at coordinates (100, 250) in the device space.
<mv:run action="zoomin" x="100" y="250"/>
The setParam tag specifies one or more parameters for the current map request. You can set all desired parameters at one time with a single setParam tag, or you can set different parameters at different times with multiple setParam tags. Most of the parameters have the same names and functions as the attributes of the <map_request> root element, which is described in Section 3.2.1.1. The parameter names are case-sensitive.
Table 5-10 lists the setParam tag parameters.
Table 5-10 setParam Tag Parameters
| Parameter Name | Description | Required |
|---|---|---|
|
When its value is |
No |
|
|
Base map whose predefined themes are to be rendered by MapViewer. The definition of a base map is stored in the user's USER_SDO_MAPS view, as described in Section 2.9.1. Use this parameter if you will always need a background map on which to plot your own themes and geometry features. |
No |
|
|
The background color in the resulting map image. The default is water-blue (RGB value #A6CAF0). It must be specified as a hexadecimal value. |
No |
|
|
The background image (GIF or JPEG format only) in the resulting map image. The image is retrieved at run time when a map request is being processed, and it is rendered before any other map features, except that any |
No |
|
|
X ordinate of the map center in the data coordinate space |
No |
|
|
Y ordinate of the map center in the data coordinate space |
No |
|
|
The height (in device units) of the resulting map image |
No |
|
|
When its value is |
No |
|
|
|
Vertical span of the map in the data coordinate space |
No |
|
The map title to be displayed on the top of the resulting map image |
No |
|
|
The width (in device units) of the resulting map image |
No |
The following example uses two setParam tags. The first setParam tag sets the background color, width, height, and title for the map. The second setParam tag sets the center point and vertical span for the map.
<mv:setParam bgcolor="#ff0000" width="800" height="600"
title="My Map!"/>
<mv:setParam centerX="-122.35" centerY="37.85" size="1.5"/>
This section presents an example of using JSP code to perform several MapViewer operations.
Example 5-1 initializes a MapViewer bean, sets up map request parameters, issues a request, and displays the resulting map image. It also obtains the associated MapViewer bean and places it in a scripting variable (myHandle), which is then accessed directly in the statement:
Displaying map: <B> <%=myHandle.getMapTitle()%> </B>
Example 5-1 MapViewer Operations Using JSP Tags
<%@ page contentType="text/html" %>
<%@ page session="true" %>
<%@ page import="oracle.lbs.mapclient.MapViewer" %>
<%@ taglib uri="http://xmlns.oracle.com/spatial/mvtaglib"
prefix="mv" %>
<HTML>
<BODY>
Initializing client MapViewer bean. Save the bean in the session
using key "mvHandle"....<P>
<mv:init url="http://my_corp.com:8888/mapviewer/omserver"
datasource="mvdemo" id="mvHandle"/>
Setting MapViewer parameters...<P>
<mv:setParam title="Hello World!" bgcolor="#ffffff" width="500" height="375" antialiasing="true"/>
Adding themes from a base map...<P>
<mv:importBaseMap name="density_map"/>
Setting initial map center and size...<P>
<mv:setParam centerX="-122.0" centerY="37.8" size="1.5"/>
Issuing a map request... <P>
<mv:run/>
<%
// Place the MapViewer bean in a Java variable.
MapViewer myHandle = (MapViewer) session.getAttribute("mvHandle");
%>
Displaying map: <B> <%=myHandle.getMapTitle()%> </B>
<IMG SRC="<mv:getMapURL/>" ALIGN="top"/>
</BODY>
</HTML>