10g (9.0.4)
Part Number B10559-01
 Home |
 Solution Area |
 Contents |
 Index |
| Oracle® Application Server 10g MapViewer User's Guide 10g (9.0.4) Part Number B10559-01 |
|
This chapter explains how to submit map requests in XML format to MapViewer, and it describes the XML document type definitions (DTDs) for the map requests (input) and responses (output). XML is widely used for transmitting structured documents using the HTTP protocol. If an HTTP request (GET or POST method) is used, it is assumed the request has a parameter named xml_request whose value is a string containing the XML document for the request.
(In addition to map requests, the MapViewer XML API can be used for administrative requests, such as adding new data sources. Administrative requests are described in Chapter 6.)
As shown in Figure 1-1 in Section 1.1.1, the basic flow of action with MapViewer is that a client locates a remote MapViewer instance, binds to it, sends a map request, and processes the map response returned by the MapViewer instance.
A request to the MapViewer servlet has the following format:
http://hostname[:port]/MapViewer-servlet-path?xml_request=xml-request
In this format:
mapviewer/omserver).
The input XML is required for all requests. The output depends on the content of the request: the response can be either an XML document, or a binary object containing the (generated image) file requested by the user.
In an input request, you must specify a data source, and you can specify one or more of the following:
You can manage the definition of base maps, themes, and styles (individual symbologies) using the Map Definition Tool, which is described in Chapter 7.
For the current release, MapViewer accepts only a coordinate pair to identify the location for a map request; it cannot take a postal address as direct input for a map.
This chapter first presents some examples of map requests (see Section 3.1), and then presents detailed explanations of the following XML DTDs for requests and other operations:
This section provides examples of map requests. It refers to concepts, elements, and attributes that are explained in detail in Section 3.2.
Example 3-1 is a very simple map request. It requests a map consisting of a blank blue image (from the mvdemo data source) with the string Hello World drawn on top. (The datasource attribute is required for a map request, even though this specific map request does not retrieve any map data from the data source.)
<?xml version="1.0" standalone="yes"?> <map_request title="Hello World" datasource = "mvdemo" />
Example 3-2 is a simple map request with one dynamically defined theme. It requests a map of all Oracle Spatial geometries from the COUNTIES table.
<?xml version="1.0" encoding="UTF-8" ?> <map_request datasource="lbs_data"> <themes> <theme name="t1"> <jdbc_query spatial_column = "GEOM" datasource = "lbs_data"> SELECT geom FROM counties </jdbc_query> </theme> </themes > </map_request>
Example 3-3 requests a map with a specified center for the result map, and specifies a predefined theme (poi_theme_us_restaurants) to be rendered in addition to the predefined themes that are part of the base map (basemap="us_base").
<?xml version="1.0" encoding="UTF-8" ?> <map_request datasource="lbs_data" title="LBS CUSTOMER MAP" basemap="us_base" width="500" height="375" bgcolor="#a6cae0" format="GIF_URL"> <center size="1"> <geoFeature typeName="mapcenter" label="Motel 1" text_style="T.MOTEL" render_style="M.MOTEL" radius="300"> <geometricProperty> <Point> <coordinates>-122.2615, 37.5266</coordinates> </Point> </geometricProperty> </geoFeature> </center> <srs>SDO:8265</srs> <themes> <theme name="poi_theme_us_restaurants" /> </themes > </map_request>
Notes on Example 3-3:
basemap is specified, MapViewer first draws all predefined themes for that base map before drawing the specified theme (poi_theme_us_restaurants).
M.MOTEL style and the label Motel 1 in the T.MOTEL style.
Example 3-4 requests a map with a specified center, a predefined theme named theme_lbs_customers, a dynamically defined theme named sales_by_region, and all base themes in the base map us_base_road, plus two features: a polygon representing the top sales region, and a point. The requested map will be stored at the MapViewer host and a URL to that GIF image (format="GIF_URL") will be returned to the requester.
<?xml version="1.0" encoding="UTF-8" ?> <map_request datasource="lbs_data2" title="LBS CUSTOMER MAP 2" width="400" height="300" format="GIF_URL" basemap="us_base_road"> <center size="1.5"> <geoFeature typeName="nil"> <geometricProperty> <Point> <coordinates>-122.2615, 37.5266</coordinates> </Point> </geometricProperty> </geoFeature> </center> <themes> <theme name="theme_lbs_customers" /> <theme name="sales_by_region"> <jdbc_query spatial_column ="region" label_column="manager" render_style="V.SALES COLOR" label_style="T.SMALL TEXT" jdbc_host="data.my_corp.com" jdbc_sid="orcl" jdbc_port="1521" jdbc_user="scott" jdbc_password="tiger" jdbc_mode="thin" > select region, sales, manager from my_corp_sales_2001 </jdbc_query> </theme> </themes> <geoFeature typeName="nil" label="TopSalesRegion" text_style="9988" render_style="2837" > <geometricProperty> <Polygon srsName="SDO:8265"> <outerBoundaryIs> <LinearRing> <coordinates>42.9,71.1 43.2,72.3 39.2,73.0 39.0, 73.1 42.9,71.1</coordinates> </LinearRing> </outerBoundaryIs> </Polygon> </geometricProperty> </geoFeature> <geoFeature render_style="1397" text_style="9987"> <geometricProperty> <Point> <coordinates>-122.5615, 37.3266</coordinates> </Point> </geometricProperty> </geoFeature> </map_request>
In Example 3-4, sales_by_region is a dynamically defined theme. For information about dynamically defining a theme, see Section 3.2.6 and Section 3.2.7.
Example 3-5 requests a map in which an image theme is to be plotted underneath all other regular vector data. The image theme is specified in the <jdbc_image_query> element as part of the <theme> element in a map request. (For an explanation of image themes, see Section 2.3.4.)
<?xml version="1.0" encoding="UTF-8" ?> <map_request datasource="lbs_data" title="LBS Image MAP" basemap="us_roads" format="GIF_STREAM"> <center size="1"> <geoFeature > <geometricProperty> <Point> <coordinates>-122.2615, 37.5266</coordinates> </Point> </geometricProperty> </geoFeature> </center> <themes> <theme name="anImageTheme" > <jdbc_image_query image_format="ECW" image_column="image" image_mbr_column="img_extent" jdbc_srid="33709" data_source="lbs_data"> SELECT image, img_extent, image_id FROM my_images </jdbc_image_query> </theme> </themes > </map_request>
MapViewer processes the request in Example 3-5 as follows:
SELECT image, img_extent, image_id FROM my_images) in the current map window context.
image_format="ECW"). Because MapViewer as supplied by Oracle does not support the ECW format, you must implement and register a custom image renderer that supports the format, as explained in Appendix B.
renderImages method, and image data retrieved from the user-supplied query is passed to the method as one of its parameters.
Example 3-6 requests a map with just the map legend but without rendering any spatial data. In this example, the legend explains the symbology used for identifying cities, state boundaries, interstate highways, and county population density. (Map legends are explained in Section 3.2.10.)
<?xml version="1.0" standalone="yes"?> <map_request datasource = "mvdemo" format="PNG_URL"> <legend bgstyle="fill:#ffffff;stroke:#ff0000" profile="MEDIUM" position="SOUTH_EAST"> <column> <entry text="Map 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:" /> <entry style="V.COUNTY_POP_DENSITY" tab="1" /> </column> </legend> </map_request>
Generating just the map legend image, as in Example 3-6, can save processing time if you display the stored map legend image on a Web page separately from the actual displayed maps. This avoids the need to generate a legend each time there is a map request.
This section shows how to use thematic mapping with a pie chart theme. The result is a map in which each county contains a pie chart in which the size of each slice reflects the proportion of the population in a specified household income level category (low, medium, or high) in the county.
The basic steps are as follows.
V.PIECHART1.
INSERT INTO user_sdo_styles VALUES ( 'V.PIECHART1', 'ADVANCED', null, '<?xml version="1.0" ?> <AdvancedStyle> <PieChartStyle pieradius="10"> <PieSlice name="low" color="#ff0000" /> <PieSlice name="medium" color="#ffff00" /> <PieSlice name="high" color="#00ff00" /> </PieChartStyle> </AdvancedStyle>', null, null);
When the style defined in the preceding example is applied to a geographic feature, a pie chart is created with three slices. The pieradius attribute specifies the size of each pie chart in pixels. Each slice (<PieSlice> element) has a color defined for it. The name attribute for each slice is ignored by MapViewer.
INSERT INTO user_sdo_themes VALUES ( 'THEME_PIE_CHART', null, 'COUNTIES', 'GEOM', '<?xml version="1.0" standalone="yes"?> <styling_rules > <rule column="INC_LOW,INC_MED,INC_HIGH" > <features style="C.US MAP YELLOW"> </features> <label column="''dummy''" style="V.PIECHART1"> 1 </label> </rule> </styling_rules>');
In the theme definition in the preceding example, the <label> element of the styling rule specifies style="V.PIECHART1", to indicate that this pie chart style (the style created in step 1) is used to label each geometry displayed on the map.
The column attribute (column="''dummy''" in this example) is required, even though it has no effect on the resulting map. The column attribute value can be dummy or any other string, and the value must be enclosed on both sides by two single quotation marks.
Because the V.PIECHART1 style is defined with three slices, the preceding example must specify the names of three columns from the COUNTIES table, and these columns must have a numeric data type. The column names are INC_LOW, INC_MED, and INC_HIGH. These columns will supply the value that will be used to determine the size of each pie slice.
THEME_PIE_CHART theme that was created in step 2.
<?xml version="1.0" standalone="yes"?> <map_request datasource = "mvdemo" format="PNG_STREAM"> <themes> <theme name="THEME_PIE_CHART" /> </themes> </map_request>
Figure 3-1 shows part of a display resulting from the map request in Example 3-7.
You can also use the pie chart style in a dynamic (JDBC) theme when issuing a map request. You must specify the complete SQL query for a JDBC theme in the map request, because you must identify the attribute columns that are needed by the pie chart style. Any columns in the SELECT list that are not SDO_GEOMETRY columns or label columns are considered to be attribute columns that can be used by an advanced style.
Example 3-8 is a sample request with a JDBC theme using a pie chart style. The SQL query (SELECT geom, `dummy', sales, service, training FROM support_centers) is included in the theme definition.
<?xml version="1.0" standalone="yes"?> <map_request basemap="CA_MAP" datasource = "mvdemo" format="PNG_URL"> > <themes> <theme name="support_center"> <jdbc_query spatial_column="geom" datasource="tilsmenv" label_column="dummy", label_style="V.PIECHART1"> SELECT geom, `dummy', sales, service, training FROM support_centers </jdbc_query> </theme> </themes> </map_request>
Example 3-9 uses the java.net package to send an XML request to MapViewer and to receive the response from MapViewer. (Note, however, most programmers will find it more convenient to use the JavaBean-based API, described in Chapter 4, or the JSP tag library, described in Chapter 5.)
import java.net.*; import java.io.*; /** * A sample program that shows how to interact with MapViewer */ public class MapViewerDemo { private HttpURLConnection mapViewer = null; /** * Initializes this demo with the url to the MapViewer server. * The URL is typically http://my_corp.com:8888/mapviewer/omserver. */ public MapViewerDemo(String mapViewerURLString) { URL url; try { url = new URL(mapViewerURLString); mapViewer = (HttpURLConnection) url.openConnection(); mapViewer.setDoOutput(true); mapViewer.setDoInput(true); mapViewer.setUseCaches(false); } catch (Exception e) { e.printStackTrace(System.err); System.exit(1); } } /** * Submits an XML request to MapViewer. * @param xmlreq the xml document that is a MapViewer request. */ public void submitRequest(String xmlreq) { try { mapViewer.setRequestMethod("POST"); //use HTTP POST method OutputStream os = mapViewer.getOutputStream(); //MapViewer expects to find the request as a parameter //named "xml_request". xmlreq = "xml_request="+URLEncoder.encode(xmlreq); os.write(xmlreq.getBytes()); os.flush(); os.close(); } catch (Exception e) { e.printStackTrace(System.err); System.exit(1); } } /** * Receives an XML response from MapViewer. */ public String getResponse() { ByteArrayOutputStream content = new ByteArrayOutputStream(); InputStream is = null; try { is = mapViewer.getInputStream(); int c; while ((c = is.read()) != -1) content.write(c); is.close(); content.flush(); content.close(); return content.toString(); } catch (Exception e) { e.printStackTrace(System.err); return null; } } // A simple main program that sends a list_data_sources xml // request to MapViewer through HTTP POST. public static void main(String[] args) { if(args.length<1) { System.out.println("Usage: java MapViewerDemo <mapviewer url>"); System.out.println("Example: java MapViewerDemo http://my_ corp.com/mapviewer/omserver"); System.exit(1); } // a sample xml request for MapViewer String listDataSources = "<?xml version=\"1.0\" standalone=\"yes\"?>" + " <non_map_request>" + " <list_data_sources />" + " </non_map_request>"; MapViewerDemo tester = null; tester = new MapViewerDemo(args[0]); System.out.println("submitting request:\n"+listDataSources); tester.submitRequest(listDataSources); String response = tester.getResponse(); System.out.println("response from MapViewer: \n" + response); } }
Example 3-10 is a sample PL/SQL program that sends an XML request to the MapViewer server. This example works only on Oracle Database release 9.0.1 and higher.
set serverout on size 1000000; -- -- Author: Clarke Colombo -- declare l_http_req utl_http.req; l_http_resp utl_http.resp; l_url varchar2(4000):= 'http://my_corp.com:8888/mapviewer/omserver'; l_value varchar2(4000); img_url varchar2(4000); response sys.xmltype; output varchar2(255); map_req varchar2(4000); begin utl_http.set_persistent_conn_support(TRUE); map_req := '<?xml version="1.0" standalone="yes"?> <map_request title="MapViewer Demonstration" datasource="mvdemo" basemap="course_map" width="500" height="375" bgcolor="#a6cae0" antialiasing="false" format="GIF_URL"> <center size="5" > <geoFeature> <geometricProperty> <Point> <coordinates>-122.2615, 37.5266</coordinates> </Point> </geometricProperty> </geoFeature> </center> </map_request>'; l_http_req := utl_http.begin_request(l_url, 'POST', 'HTTP/1.0'); -- -- sets up proper HTTP headers -- utl_http.set_header(l_http_req, 'Content-Type', 'application/x-www-form-urlencoded'); utl_http.set_header(l_http_req, 'Content-Length', length('xml_request=' || map_req)); utl_http.set_header(l_http_req, 'Host', 'my_corp.com'); utl_http.set_header(l_http_req, 'Port', '8888'); utl_http.write_text(l_http_req, 'xml_request=' || map_req); -- l_http_resp := utl_http.get_response(l_http_req); utl_http.read_text(l_http_resp, l_value); response := sys.xmltype.createxml (l_value); utl_http.end_response(l_http_resp); img_url := response.extract('/map_response/map_image/map_ content/@url').getstringval(); dbms_output.put_line(img_url); end; /
The following is the complete DTD for a map request. The main elements and attributes of the DTD are explained in sections that follow.
<?xml version="1.0" encoding="UTF-8"?> <!-- <box> is defined in OGC GML v1.0 --> <!ELEMENT map_request ((box | center)?, srs?, legend?, themes?, geoFeature*)> <!ATTLIST map_request datasource CDATA #REQUIRED basemap CDATA #IMPLIED width CDATA #IMPLIED height CDATA #IMPLIED antialiasing (TRUE|FALSE) "FALSE" imagescaling (TRUE|FALSE) "TRUE" format (GIF|GIF_URL|GIF_STREAM|JAVA_IMAGE|PNG_STREAM|PNG_URL) "GIF_URL" title CDATA #IMPLIED bgcolor (CDATA) "#A6CAF0" bgimage CDATA #IMPLIED > <!ELEMENT center (geoFeature)> <!ATTLIST center size CDATA #REQUIRED > <!ELEMENT srs (#PCDATA) > <!ELEMENT themes (theme+) > <!ELEMENT theme (jdbc_query | jdbc_image_query)? > <!ATTLIST theme name CDATA #REQUIRED max_scale CDATA #IMPLIED min_scale CDATA #IMPLIED label_always_on (TRUE|FALSE) "FALSE" > <!ELEMENT jdbc_query (#PCDATA)> <!ATTLIST jdbc_query asis (TRUE|FALSE) "FALSE" spatial_column CDATA #REQUIRED label_column CDATA #IMPLIED label_style CDATA #IMPLIED render_style CDATA #IMPLIED datasource CDATA #IMPLIED jdbc_host CDATA #IMPLIED jdbc_port CDATA #IMPLIED jdbc_sid CDATA #IMPLIED jdbc_user CDATA #IMPLIED jdbc_password CDATA #IMPLIED jdbc_srid CDATA #IMPLIED jdbc_mode (thin|oci8) "thin" > <!ELEMENT jdbc_image_query (#PCDATA) > <!ATTLIST jdbc_image_query asis (TRUE|FALSE) "FALSE" image_format CDATA #REQUIRED image_column CDATA #REQUIRED image_mbr_column CDATA #REQUIRED image_resolution CDATA #IMPLIED image_unit CDATA #IMPLIED datasource CDATA #IMPLIED jdbc_host CDATA #IMPLIED jdbc_port CDATA #IMPLIED jdbc_sid CDATA #IMPLIED jdbc_user CDATA #IMPLIED jdbc_password CDATA #IMPLIED jdbc_srid CDATA #IMPLIED jdbc_mode (thin|oci8) "thin" > <!ELEMENT geoFeature (description?, property*, geometricProperty)> <!ATTLIST geoFeature typeName CDATA #IMPLIED id CDATA #IMPLIED label CDATA #IMPLIED render_style CDATA #IMPLIED text_style CDATA #IMPLIED label_always_on (TRUE|FALSE) "FALSE" marker_size CDATA #IMPLIED radius CDATA #IMPLIED > <!ELEMENT legend column+ > <!ATTLIST legend bgstyle CDATA #implied profile (MEDIUM|SMALL|LARGE) "MEDIUM" > <!ELEMENT column entry+ > <!ATTLIST entry is_separator (true|false) "false" tab CDATA "0" style CDATA #implied text CDATA #implied >
The <map_request> element has the following definition:
<!ELEMENT map_request ((box | center)?, srs?, themes?, geoFeature*)>
The root element of a map request to MapViewer is always named map_request.
<map_request> can have a child element that is either <box> (see Section 3.2.3) or <center> (see Section 3.2.4), which specifies the range of the user data to be plotted on a map. If neither box nor center is specified, the result map is drawn using all data available to MapViewer.
The optional <SRS> child element is ignored by the current version of MapViewer.
The optional <themes> element (see Section 3.2.5) specifies predefined or dynamically defined themes.
The <geoFeature> element (see Section 3.2.9) can be used to specify any number of individual geometries and their rendering attributes.
MapViewer first draws the themes defined in a base map (if a base map is specified as an attribute in the root element), then any user-provided themes, and finally any geoFeature elements.
The root element <map_request> has a number of attributes, some required and the others optional. The attributes are defined as follows:
<!ATTLIST map_request datasource CDATA #REQUIRED basemap CDATA #IMPLIED width CDATA #IMPLIED height CDATA #IMPLIED antialiasing (TRUE|FALSE) "FALSE" imagescaling (TRUE|FALSE) "TRUE" format (GIF|GIF_URL|GIF_STREAM|JAVA_IMAGE|PNG_STREAM|PNG_URL) "GIF_URL" title CDATA #IMPLIED bgcolor (CDATA) "#A6CAF0" bgimage CDATA #IMPLIED >
datasource is a required attribute that specifies a data source. A data source provides information to MapViewer about where to fetch the user data (and the mapping metadata) that are required to render a map.
basemap is an optional attribute. When it is specified, MapViewer renders all themes that are specified for this base map. The definition of a base map is stored in the user's USER_SDO_MAPS view, as described in Section 2.5.1. Use this attribute if you will always need a background map on which to plot your own themes and geometry features.
width and height are required attributes that together specify the size (in device units) of the resulting map image. This size is different from the size specified in the center element or box element, which is the range of the window into a user's source data.
antialiasing is an optional attribute. When its value is TRUE, 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). (For backward compatibility, antialiase is a synonym for antialiasing, but you are encouraged to use antialiasing.)
imagescaling is an optional attribute. When its value is TRUE (the default), 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 attribute has no effect when no image theme is involved in a map request.
format is an optional attribute that specifies the file format of the returned map image. The default value is GIF_URL, which is a URL to a GIF image stored on the MapViewer host system. If you specify GIF, the generated GIF image data is embedded in a MapResponse object and returned to the client. If you specify GIF_STREAM, the generated image map content is returned directly to the client through the HTTP MIME type image/gif. If you specify JAVA_IMAGE, a Java 2D BufferedImage object with a color model of TYPE_INT_RGB is embedded in a MapResponse object and returned to the client. If you specify PNG_STREAM, the stream of the image in PNG format is returned directly; if you specify PNG_URL, a URL to a PNG image stored on the MapViewer host system is returned. (The PNG image format has some advantages over the GIF format, including faster image encoding and true color support.)
title is an optional attribute that specifies the map title to be displayed on the top of the resulting map image.
bgcolor is an optional attribute that specifies the background color in the resulting map image. The default is water-blue (RGB value #A6CAF0). It must be specified as a hexadecimal value.
bgimage is an optional attribute that specifies the background image (GIF or JPEG format only) in the resulting map image. The image is retrieved at runtime 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.
The <box> element has the following definition:
<!ELEMENT Box (coordinates) > <!ATTLIST Box ID CDATA #IMPLIED srsName CDATA #REQUIRED >
The <box> element is used to specify the bounding box of a resulting map. It uses a <coordinates> element to specify two coordinate value pairs that identify the lower-left and upper-right corners of the rectangle. The coordinate values are interpreted in terms of the user's data. For example, if the user's data is geodetic and is specified in decimal degrees of longitude and latitude, a <coordinates> specification of -72.84, 41.67, -70.88, 42.70 indicates a bounding box with the lower-left corner at longitude-latitude coordinates (-72.84, 41.67) and the upper-right corner at coordinates (-70.88, 42.70), which are in the New England region of the United States. However, if the data is projected with meter as its unit of measurement, the coordinate values are interpreted in meters.
The <center> element has the following definition:
<!ELEMENT center (geoFeature)> <!ATTLIST center size CDATA #REQUIRED >
The <center> element is used to specify the center of a resulting map. It has a required attribute named size, which specifies the vertical span of the map in terms of the original data unit. For example, if the user's data is in decimal degrees, the size attribute specifies the number of decimal degrees in latitude. If the user's data is projected with meter as its unit, MapViewer interprets the size in meters.
The center itself must embed a <geoFeature> element, which is specified in Section 3.2.9.
The <themes> element has the following definition:
<!ELEMENT themes (theme+) >
The <themes> element specifies one or more <theme> elements (described in Section 3.2.6). If you have specified a base map (basemap attribute of the map_request element), any themes that you specify in a <themes> element are plotted after those defined in the base map. If no base map is specified, only the specified themes are rendered.
Inside this <themes> element, there must be one or more <theme> child elements, which are rendered in the order in which they appear.
The <theme> element has the following definition:
<!ELEMENT theme (jdbc_query | jdbc_image_query)? > <!ATTLIST theme name CDATA #REQUIRED max_scale CDATA #IMPLIED min_scale CDATA #IMPLIED label_always_on (TRUE|FALSE) "FALSE" >
The <theme> element lets you specify a predefined or dynamically defined theme.
<jdbc_query> element (described in Section 3.2.7) or a <jdbc_image_query> element (described in Section 3.2.8).
The name attribute identifies the theme name. For a predefined theme, the name must match a value in the NAME column of the USER_SDO_THEMES view (described in Section 2.5.2). For a dynamically defined theme, this is just a temporary name for referencing the jdbc_query-based theme.
The max_scale and min_scale attributes affect the visibility of this theme. If max_scale and min_scale are omitted, the theme is always rendered, regardless of the map scale. (See Section 2.4.1 for an explanation of max_scale and min_scale.)
label_always_on is an optional attribute. If it is set to TRUE, MapViewer labels all features of the theme even if two or more labels will overlap in the display. (MapViewer always tries to avoid overlapping labels.) If label_always_on is FALSE (the default), when it is impossible to avoid overlapping labels, MapViewer disables the display of one or more labels so that no overlapping occurs. The label_always_on attribute can also be specified for a map feature (geoFeature element, described in Section 3.2.9), thus allowing you to control which features will have their labels displayed if label_always_on is FALSE for a theme and if overlapping labels cannot be avoided.
The <jdbc_query> element, which is used to define a theme dynamically, has the following definition:
<!ELEMENT jdbc_query (#PCDATA)> <!ATTLIST jdbc_query asis (TRUE|FALSE) "FALSE" spatial_column CDATA #REQUIRED label_column CDATA #IMPLIED label_style CDATA #IMPLIED render_style CDATA #IMPLIED datasource CDATA #IMPLIED jdbc_host CDATA #IMPLIED jdbc_port CDATA #IMPLIED jdbc_sid CDATA #IMPLIED jdbc_user CDATA #IMPLIED jdbc_password CDATA #IMPLIED jdbc_srid CDATA #IMPLIED jdbc_mode (thin|oci8) "thin" >
To define a theme dynamically, you must supply a valid SQL query as the content of the <jdbc_query> element. You must specify the spatial_column (column of type MDSYS.SDO_GEOMETRY) and the JDBC connection information for a dynamically defined theme (either datasource or the combination of jdbc_host, jdbc_port, jdbc_sid, jdbc_user, and jdbc_password).
render_style and label_style are optional attributes. For render_style, 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.
jdbc_srid is an optional attribute that specifies the coordinate system (SDO_SRID value) of the data to be rendered.
jdbc_mode identifies the Oracle JDBC driver (thin or oci8) to use to connect to the database.
asis is an optional attribute. If it is set to TRUE, MapViewer does not attempt to modify the supplied query string. If asis is FALSE (the default), MapViewer embeds the SQL query as a subquery of its spatial filter query. For example, assume that you want a map centered at (-122, 37) with size 1, and the supplied query is:
SELECT geometry, sales FROM crm_sales WHERE sales < 100000;
If asis is FALSE, the actual query that MapViewer executes is similar to:
SELECT * FROM (SELECT geometry, sales FROM crm_sales WHERE sales < 100000) WHERE sdo_filter(geometry, sdo_geometry(... -122.5, 36.5, -123.5, 37.5...) ='TRUE';
In other words, the original query is further refined by a spatial filter query using the current map window. However, if asis is TRUE, MapViewer executes the query as specified, namely:
SELECT geometry, sales FROM crm_sales WHERE sales < 100000;
For examples of using the <jdbc_query> element to define a theme dynamically, see Example 3-2 in Section 3.1.2 and Example 3-4 in Section 3.1.4.
The <jdbc_image_query> element, which is used to define an image theme (described in Section 2.3.4), has the following definition:
<!ELEMENT jdbc_image_query (#PCDATA) > <!ATTLIST jdbc_image_query asis (TRUE|FALSE) "FALSE" image_format CDATA #REQUIRED image_column CDATA #REQUIRED image_mbr_column CDATA #REQUIRED image_resolution CDATA #IMPLIED image_unit CDATA #IMPLIED datasource CDATA #IMPLIED jdbc_host CDATA #IMPLIED jdbc_port CDATA #IMPLIED jdbc_sid CDATA #IMPLIED jdbc_user CDATA #IMPLIED jdbc_password CDATA #IMPLIED jdbc_srid CDATA #IMPLIED jdbc_mode (thin|oci8) "thin" >
To define a theme dynamically, you must supply a valid SQL query as the content of the <jdbc_image_query> element. You must specify the JDBC connection information for an image theme (either datasource or the combination of jdbc_host, jdbc_port, jdbc_sid, jdbc_user, and jdbc_password).
jdbc_srid is an optional attribute that specifies the coordinate system (SDO_SRID value) of the data to be rendered.
jdbc_mode identifies the Oracle JDBC driver (thin or oci8) to use to connect to the database.
asis is an optional attribute. If it is set to TRUE, MapViewer does not attempt to modify the supplied query string. If asis is FALSE (the default), MapViewer embeds the SQL query as a subquery of its spatial filter query. For example, assume that you want a map centered at (-122, 37) with size 1, and the supplied query is:
SELECT geometry, sales FROM crm_sales WHERE sales < 100000;
If asis is FALSE, the actual query that MapViewer executes is similar to:
SELECT * FROM (SELECT geometry, sales FROM crm_sales WHERE sales < 100000) WHERE sdo_filter(geometry, sdo_geometry(... -122.5, 36.5, -123.5, 37.5...) ='TRUE';
In other words, the original query is further refined by a spatial filter query for current map window. However, if asis is TRUE, MapViewer executes the query as specified, namely:
SELECT geometry, sales FROM crm_sales WHERE sales < 100000;
image_format identifies the format (such as GIF or JPEG) of the image data. If the image format is not supported by MapViewer, you must create and register a custom image renderer for the format, as explained in Appendix B.
image_column identifies the column of type BLOB where each image is stored.
image_mbr_column identifies the column of type SDO_GEOMETRY where the footprint (minimum bounding rectangle, or MBR) of each image is stored.
image_resolution is an optional attribute that identifies the original image resolution (number of image_unit units for each pixel).
image_unit is an optional attribute, except it is required if you specify the image_resolution attribute. The image_unit attribute specifies the unit of the resolution, such as M for meter. The value for this attribute must be one of the values in the SDO_UNIT column of the MDSYS.SDO_DIST_UNITS table. In Example 2-11 in Section 2.3.4.1, the image resolution is 2 meters per pixel.
For an example of using the <jdbc_image_query> element to specify an image theme, see Example 3-5 in Section 3.1.5.
The <geoFeature> element has the following definition:
<!ELEMENT geoFeature (description?, property*, geometricProperty)> <!ATTLIST geoFeature typeName CDATA #IMPLIED id CDATA #IMPLIED render_style CDATA #IMPLIED text_style CDATA #IMPLIED label CDATA #IMPLIED label_always_on (TRUE|FALSE) "FALSE" marker_size CDATA #IMPLIED radius CDATA #IMPLIED >
<geoFeature> elements are used to provide individual geospatial entities to be rendered on a map. The main part of a <geoFeature> element is the geometry (<geometricProperty> element), which must be supplied in compliance with the OGC GML v1.0 Geometry DTD (described in Section 3.6).
typeName is an optional attribute that is ignored by the current release of MapViewer.
id is an optional attribute that is ignored by the current release of MapViewer.
render_style is an optional attribute. When it is omitted, the geoFeature is not rendered. If it is supplied, its value must be the name of a style stored in the user's USER_SDO_STYLES view.
text_style is an optional attribute. If it is supplied (and if the render_style and label attributes are present and valid), it identifies the style to be used in labeling the geoFeature. If it is not specified, a default text style is used.
label is an optional attribute. If it is supplied (and if the render_style and label attributes are present and valid), it identifies text that is used to label the geoFeature.
label_always_on is an optional attribute. If it is set to TRUE, MapViewer labels the features even if two or more labels will overlap in the display of a theme. (MapViewer always tries to avoid overlapping labels.) If label_always_on is FALSE (the default), when it is impossible to avoid overlapping labels, MapViewer disables the display of one or more labels so that no overlapping occurs. The label_always_on attribute can also be specified for a theme (theme element, described in Section 3.2.6). Specifying label_always_on as TRUE for a feature in the geoFeature element definition gives you control over which features will have their labels displayed if label_always_on is FALSE for a theme and if overlapping labels cannot be avoided.
marker_size is an optional attribute. If it is supplied with a point geoFeature, and if render_style is a marker-type style, the specified size is used by MapViewer in rendering this geoFeature. This provides a mechanism to override the default value specified for a marker style.
radius is an optional attribute. If it is supplied, it specifies a number or a comma-delimited list of numbers, with each number representing the radius of a circle to be drawn centered on this feature. For geodetic data, the unit is meters; for non-geodetic data, the unit is the unit of measurement associated with the data.
The following example shows a <geoFeature> element specification for a restaurant at longitude and latitude coordinates (-78.1234, 41.0346). In this case, the feature will be invisible because the render_style and text_style attributes are not specified.
<geoFeature typeName="Customer" label="PizzaHut in Nashua"> <geometricProperty> <Point srsName="SDO:8265"> <coordinates>-78.1234,41.0346</coordinates> </Point> </geometricProperty> </geoFeature>
The following example shows a <geoFeature> element specification for a point of interest at longitude and latitude coordinates (-122.2615, 37.5266). The feature will be rendered on the generated map because the render_style attribute is specified. The example specifies some label text (A Place) and a text style for drawing the label text. It also instructs MapViewer to draw two circles, centered on this feature, with radii of 1600 and 4800 meters. (In this case, the srsName attribute of the <Point> element must be present, and it must specify an Oracle Spatial SRID value using the format "SDO:<srid>". Because SRID value 8265 is associated with a geodetic coordinate system, the radius values are interpreted as 1600 and 4800 meters.)
<geoFeature render_style="m.star" radius="1600,4800" label="A Place" text_style="T.Name" > <geometricProperty > <Point srsName="SDO:8265"> <coordinates>-122.2615, 37.5266</coordinates> </Point> </geometricProperty> </geoFeature>
Figure 3-2 is a map drawn using the <geoFeature> element in the preceding example. The feature is labeled with the text A Place, and it is represented by a red star marker surrounded by two concentric circles.
The <legend> element has the following definition:
<!ELEMENT legend column+ > <!ATTLIST legend bgstyle CDATA #implied profile (MEDIUM|SMALL|LARGE) "MEDIUM" position (SOUTH_WEST|SOUTH_EAST|SOUTH|NORTH| NORTH_WEST|NORTH_EAST|EAST|WEST|CENTER) "SOUTH_WEST" > <!ELEMENT column entry+ > <!ATTLIST entry is_title (true|false) "false" is_separator (true|false) "false" tab CDATA "0" style CDATA #implied text CDATA #implied >
<legend> elements are used to draw a legend (map inset illustration) on top of a generated map, to make the visual aspects of the map more meaningful to users. The main part of a <legend> element is one or more <column> elements, each of which defines a column in the legend. A one-column legend will have all entries arranged from top to bottom. A two-column legend will have the two columns side by side, with the first column on the left, and each column having its own legend entries. Figure 2-2 in Section 2.4.2 shows a one-column legend. Figure 3-3 shows a two-column legend.
bgstyle is an optional attribute that specifies the overall background style of the legend. It uses a string with syntax similar to scalable vector graphics (SVG) to specify the fill and stroke colors for the bounding box of the legend. If you specify an opacity (fill-opacity or stroke-opacity) value, the fill and stroke colors can be transparent or partially transparent. The following example specifies a background that is white and half transparent, and a stroke (for the legend box boundary) that is red:
bgstyle="fill:#ffffff;fill-opacity:128;stroke:#ff0000"
profile is an optional attribute that specifies a relative size of the legend on the map, using one of the following keywords: SMALL, MEDIUM (the default), or LARGE.
position is an optional attribute that specifies where the legend should be drawn on the map. The default is SOUTH_WEST, which draws the legend in the lower-left corner of the resulting map.
is_title is an optional attribute of the <entry> element. When its value is TRUE, the entry is used as the title for the column, which means that the description text appears in a more prominent font than regular legend text, and any other style attribute defined for the entry is ignored. The default is FALSE.
is_separator is an optional attribute of the <entry> element. When its value is TRUE, the entry is used to insert a blank line for vertical spacing in the column. The default is FALSE.
tab is an optional attribute of the <entry> element. It specifies the number of tab positions to indent the entry from the left margin of the column. The default is 0 (zero), which means no indentation.
style is an optional attribute of the <entry> element. It specifies the name of the MapViewer style (such as a color or an image) to be depicted as part of the entry.
text is an optional attribute of the <entry> element. It specifies the description text (for example, a short explanation of the associated color or image) to be included in the entry.
The following example shows the <legend> element specification for the legend in Figure 2-2 in Section 2.4.2.
<legend bgstyle="fill:#ffffff;fill-opacity:128;stroke:#ff0000" position="NORTH_WEST"> <column> <entry text="Map 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:" /> <entry style="V.COUNTY_POP_DENSITY" tab="1" /> </column> </legend>
In the preceding example:
fill-opacity:128), which means that the white background will be half transparent.
stroke:#ff0000).
profile attribute (which has a default value of MEDIUM) is not specified.
style="V.COUNTY_POP_DENSITY"), and it is indented one tab position (tab="1") so that the colors and text identifying various population density ranges will be easy for users to distinguish from the preceding County population: description text.
In addition to issuing map requests (see Section 3.2) and administrative requests (see Chapter 6), you can issue information requests to MapViewer. An information request is an XML request string that you can use to execute SQL queries and obtain the result as an array of strings or an XML document. The SQL query must be a SELECT statement and must select only primitive SQL types (for example, not LOB types or user-defined object types).
The following is the DTD for a MapViewer information request.
<!ELEMENT info_request (#PCDATA) > <!ATTLIST info_request datasource CDATA #REQUIRED format (strict | non-strict) "strict" >
datasource is a required attribute that specifies the data source for which to get the information.
format is an optional attribute. If it is strict (the default), all rows are formatted and returned in an XML document. If format is set to non-strict, all rows plus a column heading list are returned in a comma-delimited text string.
Example 3-11 shows an information request to select the city, 1990 population, and state abbreviation from the CITIES table, using the connection information in the mvdemo data source and returning the information as an XML document (format="strict").
<?xml version="1.0" standalone="yes"?> <info_request datasource="mvdemo" format="strict" > SELECT city, pop90 population, state_abrv state FROM cities </info_request>
Example 3-11 returns an XML document that includes the following:
<?xml version="1.0" encoding="UTF-8"?> <ROWSET> <ROW num="1"> <CITY>New York</CITY> <POPULATION>7322564</POPULATION> <STATE>NY</STATE> </ROW> <ROW num="2"> <CITY>Los Angeles</CITY> <POPULATION>3485398</POPULATION> <STATE>CA</STATE> </ROW> <ROW num="3"> <CITY>Chicago</CITY> <POPULATION>2783726</POPULATION> <STATE>IL</STATE> </ROW> <ROW num="4"> <CITY>Houston</CITY> <POPULATION>1630553</POPULATION> <STATE>TX</STATE> </ROW> . . . </ROWSET>
The following is the DTD for the map response resulting from normal processing of a map request. (Section 3.5 shows the DTD for the response if there was an exception or unrecoverable error.)
<!ELEMENT map_response (map_image)> <!ELEMENT map_image (map_content, box, WMTException)> <!ELEMENT map_content EMPTY> <!ATTLIST map_content url CDATA #REQUIRED> <!ELEMENT WMTException (#PCDATA)> <!ATTLIST WMTException version CDATA "1.0.0" error_code (SUCCESS|FAILURE) #REQUIRED >
The response includes the URL for retrieving the image, as well as any error information. When a valid map is generated, its minimum bounding box is also returned.
Example 3-12 shows a map response.
<?xml version="1.0" encoding="UTF-8" ?> <map_response> <map_image> <map_content url="http://map.oracle.com/output/map029763.gif" /> <box srsName="default"> <coordinates>-122.260443,37.531621 -120.345,39.543</coordinates> </box> <WMTException version="1.0.0" error_code="SUCCESS"> </WMTException> </map_image> </map_response>
The following DTD is used by the output XML when an exception or unrecoverable error is encountered while processing a map request:
<!ELEMENT oms_error (#PCDATA)>
The exception or error message is embedded in this element.
This section contains the Geometry DTD as defined in the Open GIS Consortium (OGC) GML v1.0 specification, which is available at the following URL:
http://www.opengis.org/techno/specs/00-029/GML.html
The specification has the following copyright information:
Copyright © 2000 OGC All Rights Reserved.
The specification has the following status information:
This document is an OpenGIS® Consortium Recommendation Paper. It is similar to a proposed recommendation in other organizations. While it reflects a public statement of the official view of the OGC, it does not have the status of a OGC Technology Specification. It is anticipated that the position stated in this document will develop in response to changes in the underlying technology. Although changes to this document are governed by a comprehensive review procedure, it is expected that some of these changes may be significant. The OGC explicitly invites comments on this document. Please send them to gml.rfc@opengis.org
The following additional legal notice text applies to the specification:
THIS DOCUMENT IS PROVIDED "AS IS," AND COPYRIGHT HOLDERS MAKE NO REPRESENTATIONS OR WARRANTIES, EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, NON-INFRINGEMENT, OR TITLE; THAT THE CONTENTS OF THE DOCUMENT ARE SUITABLE FOR ANY PURPOSE; NOR THAT THE IMPLEMENTATION OF SUCH CONTENTS WILL NOT INFRINGE ANY THIRD PARTY PATENTS, COPYRIGHTS, TRADEMARKS OR OTHER RIGHTS COPYRIGHT HOLDERS WILL NOT BE LIABLE FOR ANY DIRECT, INDIRECT, SPECIAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF ANY USE OF THE DOCUMENT OR THE PERFORMANCE OR IMPLEMENTATION OF THE CONTENTS THEREOF.
The OGC Geometry DTD is as follows:
<!-- ============================================================== --> <!-- G e o g r a p h y --> <!-- M a r k u p --> <!-- L a n g u a g e --> <!-- --> <!-- ( G M L ) --> <!-- --> <!-- G E O M E T R Y D T D --> <!-- --> <!-- Copyright (c) 2000 OGC All Rights Reserved. --> <!-- ============================================================== --> <!-- the coordinate element holds a list of coordinates as parsed character data. Note that it does not reference a SRS and does not constitute a proper geometry class. --> <!ELEMENT coordinates (#PCDATA) > <!ATTLIST coordinates decimal CDATA #IMPLIED cs CDATA #IMPLIED ts CDATA #IMPLIED > <!-- the Box element defines an extent using a pair of coordinates and a SRS name. --> <!ELEMENT Box (coordinates) > <!ATTLIST Box ID CDATA #IMPLIED srsName CDATA #REQUIRED > <!-- ============================================================== --> <!-- G E O M E T R Y C L A S S D e f i n i t i o n s --> <!-- ============================================================== --> <!-- a Point is defined by a single coordinate. --> <!ELEMENT Point (coordinates) > <!ATTLIST Point ID CDATA #IMPLIED srsName CDATA #IMPLIED > <!-- a LineString is defined by two or more coordinates, with linear interoplation between them. --> <!ELEMENT LineString (coordinates) > <!ATTLIST LineString ID CDATA #IMPLIED srsName CDATA #IMPLIED > <!-- a Polygon is defined by an outer boundary and zero or more inner boundaries. These boundaries are themselves defined by LinerRings. --> <!ELEMENT Polygon (outerBoundaryIs, innerBoundaryIs*) > <!ATTLIST Polygon ID CDATA #IMPLIED srsName CDATA #IMPLIED > <!ELEMENT outerBoundaryIs (LinearRing) > <!ELEMENT innerBoundaryIs (LinearRing) > <!-- a LinearRing is defined by four or more coordinates, with linear interpolation between them. The first and last coordinates must be coincident. --> <!ELEMENT LinearRing (coordinates) > <!ATTLIST LinearRing ID CDATA #IMPLIED > <!-- a MultiPoint is defined by zero or more Points, referenced through a pointMember element. --> <!ELEMENT MultiPoint (pointMember+) > <!ATTLIST MultiPoint ID CDATA #IMPLIED srsName CDATA #IMPLIED > <!ELEMENT pointMember (Point) > <!-- a MultiLineString is defined by zero or more LineStrings, referenced through a lineStringMember element. --> <!ELEMENT MultiLineString (lineStringMember+) > <!ATTLIST MultiLineString ID CDATA #IMPLIED srsName CDATA #IMPLIED > <!ELEMENT lineStringMember (LineString) > <!-- a MultiPolygon is defined by zero or more Polygons, referenced through a polygonMember element. --> <!ELEMENT MultiPolygon (polygonMember+) > <!ATTLIST MultiPolygon ID CDATA #IMPLIED srsName CDATA #IMPLIED > <!ELEMENT polygonMember (Polygon) > <!-- a GeometryCollection is defined by zero or more geometries, referenced through a geometryMember element. A geometryMember element may be any one of the geometry classes. --> <!ENTITY % GeometryClasses "( Point | LineString | Polygon | MultiPoint | MultiLineString | MultiPolygon | GeometryCollection )" > <!ELEMENT GeometryCollection (geometryMember+) > <!ATTLIST GeometryCollection ID CDATA #IMPLIED srsName CDATA #IMPLIED > <!ELEMENT geometryMember %GeometryClasses; > <!-- ============================================================== --> <!-- G E O M E T R Y P R O P E R T Y D e f i n i t i o n s --> <!-- ============================================================== --> <!-- GML provides an 'endorsed' name to define the extent of a feature. The extent is defined by a Box element, the name of the property is boundedBy. --> <!ELEMENT boundedBy (Box) > <!-- the generic geometryProperty can accept a geometry of any class. --> <!ELEMENT geometryProperty (%GeometryClasses;) > <!-- the pointProperty has three descriptive names: centerOf, location and position. --> <!ELEMENT pointProperty (Point) > <!ELEMENT centerOf (Point) > <!ELEMENT location (Point) > <!ELEMENT position (Point) > <!-- the lineStringProperty has two descriptive names: centerLineOf and edgeOf. --> <!ELEMENT lineStringProperty (LineString) > <!ELEMENT centerLineOf (LineString)> <!ELEMENT edgeOf (LineString)> <!-- the polygonProperty has two descriptive names: coverage and extentOf. --> <!ELEMENT polygonProperty (Polygon) > <!ELEMENT coverage (Polygon)> <!ELEMENT extentOf (Polygon)> <!-- the multiPointProperty has three descriptive names: multiCenterOf, multiLocation and multiPosition. --> <!ELEMENT multiPointProperty (MultiPoint) > <!ELEMENT multiCenterOf (MultiPoint) > <!ELEMENT multiLocation (MultiPoint) > <!ELEMENT multiPosition (MultiPoint) > <!-- the multiLineStringProperty has two descriptive names: multiCenterLineOf and multiEdgeOf. --> <!ELEMENT multiLineStringProperty (MultiLineString) > <!ELEMENT multiCenterLineOf (MultiLineString) > <!ELEMENT multiEdgeOf (MultiLineString) > <!-- the multiPolygonProperty has two descriptive names: multiCoverage and multiExtentOf. --> <!ELEMENT multiPolygonProperty (MultiPolygon) > <!ELEMENT multiCoverage (MultiPolygon) > <!ELEMENT multiExtentOf (MultiPolygon) > <!ELEMENT geometryCollectionProperty (GeometryCollection) > <!-- ============================================================== --> <!-- F E A T U R E M E T A D A T A D e f i n i t i o n s --> <!-- ============================================================== --> <!-- Feature metadata, included in GML Geometry DTD for convenience; name and description are two 'standard' string properties defined by GML. --> <!ELEMENT name (#PCDATA)> <!ELEMENT description (#PCDATA)>
|
 Copyright © 2001, 2003 Oracle Corporation. All Rights Reserved. |
|