5 OracleAS MapViewer JSP Tag Library

This chapter explains how to submit requests to OracleAS 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) OracleAS MapViewer capabilities, such as setting up a map request, zooming, and panning, as well as identifying nonspatial attributes of user-clicked features.

Note:

The OracleAS 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 OracleAS MapViewer JSP tags in the same session scope share access to a single OracleAS MapViewer bean.

This chapter contains the following major sections:

Section 5.1, "Using OracleAS MapViewer JSP Tags"
Section 5.2, "OracleAS MapViewer JSP Tag Reference Information"
Section 5.3, "JSP Example (Several Tags) for OracleAS MapViewer"

5.1 Using OracleAS MapViewer JSP Tags

Before you can use OracleAS 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 OracleAS MapViewer.

If the Web application will be deployed in the same OC4J instance that is running OracleAS 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 OracleAS 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 OracleAS MapViewer tag library, and its value must be http://xmlns.oracle.com/spatial/mvtaglib, because it is so defined in the OracleAS MapViewer web.xml initialization file.
- prefix identifies the prefix for tags on the page that belong to the OracleAS 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 OracleAS 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 OracleAS MapViewer operations:

To create the OracleAS MapViewer bean and place it in the current session, use the init tag, which must come before any other OracleAS 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.

5.2 OracleAS MapViewer JSP Tag Reference Information

This section provides detailed information about the Oracle-supplied JSP tags that you can use to communicate with OracleAS MapViewer. Table 5-1 lists each tag and briefly describes the information specified by the tag.

Table 5-1 JSP Tags for OracleAS MapViewer

Tag Name	Explanation
init	Creates the OracleAS MapViewer bean and places it in the current session. Must come before any other OracleAS MapViewer JSP tags.
setParam	Specifies one or more parameters for the current map request.
addPredefinedTheme	Adds a predefined theme to the current map request.
addJDBCTheme	Adds a dynamically defined theme to the map request.
importBaseMap	Adds the predefined themes that are in the specified base map to the current map request.
makeLegend	Creates a legend (map inset illustration) drawn on top of the generated map.
getParam	Gets the value associated with a specified parameter for the current map request.
getMapURL	Gets the HTTP URL for the currently available map image, as generated by the OracleAS MapViewer service.
identify	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.
run	Submits the current map request to the OracleAS 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.

5.2.1 addJDBCTheme

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`	Name for the dynamically defined theme. Must be unique among all themes already added to the associated OracleAS MapViewer bean.	Yes
`min_scale`	The value to which the display must be zoomed in for the theme to be displayed, as explained in Section 2.4.1. If `min_scale` and `max_scale` are not specified, the theme is displayed for all map scales, if possible given the display characteristics.	No
`max_scale`	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 `min_scale` and `max_scale` are not specified, the theme is displayed for all map scales, if possible given the display characteristics.	No
`spatial_column`	Column of type SDO_GEOMETRY containing geometry objects for the map display	Yes
`srid`	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
`datasource`	Name of the data source instance that contains information for connecting to the database	Yes^Foot 1
`jdbc_host`	Host name for connecting to the database	Yes^Footref 1
`jdbc_port`	Port name for connecting to the database	Yes^Footref 1
`jdbc_sid`	SID for connecting to the database	Yes^Footref 1
`jdbc_user`	User name for connecting to the database	Yes^Footref 1
`jdbc_password`	Password for connecting to the database	Yes^Footref 1
`jdbc_mode`	The Oracle JDBC driver (`thin` or `oci8`) to use to connect to the database. The default is `thin`.	No
`asis`	If set to `TRUE`, OracleAS MapViewer does not attempt to modify the supplied query string. If `FALSE` (the default), OracleAS MapViewer embeds the SQL query as a subquery of its spatial filter query. (For more information and an example, see Section 3.2.9.)	No
`render_style`	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
`label_style`	Name of the text style to be used to draw labeling text on the spatial feature for this theme. If you specify `label_style`, you must also specify `label_column`. If you do not specify `label_style`, no label is drawn for the spatial feature of this theme.	No
`label_column`	The column in the SELECT list of the supplied query that contains the labeling text for each feature (row). If `label_style` is not specified, any `label_column` value is ignored.	No

^Footnote 1You 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>

5.2.2 addPredefinedTheme

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.14.) The predefined theme is added at the end of the theme list maintained in the associated OracleAS MapViewer bean.

Table 5-3 lists the addPredefinedTheme tag parameters.

Table 5-3 addPredefinedTheme Tag Parameters

Parameter Name	Description	Required
`name`	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 OracleAS MapViewer bean.	Yes
`datasource`	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
`min_scale`	The value to which the display must be zoomed in for the theme to be displayed, as explained in Section 2.4.1. If `min_scale` and `max_scale` are not specified, the theme is displayed for all map scales, if possible given the display characteristics.	No
`max_scale`	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 `min_scale` and `max_scale` are not specified, the theme is displayed for all map scales, if possible given the display characteristics.	No

The following example adds the theme named THEME_DEMO_CITIES to the current Map request:

<mv:addPredefinedTheme name="THEME_DEMO_CITIES"/>

5.2.3 getMapURL

The getMapURL tag gets the HTTP URL (uniform resource locator) for the currently available map image, as generated by the OracleAS MapViewer service. This map image URL is kept in the associated OracleAS 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">

5.2.4 getParam

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`	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>

