3 OracleAS MapViewer Map Request XML API

3.1.1 Simple Map Request

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

3.1.2 Map Request with Dynamically Defined Theme

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>

3.1.3 Map Request with Base Map, Center, and Additional Predefined Theme

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>

• Because basemap is specified, OracleAS MapViewer first draws all predefined themes for that base map before drawing the specified theme (poi_theme_us_restaurants).

• The center will be drawn with a marker of the M.MOTEL style and the label Motel 1 in the T.MOTEL style.

• A circle with a radius of 300 meters will be drawn around the center.

3.1.4 Map Request with Center, Base Map, Dynamically Defined Theme, and Other Features

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

3.1.5 Map Request for Point Features with Attribute Value and Dynamically Defined Variable Marker Style

Example 3-5 shows a map request to render point features with a dynamically defined variable marker style. The attribute_values attribute defines the value that will be used to find the appropriate bucket (for the range into which the value falls), as defined in the variable marker style.

<?xml version="1.0" standalone="yes"?>
<map_request
  title="Point Features with Variable Marker Style"
  datasource="mvdemo"
  srid="0"
  width="500"
  height="375"
  bgcolor="#a6caf0"
  antialiase="true"
  format="PNG_URL">
  <center size="19.2">
    <geoFeature>
      <geometricProperty typeName="center">
        <Point>
          <coordinates>-116.65,38.92</coordinates>
        </Point>
      </geometricProperty>
    </geoFeature>
  </center>
  <geoFeature
     render_style="varmarkerpf"
     attribute_values="50000.0">
    <geometricProperty>
      <Point>
        <coordinates>-112.0,43.0</coordinates>
      </Point>
    </geometricProperty>
  </geoFeature>
  <geoFeature
     render_style="varmarkerpf"
     attribute_values="125000.0">
    <geometricProperty>
      <Point>
        <coordinates>-123.0,40.0</coordinates>
      </Point>
    </geometricProperty>
  </geoFeature>
  <geoFeature
     render_style="varmarkerpf"
     attribute_values="200000.0">
    <geometricProperty>
      <Point>
        <coordinates>-116.64,38.92</coordinates>
      </Point>
    </geometricProperty>
  </geoFeature>
  <geoFeature
     render_style="varmarkerpf"
   attribute_values="300000.0">
    <geometricProperty>
      <Point>
        <coordinates>-112.0,35.0</coordinates>
      </Point>
    </geometricProperty>
  </geoFeature>
  <styles>
    <style name="varmarkerpf">
        <AdvancedStyle>
           <VariableMarkerStyle basemarker="mkcircle" startsize="10"
                                increment="5">
             <Buckets>
             <RangedBucket label="less than 100k" high="100000.0"/>
             <RangedBucket label="100k - 150k" low="100000.0" high="150000.0"/>
             <RangedBucket label="150k - 250k" low="150000.0" high="250000.0"/>
             <RangedBucket label="250k - 350k" low="250000.0" high="350000.0"/>
              </Buckets>
           </VariableMarkerStyle>
        </AdvancedStyle>
    </style>
 
    <style name="mkcircle">
      <svg>
        <g class="marker" style="stroke:blue;fill:red;">
          <circle r="20"/>
          </g>
        </svg>
    </style>
 
  </styles>
</map_request>

3.1.6 Map Request with an Image Theme

Example 3-6 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.5.)

<?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"
                          datasource="lbs_data">
        SELECT image, img_extent, image_id FROM my_images
      </jdbc_image_query>
    </theme>
  </themes>
</map_request>

1. OracleAS MapViewer retrieves the image data by executing the user-supplied query (SELECT image, img_extent, image_id FROM my_images) in the current map window context.

2. OracleAS MapViewer checks its internal list of all registered image renderers to see if one supports the ECW format (image_format="ECW"). Because OracleAS 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 C.

3. OracleAS MapViewer calls the renderImages method, and image data retrieved from the user-supplied query is passed to the method as one of its parameters.

4. OracleAS MapViewer retrieves and renders any requested vector data on top of the rendered image.

3.1.7 Map Request for Image of Map Legend Only

