4 OracleAS MapViewer JavaBean-Based API

This chapter describes the JavaBean-based OracleAS MapViewer API. This API exposes all capabilities of OracleAS MapViewer through a single JavaBean, oracle.lbs.mapclient.MapViewer. This bean is a lightweight client that handles all communications with the actual OracleAS MapViewer service running on the middle tier on behalf of a user making map requests.

All communications between the bean and the actual OracleAS MapViewer service follow a request/response model. Requests are always sent as XML documents to the service. Depending on the type and nature of a request, the response received by the bean is either an XML document or some binary data. However, using the OracleAS MapViewer bean is easier than manipulating XML documents for forming and sending OracleAS MapViewer requests, as well as for extracting information from the responses.

The bean delegates most of map data processing and rendering to the OracleAS MapViewer service. All the bean does is formulate user requests into valid OracleAS MapViewer XML requests and send them to an OracleAS MapViewer service for processing.

This chapter contains the following major sections:

Section 4.1, "Usage Model for the OracleAS MapViewer JavaBean-Based API"
Section 4.2, "Preparing to Use the OracleAS MapViewer JavaBean-Based API"
Section 4.3, "Using the OracleAS MapViewer Bean"

4.1 Usage Model for the OracleAS MapViewer JavaBean-Based API

The OracleAS MapViewer bean can be created and used in either server-side objects such as JavaServer Pages (JSP) and servlets, or in client-side objects such as Java applets or standalone Java applications. The bean is a lightweight class that maintains an active HTTP connection to the OracleAS MapViewer service and the current map request and map response objects. In most cases, you will create only one OracleAS MapViewer bean and use it for all subsequent tasks; however, you can create more than one bean and use these beans simultaneously. For example, you may need to create a Web page where a small overview map displays the whole world and a large map image displays a more detailed map of the region that is selected on the overview map. In this case, it is probably easier to create two OracleAS MapViewer beans, one dedicated to the smaller overview map, and the other to the larger detail map.

Figure 4-1 shows some possible usage scenarios for the OracleAS MapViewer bean.

Figure 4-1 OracleAS MapViewer Bean Usage Scenarios

Description of "Figure 4-1 OracleAS MapViewer Bean Usage Scenarios"

The OracleAS MapViewer bean can communicate through the HTTP protocol with the OracleAS MapViewer service in several usage scenarios, the following of which are shown in Figure 4-1:

In a Java application
In a Java applet
In a servlet within a Java 2 Enterprise Edition (J2EE) container different from the J2EE container that contains the OracleAS MapViewer service
In JavaServer Pages (JSP) code within the J2EE container that contains the OracleAS MapViewer service

In all usage models, the same JavaBean class is used, and most of its methods apply. However, some methods work or are useful only in a JSP HTML-based context, and other methods work or are useful only in an interactive standalone Java application or applet context (thick clients). For example, consider the following methods of the bean:

java.awt.Image getGeneratedMapImage
String getGeneratedMapImageURL

Both methods extract the generated map image information from a response received from an OracleAS MapViewer service; however, the first method returns the actual binary image data that is a java.awt.BufferedImage class, and the second method returns an HTTP URL string to the generated map image that is stored in the host running the OracleAS MapViewer service. Clearly, if your application is a JavaServer Page, you should use the second method, because otherwise the JSP page will not know how to handle the BufferedImage. However, if you are programming a standalone Java application where you have a Java panel or window for displaying the map, you can use the first method to get the actual image and render it inside your panel or window, plus any other features that you may have created locally and want to render on top of the map.

The set of methods that are only applicable in the thick client context, which are designed to achieve optimal performance for such clients, are described in more detail in Section 4.3.10.

4.2 Preparing to Use the OracleAS MapViewer JavaBean-Based API

Before you can use the OracleAS MapViewer JavaBean, the OracleAS MapViewer mvclient.jar library must be in a directory that is included in the CLASSPATH definition. After you deploy the mapviewer.ear file in OC4J or Oracle Application Server, the mvclient.jar file is located in the $MAPVIEWER/web/WEB-INF/lib directory. ($MAPVIEWER is the base directory that the mapviewer.ear file is unpacked into by OC4J. In a typical OC4J installation, if you placed the mapviewer.ear file in $OC4J_HOME/j2ee/home/applications, the base directory for unpacked OracleAS MapViewer is $OC4J_HOME/j2ee/home/applications/mapviewer.)

Before you use the OracleAS MapViewer JavaBean, you should examine the Javadoc-generated API documentation and try the JSP demo:

Javadoc documentation for the OracleAS MapViewer bean API is available at a URL with the following format:
```
http://host:port/mapviewer/mapclient
```
In this format, host and port indicate where OC4J or Oracle Application Server listens for incoming requests.
A demo supplied with OracleAS MapViewer shows how to use the bean. After you have set up the OracleAS MapViewer demo data set (which can be downloaded from the Oracle Technology Network) by importing it into a database and running all necessary scripts, you can try the JSP demo. The URL for the JSP demo has the following format:
```
http://host:port/mapviewer/demo/mapinit.jsp
```
In this format, host and port indicate where OC4J or Oracle Application Server listens for incoming requests. This JSP page confirms the OracleAS MapViewer service URL and then proceeds to the real demo page, map.jsp.

4.3 Using the OracleAS MapViewer Bean

To use the OracleAS MapViewer bean, you must create the bean (see Section 4.3.1), after which you can invoke methods to do the following kinds of operations:

Set up parameters of the current map request (see Section 4.3.2)
Add themes or features to the current map request (see Section 4.3.3)
Add dynamically defined styles to a map request (see Section 4.3.4)
Manipulate the themes in the current map request (see Section 4.3.5)
Send a request to the OracleAS MapViewer service (see Section 4.3.6)
Extract information from the current map response (see Section 4.3.7)
Obtain information about data sources (see Section 4.3.8)
Query nonspatial attributes in the current map window (see Section 4.3.9)
Use optimal methods for thick clients (see Section 4.3.10)

The sections about methods for kinds of operations provide introductory information about what the bean can do. For detailed descriptions of each method, including its parameters and return type, see the Javadoc-generated API documentation (described in Section 4.2).

4.3.1 Creating the OracleAS MapViewer Bean

The first step in any planned use of the OracleAS MapViewer bean is to create the bean, as shown in the following example:

import oracle.lbs.mapclient.MapViewer;
MapViewer mv = new MapViewer("http://my_corp.com:8888/mapviewer/omserver");

The only parameter to the constructor is a URL to an actual OracleAS MapViewer service. Unless you change it to something else using setServiceURL, the OracleAS MapViewer service at this URL will receive all subsequent requests from this bean. When an OracleAS MapViewer bean is created, it contains an empty current map request. There are a few parameters in the current request that are initialized with default values, such as the width and height of the map image and the background color for maps. These default values are explained in the XML API element and attribute descriptions in Chapter 3.

4.3.2 Setting Up Parameters of the Current Map Request

As explained in Chapter 3, a map request can have many parameters that affect the final look of the generated map image. When you use the OracleAS MapViewer JavaBean, such parameters can be set through a group of methods whose names start with set. Many of these parameters have a corresponding method that starts with get. For example, setAntiAliasing sets antialiasing on or off, and getAntiAliasing returns the current antialiasing setting.

The methods for setting parameters of the current map request include the following:

setAntiAliasing(boolean aa) specifies whether or not the map should be rendered using the antialiasing technique.
setBackgroundColor(java.awt.Color bg) sets the background color for the map to be generated.
setBackgroundImageURL(java.lang.String bgImgUrl) sets the URL for the background image to be rendered in the map.
setBaseMapName(java.lang.String name) sets the name of the base map to be rendered before any explicitly added themes.
setBoundingThemes(String[] themeNames, double borderMargin, boolean preserveAspectRatio) sets the bounding themes for the current map request. Any previous center point and box settings will be cleared as a result of calling this method.
setBox(double xmin, double ymin, double xmax, double ymax) sets the map query window box in the data coordinate space. Any previous center point and size settings will be lost as a result of calling this method.
setCenter(double cx, double cy) sets the center point for this map request. The coordinates must be in the user data space.
setCenterAndSize(double cx, double cy, double size) sets the map center and size for the map to be generated. All data must be in the user data space.
setDataSourceName(java.lang.String name) sets the name of the data source to be used when loading data for the map.
setDefaultStyleForCenter(java.lang.String defRenderStyleName, java.lang.String defLabelStyleName, java.lang.String defLabel, double[] defRadii) sets the default styling and labeling information for the center (point) of the map. Each subsequent map generated will have its center point rendered and optionally labeled with circles of the specified radii.
setDeviceSize(java.awt.Dimension dsz) sets the image dimension of the map to be generated.
setFullExtent() tells the OracleAS MapViewer server not to impose any center and size restriction for the next map request. This effectively removes the current map center and size settings. The resulting map will be automatically centered at the full extent of all features being displayed.
setImageFormat(int f) sets the image format that OracleAS MapViewer should use when generating the map. For JSP pages, you should always set it to FORMAT_PNG_URL or FORMAT_GIF_URL.
setImageScaling(boolean is) specifies whether images in an image theme should automatically be rescaled to fit the current query window. The default is TRUE. If you specify FALSE, the images will be rendered without any scaling by OracleAS MapViewer; however, the original query window may be slightly modified to allow other (vector) themes to overlay properly with the images. In all cases, the map center is not changed.
setMapLegend(java.lang.String legendSpec) sets the map legend (in XML format) to be plotted with current map. The legend must be specified in the legendSpec parameter, in the format for the <legend> element that is documented in Section 3.2.11.
setMapLegend(java.lang.String fill, java.lang.String fillopacity, java.lang.String stroke, java.lang.String profile, java.lang.String position, java.lang.String fontFamily, java.lang.String[][][] legenddata) sets the map request legend to be plotted with current map. The legenddata attribute contains the legend items, and its structure is String [x][y][z] legenddata, where x is the number of legend columns, y is the number of column items, and z is the legend attributes (index 0 = legend text, index 1 = style name, index 2 = is title or not, index 3 = tab, index 4 = is separator or not).
setMapLegend(java.lang.String fill, java.lang.String fillopacity, java.lang.String stroke, java.lang.String profile, java.lang.String position, java.lang.String[][][] legenddata) is the same as the preceding method, but without the fontFamily attribute.
setMapRequestSRID(int d) sets the map request output SRID, which must match an SRID value in the MDSYS.CS_SRS table. Themes whose SRID value is different from the map request SRID will be automatically converted to the output SRID if the theme SRID is not null or not equal to 0. If no map request SRID is defined (equal to zero), OracleAS MapViewer will use the theme's SRID as reference, but no transformation will be performed if the themes have different SRID values.
setMapResultFileName(String mapFile) sets the name of the resulting map image file on the server side. If the name is set to null (the default), OracleAS MapViewer will generate map image files based on the prefix omsmap and a counter value. You do not need to specify the extension (.gif or .png) when specifying a custom map file name.
setMapTitle(java.lang.String title) sets the map title for the map to be generated.
setServiceURL(java.lang.String url) sets the OracleAS MapViewer service URL.
setSize(double size) sets the height (size) in the user data space for the map to be generated.
setShowSVGNavBar(boolean s) specifies whether or not to show the built-in SVG navigation bar. The default value is TRUE (that is, show the navigation bar).
setSVGOnClick(java.lang.String onClick) sets the onClick function for an SVG map. The onClick function is a JavaScript function defined in the Web page in which the SVG map is embedded. The onClick function is called whenever the SVG map is clicked if both theme feature selection and window selection are disabled. For information about using JavaScript functions with SVG maps, see Appendix B.
setSVGShowInfo(boolean info) specifies whether or not to display hidden information when the mouse moves over features for which hidden information is provided. If its value is TRUE (the default), hidden information is displayed when the mouse moves over such features; if it is set to FALSE, hidden information is not displayed when the mouse moves over such features. Regardless of the value, however, hidden information is always rendered in an SVG map; this method only controls whether hidden information can be displayed.
setSVGZoomFactor(double zfactor) sets the zoom factor for an SVG map. The zoom factor is the number by which to multiply the current zoom ratio for each integer increment (a zoomin operation) in the zoom level. The inverse of the zoom factor value is used for each integer decrement (a zoomout operation) in the zoom level. For example, if the zfactor value is 2 (the default), zooming in from zoom level 4 to 5 will enlarge the detail by two; for example, if 1 inch of the map at zoom level 4 represents 10 miles, 1 inch of the map at zoom level 5 will represent 5 miles. The zoom ratio refers to the relative scale of the SVG map, which in its original size (zoom level 0) has a zoom ratio of 1.
setSVGZoomLevels(int zlevels) sets the number of zoom levels for an SVG map.
setSVGZoomRatio(double s) sets the zoom factor to be used when an SVG map is initially loaded. The default value is 1, which is the original map size (zoom level 0). Higher zoom ratio values show the map zoomed in, and lower values show the map zoomed out.
setWebProxy(java.lang.String proxyHost, java.lang.String proxyPort) sets the Web proxy to be used when connecting to the OracleAS MapViewer service. This is needed only if there is a firewall between the Web service and this bean.

You can remove the map legend from the current map request by calling the deleteMapLegend method.

4.3.3 Adding Themes or Features to the Current Map Request

Besides specifying a base map to be included in a map request, you can add themes or individual point and linear features, such as a point of interest or a dynamically generated route, to the current map request. The themes can be predefined themes whose definitions are stored in the database, or dynamic themes where you supply the actual query string when you add the theme to the current request.

There are several kinds of dynamic themes: to retrieve geometric data (JDBC theme), to retrieve image data (image theme), to retrieve GeoRaster data (GeoRaster theme), to retrieve network data (network theme), and to retrieve topology data (topology theme). For dynamic themes and features, you must explicitly specify the styles you want to be used when rendering them. Being able to add dynamic themes and features gives you flexibility in adapting to application development needs.

The methods for adding themes or features to the current map request have names that start with add, and they include the following:

addGeoRasterTheme and its variants add GeoRaster data to the current map request. In some cases you supply the query string to retrieve the raster data; in other cases you supply the necessary GeoRaster information to retrieve a specific image. (Section 2.3.6 explains GeoRaster themes.)
addImageTheme and its variants add an image theme, for which you must supply the query string for retrieving the image data to be rendered as part of the map. (Section 2.3.5 explains image themes.)
addJDBCTheme and its variants add a JDBC theme, for which you must supply the query string for retrieving the geometric data. (Section 2.3.2 explains JDBC themes.)
addLinearFeature and its variants add a single linear feature (line string) to the current map request. You must specify a rendering style. You can specify the labeling text and text style for drawing the label, and you can also specify if the label will always be present regardless of any overlapping. The coordinates must be in the user data space. There is no limit to the number of linear features that you can add.
addLinksWithinCost adds a network theme to the current map request; the theme will be a result of the within-cost analysis on network data. The within-cost analysis finds all nodes that are within a specified cost, and generates the shortest path to each node.
addNetworkLinks adds network links to the current map request as a network theme, for which you must supply the rendering styles.
addNetworkNodes adds the network nodes to the current map request as a network theme, for which you must supply the rendering styles.
addNetworkPaths adds the network paths to the current map request as a network theme, for which you must supply the rendering styles.
addNetworkTheme and its variants add the network links, nodes, and paths to the current map request as a network theme, for which you must supply the rendering styles. (Section 2.3.7 explains network themes.)
addPointFeature and its variants add a single feature that is a point to the current map request. This point will be rendered using the supplied rendering style on the map after all themes have been rendered. You can optionally supply a labeling text to be drawn alongside the point feature, and you can specify if the label will always be present regardless of any overlapping. You can also supply an array of radii (the units are always in meters), in which case a series of circles will be drawn centering on the point. The coordinates x and y must be in the user data space. You can assign attribute values to the point feature for use with an advanced style. For oriented point features, you can specify orientation parameters. There is no limit to the number of point features you can add.
addPredefinedTheme and its variants add a predefined theme to the current map request.
addShortestPath and its variants add a network theme to the current map request; the theme will be a result of the shortest-path analysis on a network data. You must supply the necessary parameters for the shortest-path algorithm.
addThemesFromBaseMap(java.lang.String basemap) adds all predefined themes in the specified base map to the current map request. This has an advantage over setBaseMapName, in that you can manipulate the themes for the current map request, as explained in Section 4.3.5.
addTopologyDebugTheme and its variants add the topology data structure as a topology debug-mode theme to the current map request. You must supply the rendering styles for the edges, nodes, and faces. (Section 2.3.8 explains topology themes, including the debug mode.)
addTopologyTheme adds the topology features as a topology theme to the current map request. You must supply the query string. (Section 2.3.8 explains topology themes.)

You can remove all added point and linear features by calling the removeAllPointFeatures and removeAllLinearFeatures methods, respectively.

4.3.4 Adding Dynamically Defined Styles to a Map Request

Besides the styles stored on the USER_SDO_STYLES view, you can also add dynamically defined (temporary) styles to a map request. These dynamically defined styles provide temporary information for the map request, and they should always be added to the map request before it is sent to the server.

The methods for adding dynamically defined styles to the map request have names that start with add, and they include the following:

addBucketStyle(java.lang.String name, java.lang.String low, java.lang.String high, int nbuckets, java.lang.String []styleName) adds a bucket style with equal intervals, for which you specify the range values, the number of buckets, and the style name for each bucket.
addCollectionBucketStyle(java.lang.String name, java.lang.String []label, java.lang.String []styleName, java.lang.String [][]value) adds a collection bucket style, for which you specify the label, the style name, and the values for each bucket.
addColorSchemeStyle(java.lang.String name, java.lang.String baseColor, java.lang.String strokeColor, java.lang.String low, java.lang.String high, int nbuckets) adds a color scheme style with equal intervals, for which you specify the color parameters, the range values, and the number of buckets.
addColorSchemeStyle(java.lang.String name, java.lang.String baseColor, java.lang.String strokeColor, java.lang.String []label, java.lang.String []low, java.lang.String []high) adds a color scheme style, for which you specify the color parameters and the range values.
addColorStyle(java.lang.String name, java.lang.String stroke, java.lang.String fill, int strokeOpacity, int fillOpacity) adds a color style with the specified color parameters.
addImageAreaStyleFromURL(java.lang.String styleName, java.lang.String imgURL) adds a GIF or JPEG image as an area symbol to the OracleAS MapViewer client.
addImageAreaStyleFromURL(java.lang.String styleName, java.lang.String imgURL, java.lang.String lineStyle) adds a GIF or JPEG image as an area symbol to the OracleAS MapViewer client. You can also specify parameters for stroking the boundary of the area being filled.
addImageMarkerStyleFromURL(java.lang.String styleName, java.lang.String imgURL, java.lang.String strokeColor, float strokeWidth, int strokeOpacity) adds a GIF image as a marker symbol to the OracleAS MapViewer client.
addImageMarkerStyleFromURL(java.lang.String styleName, java.lang.String imgURL) adds a GIF image as a marker symbol to the OracleAS MapViewer client. You can also specify parameters for the desired width and height of the image when applied to features on a map, as well as the font properties of any text label that will go inside or on top of the marker.
addImageMarkerStyleFromURL(java.lang.String styleName, java.lang.String imgURL) adds a GIF image as a marker symbol to the OracleAS MapViewer client.
addImageMarkerStyleFromURL(java.lang.String styleName, java.lang.String imgURL, int desiredWidth, int desiredHeight, java.lang.String fontName, int fontSize, java.lang.String fontStyle, java.lang.String fontWeight, java.lang.String fontColor) adds a GIF image as a marker symbol to the OracleAS MapViewer client. You can also specify parameters for the desired width and height of the image when applied to features on a map, as well as the font properties of any text label that will go inside or on top of the marker.
addLineStyle(java.lang.String name, java.lang.String fill, java.lang.String strokeWidth, boolean hasBase, java.lang.String baseFill, java.lang.String baseStroke, java.lang.String baseDash, boolean hasParallel, java.lang.String fillParallel, java.lang.String strokeParallel, boolean hasHashMark, java.lang.String fillHash, java.lang.String dashHash) adds a line style to the OracleAS MapViewer client.
addLineStyle(java.lang.String name, java.lang.String fill, java.lang.String strokeWidth, boolean hasBase, java.lang.String baseFill, java.lang.String baseStroke, java.lang.String baseDash, boolean hasParallel, java.lang.String fillParallel, java.lang.String strokeParallel, boolean hasHashMark, java.lang.String fillHash, java.lang.String dashHash, java.lang.String measureMarker, double measurePosition, int measureSize) adds a line style to the OracleAS MapViewer client.
addMarkerStyle(java.lang.String name, int mktype, java.lang.String strokeColor, java.lang.String fillColor, java.lang.String markerWidth, java.lang.String markerHeight, java.lang.String coords, java.lang.String radius) adds a vector marker style with the given parameters. The available vector marker style types are MARKER_POLYGON, MARKER_POLYLINE, MARKER_CIRCLE, and MARKER_RECT.
addTextStyle(java.lang.String name, java.lang.String style, java.lang.String family, java.lang.String size, java.lang.String weight, java.lang.String fill) adds a text style with the specified parameters.
addVariableMarkerStyle(java.lang.String name, java.lang.String []label, java.lang.String baseMarker, int startSize,int increment, java.lang.String []low, java.lang.String []high) adds a variable marker style, for which you specify the parameters for the base marker, and also the label and the values for each bucket.

You can remove a dynamically defined style from the current map request by calling the deleteStyle(java.lang.String name) method, or you can remove all dynamically defined styles from the current map request by calling the removeAllDynamicStyles method.

4.3.5 Manipulating Themes in the Current Map Request

After you add themes using any of the methods that start with add, you can manipulate them, performing such operations as listing their names, moving them up or down in rendering order for the current request, and even disabling themes and enabling themes that had been disabled. However, you cannot manipulate themes that are implicitly included when you set a base map (using the setBaseMapName method), because the list of themes in the base map is not actually included until the OracleAS MapViewer service processes the request.

The methods for manipulating themes in the current map request include the following:

deleteAllThemes deletes all added themes from the current map request.
deleteTheme(java.lang.String name) deletes an explicitly added theme from the current map request.
enableThemes(java.lang.String[] themes) enables all themes whose names appear in the supplied list.
getActiveTheme(double currentScale) gets the name of the active theme, that is, the top theme on the current display map.
getEnabledThemes gets a list of all themes that are currently enabled.
getThemeEnabled(java.land.String themeName) determines whether or not a specified theme is currently enabled.
getThemeNames returns an ordered list of names of themes that have been explicitly added to the current map request.
getThemePosition(java.lang.String name) returns the position in the rendering sequence of an explicitly added theme.
getThemeVisibleInSVG(java.lang.String name) determines whether or not a specified theme is currently visible in an SVG map. (If the theme is not visible, it is hidden.)
hasThemes checks to see if the current map request has any explicitly added themes. For example, if you have only set the name of the base map in the current request, but have not added any other theme through one of the add*Theme methods, this method returns FALSE.
moveThemeDown(int index) moves a theme down one position in the list of themes to be rendered, so that it is rendered later.
moveThemeUp(int index) moves a theme up one position in the list of themes to be rendered, so that it is rendered sooner.
setAllThemesEnabled(boolean v) sets all themes to be enabled or disabled.
setGeoRasterThemePolygonMask(java.lang.String name,double []coords) sets the polygon mask to be applied on the GeoRaster theme. The GeoRaster area outside the polygon mask will be transparent. The coordinates are defined as x1,y1,x2,y2, . . . . The mask coordinates must be in the data coordinate space.
setLabelAlwaysOn(boolean labelAlwaysOn, java.lang.String name) controls whether or not OracleAS MapViewer labels all features in a theme even if two or more labels will overlap in the display of a theme. (OracleAS MapViewer always tries to avoid overlapping labels.) If labelAlwaysOn is TRUE, OracleAS MapViewer displays the labels for all features even if two or more labels overlap. If labelAlwaysOn is FALSE, when it is impossible to avoid overlapping labels, OracleAS MapViewer disables the display of one or more labels so that no overlapping occurs.
setNetworkThemeLabels(java.lang.String name, java.lang.String linkLabelStyle, java.lang.String linkLabelColumn, java.lang.String nodeLabelStyle, java.lang.String nodeLabelColumn, java.lang.String pathLabelStyle, java.lang.String pathLabelColumn) sets network theme label parameters for links, nodes, and paths. The attribute column name must be an existing attribute of the link, node, and path tables.
setThemeAlpha(java.lang.String themeName, float alpha) sets the transparency value for an image theme.
setThemeEnabled(boolean v, java.lang.String themeName) sets a specified theme to be enabled or disabled in the current map request.
setThemeFastUnpickle(java.lang.String name, boolean noUnpickler) specifies whether to use the OracleAS MapViewer fast unpickling algorithm (TRUE, the default) or the generic JDBC conversion algorithm (FALSE) to convert SDO_GEOMETRY objects fetched from the database into a Java object accessible to OracleAS MapViewer. The OracleAS MapViewer fast unpickling algorithm improves performance, but occasionally the coordinates may lose some precision (around 0.00000005), which can be significant in applications where all precision digits of each coordinate must be kept. The generic JDBC conversion algorithm is slower than the OracleAS MapViewer fast unpickling process, but there is never any loss of precision.
setThemeOnClickInSVG (java.lang.String theme, java.lang.String onClickFunction) sets the theme's onClick function for an SVG map. The onClick function is a JavaScript function defined in the Web page in which the SVG map is embedded. The onClick function is called whenever the SVG map is clicked if both theme feature selection and window selection are disabled. For information about using JavaScript functions with SVG maps, see Appendix B.
setThemeScale(java.lang.String name, double minScale, double maxScale) sets the minimum and maximum scale values for displaying a theme.
setThemeSelectableInSVG (java.lang.String theme, boolean sel) sets the theme to be selectable (TRUE) or not selectable (FALSE) in an SVG map. If the theme is set to selectable, any feature of the theme can be selected in the SVG map by clicking on it. If the feature is selected, its color is changed and its ID (its rowid by default) is recorded. You can get a list of the ID values of all selected features by calling the JavaScript function getSelectedIdList() defined in the SVG map. For information about using JavaScript functions with SVG maps, see Appendix B.
setThemeUnitAndResolution(java.lang.String themeName, java.lang.String unit, double resolution) sets the unit and resolution values for an image theme.
setThemeVisible(java.lang.String name, boolean vis) sets the theme to be visible (TRUE) or hidden (FALSE) in an SVG map. If the theme is set to be hidden, the theme will be still rendered, but will be invisible.

4.3.6 Sending a Request to the OracleAS MapViewer Service

As an application developer, you typically issue a new map request as a result of certain user input (such as a mouse click on the currently displayed map) or after you have modified some aspect of the map request (such as setting a new background color). In fact, you can issue a map request any time you want, as long as you do not overwhelm the middle-tier OracleAS MapViewer service with too many rapid requests from the OracleAS MapViewer bean or beans. The OracleAS MapViewer service tries to process requests in the order in which they arrive; if you send a second request before receiving the response from the first one, OracleAS MapViewer continues to process the first request completely before starting to process the second request.

Any modifications to the current map request, such as changing to a new background color or moving a theme down in the rendering sequence, do not take effect in the map display until you send the map request, at which time the OracleAS MapViewer service actually receives the request and processes it.

The methods for sending a map request to the OracleAS MapViewer service include the following:

run sends the current map request to the OracleAS MapViewer service, and obtains a map response as sent back by the OracleAS MapViewer service.
pan(int x, int y) pans to the specified device point. Each coordinate is in the screen or display unit, in this case, pixel.
zoomIn(double factor) zooms in on the map without changing the other map request parameters.
zoomIn(int x, int y, double factor) zooms in on the specified device point.
zoomIn(int x1, int y1, int x2, int y2) zooms in on the specified device rectangle.
zoomOut(double factor) zooms out on the current map without changing the other map request parameters.
zoomOut(int x, int y, double factor) zooms out and recenters the current map.

Each of these methods assembles a single XML map request document based on all properties of the current map request, and then sends it to the OracleAS MapViewer service. After the OracleAS MapViewer bean receives the response from the OracleAS MapViewer service, the bean does any necessary postprocessing and makes the response ready for your use.