5.2.5 identify

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 OracleAS 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
`id`	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
`datasource`	Name of the OracleAS MapViewer data source from which to retrieve the nonspatial information.	No
`table`	Name of the table containing the column identified in `spatial_column`. (This attribute must have a literal value; it cannot take a JSP expression value.)	Yes
`spatial_column`	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
`srid`	Coordinate system (SDO_SRID value) of the data in `spatial_column`. If you do not specify this parameter, a null coordinate system is assumed.	No
`x`	The X ordinate value of the point; or the X ordinate value of the lower-left corner of the rectangle if `x2` and `y2` are specified.	Yes
`y`	The Y ordinate value of the point; or the Y ordinate value of the lower-left corner of the rectangle if `x2` and `y2` are specified.	Yes
`x2`	The X ordinate value of the upper-right corner of the rectangle.	No
`y2`	The Y ordinate value of the upper-right corner of the rectangle.	No
`style`	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>");
    }
%>

5.2.6 importBaseMap

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`	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 OracleAS 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"/>

5.2.7 init

The init tag creates the OracleAS MapViewer bean and places it in the current session. This bean is then shared by all other OracleAS MapViewer JSP tags in the same session. The init tag must come before any other OracleAS MapViewer JSP tags.

Table 5-7 lists the init tag parameters.

Table 5-7 init Tag Parameters

Parameter Name	Description	Required
`url`	The uniform resource locator (URL) of the OracleAS MapViewer service. It must be in the form `http://host:port/mapviewer/omserver`, where `host` and `port` identify the system name and port, respectively, on which Oracle Application Server or OC4J listens.	Yes
`datasource`	Name of the OracleAS 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 `init` tag. (For information about creating a data source, see Section 1.7.1.)	Yes
`id`	Name that can be used to refer to the OracleAS 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"/>

5.2.8 makeLegend

The makeLegend tag accepts a user-supplied XML legend specification and creates a standalone map legend image. The legend image is generated by the OracleAS MapViewer service, and a URL for that image is returned to the associated OracleAS 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
`id`	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
`datasource`	Name of the OracleAS MapViewer data source from which to retrieve information about styles specified in the legend request	No
`format`	Format of the legend image to be created on the server. If specified, must be `GIF_URL` (the default) or `PNG_URL`.	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>

5.2.9 run

The run tag submits the current map request to the OracleAS 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 OracleAS MapViewer generates as a result of the run tag, you must use the getMapURL tag.

Table 5-9 lists the run tag parameters.

Table 5-9 run Tag Parameters

Parameter Name	Description	Required
`action`	One of the following values to indicate the map navigation action to be taken: `zoomin` (zoom in), `zoomout` (zoom out), or `recenter` (recenter the map). For `zoomin` or `zoomout`, `factor` specifies the zoom factor; for all actions (including no specified action), `x` and `y` specify the new center point; for all actions (including no specified action), `x2` and `y2` specify (with `x` and `y`) the rectangular area to which to crop the resulting image. If you do not specify an action, the map request is submitted for processing with no zooming or recentering, and with cropping only if `x`, `y`, `x2`, and `y2` are specified.	No
`x`	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 `x2` and `y2` are specified	No
`y`	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 `x2` and `y2` are specified	No
`x2`	The X ordinate value of the upper-right corner of the rectangular area to which to crop the resulting image	No
`y2`	The Y ordinate value of the upper-right corner of the rectangular area to which to crop the resulting image	No
`factor`	Zoom factor: a number by which the current map size is multiplied (for `zoomin`) or divided (for `zoomout`). The default is 2. This parameter is ignored if `action` is not `zoomin` or `zoomout`.	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"/>

5.2.10 setParam

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
`antialiasing`	When its value is `TRUE`, OracleAS MapViewer renders the map image in an antialiased manner. This usually provides a map with better graphic quality, but it may take longer for the map to be generated. The default value is `FALSE` (for faster map generation).	No
`basemap`	Base map whose predefined themes are to be rendered by OracleAS MapViewer. The definition of a base map is stored in the user's USER_SDO_MAPS view, as described in Section 2.8.1. Use this parameter if you will always need a background map on which to plot your own themes and geometry features.	No
`bgcolor`	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
`bgimage`	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 `bgcolor` value is rendered before the background image.	No
`centerX`	X ordinate of the map center in the data coordinate space	No
`centerY`	Y ordinate of the map center in the data coordinate space	No
`height`	The height (in device units) of the resulting map image	No
`imagescaling`	When its value is `TRUE` (the default), OracleAS MapViewer attempts to scale the images to fit the current querying window and the generated map image size. When its value is `FALSE`, and if an image theme is included directly or indirectly (such as through a base map), the images from the image theme are displayed in their original resolution. This parameter has no effect when no image theme is involved in a map request.	No
`size`	Vertical span of the map in the data coordinate space	No
`title`	The map title to be displayed on the top of the resulting map image	No
`width`	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"/>

5.3 JSP Example (Several Tags) for OracleAS MapViewer

This section presents an example of using JSP code to perform several OracleAS MapViewer operations.

Example 5-1 initializes an OracleAS MapViewer bean, sets up map request parameters, issues a request, and displays the resulting map image. It also obtains the associated OracleAS 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 OracleAS 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 OracleAS 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 OracleAS 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 OracleAS 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>