Example 3-7 requests a map with just the image of 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.11.)

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

3.1.8 Map Request with SRID Different from Data SRID

Example 3-8 requests a map displayed in a coordinate system (srid="32775" for US - Equal Area Projection) that is different from the coordinate system associated with the county theme data (jdbc_srid="8265" for Longitude/Latitude - NAD 83). As a result, during the rendering process, OracleAS MapViewer converts all geometries from the data SRID to the map request SRID.

If no coordinate system is associated with the theme data, OracleAS MapViewer assumes that the data is associated with the coordinate system of the map request, and no conversion occurs.

<?xml version="1.0" standalone="yes"?>
<map_request
  title="US Counties: Equal-Area Projection (SRID=32775)"
  datasource="mvdemo"
  srid="32775"
  width="500"
  height="375"
  bgcolor="#a6caf0"
  antialiase="true"
  format="PNG_URL">
  <center size="4000000.0">
    <geoFeature>
      <geometricProperty typeName="center">
        <Point>
          <coordinates>-218191.9643,1830357.1429</coordinates>
        </Point>
      </geometricProperty>
    </geoFeature>
  </center>
  <themes>
    <theme name="county_th" user_clickable="false">
       <jdbc_query
         spatial_column="geom"
         render_style="C.COUNTIES"
         jdbc_srid="8265"
         datasource="mvdemo"
         asis="false">select geom from counties</jdbc_query>
     </theme>
  </themes>
</map_request>

3.1.9 Map Request Using a Pie Chart Theme

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.

1. Create an advanced style that defines the characteristics of the pie charts to be used. The following example creates an advanced style named 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 OracleAS MapViewer.

2. Create a new theme that uses the style that you created, as in the following example:

   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.

3. Issue a map request that uses the theme that you created. Example 3-9 requests a map that uses the 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 Map Display Using a Pie Chart Theme

Description of "Figure 3-1 Map Display Using a Pie Chart Theme"

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

3.1.10 Java Program Using OracleAS MapViewer

Example 3-11 uses the java.net package to send an XML request to OracleAS MapViewer and to receive the response from OracleAS 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 OracleAS MapViewer
 */
public class MapViewerDemo
{
    private HttpURLConnection mapViewer = null;

    /**
     * Initializes this demo with the URL to the OracleAS 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 OracleAS MapViewer.
     * @param xmlreq   the XML document that is an OracleAS MapViewer request
     */
    public void submitRequest(String xmlreq)
    {
        try
        {
            mapViewer.setRequestMethod("POST");  //Use HTTP POST method.
            OutputStream os = mapViewer.getOutputStream();
            //OracleAS 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 OracleAS 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 OracleAS 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 OracleAS 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);
    }
}

3.1.11 PL/SQL Program Using OracleAS MapViewer

Example 3-12 is a sample PL/SQL program that sends an XML request to the OracleAS MapViewer server. This example works only on Oracle9i Release 9.0.1 and later releases.

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;
/

3.2.1 map_request Element

The <map_request> element has the following definition:

<!ELEMENT map_request ((box | center | bounding_themes)?, srs?, legend?, themes?,
  styles?, geoFeature*)>

The root element of a map request to OracleAS MapViewer is always named map_request.

<map_request> can have a child element that is <box> (see Section 3.2.3), <center> (see Section 3.2.4), or <bounding_themes> (see Section 3.2.2), which specifies the range of the user data to be plotted on a map. If none of these child elements is specified, the result map is drawn using all data available to OracleAS MapViewer.

The optional <srs> child element is ignored by the current version of OracleAS MapViewer.

The optional <legend> element (see Section 3.2.11) is 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 optional <themes> element (see Section 3.2.15) specifies predefined or dynamically defined themes.

The optional <styles> element (see Section 3.2.13) specifies dynamically defined styles.

The <geoFeature> element (see Section 3.2.5) can be used to specify any number of individual geometries and their rendering attributes.

OracleAS 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.

<!ATTLIST map_request
  datasource    CDATA #REQUIRED
  srid          CDATA #IMPLIED
  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|PNG8_STREAM|PNG8_URL|
                 JPEG_STREAM|JPEG_URL|
                 SVG_STREAM|SVGZ_STREAM|SVGTINY_STREAM|
                 SVG_URL|SVGZ_URL|SVGTINY_URL) "GIF_URL"
  transparent   (TRUE|FALSE) "FALSE"
  title         CDATA #IMPLIED
  bgcolor       (CDATA) "#A6CAF0"
  bgimage       CDATA #IMPLIED
  zoomlevels    CDATA #IMPLIED
  zoomfactor    CDATA #IMPLIED
  zoomratio     CDATA #IMPLIED
  initscale     CDATA #IMPLIED
  navbar        (TRUE|FALSE) "TRUE"
  infoon        (TRUE|FALSE) "TRUE"
  onclick       CDATA #IMPLIED
  onmousemove   CDATA #IMPLIED
  rasterbasemap (TRUE|FALSE) "FALSE"
  onrectselect  CDATA #IMPLIED
  onpolyselect  CDATA #IMPLIED
