Skip Headers
Oracle® Application Server MapViewer User's Guide
10g Release 2 (10.1.2)
B14036-02
  Go To Documentation Library
Home
Go To Product List
Solution Area
Go To Table Of Contents
Contents
Go To Index
Index

Previous
Previous
Next
Next
 

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:

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:

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.

  1. 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>
    
    
  2. 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:

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

YesFoot 1 

jdbc_host

Host name for connecting to the database

YesFootref 1

jdbc_port

Port name for connecting to the database

YesFootref 1

jdbc_sid

SID for connecting to the database

YesFootref 1

jdbc_user

User name for connecting to the database

YesFootref 1

jdbc_password

Password for connecting to the database

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

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>