As an alternative to using these methods, you can formulate an XML request string outside the bean, and then use the sendXMLRequest(java.lang.String req) method to send the request to the OracleAS MapViewer service. However, if you use this method, you are responsible for receiving and unpacking the response using the getXMLResponse method, and for parsing and interpreting the response string yourself. The state of the bean remains unchanged, because the methods are only making use of the bean's capability to open an HTTP connection to send and receive documents over the connection.

All methods described in this section throw an exception if any unrecoverable error occurs during the transmission of the request or response, or in the OracleAS MapViewer service during processing. You are responsible for taking care of such exceptions in any way you consider appropriate, such as by trying the request again or by reporting the problem directly to the user.

4.3.7 Extracting Information from the Current Map Response

You can extract information, such as the generated map image or the URL for the image, from the current map response. The methods for extracting information from the map response include the following:

getGeneratedMapImage returns the actual map image data contained in the response from the OracleAS MapViewer service. You must have set the image format to FORMAT_RAW_COMPRESSED using the setImageFormat method. The getGeneratedMapImage method is primarily used in thick clients, although you may also use it in a JavaServer Page or a servlet (for example, to save the image in a format that is not supported by OracleAS MapViewer).
getGeneratedMapImageURL returns the URL to the currently generated map image in the application server. You must have set the image format to FORMAT_PNG_URL or FORMAT_GIF_URL using the setImageFormat method.
getMapMBR returns the MBR (minimum bounding rectangle) for the currently generated map, in the user's data space.
getMapResponseString returns the last map response in XML format.

4.3.8 Obtaining Information About Data Sources

The OracleAS MapViewer bean has methods that you can use to obtain information about data sources. These methods include the following:

dataSourceExists(java.lang.String dsrc) checks if a given data source exists in (that is, is known to) the OracleAS MapViewer service.
getDataSources() lists the currently available data sources in the server. This method lists only the names and no other details about each data source (such as database host or user login information).

4.3.9 Querying Nonspatial Attributes in the Current Map Window

It is often necessary to query nonspatial attributes that are associated with the spatial features being displayed in the current map image. For example, assume that you just issued a map request to draw a map of all customer locations within a certain county or postal code. The next logical step is to find more information about each customer being displayed in the resulting map image. In the JSP or HTML environment, because you get only an image back from the OracleAS MapViewer service, you will need another round-trip to the service to fetch the nonspatial information requested by the user. This section describes a set of methods that can help you do just that. (You can, however, obtain both the nonspatial attribute values of a certain theme and the resulting map image in a single request when the bean is used in a standalone Java application or applet environment, as described in Section 4.3.10.)