>

3.2.2 bounding_themes Element

The <bounding_themes> element has the following definition:

<!ELEMENT bounding_themes (#PCDATA) >
<!ATTLIST bounding_themes  
     border_margin          CDATA  #IMPLIED
     preserve_aspect_ratio  CDATA  "TRUE"
>

You can specify one or more themes as the bounding themes when you cannot predetermine the data size for a map. For example, you may have one dynamic theme that selects all data points that meet certain criteria, and you then want to plot those data points on a map that is just big enough to enclose all the selected data points. In such cases, you can use the <bounding_themes> element to specify the names of such dynamic themes. OracleAS MapViewer first processes any themes that are specified in the <bounding_themes> element, generates a bounding box based on the resulting features of the bounding themes, and then prepares other themes according to the new bounding box.

The <bounding_themes> element is ignored if you specify the <box> or <center> element in the map request.

border_margin is an optional attribute that specifies the percentage to be added to each margin of the generated bounding box. For example, if you specify a value of 0.025, OracleAS MapViewer adds 2.5% of the width to the left and right margins of the generated bounding box (resulting in a total 5% width expansion in the x-axis); similarly, 2.5% of the height is added to the top and bottom margins. The default value is 0.05, or 5% to be added to each margin.

preserve_aspect_ratio is an optional attribute that indicates whether or not the bounding box generated after processing the bounding themes should be further modified so that it has the same aspect ratio as the map image or device. The default is TRUE, which modifies the bounding box to preserve the aspect ratio, so as not to distort the resulting map image.

The element itself contains a comma-delimited list of names of the bounding themes. The theme names must exactly match their names in the map request or the base map used in the map request. The following example shows a map request with two bounding themes, named theme1 and theme3, and with 2 percent (border_margin="0.02") added to all four margins of the minimum bounding box needed to hold features associated with the two themes:

<?xml version="1.0" standalone="yes"?>
<map_request
             title="bounding themes"
             datasource = "tilsmenv"
             basemap="qa_map"
             width="400"
             height="400"
             bgcolor="#a6cae0"
             antialiase="false"
             mapfilename="tilsmq202"
             format="PNG_STREAM">
 
  <bounding_themes border_margin="0.02">theme1, theme3</bounding_themes>
 
  <themes>
    <theme name="theme1" min_scale="5.0E7" max_scale="0.0">
       <jdbc_query
         datasource="tilsmenv"
         jdbc_srid="8265"
         spatial_column="geom" label_column="STATE"
         render_style="myPattern" label_style="myText"
         >SELECT geom, state from states where state_abrv='IL'</jdbc_query>
     </theme>
    <theme name="theme3" min_scale="5.0E7" max_scale="0.0">
       <jdbc_query
         datasource="tilsmenv"
         jdbc_srid="8265"
         spatial_column="geom" label_column="STATE"
         render_style="myPattern" label_style="myText"
         >SELECT geom,state from states where state_abrv='IN'</jdbc_query>
     </theme>
 
  </themes>
 
  <styles>
   <style name="myPattern">
     <svg width="1in" height="1in">
     <desc></desc>
       <g class="area" 
          style="stroke:#0000cc;fill:#3300ff;fill-opacity:128;line-style:L.DPH">
       </g>
     </svg>
   </style>
   <style name="myText">
     <svg width="1in" height="1in">
        <g class="text" float-width="3.0"
           style="font-style:bold;font-family:Serif;font-size:18pt;fill:#000000">
          Hello World!
        </g>
     </svg>
   </style>
  </styles>
</map_request>

The preceding example displays a map in which the states of Illinois and Indiana are displayed according to the specifications in the two <theme> elements, both of which specify a rendering style named myPattern. In the myText style, the text "Hello World!" is displayed only when the style is being previewed in a style creation tool, such as the Map Definition Tool. When the style is applied to a map, it is supplied with an actual text label that OracleAS MapViewer obtains from a theme.

Figure 3-2 shows the display from the preceding example.

Figure 3-2 Bounding Themes

Description of "Figure 3-2 Bounding Themes"

3.2.3 box Element

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.

3.2.4 center Element

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, OracleAS MapViewer interprets the size in meters.

The center itself must embed a <geoFeature> element, which is specified in Section 3.2.5.

3.2.5 geoFeature Element

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
   attribute_values  CDATA #IMPLIED
   orient_x          CDATA #IMPLIED
   orient_y          CDATA #IMPLIED
   orient_z          CDATA #IMPLIED
   selectable_in_svg (TRUE|FALSE) "FALSE"
   onclick           CDATA #IMPLIED
   hidden_info       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 OracleAS MapViewer.

id is an optional attribute that can be used to uniquely identify the feature among all the geospatial features on the SVG map. (See the explanation of the selectable_in_svg attribute.) Otherwise, this attribute is ignored by OracleAS 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 feature. 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 feature.

label_always_on is an optional attribute. If it is set to TRUE, OracleAS MapViewer labels the features even if two or more labels will overlap in the display of a theme. (OracleAS MapViewer always tries to avoid overlapping labels.) If label_always_on is FALSE (the default), when it is impossible to avoid overlapping labels, OracleAS 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.14). 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 feature, and if render_style is a marker-type style, the specified size is used by OracleAS MapViewer in rendering this feature. 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.

