This chapter describes the JavaBean-based MapViewer API. This API exposes all capabilities of MapViewer through a single JavaBean,
oracle.lbs.mapclient.MapViewer. This bean is a lightweight client that handles all communications with the actual MapViewer service running on the middle tier on behalf of a user making map requests.
All communications between the bean and the actual 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 MapViewer bean is easier than manipulating XML documents for forming and sending MapViewer requests, as well as for extracting information from the responses.
The bean delegates most of map data processing and rendering to the MapViewer service. All the bean does is formulate user requests into valid MapViewer XML requests and send them to a MapViewer service for processing.
This chapter contains the following major sections:
The 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 MapViewer service and the current map request and map response objects. In most cases, you will create only one 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 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 MapViewer bean.
The MapViewer bean can communicate through the HTTP protocol with the 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 MapViewer service
In JavaServer Pages (JSP) code within the J2EE container that contains the 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:
Both methods extract the generated map image information from a response received from a 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 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.
Before you can use the MapViewer JavaBean, the 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 Fusion Middleware, the
mvclient.jar file is located in the
/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
/j2ee/home/applications, the base directory for unpacked MapViewer is
Javadoc documentation for the MapViewer bean API is available at a URL with the following format:
In this format,
port indicate where OC4J or Oracle Fusion Middleware listens for incoming requests.
A demo supplied with MapViewer shows how to use the bean. After you have set up the 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:
In this format,
port indicate where OC4J or Oracle Fusion Middleware listens for incoming requests. This JSP page confirms the MapViewer service URL and then proceeds to the real demo page,
To use the 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 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).
The first step in any planned use of the 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 MapViewer service. Unless you change it to something else using
setServiceURL, the MapViewer service at this URL will receive all subsequent requests from this bean. When a 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.
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 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:
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.
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.
setFullExtent() tells the 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.
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 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
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), 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), MapViewer will generate map image files based on the prefix
omsmap and a counter value. You do not need to specify the extension (
.png) when specifying a custom map file name.
setSVGOnClick(java.lang.String onClick) sets the
onClick function for an SVG map. The
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.
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 MapViewer service. This is needed only if there is a firewall between the web service and this bean.
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.4 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.3 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.
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.5 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
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.
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.6 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.6 explains topology themes.)
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. Effective with release 11g, you can add any kind of dynamically defined style to a map request with the single method
addStyle, which has the following definition:
public void addStyle(java.lang.String name, StyleModel tempStyle)
In the preceding definition,
StyleModel is an interface defined in the Java client package
oracle.mapviewer.share.style. This package and the
oracle.mapviewer.share.stylex package also contain concrete style model classes that represent the definitions of all types of styles supported by MapViewer. See the Javadoc reference documentation for information about these packages.
The following code excerpt shows how to use the addStyle method and the ColorStyleModel class to add a dynamic color style to a map request:
import oracle.lbs.mapclient.*; import oracle.mapviewer.share.* … ColorStyleModel csm = new ColorStyleModel(); csm.setFillColor(new Color(255, 0, 0, 100)); csm.setStrokeColor(new Color(0, 0, 255, 100)); mapViewer.addStyle("my_color", csm);
As an alternative to using the
addStyle method, you can use the following methods for adding specific types of styles:
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.
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 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 MapViewer client.
addImageMarkerStyleFromURL(java.lang.String styleName, java.lang.String imgURL) adds a GIF image as a marker symbol to the 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, 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 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 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 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
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
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 MapViewer service processes the request.
The methods for manipulating themes in the current map request include the following:
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
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 MapViewer labels all features in a theme even if two or more labels will overlap in the display of a theme. (MapViewer always tries to avoid overlapping labels.) If
TRUE, MapViewer displays the labels for all features even if two or more labels overlap. If
FALSE, when it is impossible to avoid overlapping labels, 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.
setThemeFastUnpickle(java.lang.String name, boolean noUnpickler) specifies whether to use the 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 MapViewer. The 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 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
setThemeSelectableInSVG (java.lang.String theme, boolean sel) sets the theme to be selectable (
TRUE) or not selectable (
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.
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 MapViewer service with too many rapid requests from the MapViewer bean or beans. The 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, 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 MapViewer service actually receives the request and processes it.
The methods for sending a map request to the MapViewer service include the following:
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 MapViewer service. After the MapViewer bean receives the response from the 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 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 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.
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 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 MapViewer).
getGeneratedMapImageURL returns the URL to the currently generated map image in the application server. You must have set the image format to
FORMAT_GIF_URL using the
The MapViewer bean has methods that you can use to obtain information about data sources. These methods include the following:
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).
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 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 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.
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
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
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.
When you use the MapViewer bean in a JavaServer Page in an HTML file, a second round-trip to the 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 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 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 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 MapViewer service with a clickable theme, 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 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:
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 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.