A typical situation is that the user clicks on a feature on the displayed map and then wants to find out more (nonspatial attributes) about the feature. This action can be essentially implemented using a query with the desired nonspatial attributes in its SELECT list, and a spatial filter as its WHERE clause. The spatial filter is an Oracle Spatial SQL operator that checks if the geometries in a table column (the column of type SDO_GEOMETRY in the customer table) spatially interact with a given target geometry (in this case, the user's mouse-click point). The spatial filter in the WHERE clause of the query selects and returns only the nonspatial attributes associated with the geometries that are being clicked on by the user.

You will need to call an Oracle Spatial operator to perform the filtering; however, you can use the OracleAS MapViewer bean-based API to obtain information, and to preassemble the spatial filter string to be appended to the WHERE clause of your query. The identify method simplifies the task even further.

The methods for querying nonspatial attributes in the current map window include the following:

doQuery and variants execute a supplied SQL query and return an array of strings representing the result set. These are convenient methods to issue your own query without manually opening a JDBC connection to the database from the bean.
doQueryInMapWindow and variants are extensions of doQuery and its variants. They automatically subject the user-supplied query to a spatial filtering process using the current map window.
getSpatialFilter(java.lang.String spatialColumn, int srid, boolean pre9i) returns a spatial filter string that can be used as a WHERE clause condition in formulating your own queries in the current map window context. The spatial filter evaluates to TRUE for any geometries that are being displayed in the entire map window. You can use this method to obtain information about every spatial feature of a theme that is being displayed.
getSpatialFilter(java.lang.String spatialColumn, int srid, double xl, double yl, double xh, double yh, boolean pre9i) returns a spatial filter string that can be used as a query condition in formulating your queries in the given window. This filter evaluates to TRUE for all geometries that interact with the supplied (xl,yl, xh,yh) data window. The window is not in device or screen coordinate space, but in the user's data space; therefore, you must first call the getUserPoint method to convert the user's mouse-click point to a point in the user data space before using the getSpatialFilter method.
getUserPoint(int x, int y) returns the user data space point corresponding to the mouse click.
getUserPoint(int x, int y, java.lang.String dataSource, int outSRID) returns the user data space point corresponding to the mouse click, using the specified coordinate system (SRID value).
getUserPoint(int x, int y, java.lang.String dataSource, java.lang.String themeName) returns the user data space point corresponding to the mouse click, using the coordinate system (SRID value) associated with the specified theme.
getWhereClauseForAnyInteract(java.lang.String spatialColumn, int srid, double x, double y) returns geometries that have any interaction with a specified point in the user's data space. This provides a WHERE clause string that will use a more precise spatial filtering method than the one provided by the getSpatialFilter method.
getWhereClauseForAnyInteract(java.lang.String spatialColumn, int srid, double xl, double yl, double xh, double yh) returns the WHERE clause that can be used to find geometries that have any interaction with the specified user space window. It is similar to the getSpatialFilter method, but uses a more precise version of the Oracle Spatial filtering method.
identify and variants provide a convenient method for identifying nonspatial attributes. This is desirable if you do not need more flexibility and control over how a nonspatial attribute query should be formulated. As with the doQuery methods, all identify methods return a double String array that contains the result set of the query.

4.3.10 Using Optimal Methods for Thick Clients

When you use the OracleAS MapViewer bean in a JavaServer Page in an HTML file, a second round-trip to the OracleAS MapViewer service is needed to obtain nonspatial attributes of features being displayed. It is also true that with a JavaServer Page in an HTML file, even if most themes remain unchanged from one map request to the next (such as when zooming in to the center of a map), all themes must still be reprocessed each time the OracleAS MapViewer service processes the page, which causes the data for each theme to be retrieved again from the database. (This is mainly due to the stateless nature of the OracleAS MapViewer service and the insufficient mechanism provided in the JSP context for handling user interaction, which must be based on the request/response model.)

However, when you are working in a thick client environment, such as with J2SE (Java 2 Platform Standard Edition) applications and applets, you can reduce the processing and bandwidth overhead when using the bean. This is primarily because in such environments you have greater control of how content (including the map) should be displayed, you can better respond to the user's interaction, and you can devote more resources to maintaining the states on the client side.

A key optimization available only to the thick client context is live features. Basically, a live feature is a spatial feature that originates from the OracleAS MapViewer service but exists in the thick client. Each live feature contains the actual shape representing the geometry data, and a set of nonspatial attributes that the user might be interested in. To obtain live features, a thick client must set its parent theme to be clickable. When a map request is sent to the OracleAS MapViewer service with a clickable theme, OracleAS MapViewer does not attempt to render features for that theme in the resulting map. Rather, the set of features that would have been drawn as part of the map is returned to the requesting client as an array of live feature objects. The rest of the map is still rendered and transmitted as a single image to the client. After the client has received both the live features and the base image, it must render the live features on top of the accompanying map image, using one of the methods described later in this section.

One benefit of using live features is that the thick client will not need to issue a request for the clickable theme every time a map request is sent. For example, if the request is to zoom in to the current map, the client can determine for each live feature if it should be displayed in the zoomed-in map image. Another, and probably more significant, advantage is that the nonspatial attributes for all features displayed in the map are now readily available to the user. For example, as the user moves the mouse over a range of features on the map, the thick client can immediately get the corresponding nonspatial attributes and display them in a pop-up window that follows the mouse trail. No round-trip to the OracleAS MapViewer service is needed for this type of action, and the feedback to the user is more responsive.

The methods that are optimal for thick clients include the following:

drawLiveFeatures(java.awt.Graphics2D g2, java.awt.Color stroke, java.awt.Color fill, double pointRadius, double strokeWidth) draws all live features that are returned to this client from OracleAS MapViewer.
getLiveFeatureAttrs(int x, int y, int tol) gets the nonspatial attributes of the feature being clicked on by the user.
getNumLiveFeatures returns the number of live features currently available.
hasLiveFeatures checks if there are any live (clickable) features.
highlightFeatures and variants highlight all live features that are intersecting the user-specified rectangle. These methods also let you specify the style for highlighting features.
isClickable(java.lang.String themeName) checks if the specified theme is clickable (that is, if users can click on the theme to get its attributes).
setClickable(boolean v, java.lang.String themeName) sets the theme clickable (so that its features will be available to the client as live features that users can click on and get attributes of).

To obtain a set of features and keep them live at the thick client, you must first call setClickable to set the theme whose features you want to be live. Then, after you issue the current map request, the bean processes the response from the OracleAS MapViewer service, which (if it succeeded) contains both a base map image and an array of LiveFeature instances. You can then call getGeneratedMapImage to get and draw the base image, and use drawLiveFeatures to render the set of live features on top of the base map. If the user clicks or moves the mouse over a certain position on the map, you can use the highlightFeatures method to highlight the touched features on the map. You can also use the getLiveFeatureAttrs method to obtain the associated nonspatial attributes of the features being highlighted. You do not have direct access to the LiveFeature instances themselves.

The behavior of calling the methods described in this section in the context of JSP pages is not defined.