attribute_values is an optional attribute. If it is supplied, it specifies a value or a comma-delimited list of values to be used with bucket ranges of an advanced style (for example, values for pie chart segments or bucket values for variable markers).

orient_x and orient_y optionally specify a virtual end point to indicate an orientation vector for rotating a marker symbol (such as a shield symbol to indicate a highway) or text at a specified point. (orient_z is reserved for future use by Oracle.) The value for each must be from -1 to 1. The orientation start point is assumed to be (0,0), and it is translated to the location of the physical point to which it corresponds.

Figure 3-3 illustrates an orientation vector of approximately 34 degrees (counterclockwise from the x-axis), resulting from specifying orient_x="0.3" orient_y="0.2". (To have an orientation that more precisely matches a specific angle, refer to the cotangent or tangent values in the tables in a trigonometry textbook.)

Figure 3-3 Orientation Vector

Description of "Figure 3-3 Orientation Vector"

selectable_in_svg is an optional attribute that specifies whether or not the feature is selectable on an SVG map. The default is FALSE; that is, the feature is not selectable on an SVG map. If this attribute is set to TRUE and if theme feature selection is allowed, the feature can be selected by clicking on it. If the feature is selected, its color is changed and its ID 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 feature selection to work correctly, the id attribute value of the feature must be set to a value that uniquely identifies it among all the geospatial features on the SVG map.) For information about using JavaScript functions with SVG maps, see Appendix B.

onclick is an optional attribute that specifies the name of the JavaScript function to be called when a user clicks on the feature. The JavaScript function must be defined in the HTML document outside the SVG definition. This function must accept only four parameters: the theme name, the key of the feature, and x and y, which specify the coordinates (in pixels) of the clicked point on the SVG map. For information about using JavaScript functions with SVG maps, see Appendix B.

hidden_info is an optional attribute that specifies an informational note or tip to be displayed when the mouse is moved over the feature. To specify multiple lines, use "\n" between lines. For example, hidden_info="State park with\nhistorical attractions" specifies a two-line tip. (To enable the display of hidden information in the map, you must specify infoon="true" in the <map_request> element, as explained in Section 3.2.1.1.)

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 OracleAS 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-4 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.

Figure 3-4 Map with <geoFeature> Element Showing Two Concentric Circles

Description of "Figure 3-4 Map with <geoFeature> Element Showing Two Concentric Circles"

3.2.6 jdbc_georaster_query Element

The <jdbc_georaster_query> element, which is used to define a GeoRaster theme, has the following definition:

<!ELEMENT jdbc_georaster_query (#PCDATA) >
<!ATTLIST jdbc_georaster_query 
    asis              (TRUE|FALSE) "FALSE"
    georaster_table   CDATA #REQUIRED
    georaster_column  CDATA #REQUIRED
    raster_id         CDATA #IMPLIED
    raster_table      CDATA #IMPLIED
    raster_pyramid    CDATA #IMPLIED
    raster_bands      CDATA #IMPLIED
    datasource        CDATA #IMPLIED
    polygon_mask      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"
>

For detailed usage and reference information about GeoRaster themes, see Section 2.3.6.

3.2.7 jdbc_image_query Element

The <jdbc_image_query> element, which is used to define an image theme (described in Section 2.3.5), 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, OracleAS MapViewer does not attempt to modify the supplied query string. If asis is FALSE (the default), OracleAS 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 OracleAS 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 the current map window. However, if asis is TRUE, OracleAS 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 OracleAS MapViewer, you must create and register a custom image renderer for the format, as explained in Appendix C.

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-13 in Section 2.3.5.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-6 in Section 3.1.6.

3.2.8 jdbc_network_query Element

The <jdbc_network_query> element, which is used to define a network theme, has the following definition:

<!ELEMENT jdbc_network_query (#PCDATA) >
<!ATTLIST jdbc_network_query 
    asis                    (TRUE|FALSE) "FALSE"
    network_name            CDATA #REQUIRED
    network_level           CDATA #IMPLIED
    link_style              CDATA #IMPLIED
    direction_style         CDATA #IMPLIED
    direction_position      CDATA #IMPLIED
    direction_markersize    CDATA #IMPLIED
    link_labelstyle         CDATA #IMPLIED
    link_labelcolumn        CDATA #IMPLIED
    node_style              CDATA #IMPLIED
    node_markersize         CDATA #IMPLIED
    node_labelstyle         CDATA #IMPLIED
    node_labelcolumn        CDATA #IMPLIED
    path_ids                CDATA #IMPLIED
    path_styles             CDATA #IMPLIED
    path_labelstyle         CDATA #IMPLIED
    path_labelcolumn        CDATA #IMPLIED
    analysis_algorithm      CDATA #IMPLIED
    shortestpath_style      CDATA #IMPLIED
    shortestpath_startnode  CDATA #IMPLIED
    shortestpath_endnode    CDATA #IMPLIED
    shortestpath_startstyle CDATA #IMPLIED
    shortestpath_endstyle   CDATA #IMPLIED
    withincost_startnode    CDATA #IMPLIED
    withincost_style        CDATA #IMPLIED
    withincost_cost         CDATA #IMPLIED
    withincost_startstyle   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"
>

For detailed usage and reference information about network themes, see Section 2.3.7.

3.2.9 jdbc_query Element

The <jdbc_query> element is used to define a theme dynamically. This element and its associated <hidden_info> element have the following definitions:

<!ELEMENT jdbc_query (#PCDATA, hidden_info?)>
<!ATTLIST jdbc_query
    asis               (TRUE|FALSE) "FALSE"
    spatial_column     CDATA #REQUIRED
    key_column         CDATA #IMPLIED
    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 hidden_info (field+)> 
<!ELEMENT field (#PCDATA)> 
<!ATTLIST field 
    column  CDATA #REQUIRED 
    name    CDATA #IMPLIED
> 

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 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).

If the selectable_in_svg attribute value is TRUE in the <theme> element, you must use the key_column attribute in the <jdbc_query> element to specify the name of a column that can uniquely identify each selected feature from the JDBC query. The specified column must also appear in the SELECT list in the JDBC query.

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, OracleAS MapViewer does not attempt to modify the supplied query string. If asis is FALSE (the default), OracleAS 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 OracleAS 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, OracleAS MapViewer executes the query as specified, namely:

SELECT geometry, sales FROM crm_sales WHERE sales < 100000;

The <hidden_info> element specifies the list of attributes from the base table to be displayed when the user moves the mouse over the theme's features. The attributes are specified by a list of <field> elements.

Each <field> element must have a column attribute, which specifies the name of the column from the base table, and it can have a name attribute, which specifies the display name of the column. (The name attribute is useful if you want a text string other than the column name to be displayed.)

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.

3.2.10 jdbc_topology_query Element

The <jdbc_topology_query> element, which is used to define a topology theme, has the following definition:

<!ELEMENT jdbc_topology_query (#PCDATA)>
<!ATTLIST jdbc_topology_query
    asis               (TRUE|FALSE) "FALSE"
    topology_name      CDATA #REQUIRED
    feature_table      CDATA #REQUIRED
    spatial_column     CDATA #REQUIRED
    label_column       CDATA #IMPLIED
    label_style        CDATA #IMPLIED
    render_style       CDATA #IMPLIED
    datasource         CDATA #IMPLIED
    edge_style         CDATA #IMPLIED
    edge_marker_style  CDATA #IMPLIED
    edge_marker_size   CDATA #IMPLIED
    edge_label_style   CDATA #IMPLIED
    node_style         CDATA #IMPLIED
    node_label_style   CDATA #IMPLIED
    face_style         CDATA #IMPLIED
    face_label_style   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"
>

For detailed usage and reference information about topology themes, see Section 2.3.8.

3.2.11 legend Element

The <legend> element has the following definition:

<!ELEMENT legend column+ >
<!ATTLIST legend
    bgstyle   CDATA #implied
    font      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-6 in Section 2.4.2 shows a one-column legend. Figure 3-5 shows a two-column legend.

Figure 3-5 Two-Column Map Legend

Description of "Figure 3-5 Two-Column Map 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"

font is an optional attribute that specifies the name of the font to be used for text that appears in the legend image. You can specify a logical font name that is supported by Java (serif, sansserif, monospaced, dialog, or dialoginput). You can also specify the name of a physical font that is available on the system where the OracleAS MapViewer server is running.

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 OracleAS 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-6 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:

• The background color has an opacity value of 128 (fill-opacity:128), which means that the white background will be half transparent.

• The legend boundary box will be red (stroke:#ff0000).

• The legend boundary box will be positioned in the upper-left part of the display (position="NORTH_WEST").

• The legend will be the default size, because the profile attribute (which has a default value of MEDIUM) is not specified.

• The legend will have a single column, with entries arranged from top to bottom.

• The first entry is the legend title, with the text Map Legend.

• The fourth entry is a separator for adding a blank line.

• The seventh entry is description text (County population:) that users of the generated map will associate with the next (and last) entry, which specifies an advanced style. The County population: text entry is helpful because advanced styles usually have their own descriptive text, and you do not want users to become confused about which text applies to which parts of the legend.

• The last entry specifies an advanced style (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.

3.2.12 style Element

The <style> element has the following definition:

<!ELEMENT style (svg | AdvancedStyle)?>
<!ATTLIST style
    name  CDATA #REQUIRED
>

The <style> element lets you specify a dynamically defined style. The style can be either of the following:

• An SVG description representing a color, line, marker, area, or text style

• An advanced style definition (see Section A.6) representing a bucket, a color scheme, or a variable marker style

The name attribute identifies the style name.

The following example shows an excerpt that dynamically defines two styles (a color style and an advanced style) for a map request:

<map_request . . .>
  . . .
  <styles>
    <style name="color_red">
      <svg width="1in" height="1in">
        <g class="color" 
           style="stroke:red;stroke-opacity:100;fill:red;fill-opacity:100">
          <rect width="50" height="50"/>
        </g>
      </svg>
    </style>
 
    <style name="ranged_bucket_style">
        <AdvancedStyle>
           <BucketStyle>
             <Buckets>
             <RangedBucket seq="0" label="less than 100k" 
               high="100000.0" style="C.RB13_13"/>
             <RangedBucket seq="1" label="100k - 150k" low="100000.0" 
               high="150000.0" style="C.RB13_1"/>
             <RangedBucket seq="2" label="150k - 250k" low="150000.0" 
               high="250000.0" style="C.RB13_4"/>
             <RangedBucket seq="3" label="250k - 350k" low="250000.0" 
               high="350000.0" style="C.RB13_7"/>
             <RangedBucket seq="4" label="350k - 450k" low="350000.0" 
               high="450000.0" style="C.RB13_10"/>
              </Buckets>
           </BucketStyle>
        </AdvancedStyle>
    </style>
  </styles>
</map_request>

3.2.13 styles Element

The <styles> element has the following definition:

<!ELEMENT styles (style+) >

The <styles> element specifies one or more <style> elements (described in Section 3.2.12).

3.2.14 theme Element

The <theme> element has the following definition:

<!ELEMENT theme (jdbc_query | jdbc_image_query | jdbc_georaster_query
                            | jdbc_network_query | jdbc_topology_query )? >
<!ATTLIST theme
    name                  CDATA #REQUIRED
    datasource            CDATA #IMPLIED
    max_scale             CDATA #IMPLIED
    min_scale             CDATA #IMPLIED
    label_always_on       (TRUE|FALSE) "FALSE"
    fast_unpickle         (TRUE|FALSE) "TRUE"
    mode                  CDATA #IMPLIED
    min_dist              CDATA #IMPLIED
    fixed_svglabel        (TRUE|FALSE) "FALSE"
    visible_in_svg        (TRUE|FALSE) "TRUE"
    selectable_in_svg     (TRUE|FALSE) "FALSE"
    part_of_basemap       (TRUE|FALSE) "FALSE"
    onclick               CDATA #IMPLIED
    onmousemove           CDATA #IMPLIED
    onmouseover           CDATA #IMPLIED
    onmouseout            CDATA #IMPLIED
    workspace_name        CDATA #IMPLIED
    workspace_savepoint   CDATA #IMPLIED
    workspace_date        CDATA #IMPLIED
    workspace_date_format CDATA #IMPLIED
>

The <theme> element lets you specify a predefined or dynamically defined theme.

• For a predefined theme, whose definition is already stored in your USER_SDO_THEMES view, only the theme name is required.

• For a dynamically defined theme, you must provide the information in one of the following elements: <jdbc_query> (described in Section 3.2.9), <jdbc_image_query> (described in Section 3.2.7), <jdbc_georaster_query> (described in Section 2.3.6), <jdbc_network_query> (described in Section 2.3.7), or <jdbc_topology_query> (described in Section 2.3.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.8.2). For a dynamically defined theme, this is just a temporary name for referencing the jdbc_query-based theme.

datasource is an optional attribute that specifies a data source for the theme. If you do not specify this attribute, the data source for the map request is assumed (see the datasource attribute explanation in Section 3.2.1.1). By specifying different data sources for different themes, you can use multiple data sources in a map request.

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, OracleAS MapViewer labels all features of the theme even if two or more labels will overlap in the display. (OracleAS MapViewer always tries to avoid overlapping labels.) If label_always_on is FALSE (the default), when it is impossible to avoid overlapping labels, OracleAS 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.5), 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.

fast_unpickle is an optional attribute. If it is TRUE (the default), OracleAS MapViewer uses its own fast unpickling (unstreaming) algorithm instead of the generic JDBC conversion algorithm to convert SDO_GEOMETRY objects fetched from the database into a Java object accessible to OracleAS MapViewer. This process 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. If fast_unpickle is set to FALSE, OracleAS MapViewer uses the generic JDBC conversion algorithm. This process is slower than OracleAS MapViewer's fast unpickling process, but there is never any loss of precision.

mode is an optional attribute. For a topology theme, you can specify mode="debug" to display edges, nodes, and faces, as explained in Section 2.3.8. The mode attribute is ignored for other types of themes.

min_dist is an optional attribute. It specifies the minimum on-screen distance (number of pixels) between two adjacent shape points on a line string or polygon for rendering of separate shape points. If the on-screen distance between two adjacent shape points is less than the min_dist value, only one shape point is rendered. The default value is 0.5. You can specify higher values to reduce the number of shape points rendered on an SVG map, and thus reduce the size of the resulting SVG file. You can specify different values in different theme definitions, to allow for customized levels of detail in SVG maps.

fixed_svglabel is an optional attribute that specifies whether to display the labels on an SVG map using the original "fixed" labels, but having them appear larger or smaller as the zoom level increases (zoomin) or decreases (zoomout), or to use different labels with the same text but different actual sizes so that the apparent size of each label remains the same at all zoom levels. If the fixed_svglabel value is specified as TRUE, the same theme labels are displayed on the map at all zoom levels, with the labels zoomed in and out as the map is zoomed in and out. If the value is FALSE (the default), different theme labels are displayed at different zoom levels so that the size of each displayed label appears not to change during zoomin and zoomout operations.

visible_in_svg is an optional attribute that specifies whether or not to display the theme on an SVG map. If its value is TRUE (the default), the theme is displayed; if it is set to FALSE, the theme is not displayed. However, even if this attribute is set to FALSE, the theme is still rendered to the SVG map: the theme is initially invisible, but you can make it visible later by calling the JavaScript function showTheme() defined in the SVG map. For information about using JavaScript functions with SVG maps, see Appendix B.

selectable_in_svg is an optional attribute that specifies whether or not the theme is selectable on an SVG map. The default is FALSE; that is, the theme is not selectable on an SVG map. If this attribute is set to TRUE and if theme feature selection is allowed, each feature of the theme displayed on the SVG map can be selected 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.

part_of_basemap is an optional attribute. If the map format is SVG and the value of this attribute is TRUE, OracleAS MapViewer renders the theme as part of and on top of the base map, which is rendered as a raster image.

onclick is an optional attribute that specifies the name of the JavaScript function to be called when a user clicks on an SVG map and theme feature selection is allowed (see the selectable_in_svg attribute explanation). The JavaScript function must be defined in the HTML document that has the SVG map embedded. This function must accept only four parameters: the theme name, the key of the feature, and x and y, which specify the coordinates (in pixels) of the clicked point on the SVG map. For information about using JavaScript functions with SVG maps, see Appendix B.

onmousemove is an optional attribute that specifies the name of the JavaScript function to be called when a user moves the mouse on top of any feature of the theme on an SVG map. The JavaScript function must be defined in the HTML document that has the SVG map embedded. This function must accept only four parameters: the theme name, the key of the feature, and x and y, which specify the coordinates (in pixels) of the point for the move on the SVG map. For information about using JavaScript functions with SVG maps, see Appendix B.

onmouseover is an optional attribute that specifies the name of the JavaScript function to be called when a user moves the mouse into a feature of the theme on an SVG map. (Unlike the onmousemove function, which is called whenever the mouse moves inside the theme, the onmouseover function is called only once when the mouse moves from outside a feature of the theme to inside a feature of the theme.) The JavaScript function must be defined in the HTML document that has the SVG map embedded. This function must accept only four parameters: the theme name, the key of the feature, and x and y, which specify the coordinates (in pixels) of the point at which the mouse moves inside a feature on the SVG map. For information about using JavaScript functions with SVG maps, see Appendix B.

onmouseout is an optional attribute that specifies the name of the JavaScript function to be called when a user moves the mouse out of a feature of the theme on an SVG map. The JavaScript function must be defined in the HTML document that has the SVG map embedded. This function must accept only four parameters: the theme name, the key of the feature, and x and y, which specify the coordinates (in pixels) of the point at which the mouse moves out of a feature on the SVG map. For information about using JavaScript functions with SVG maps, see Appendix B.

workspace_name, workspace_savepoint, workspace_date, and workspace_date_format are optional attributes related to support for Workspace Manager in Mapviewer, which is explained in Section 2.7.

3.2.15 themes Element

The <themes> element has the following definition:

<!ELEMENT themes (theme+) >

The <themes> element specifies one or more <theme> elements (described in Section 3.2.14). 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.