If you specify a unit other than the default of pixels (px) in a style definition, the style becomes scalable: that is, the size of features associated with the style is scaled as users zoom in or out on a map. For example, if you specify a marker style's width and height as 100m, the marker is displayed as a square 100 meters on each side according to the map scale at the current zoom level.

The following are style types and the attributes that can have an associated size unit:

• Marker styles: marker size (height and width) and text attributes (font size, label offsets)

• Line styles: overall line width, center line width and dash pattern, wing line width and dash pattern, hash mark, and marker pattern (size, offset, interval)

• Text styles: font size, halo width

• Bar chart styles: bar width and height

• Dot density styles: dot width and height

• Pie chart styles: pit radius

<style name="M.STAR_CAPITAL_CITY">
  <svg width="1in" height="1in">
    <desc/>
    <g class="marker" style="stroke:#000000;fill:#FF0000;fill-opacity:0;width:15.0km;height:15.0km;font-family:Dialog;font-size:12;font-fill:#FF0000">
        <polyline points="138.0,123.0,161.0,198.0,100.0,152.0,38.0,198.0,61.0,123.0,0.0,76.0,76.0,76.0,100.0,0.0,123.0,76.0,199.0,76.0"/>
    </g>
  </svg>
</style>

<style name="L.PRIMARY_HIGHWAY">
  <svg width="1in" height="1in">
    <desc></desc>
    <g class="line" cased="true" style="fill:#33a9ff;stroke-width:10.0m">
      <line class="parallel" style="fill:#aa55cc;stroke-width:1.0m"/>
    </g>
  </svg>
</style>

For collection-based bucket styles and individual range-based bucket styles (described in Bucket Styles and Color Scheme Styles, respectively), you can specify a labeling style by using the label_style attribute in each bucket element. Example 2-3 creates an advanced style named V.COUNTY_POP_DENSITY in which each bucket is assigned a text label style (using the label_style attribute), with some styles being used for several buckets.

Example 2-3 Advanced Style with Text Label Style for Each Bucket

<?xml version="1.0" ?>
<AdvancedStyle>
     <BucketStyle>
        <Buckets>
            <RangedBucket seq="0" label="&lt;150k" 
              low="-Infinity" high="150000" 
              style="C.CB_QUAL_8_CLASS_DARK2_1" 
              label_style="T.BLUE_SERIF_12"/>
            <RangedBucket seq="1" label="150k - 350k" 
              low="150000" high="350000" 
              style="C.CB_QUAL_8_CLASS_DARK2_2" 
              label_style="T.BLUE_SERIF_12"/>
            <RangedBucket seq="2" label="350k - 600k" 
              low="350000" high="600000" 
              style="C.CB_QUAL_8_CLASS_DARK2_3" 
              label_style="T.BROWN_SERIF_12"/>
            <RangedBucket seq="3" label="600k - 1000k" 
              low="600000" high="1000000" 
              style="C.CB_QUAL_8_CLASS_DARK2_4" 
              label_style="T.BROWN_SERIF_12"/>
            <RangedBucket seq="4" label="1000k - 1500k" 
              low="1000000" high="1500000" 
              style="C.CB_QUAL_8_CLASS_DARK2_5" 
              label_style="T.GREY_SERIF_12"/>
            <RangedBucket seq="5" label="1500k - 2500k" 
              low="1500000" high="2500000" 
              style="C.CB_QUAL_8_CLASS_DARK2_6" 
              label_style="T.GREY_SERIF_12"/>
            <RangedBucket seq="6" label="2500k - 5000k" 
              low="2500000" high="5000000" 
              style="C.CB_QUAL_8_CLASS_DARK2_7" 
              label_style="T.GREEN_SERIF_12"/>
            <RangedBucket seq="7" label="&gt;=5000k" 
              low="5000000" high="Infinity" 
              style="C.CB_QUAL_8_CLASS_DARK2_8" 
              label_style="T.GREEN_SERIF_12"/>
    </Buckets>
   </BucketStyle>
</AdvancedStyle>

For individual range-based buckets, the lower-bound value is inclusive, while the upper-bound value is exclusive (except for the range that has values greater than any value in the other ranges; its upper-bound value is inclusive). No range is allowed to have a range of values that overlaps values in other ranges.

If the V.COUNTY_POP_DENSITY style in Example 2-3 is used in a map request, it displays a map that might look like the display in Figure 2-1, where the county names are shown with labels that reflect various text styles (in this case depending on the county's total population).

Figure 2-1 Varying Label Styles for Different Buckets

Description of "Figure 2-1 Varying Label Styles for Different Buckets"

In Example 2-3, all buckets except the last one specify a label style. For any features that fall into a bucket that has no specified label style, the label style (if any) applied to the feature depends on the following:

• If the <label> element of the theme's styling rules specifies a label style other than the advanced style itself, the specified label style is used to label the feature. In the following example, because the <label> element's style specification (T.STATE_NAME) is different from the <features> element's style specification (V.COUNTY_POP_DENSITY), features that fall into a bucket with no specified label style are labeled using the T.STATE_NAME style:

  <?xml version="1.0" standalone="yes"?>
  <styling_rules>
    <rule column="TOTPOP">
      <features style="V.COUNTY_POP_DENSITY">
      </features>
      <label column="county" style="T.STATE NAME">
          1
      </label>
    </rule>
  </styling_rules>
  

• If the <label> element of the theme's styling rules specifies the advanced style as its label style, the feature is not labeled. (This is why some counties in Figure 2-1 are not labeled.) In the following example, because the <features> and <label> elements both specify the advanced style V.COUNTY_POP_DENSITY, features that fall into a bucket with no specified label style are not labeled:

  <?xml version="1.0" standalone="yes"?>
  <styling_rules>
    <rule column="TOTPOP">
      <features style="V.COUNTY_POP_DENSITY">
      </features>
      <label column="county" style="V.COUNTY_POP_DENSITY">
          1
      </label>
    </rule>
  </styling_rules>

You can control the orientation of text labels and markers on a map by using oriented points. The oriented point is a special type of point geometry in Oracle Spatial and Graph. In an oriented point, the coordinates represent both the location of the point and a virtual end point, to indicate an orientation vector. The text is aligned or the marker symbol is rotated according to the orientation vector, which is explained and illustrated in Controlling Marker Orientation. For more information about oriented points, see Oracle Spatial and Graph Developer's Guide.

• Controlling Text Style Orientation
  
• Controlling Marker Orientation
  

You can specify that a text style is "sticky," which means that any feature that uses it as a label style will always have its text label drawn on a map. Example 2-5 shows an XML definition of a style with the sticky attribute set to true.

<?xml version="1.0" standalone="yes"?>
<svg width="1in" height="1in">
<desc></desc>
 <g class="text" sticky="true" style = "font-style:plain;font-family:Serif;font-size:11pt;font-weight:bold;fill:#000000">
    Hello World!
</g>
</svg>

To get a sample image for any pre-defined style stored in a database, you can issue a simple HTTP request to the map visualization component server. This request can specify the size of the sample image, the background color, and the format of the returned image. Such requests are useful if you want to display a visual list of styles on a web page, to build a custom map legend, or just to see how various styles will appear.

The HTTP request has the following parameters, all of which are optional except for sty:

• sty (required) specifies the name of the style.

• ds specifies the data source where the style can be accessed. By default, the default map visualization component data source is used.

• w specifies the width of the sample image in pixels. The default value is 20.

• h specifies the height of the sample image in pixels. The default value is 20.

• f specifies the format of the sample image. Possible values are png for direct PNG image stream, png_url for the URL of a PNG image, gif for direct GIF image stream, or gif_url for the URL of a GIF image. The default value is png, which means the map visualization component server will directly stream the generated PNG image data back to the client without first saving it to the server disk.

• bg specifies the background color of the sample image. The format must be a hexadecimal string in the form of 0xrrggbb, such as 0x808080 for a gray color. The default value is 0xffffff (white).

  For a transparent background, specify bg as an extended hexadecimal string to include the alpha values, in the format of 0xaarrggbb. For example, 0x00ffffff will make the style image's background completely transparent, while 0x55ffffff is a white background with a transparency value of 0x55 (decimal value 80). The alpha value can range from 0x00 (completely transparent) to 0xff (completely opaque).

• aa specifies whether the sample image should be rendered in antialiasing mode. The default value is the string true. Specify the string false if you do not want to use antialiasing.

The following example generates an antialiased PNG image with a gray background with the default size of 20x20 pixels, displaying the marker style named M.STAR from the map visualization component default data source:

http://www.mycorp.com/mapviewer/omserver?sty=m.star&bg=808080

The preceding request generates a display similar to that in Figure 2-4.

Figure 2-4 Sample Image of a Specified Marker Style

Description of "Figure 2-4 Sample Image of a Specified Marker Style"

The following example generates an antialiased GIF image with the default white background, a width of 60 pixels, and a height of 25 pixels, displaying the line style named L.PH from the map visualization component data source named mvdemo:

http://www.mycorp.com/mapviewer/omserver?sty=l.ph&ds=mvdemo&f=gif&w=60&h=25&aa=true

The preceding request generates a display similar to that in Figure 2-5.

Figure 2-5 Sample Image of a Specified Line Style

Description of "Figure 2-5 Sample Image of a Specified Line Style"

You can specify that a text style allow-overlap, which means that any area feature, such as a polygon that uses it as a label style, will allow its text label be overlapped on a map. The following example shows an XML definition of a style with the allow-overlap attribute set to true.

<?xml version="1.0" standalone="yes"?>
<svg width="1in" height="1in">
<desc></desc>
 <g class="text" allow-overlap="true" style = "font-style:plain;font-family:Serif;font-size:11pt;font-weight:bold;fill:#000000">
    Hello World!
</g>
</svg>

For example, if a country's name is used as a label text, and if its style has the attribute value allow-overlap="true", then other features' labels (such as state names) are allowed to overlap with it. The following figure shows part of a rendered map in which the country label "United States" overlaps slightly with the state labels "Colorado" and "Kansas".

Figure 2-6 Text Style with allow-overlap="true"

Description of "Figure 2-6 Text Style with allow-overlap="true""

A predefined theme is a theme whose definition is stored in a user's database schema. All predefined themes for a database user are stored in that user's USER_SDO_THEMES view (described in Map Visualization Component Metadata Views, especially xxx_SDO_THEMES Views). When you include a predefined theme in a map request, you need to specify only the theme name. The map visualization component automatically finds the theme's definition, constructs a query based on it, retrieves the relevant spatial and attribute data, and renders the data according to the styling rules for the theme.

Each predefined theme must have an associated base table or view. If you base a theme on a view, you must insert a row in the view owner's USER_SDO_GEOM_METADATA view (described in Oracle Spatial and Graph Developer's Guide) specifying the view and its spatial column. If the view is a join view (that is, if it is based on multiple tables), you must specify the key_column attribute (described in Themes: Styling Rules) in the theme's styling rules. The reason for this requirement is that the map visualization component by default caches geometries for a predefined theme based on the rowid in the base table; however, for a join view there is no ROWID pseudocolumn, so you must specify a key column.

For most types of predefined themes (but not WMS themes), you can use the Map Builder tool to create and preview themes. For information about the Map Builder tool, see Oracle Map Builder Tool.

• Styling Rules in Predefined Spatial Geometry Themes
  
• How the Map Visualization Component Formulates a SQL Query for a Styling Rule
  
• Styling Rules with Binding Parameters
  
• Applying Multiple Rendering Styles in a Single Styling Rule
  
• Using Multiple Rendering Styles with Scale Ranges
  
• Caching of Predefined Themes
  
• Feature Labels and Internationalization
  
• Primary and Secondary Labels for Linear Features
  

A JDBC theme is a theme that is dynamically defined with a map request. JDBC themes are not stored permanently in the database, as is done with predefined themes.

For a JDBC theme, you must specify a valid SQL query that retrieves all the necessary spatial data (geometries or other types of data, such as image, GeoRaster, network, or topology). If attribute data is needed, such as for thematic mapping or spatial data analysis, the query must also select it. In other words, you must provide a correct and complete query for a JDBC theme. In addition to the query, you can also specify the rendering and labeling styles to be used for the theme.

For a JDBC theme based on spatial geometries, the map visualization component processed the columns specified in the query according to the following rules:

• The column of type SDO_GEOMETRY is treated as the spatial data column.

• Any column whose name or alias matches that specified in the JDBC theme's label_column attribute is treated as the labeling column, whose values are used as text for labels.

• Any other columns are treated as attribute data columns, which may or may not be used by the map visualization component. For example, if the rendering style is an advanced style, any attribute columns are processed by that style in the order in which they appear in the SELECT list in the query. Thus, if you are performing thematic mapping and using an advanced style, you must specify all attribute columns that are needed for the thematic mapping, in addition to the geometry column and optional labeling column. (A labeling column can also be an attribute column, in which case you do not need to specify that column in the SELECT list.)

Example 2-9 is a map request that includes a JDBC theme.

<?xml version="1.0" standalone="yes"?>
<map_request title="My MAP" datasource = "mvdemo">

  <themes>
    <theme name="jdbc_theme_1">
       <jdbc_query
            datasource="mvdemo"
            jdbc_srid="41052"
            spatial_column="geometry"
            render_style="C.RED">
          SELECT geometry from states where name='MA' 
       </jdbc_query>
     </theme>
  </themes>

</map_request> 

SELECT geometry FROM states WHERE name='MA';

• Defining a Point JDBC Theme Based on Two Columns
  
• Storing Complex JDBC Themes in the Database
  

An image theme is a special kind of map visualization component theme useful for visualizing geographically referenced imagery (raster) data, such as from remote sensing and aerial photography.

You can define an image theme dynamically or permanently (as a predefined theme) in the database. You can use image themes with vector (nonimage) themes in a map. Figure 2-8 shows a map in which an image theme (showing an aerial photograph of part of the city of Boston) is overlaid with themes showing several kinds of roadways in the city.

Figure 2-8 Image Theme and Other Themes Showing Boston Roadways

Description of "Figure 2-8 Image Theme and Other Themes Showing Boston Roadways"

Before you can define an image theme, you must follow these rules in organizing your image data:

• Store image data in its original format (such as JPEG) in a BLOB column in a database table, or as an Oracle Multimedia object (ORDSYS.ORDImage) that points to the original image file.

• Add a geometry (SDO_GEOMETRY) column to the same table, and store the minimum bounding rectangle (MBR) for each image in that column.

  Each geometry in the MBR column contains the geographic bounds for an image, not its size in the pixel space. For example, if an orthophoto image is 2000 by 2000 pixels in size, but covers a ground rectangle starting at the corner of (936000, 248000) and having a width and height of 8000 meters, the MBR for the geometry column should be populated with (936000, 248000, 944000, 256000).

• Insert an entry for the geometry column in the USER_SDO_GEOM_METADATA view.

• Create a spatial index on the geometry column.

To predefine an image theme, follow the guidelines in Creating Predefined Image Themes. To define a dynamic image theme in a map request, follow the guidelines for defining a JDBC theme, as explained in JDBC Themes, but note the following additional considerations with dynamic image themes:

• You must provide the original image resolution information when defining an image theme.

• The map visualization component by default automatically scales the image data when generating a map with an image theme, so that it fits the current query window. To disable this automatic scaling, specify imagescaling="false" in the map request.

For any image theme definition, the map visualization component supports only GIF, JPEG, PNG, and TIFF image formats.

• Creating Predefined Image Themes
  

A GeoRaster theme is a special kind of map visualization component theme useful for visualizing GeoRaster objects. GeoRaster is a feature of Oracle Spatial and Graph that lets you store, index, query, analyze, and deliver raster image and gridded data and its associated metadata. GeoRaster objects are defined using the SDO_GEORASTER data type. For detailed information about GeoRaster, see Oracle Spatial and Graph GeoRaster Developer's Guide.

Before you can use the map visualization component with GeoRaster themes, you must ensure that the Java Advanced Imaging (JAI) library files (jai_core.jar and jai_codec.jar) are in the map visualization component library path. You must also perform the following actions with the GeoRaster data:

1. Georeference the GeoRaster data to establish the relationship between cell coordinates of the GeoRaster data and real-world ground coordinates (or some other local coordinates).

   If you are using Oracle Database Release 10.1, you must also set the spatial resolution values.

2. Generate or define the spatial extent (footprint) associated with the raster data.

3. Optionally, generate pyramid levels that represent the raster image or data at different sizes and degrees of resolution.

4. Insert a row into the USER_SDO_GEOM_METADATA view that specifies the name of the GeoRaster table and the SPATIALEXTENT attribute of the GeoRaster column (that is, the column of type SDO_GEORASTER). The following example inserts a row for a table named GEOR_TABLE with a GeoRaster column named GEOR_COLUMN:

   INSERT INTO USER_SDO_GEOM_METADATA VALUES
   ( 'geor_table',
     'geor_column.spatialextent',
     SDO_DIM_ARRAY(
       SDO_DIM_ELEMENT('X', 496602.844, 695562.844, 0.000005),
       SDO_DIM_ELEMENT('Y',8788409.499,8973749.499, 0.000005)
     ),
     82279   -- SRID
   );
   

5. Create a spatial index on the spatial extent of the GeoRaster table. The following example creates a spatial index named GEOR_IDX on the spatial extent of the table named GEOR_TABLE:

   CREATE INDEX geor_idx ON geor_table(geor_column.spatialextent)
     INDEXTYPE IS MDSYS.SPATIAL_INDEX;
   

Example 2-17 in Creating Predefined GeoRaster Themes prepares GeoRaster data for use and stores a GeoRaster theme in the database.

The map visualization component supports two types of map requests with objects from a GeoRaster table:

• A request containing a SQL statement to select one or more GeoRaster objects

• A request specifying a single GeoRaster object by the combination of its raster data table name and its rasterID attribute value in the SDO_GEORASTER object. (The rasterID attribute value in the SDO_GEORASTER object is distinct from and unrelated to any primary key or ID column in the GeoRaster table.)

The following elements and attributes apply to the definition of a GeoRaster theme:

• <jdbc_georaster_query> element: Specifies that this is a dynamically defined GeoRaster theme. For a theme that uses a SQL statement to select one or more GeoRaster objects, this element contains the SQL query statement (without a terminating semicolon).

• georaster_table attribute: Specifies the name of the GeoRaster table.

• georaster_column attribute: Specifies the name of the column of type SDO_GEORASTER in the GeoRaster table.

• polygon_mask attribute (optional): Specifies a set of two-dimensional coordinates representing a polygon, to be used as a mask to make transparent the part of the GeoRaster image that is outside the polygon mask. The coordinates are defined as x1,y1,x2,y2, . . . . The mask coordinates must be in the data coordinate space.

• raster_bands attribute (optional): Specifies the band composition to be assigned to the red, green, and blue channels. If you specify only one value, the resulting image uses one band (gray levels for monochromatic images). If you specify two values, they are used for the red and green channels, and the default blue band stored in the GeoRaster metadata is used for the blue channel. If you do not specify this attribute, the map visualization component uses the default values stored in the GeoRaster metadata.

• raster_pyramid attribute (optional): Specifies the pyramid level (level of resolution). If you do not specify this attribute, the map visualization component calculates the best pyramid level for the current window query and device area.

• raster_id attribute (only if the definition does not include a SQL statement): Specifies the rasterID attribute value in the SDO_GEORASTER object definition of the single GeoRaster object for the map request.

• raster_table attribute (optional, and only if the definition does not include a SQL statement): Specifies the raster data table associated with the single GeoRaster object for the map request.

• transparent_nodata attribute (optional): Specifies if any GeoRaster NODATA value is to be rendered as transparent. The default value is "false".

Example 2-14 defines a GeoRaster theme that contains a SQL statement that selects a single GeoRaster object. The theme assigns band 1 to the red channel, band 2 to the green channel, and band 3 to the blue channel. Because the raster_pyramid attribute is not specified, the map visualization component calculates the best pyramid level by using the spatial resolution values set during or after the georeferencing process. (In Example 2-14, georid=1 in the WHERE clause refers to a column named GEORID in the GeoRaster table named PCI_IMAGE.)

Example 2-15 defines a GeoRaster theme that specifies the single GeoRaster object whose rasterID attribute value in the SDO_GEORASTER object is 1 (raster_id="1") and associated with the raster data table named RDT_PCI. The theme specifies 2 as the pyramid level.

Subtopics:

• Creating Predefined GeoRaster Themes

• Using Bitmap Masks with GeoRaster Themes

• Reprojection of GeoRaster Themes

• Virtual Mosaic Themes

<theme name="georaster_theme">
  <jdbc_georaster_query
    georaster_table="pci_image" 
    georaster_column="georaster"
    raster_bands="1,2,3"
    jdbc_srid="82301"
    datasource="mvdemo"
    asis="false"> SELECT georaster FROM pci_image WHERE georid =1
  </jdbc_georaster_query>
</theme>

<theme name="georaster_theme">
  <jdbc_georaster_query
    georaster_table="pci_image"
    georaster_column="georaster"
    raster_id="1"
    raster_table="rdt_pci"
    raster_pyramid="2"
    raster_bands="1,2,3"
    jdbc_srid="82301"
    datasource="mvdemo"
    asis="false">
  </jdbc_georaster_query>
</theme>

• Creating Predefined GeoRaster Themes
  
• Using Bitmap Masks with GeoRaster Themes
  
• Reprojection of GeoRaster Themes
  
• Virtual Mosaic Themes
  

A network theme is a special kind of map visualization component theme useful for visualizing networks defined using the Oracle Spatial and Graph network data model. A network consists of a set of nodes and links. A network can be directed or undirected, although links and paths typically have direction. A network can be organized into different levels of abstraction, called a network hierarchy. The map visualization component assumes that network spatial tables in a network use the same coordinate system, and that these tables are indexed and registered as described in Oracle Spatial and Graph Topology Data Model and Network Data Model Graph Developer's Guide.

Network node, link, and path tables store geometries of type SDO_GEOMETRY. You can create JDBC themes that use these geometries. In addition, you can define dynamic themes that consider aspects of the network, such as the direction of links for a directed network.

The following elements and attributes apply to the definition of a network theme:

• <jdbc_network_query> element: Specifies that this is a dynamically defined network theme.

• network_name attribute: Specifies the name of the network.

• network_level attribute (optional): Specifies the network hierarchy level to which this theme applies. (For a nonhierarchical network, specify 1, which is the default value.)

• link_style attribute (optional): Specifies the style name to be used for links.

• direction_style attribute (optional): Specifies the style name to be used for a link direction marker (for example, a directional arrow image).

• bidirection_style attribute (optional): Specifies the style name to be used for a bidirected link.

• direction_position attribute (optional): Specifies the position of the direction marker relative to the link start, as a number between 0 and 1. For example, 0.85 indicates 85 percent of the way between the link start and end points.

• direction_markersize attribute (optional): Specifies the size (number of pixels) of the direction marker.

• direction_multimarker attribute (optional): Specifies if the direction marker should be repeated over the link: true repeats the marker at a specified start position and each subsequent interval of that distance; false (the default) does not repeat the marker.

• link_labelstyle attribute (optional): Specifies the style name to be used for link labels in the column specified in the link_labelcolumn attribute.

• link_labelcolumn attribute (optional): Specifies the name of the column containing link labels to be rendered using the style specified in the link_labelstyle attribute.

• node_style attribute (optional): Specifies the style name to be used for nodes.

• node_markersize attribute (optional): Specifies the size (number of pixels) of the node marker.

• node_labelstyle attribute (optional): Specifies the style name to be used for node labels in the column specified in the node_labelcolumn attribute.

• node_labelcolumn attribute (optional): Specifies the name of the column containing node labels to be rendered using the style specified in the node_labelstyle attribute.

• path_ids attribute (optional): Specifies one or more path ID values of stored paths to be rendered. For more than one path, use commas to delimit the path ID values. For example, path_ids="1,3,4" specifies that the paths with path ID values 1, 3, and 4 are to be rendered.

• path_styles attribute (optional): Specifies one or more style names associated with the paths specified in the path_ids attribute. For example, path_styles="C.RED,C.GREEN,C.BLUE" specifies styles to be used to render the first, second, and third paths (respectively) specified in the path_ids attribute.

• path_labelstyle attribute (optional): Specifies the style name to be used for path labels in the column specified in the path_labelcolumn attribute.

• path_labelcolumn attribute (optional): Specifies the name of the column containing path labels to be rendered using the style specified in the path_labelstyle attribute.

Additional network theme attributes related to network analysis are described in Using the Map Visualization Component for Network Analysis.

A network theme can combine attributes for links, nodes, and paths, or any combination. In such cases, the map visualization component first renders the links, then the paths, and then the nodes.

Example 2-20 defines a network theme that specifies attributes for the display of links and nodes in the network named NYC_NET.

<theme name="net_theme" user_clickable="false">
  <jdbc_network_query
    network_name="NYC_NET"
    network_level="1"
    jdbc_srid="8307"
    datasource="mvdemo"
    link_style="C.RED"
    direction_style="M.IMAGE105_BW"
    direction_position="0.85"
    direction_markersize="8"
    node_style="M.STAR"
    node_markersize="5"
    asis="false">
  </jdbc_network_query>
</theme>

• Creating Predefined Network Themes
  
• Using the Map Visualization Component for Network Analysis
  

A topology theme is a special kind of map visualization component theme useful for visualizing topologies defined using the Oracle Spatial and Graph topology data model. The topology data model lets you work with data about nodes, edges, and faces in a topology. The spatial representations of nodes, edges, and faces are spatial geometries of type SDO_GEOMETRY. For nodes and edges, the geometries are explicitly stored; for faces, the initial lines (exterior and interior) are stored, allowing the face geometry to be generated.

In addition to the spatial representation of nodes, edges, and faces, a topology can have features. A feature (also called a topology geometry) is a spatial representation of a real-world object. Each feature is defined as an object of type SDO_TOPO_GEOMETRY, which identifies the topology geometry type, topology geometry ID, topology geometry layer ID, and topology ID. For detailed information, see Oracle Spatial and Graph Topology Data Model and Network Data Model Graph Developer's Guide.

The map visualization component can render topology features. It can also render a theme in debug mode (explained later in this section) to show the nodes, edges, and faces of a topology. For each topology theme, the map visualization component uses the topology metadata information stored in the USER_SDO_TOPO_METADATA view.

The following elements and attributes apply to the definition of a topology theme:

• <jdbc_topology_query> element: Specifies that this is a dynamically defined topology theme. The element can specify a SQL query statement (without a terminating semicolon).

• topology_name attribute: Specifies the name of the topology.

• feature_table attribute: Specifies the name of the feature table.

• spatial_column attribute: Specifies the name of the spatial feature column of type SDO_TOPO_GEOMETRY.

• label_column attribute: Specifies the column in the feature table that contains the text label to be used with each feature.

• label_style attribute: Specifies the name of the text style to be used to render the labels in the label column.

• render_style attribute: Specifies the name of the style to be used to render the topology.

Example 2-24 defines a topology theme that specifies attributes for the display of features and labels from the LAND_PARCELS table in the CITY_DATA topology. The SQL statement specifies the spatial feature column and the label column, and it includes all rows in the feature table.

The map visualization component also supports a debug mode that renders the nodes, edges, and faces of a topology. To specify debug mode, include the mode="debug" attribute in the <theme> element. In addition to the <jdbc_topology_query> attributes mentioned earlier in this section, the following attributes can be used in debug mode:

• edge_style attribute: Specifies the name of the style to be used to render edges.

• edge_label_style attribute: Specifies the name of the text style to be used to render edge labels.

• edge_marker_style attribute: Specifies the name of the marker style to be used for edge markers.

• edge_marker_size attribute: Specifies the size (number of pixels) of for edge markers.

• node_style attribute: Specifies the name of the style to be used to render nodes.

• node_label_style attribute: Specifies the name of the text style to be used to render node labels.

• face_style attribute: Specifies the name of the style to be used to render faces.

• face_label_style attribute: Specifies the name of the text style to be used to render face labels.

Example 2-25 defines a debug-mode topology theme for rendering features, edges, nodes, and faces from all feature tables in the CITY_DATA topology.

<theme name="topo_theme" user_clickable="false">
  <jdbc_topology_query
    topology_name="CITY_DATA"
    feature_table="LAND_PARCELS"
    label_column="FEATURE_NAME"
    spatial_column="FEATURE"
    label_style="T.CITY NAME"
    render_style="C.COUNTIES"
    jdbc_srid="0"
    datasource="topology"
    asis="false">select feature, feature_name from land_parcels
  </jdbc_topology_query>
</theme>

<theme name="topo_theme" mode="debug" user_clickable="false">
  <jdbc_topology_query
    topology_name="CITY_DATA"
    edge_style="C.RED"
    edge_marker_style="M.IMAGE105_BW"
    edge_marker_size="8"
    edge_label_style="T.EDGE"
    node_style="M.CIRCLE"
    node_label_style="T.NODE"
    face_style="C.BLUE"
    face_label_style="T.FACE"
    jdbc_srid="0"
    datasource="topology"
    asis="false">
  </jdbc_topology_query>
</theme>

• Creating Predefined Topology Themes
  

A WFS theme is a special kind of map visualization component theme that supports the rendering of data delivered using the Open GIS Consortium (OGC) Web Feature Service (WFS) protocol, specifically the WFS 1.0.0 implementation specification.

WFS theme are conceptually similar to geometry themes, and users are able to render and label features. The WFS operations GetCapabilities, DescribeFeatureType, and GetFeature are used when rendering a WFS theme. When a WFS service is accessed, the map visualization component caches the information about capabilities and feature types.

• GetCapabilities retrieves the server general information, including the URL addresses to issue requests and the features available. In general, a WFS capability request has the form:

  http://localhost:1979/geoserver/wfs/GetCapabilities?SERVICE=WFS&VERSION=1.0.0&REQUEST=GetCapabilities
  

  The result includes a <Capabilities> element with the URL addresses for the WFS requests. For example, the following includes the GetCapabilities URLs for HTTP GET and POST requests.

  <Capability>
   <Request>
    <GetCapabilities>
     <DCPType>
      <HTTP>
       <Get onlineResource="http://localhost:1979/geoserver/wfs/GetCapabilities?" />
      </HTTP>
     </DCPType>
     <DCPType>
      <HTTP>
       <Post onlineResource="http://localhost:1979/geoserver/wfs/GetCapabilities?" /> 
      </HTTP>
      </DCPType>
    </GetCapabilities>
  . . .
  </Capability>
  

• DescribeFeatureType retrieves the feature information, including attributes and types.

• GetFeature retrieves the feature geometries and attributes. The output format for GetFeature requests is GML2.

The following attributes apply to the definition of a WFS theme:

• datasource attribute: Specifies the map visualization component data source from which styles will be loaded.

• feature_attributes attribute: Specifies feature attributes (besides geometry and label columns) that can be used with advanced styles.

• feature_ids attribute: Specifies the WFS feature IDs to be retrieved. Feature IDs are represented with the fid name in the WFS responses. If feature IDs are specified, spatial filter and query conditions are not used in the WFS request.

• feature_name attribute: Specifies the WFS feature name.

• key_column attribute: Specifies the attribute to be used as a key column. Applies to predefined themes, and can be used in Oracle Maps applications. If key_column is not specified, fid is used as the key column.

• label_column attribute: Specifies the column in the feature table that contains the text label to be used with each WFS feature.

• label_style attribute: Specifies the name of the text style to be used to render the labels in the label column.

• query_condition attribute: Specifies a WHERE clause condition to be applied to the WFS theme. Cannot be a complex condition with a hierarchy of expressions defined using multiple parentheses. Each string in the query must be separated by a blank space. If the condition cannot be parsed, it is ignored on the WFS request. Any query conditions are ignored if you specify the feature_ids attribute. The following are examples of valid expressions:

  state_name = 'New Hampshire' or state_name = 'New York'
  (state_name = 'New Hampshire' or state_name = 'New York') and top_pop > 700000
  (state_name = 'New Hampshire' or state_name = 'New York') and (top_pop > 700000)
  

• render_style attribute: Specifies the name of the style to be used to render the geometry.

• service_url attribute: Corresponds to the capabilities address for HTTP GET requests. The service_url parameter for the map visualization component must be the online resource address for HTTP GET in the <GetCapabilities> element. In the preceding example, the value to be used is: http://localhost:1979/geoserver/wfs/GetCapabilities?

  Do not include the Capabilities parameters SERVICE, VERSION, and REQUEST; use just the URL from the capabilities information.

• spatial_column attribute: Specifies the name of the spatial feature column of type SDO_TOPO_GEOMETRY.

• srs attribute: Specifies the spatial reference system (coordinate system) name for the WFS feature, in EPSG or Oracle Spatial and Graph format. For example, EPSG:4325, SDO:8307, and 8307 (the Spatial and Graph SRID value) specify the same SRS. If an EPSG SRS value is specified, the map visualization component tries to identify an equivalent Spatial and Graph (SDO) SRID; and if no matching SRID is found, the SRID for the theme is assumed to be zero (0). The map visualization component looks for matching SRID values as follows:

  1. Use any custom mapping specified in an SDO to EPSG SRID mapping file specified map visualization component configuration file, as explained inCustomizing SRS Mapping.

  2. Use the Spatial and Graph function SDO_CS.MAP_EPSG_SRID_TO_ORACLE to get the equivalent SDO code (if this function is available in the version of Oracle Database used to store the data).

  3. Use the EPSG code that is in the MDSYS.CS_SRS table, if a match can be found.

• user and password attributes can be defined to access a secured WFS server that uses basic authentication.

  If the WFS server is deployed in WebLogic Application Server, the parameter -DUseSunHttpHandler=true must be added to the startup script of WebLogic server.

Example 2-27 shows a request with a dynamic WFS theme. The WFS service is geoserver, and it is installed on the local system.

<?xml version="1.0" standalone="yes"?>
<map_request
             title="WFS MAP"
             datasource = "mvdemo"
             width="640"
             height="480"
             bgcolor="#a6cae0"
             antialiase="true"
             mapfilename="wfs_map"
             format="PNG_URL">
  <center size="20.">
     <geoFeature  >
         <geometricProperty typeName="center">
             <Point>
                 <coordinates>-70., 44.</coordinates>
             </Point>
         </geometricProperty>
     </geoFeature>
  </center>
 
  <themes>
   <theme name="wfs" >
     <wfs_feature_request 
         service_url="http://localhost:1979/geoserver/wfs/GetCapabilities?"
         srs="EPSG:4326"
         feature_name="states"
         spatial_column="the_geom"
         render_style="C.COUNTIES"
         label_column="STATE_NAME"
         label_style="T.STATE NAME"
         datasource="mvdemo" />
    </theme> 
  </themes>
 
</map_request>

• Creating Predefined WFS Themes
  

A WMTS theme supports the rendering of data delivered using the Open GIS Consortium (OGC) Web Map Tile Service (WMTS) standard, specifically the WMTS 1.0.0 implementation standard.

A WMTS theme fetches tile images from a WMTS-enabled server over the Internet and renders the images. The tile images on a WMTS-enabled server are spatially referenced with predefined content, extent, and resolution.

The WMTS operations GetCapabilities, GetTile, and GetFeatureInfo are used when rendering a WMTS theme. When a WMTS service is accessed by the map visualization component, it caches the capabilities information of that WMTS service. You may need to specify a proxy server in Map Builder when creating a WMTS theme and to edit the map visualization component configuration file (MapViewerConfig.xml) when a WMTS theme is being used.

• A GetCapabilities operation retrieves the server's general information, including the URL addresses to issue requests and the features available. In general, a WMTS capability request has the form:

  http://maps.opengeo.org/geowebcache/service/wmts?service=WMTS&version=1.0.0&request=GetCapabilities
  

  The result includes a <Capabilities> element with the URL addresses for the WMTS requests. For example, the following includes the GetCapabilities URLs for HTTP GET or POST requests:

  <?xml version="1.0" encoding="UTF-8"?>
  <Capabilities xmlns="http://www.opengis.net/wmts/1.0"
  xmlns:ows="http://www.opengis.net/ows/1.1"
  xmlns:xlink="http://www.w3.org/1999/xlink"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xmlns:gml="http://www.opengis.net/gml" xsi:schemaLocation="http://www.opengis.net/wmts/1.0 http://schemas.opengis.net/wmts/1.0/wmtsGetCapabilities_response.xsd"
  version="1.0.0">
  <ows:ServiceIdentification>
    <ows:Title>Web Map Tile Service - GeoWebCache</ows:Title>
    <ows:ServiceType>OGC WMTS</ows:ServiceType>
    <ows:ServiceTypeVersion>1.0.0</ows:ServiceTypeVersion>
  </ows:ServiceIdentification>
  <ows:ServiceProvider>
    <ows:ProviderName>http://maps.opengeo.org/geowebcache/service/wmts</ows:ProviderName>
    <ows:ProviderSite xlink:href="http://maps.opengeo.org/geowebcache/service/wmts" />
    <ows:ServiceContact>
      <ows:IndividualName>GeoWebCache User</ows:IndividualName>
    </ows:ServiceContact>
  </ows:ServiceProvider>
  <ows:OperationsMetadata>
    <ows:Operation name="GetCapabilities">
      <ows:DCP>
        <ows:HTTP>
          <ows:Get xlink:href="http://maps.opengeo.org/geowebcache/service/wmts?">
            <ows:Constraint name="GetEncoding">
              <ows:AllowedValues>
                <ows:Value>KVP</ows:Value>
              </ows:AllowedValues>
            </ows:Constraint>
          </ows:Get>
        </ows:HTTP>
      </ows:DCP>
    </ows:Operation>
    <ows:Operation name="GetTile">
      <ows:DCP>
        <ows:HTTP>
          <ows:Get xlink:href="http://maps.opengeo.org/geowebcache/service/wmts?">
            <ows:Constraint name="GetEncoding">
              <ows:AllowedValues>
                <ows:Value>KVP</ows:Value>
              </ows:AllowedValues>
            </ows:Constraint>
          </ows:Get>
        </ows:HTTP>
      </ows:DCP>
    </ows:Operation>
    <ows:Operation name="GetFeatureInfo">
      <ows:DCP>
        <ows:HTTP>
          <ows:Get xlink:href="http://maps.opengeo.org/geowebcache/service/wmts?">
            <ows:Constraint name="GetEncoding">
              <ows:AllowedValues>
                <ows:Value>KVP</ows:Value>
              </ows:AllowedValues>
            </ows:Constraint>
          </ows:Get>
        </ows:HTTP>
      </ows:DCP>
    </ows:Operation>
  </ows:OperationsMetadata>
  <Contents>
    <Layer>
      <ows:Title>bluemarble</ows:Title>
      <ows:WGS84BoundingBox>
        <ows:LowerCorner>-180.0 -90.0</ows:LowerCorner>
        <ows:UpperCorner>180.0 90.0</ows:UpperCorner>
      </ows:WGS84BoundingBox>
      <ows:Identifier>bluemarble</ows:Identifier>
      <Style isDefault="true">
        <ows:Identifier>_null</ows:Identifier>
      </Style>
      <Format>image/png</Format>
      <Format>image/jpeg</Format>
      <TileMatrixSetLink>      
        <TileMatrixSet>EPSG:4326</TileMatrixSet>
      </TileMatrixSetLink>    
      <TileMatrixSetLink>
        <TileMatrixSet>EPSG:900913</TileMatrixSet>
      </TileMatrixSetLink>  
    </Layer>
    ...
    <TileMatrixSet>
      <ows:Identifier>EPSG:4326</ows:Identifier>
      <ows:SupportedCRS>urn:ogc:def:crs:EPSG::4326</ows:SupportedCRS>
      <TileMatrix>
        <ows:Identifier>EPSG:4326:0</ows:Identifier>
        <ScaleDenominator>2.795411320143589E8</ScaleDenominator>
        <TopLeftCorner>90.0 -180.0</TopLeftCorner>
        <TileWidth>256</TileWidth>
        <TileHeight>256</TileHeight>
        <MatrixWidth>2</MatrixWidth>
        <MatrixHeight>1</MatrixHeight>
      </TileMatrix>
     ...
    </TileMatrixSet>
    ...
  </Contents>
  <ServiceMetadataURL xlink:href="http://maps.opengeo.org/geowebcache/service/wmts?REQUEST=getcapabilities&amp;VERSION=1.0.0"/>
  </Capabilities>
  

• A GetTile operation retrieves a tile image from a WMTS server. A request to the server contains parameters of key-value pairs (KVP) that define the tile image.

• A GetFeatureInfo operation allows WMTS clients to request information at a specific position of a specific tile for a specific query layer.

Detailed descriptions of these operations can be found at http://www.opengeospatial.org/standards/wmts.

The following attributes apply to the definition of a WMTS theme:

• current_threads attribute (optional): an integer (int) variable; the default is 8. It is the number of concurrent threads for retrieving tile images from a WMTS server. In general, a larger number of concurrent threads allows more threads to retrieve image tiles in parallel from a map server. Other constraining factors may prevent you from using a number in the hundreds, but you may try to set it 16, 32, or a slightly larger value for faster processing.

• format attribute: Specifies the tile image formats stored in the WMTS server. The tif, jpeg, png, and png8 formats are supported in the map visualization component.

• layer attribute: Specifies the layer name for which the tile images are to be fetched.

• matrix_set_id attribute: Specifies the ID of the matrix set from which the tile images are to be fetched.

• service_url attribute: Corresponds to the capabilities address for HTTP GET requests. The service_url parameter for the map visualization component must be the online resource address for HTTP GET in the <GetCapabilities> element. In the preceding example, the value to be used is: http://maps.opengeo.org/geowebcache/service/wmts?

• snap_to_tile_scale attribute (optional): a Boolean value (true or false); the default is false.

  When snap_to_tile_scale is set to true, a request scale (derived from a device-window size and a request-data-window size) is snapped to a closest tile scale; the map scale will be in the tile scale. For example, if there are tiles in scale series of …, 1:4000, 1:2000, 1.1000, 1:500, …., a request scale of 1:1600 will be snapped to the 1:2000 tile scale, and the map will be using the same 1:2000 scale, as shown in Figure 2-9.

  Figure 2-9 snap_to_tile_scale Attribute

  
  Description of "Figure 2-9 snap_to_tile_scale Attribute"

  If a map request has more than one WMTS theme that specifies snap_to_tile_scale as true, then only the first WMTS snap_to_tile_scale specification is set to true and all others are reset to false. This is the logical behavior. For example, if two such themes both have the attribute set to true, but the two WMTS tile scale series are different from each other (the two map servers may be from different institutions using different scale series), the first theme will then use its closest tile scale to retrieve tile data and for the final request scale; at the same time, the second theme has to reset its snap_to_tile_scale to false, then has to find its own tile scale according to its tile_resizing_option, then retrieve tiles, and finally resize the tiles to match the first theme's tile scale.

• style attribute: Currently not used in the map visualization component; the default is the string default.

• tile_resizing_option attribute (optional): the string unbiased, expand_biased, or contract_biased; the default is unbiased. If snap_to_tile_scale is set to true, tile_resizing_option is ignored.

  For more information, see How the tile_resizing_option Attribute Works.

• timeout attribute (optional): an integer specifying a request's timeout period in milliseconds; the default is 0, (that is, no limit for a request to wait for a response).

  Specifying this attribute ensures that a map request is terminated when the map server does not respond within the specified time period, and thus frees the resources. You might try a value of 30000 (30,000 milliseconds, or 30 seconds).

• top_left_corner_x attribute (optional): the x coordinate value of the top left corner of the whole tile images' extent that is served by a WMTS server. If not specified, the value retrieved from the WMTS server is used. If you specify this attribute, also specify the top_left_corner_y attribute.

• top_left_corner_y attribute (optional): the y coordinate value of the top left corner of the whole tile images' extent that is served by a WMTS server. If not specified, the value retrieved from the WMTS server is used. If you specify this attribute, also specify the top_left_corner_x attribute.

• version attribute: the version of the WMTS specification implemented by the WMTS server.

• How the tile_resizing_option Attribute Works
  
• snap_to_tile_scale and tile_resizing_option Attribute Usage Guidelines
  
• Creating Predefined WMTS Themes
  

public interface SDataProvider
{
  /**
   * Returns the initialization parameters for the provider.
   * @return String[] - array with initialization parameter names
   */
  public String[] getInitParameterNames();
 
  /**
   * Returns runtime parameter names. Runtime parameters are additional parameters
   * that the provider may use when retrieving the data objects.
   * @return String[] - array with runtime parameter names
   */
  public String[] getRuntimeParameterNames();
 
  /**
   * Returns a value that gives a hint for the runtime parameter value.
   * This hin can be used as a tooltip in user intefaces.
   * @param runtimeParam
   * @return   a String representing the hint value, or null if no hint is available
   */
  public String getRuntimeParameterHintValue(String runtimeParam);
 
  /**
   * This method is used to set the initialization parameters for the specific
   * data provider.
   * @param params - parameters to be used by the initialization method.
   * @return boolean - true if success; false otherwise
   */
  public boolean init(Properties params);
 
  /**
   * This method creates and returns an instance of SDataSet which contains
   * all the Spatial data produced by this provider, based on
   * the given parameters for a specific incoming map request.
   * <br>
   * The map visualization component calls this method on the custom theme producer implementation.
   *
   * @param queryWin the search area to retrieve spatial objects. The window is
   * assumed to be already on data provider spatial reference system.
   * @param nonSpatialColumns - the list of attributes that will return with objects.
   * @param queryCondition - query condition expression (may have binding parameters).
   * @param bindingParameters - binding variables for query condition with binding parameters.
   * @param params  - parameters that the provider may use to retrieve the data.
   * @return SDataObject - an instance of SDataSet class; null if failed.
   */
  public SDataSet buildDataSet(Rectangle2D queryWin,String []nonSpatialColumns,
                               String queryCondition,Object[] bindingParameters,
                                Properties params);
 
  /**
   * Returns the list of existing attributes for this data provider.
   * @param params  parameters that the provider may use to get the attribute list.
   * @return Field[] - array of attributes for this provider.
   */
  public Field[] getAttributeList(Properties params);
 
  /**
   * Returns the data set spatial extent MBR.
   * @param params  parameters that the provider may use to get the data extents
   * @return Rectangle2D - data spatial extent for this provider.
   */
  public Rectangle2D getDataExtents(Properties params);
 
 /**
   * Returns if provider can build spatial indexes.
   * If true, means that buildSpatialIndex method can be called.
   * @return
   */
  public boolean canBuildSpatialIndex();
 
  /**
   * Builds a spatial index on the data set.
   * @param params  parameters that the provider may use to build the spatial index.
   * @return boolean - true if saptial index creation is successful.
   */
  public boolean buildSpatialIndex(Properties params);
 
  /**
   * Clears provider internal caches (if provider implement caches).
   */
  public void clearCache();
 
 
  /**
   * Returns the parameter names that can be used to query for spatial tables.
   * Can be used more as information for user interfaces.
   * @return
   */
  public String[] getParametersToQuerySpatialMetadata();
 
  /**
   * Returns the spatial tables and spatial columns.
   * @param params must define the parameters returned from
   * getParametersToQuerySpatialMetadata.
   * @return  an array list defining the table name(index [0])
   *          and spatial column (index[1])
   */
  public String[][] getSpatialTables(Properties params);
}

1. Implement a spatial provider class based on the plug-in interface, and generate a jar file with the provider implementation. Copy the jar file to a directory that is part of the map visualization component CLASSPATH definition.
2. Register the provider in the map visualization component configuration. The map visualization component ships with a shapefile provider to access ESRI shapefiles, a GDAL-OGR provider to access data formats supported by OGR, and a Teradata provider to access data stored in a Teradata database. (See the GDAL-OGR and Teradata documentation for detailed information about handling spatial data in these environments.) The GDAL-OGR library gdal.jar, and Teradata libraries terajdbc4.jar and tdgssconfig.jar, must be on server classpath. The registration section in the map visualization component configuration file looks like this:

   <s_data_provider
     id="shapefileSDP"
     class="oracle.sdovis.ShapefileDataProvider"
     >
     <parameters>
       <parameter name="datadir" value="/temp/data" />
     </parameters>
   </s_data_provider>
   

   Each provider must have id and class names defined: id is a unique name that identifies the provider, and class corresponds to the Java class implementation. The <parameters> element defines the initialization parameters of the provider.

   For the shapefile provider, the initialization parameter datadir defines where the map visualization component will look for the data files, and thus it should be a directory that is accessible to the map visualization component. The map visualization component first looks for data files based on the theme definition information; and if the data path defined in the theme definition is not accessible, the map visualization component looks for the data path defined in the configuration file.

3. Create custom geometry themes associated with the external spatial data provider.

<theme name="custom_geom_theme_1" >
   <custom_geom_theme
     provider_id="shapefileSDP"
     srid="26986"
     render_style="C.RED"
     label_column="parcel_id"
     label_style="T.CITY NAME"
     datasource="mvdemo">
   <parameters>
    <parameter name="filename" value="/lbs/demo/shapefile/parcel.shp"/>
   </parameters>
  </custom_geom_theme>
</theme>

insert into user_sdo_themes values ( 
'SHAPE_THEME', 
'Shapefile theme', 
'CUSTOM_TABLE', 
'GEOMETRY', 
'<?xml version="1.0" standalone="yes"?> 
<styling_rules theme_type="geom_custom" srid="26986" provider_id="shapefileSDP"> 
  <rule> 
    <features style="C.RED"> </features> 
    <label column="PARCEL_ID" style="T.CITY NAME"> 1 </label> 
  </rule> 
  <parameters> 
    <parameter name="filename" value="/lbs/demo/shapefile/parcel.shp"/> 
  </parameters> 
</styling_rules>' 
);

<theme name="CUSTOM_THEME" >
  <parameters>
    <parameter name="filename" value="/lbs/demo/shapefile/counties.shp"/>
  </parameters>
</theme>

Oracle Spatial and Graph supports annotation text as specified in the OpenGIS Implementation Specification for Geographic information - Simple feature access - Part 1: Common architecture, which defines annotation text as "simply placed text that can carry either geographically-related or ad-hoc data and process-related information as displayable text. This text may be used for display in editors or in simpler maps. It is usually lacking in full cartographic quality, but may act as an approximation to such text as needed by any application."

Oracle Spatial and Graph provides the ST_ANNOTATION_TEXT object type for storing annotation text, and the USER_ANNOTATION_TEXT_METADATA and ALL_ANNOTATION_TEXT_METADATA views for storing metadata related to annotation text. For more information about annotation text support, see Oracle Spatial and Graph Developer's Guide.

Each annotation text object may have one or more elements, and each element is defined by the following:

• Value: Text associated with element. If the value is null, the text is derived from the first non-null preceding element value. If all preceding elements have null values, the text is a text expression value derived from the metadata.

• Location: Spatial location associated with the annotation text object.

• Leader line: Linear feature associated with the annotation text object.

• Attributes: Graphic attributes used to display the text. If the value is null, graphic attributes are derived from the attributes value in the metadata.

The text expression in the metadata views can be any of the following:

• A column name.

• A function applied to a column name. For example: substr(my_col,1,3)

• The concatenation of two or more column names. For example: column_1 || column_2 || column_3

• A text value that is unrelated to a column name. In this case, it is treated as a simple text string that is used for any text element that has a null value.

Annotation text themes in the map visualization component are associated with database tables that have a column of type ST_ANNOTATION_TEXT. For each annotation text element, the map visualization component will render:

• The value (if not null) of the annotation text element as a string, using a text style that is created at real time based on the element attributes.

• The leader line (if not null) associated with the annotation text element. In this case, users can select a map visualization component style to render the leader line.

Each annotation text element has an envelope represented by a geometry, and which is used for spatial indexing. Therefore, you must do the following to use spatial indexing with annotation text tables in the map visualization component:

1. Insert a row into the USER_ANNOTATION_TEXT_METADATA view that specifies the name of the annotation text table and the PRIVATEENVELOPE attribute of the annotation text column (that is, the column of type ST_ANNOTATION_TEXT).

   The following example inserts a row for a table named ANNOTEXT_TABLE with an annotation text column named TEXTOBJ:

   INSERT INTO USER_SDO_GEOM_METADATA 
     VALUES (
     'ANNOTEXT_TABLE',
     'TEXTOBJ.PRIVATEENVELOPE',
     SDO_DIM_ARRAY(
       SDO_DIM_ELEMENT('X', 0.0, 10.0, 0.0005),
       SDO_DIM_ELEMENT('Y', 0.0,10.0, 0.0005)
        ),
     null   -- SRID
   );
   

2. Create a spatial index on the annotation text envelope of the annotation text table.

   The following example creates a spatial index named ANNO_TEXT_IDX on the annotation envelope of the table named ANNOTEXT_TABLE:

   CREATE INDEX anno_text_idx ON annotext_table(textobj.privateenvelope)
     INDEXTYPE IS mdsys.spatial_index;
   

For themes with valid SRID information, if the metadata base map scale is defined, the element text sizes will be scaled as maps zoom in or out.

Example 2-35 defines the styling rules for a predefined annotation text theme in the map visualization component. The structure is similar to other map visualization component themes. Currently, just one styling rule is processed for each annotation theme. In this example, the theme type is annotation, the feature style L.PH is used to render leader lines, and the query condition (id = 1 or id = 2) is appended on the final query.

Example 2-36 shows the theme definition for a dynamic annotation text theme. The parameters defined are:

• datasource: the data source name

• jdbc_srid: the spatial reference identifier

• annotation_table: the annotation text table

• annotation_column: the annotation text column

• leaderline_style: the leader line style to be used

Example 2-37 is similar to Example 2-36, but it adds the behavior that if the annotation_column column contains a null value, then the value in the textexpr_column is used for the annotation instead. In Example 2-37, assume that the ANNOTATION_TABLE table contains a column named DEFAULT_ANNOTATION (which is used in Example 2-38). This additional column is specified in the textexpr_column attribute and in the SELECT statement.

Example 2-38 creates an annotation text table and prepares it to be used with the map visualization component.

<?xml version="1.0" standalone="yes"?>
<styling_rules theme_type="annotation">
    <rule>
        <features style="L.PH"> (id = 1 or id = 2) </features>
  </rule>
</styling_rules>

<themes>
  <theme name="theme1" >
     <jdbc_annotation_query
       datasource="tilsmenv"
       jdbc_srid="0"
       annotation_table="ANNOTEXT_TABLE"
       annotation_column="textobj"
       leaderline_style="L.PH"
       >select textobj from annotext_table
     </jdbc_annotation_query>
   </theme>
</themes>

<themes>
  <theme name="theme1" >
     <jdbc_annotation_query
       datasource="tilsmenv"
       jdbc_srid="0"
       annotation_table="ANNOTEXT_TABLE"
       annotation_column="textobj"
       textexpr_column="default_annotation"
       leaderline_style="L.PH"
       >select textobj, default_annotation from annotext_table
     </jdbc_annotation_query>
   </theme>
</themes>

SET ECHO ON
SET FEEDBACK 1
SET NUMWIDTH 10
SET LINESIZE 100
SET PAGESIZE 10000
SET SERVEROUTPUT ON SIZE 5000
SET LONG 20000
SET TIMING ON
call dbms_java.set_output(5000);
 
---------------------------------------------------------------------
-- Create an annotation text table (a table that has a
-- column of ST_ANNOTATION_TEXT object type), and insert some records.
---------------------------------------------------------------------
 
create table annotext_table (
  id number, 
  default_annotation varchar2(32), 
  textobj ST_ANNOTATION_TEXT);
 
insert into annotext_table values (1,'Text_1',
ST_ANNOTATION_TEXT(
   ST_ANNOTATIONTEXTELEMENT_ARRAY(
          ST_ANNOT_TEXTELEMENT_ARRAY(
                ST_ANNOTATIONTEXTELEMENT('Sample Label 1',
                   SDO_GEOMETRY(2001, null, sdo_point_type(1,1,null),null,null),
                   SDO_GEOMETRY(2002,null,null,
                       SDO_ELEM_INFO_ARRAY(1,2,1),
                       SDO_ORDINATE_ARRAY(0,0, 1,1)), NULL)))));
 
insert into annotext_table values (2,'Text_2',
ST_ANNOTATION_TEXT(
   ST_ANNOTATIONTEXTELEMENT_ARRAY(
          ST_ANNOT_TEXTELEMENT_ARRAY(
                ST_ANNOTATIONTEXTELEMENT('Sample Label 2',
                   SDO_GEOMETRY(2001,null,sdo_point_type(10,10,null),null,null),
                   SDO_GEOMETRY(2002,null,null,
                       SDO_ELEM_INFO_ARRAY(1,2,1),
                       SDO_ORDINATE_ARRAY(5,10, 10,10)), NULL)))));
 
insert into annotext_table values (3, 'Text_3',
ST_ANNOTATION_TEXT(
   ST_ANNOTATIONTEXTELEMENT_ARRAY(
          ST_ANNOT_TEXTELEMENT_ARRAY(
                ST_ANNOTATIONTEXTELEMENT(null,
                   SDO_GEOMETRY(2002, null, null,
                       SDO_ELEM_INFO_ARRAY(1,2,1),
                       SDO_ORDINATE_ARRAY(2,5,4,5,6,5)),
                   SDO_GEOMETRY(2002,null,null,
                       SDO_ELEM_INFO_ARRAY(1,2,1),
                       SDO_ORDINATE_ARRAY(4,3, 4,5)),
'<?xml version="1.0" encoding="UTF-8" ?>
<textAttributes xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
               xsi:noNamespaceSchemaLocation="../../annotation_text.xsd">
 <textStyle fontFamily="Dialog" fontSize="14" fill="blue"/>
 <textlayout/>
</textAttributes>'
)))));
 
---------------------------------------------------------------------
-- Register the annotation text table in the user metadata view.
---------------------------------------------------------------------
 
insert into USER_ANNOTATION_TEXT_METADATA values(
  'ANNOTEXT_TABLE', 'TEXTOBJ', null, null, null);
 
---------------------------------------------------------------------
-- Update the metadata information.
---------------------------------------------------------------------
 
update user_annotation_text_metadata set
text_expression='default_annotation',
text_attributes =
'<?xml version="1.0" encoding="UTF-8" ?>
<textAttributes xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
               xsi:noNamespaceSchemaLocation="../../annotation_text.xsd">
 <textStyle fontFamily="Serif" fontSize="14" fill="#ff0000"/>
 <textlayout/>
</textAttributes>';
 
---------------------------------------------------------------------
-- Register the annotation text geometry envelope on the user
-- metadata view of geometries.
---------------------------------------------------------------------
 
INSERT INTO USER_SDO_GEOM_METADATA
 VALUES (
 'ANNOTEXT_TABLE',
 'TEXTOBJ.PRIVATEENVELOPE',
 SDO_DIM_ARRAY(
   SDO_DIM_ELEMENT('X', 0.0, 10.0, 0.0005),
   SDO_DIM_ELEMENT('Y', 0.0,10.0, 0.0005)
    ),
 null   -- SRID
);
 
---------------------------------------------------------------------
-- Create a spatial index on the annotation text envelope.
---------------------------------------------------------------------
 
create index anno_text_idx on annotext_table(textobj.privateenvelope)
  indextype is mdsys.spatial_index;
 
-------------------------------------------------------------------------------
-- Insert a predefined theme into the map visualization component's theme view.
-------------------------------------------------------------------------------
 
INSERT INTO user_sdo_themes  VALUES (
  'ANNOTEXT_THEME',
  'Annotation text',
  'ANNOTEXT_TABLE',
  'TEXTOBJ',
  '<?xml version="1.0" standalone="yes"?>
   <styling_rules theme_type="annotation">
     <rule >
      <features style="L.PH"> </features>
     </rule>
   </styling_rules>' );
 
commit;

An LRS theme is a special kind of map visualization component theme useful for visualizing features defined using the linear referencing system (LRS) of Oracle Spatial and Graph, which is explained in Oracle Spatial and Graph Developer's Guide.

Two tables are needed by an LRS theme: one (the LRS table) has an LRS geometry column, and the other (the join table) has one or two measure columns. Point events must have one measure column in the join table (for example, a road sign located at a measure of m1, and an accident that occurred at a measure of m2); while linear events must have two measure columns, one for a starting measure and one for an end measure (for example, from measure m1 to measure m2 the road pavement condition is poor, and from measure n1 to measure n2 the condition is fair). Each event is stored in one row in the join table.

After an LRS theme is defined, you only need to specify the theme name in a map request when you use the theme. The map visualization component automatically finds the theme's definition and constructs a query that joins these two specified tables; it then generates the geometry data by internally using an LRS function, either SDO_LRS.LOCATE_PT for point events or SDO_LRS.CLIP_GEOM_SEGMENT for linear events. The map visualization component then renders the generated point or linear segment, together with their attribute data, according to the styling rules for the theme.

To create a predefined LRS theme, you must store the definition of the LRS theme in the database by inserting a row into the USER_SDO_THEMES view. Example 2-39 stores the definition of an LRS theme named LRS_THEME.

In Example 2-39, the LRS table name (INTERSTATES_LRS, which has three columns, GEOM, HIGHWAY, and ROUTEN) is inserted in the BASE_TABLE column of the USER_SDO_THEMES view, the LRS geometry column (GEOM) is inserted in the GEOMETRY_COLUMN column, and XML document with one <styling_rules> element is inserted into the STYLING_RULES column.

In the <styling_rules> element for an LRS theme, theme_type must be lrs in order for this theme to be recognized as an LRS theme.

If the optional key_column attribute is omitted, no key column is included when constructing a query string to fetch data from a database. This is different from a predefined geometry theme, in which the ROWID column is the default key column.

The child elements <rule>, <hidden_info>, <join_table>, and <join_columns> can be included within the <styling_rules> element. The <join_table> and <join_columns> child elements are specific to LRS themes.

The <rule> element for an LRS theme is similar to the definition in a predefined themes, but its child element <features> must contain an asis attribute with its value set to true (asis="true").There can be 0, 1, or more <rule> elements within a <styling_rules> element.

The <hidden_info> element is optional for an LRS theme. It is defined for use in Oracle Maps applications. It specifies a list of attributes from either the LRS table or the join table, or both.

In <join_table> element, the name attribute (pavement_condition in this example) specifies the join table name. In this example, the join table contains columns such as id, seg_id, condition, from_measure, and to_measure. If two measure columns are used to define linear events in the join table, then attributes start_measure and end_measure (from_measure and to_measure in this example) must be specified, which indicate column names of measurements in the join table. If the join table contains one measure for point events, then a measure attribute is specified in this <join_table> element.

In the <join_columns> element, the lrs_table_column and join_table_column attributes must be specified, where lrs_table_column defines the column from the LRS table, and join_table_column specifies the column from the join table to join these two tables.

Example 2-40 shows a map request that uses the predefined LRS theme from Example 2-39.

INSERT INTO user_sdo_themes (name, description, base_table, geometry_column, styling_rules)
VALUES (
'LRS_THEME',
'LRS theme example with 3 rules, 2 measure columns',
'INTERSTATES_LRS',
'GEOM',
'<?xml version="1.0" standalone="yes"?>
<styling_rules key_column="id" theme_type="lrs">
  <rule>
    <features  asis="true">
      condition=''good''
    </features>
    <label column="condition" style="T.STREET NAME"/>  
    <rendering>
      <style name="L.PTH"/>
    </rendering>
  </rule>
  <rule>
    <features  asis="true">
      condition=''fair''
    </features>
    <label column="condition" style="T.STREET NAME"/>  
    <rendering>
      <style name="L.SH"/>
    </rendering>
  </rule>
  <rule>
    <features  asis="true">
      condition=''poor''
    </features>
    <label column="condition" style="T.STREET NAME"/>  
    <rendering>
      <style name="L.MAJOR STREET"/>
    </rendering>
  </rule>
  <hidden_info>
    <field column="highway"      name="highway name"/>
    <field column="routen"       name="highway number"/>
    <field column="condition"    name="pavement condition"/>
  </hidden_info>
  <join_table
    name="pavement_condition"
    start_measure="from_measure"
    end_measure="to_measure"
  />
  <join_columns
    lrs_table_column="highway"
    join_table_column="seg_id"
  />
</styling_rules>'
);

<?xml version="1.0" standalone="yes"?>
<map_request
  title="LRS Theme test"
  datasource="mvdemo"
  width="640"
  height="480"
  bgcolor="#a6caf0"
  antialiase="true"
  format="PNG_STREAM">
  <center size="45">
    <geoFeature>
      <geometricProperty typeName="center">
        <Point>
          <coordinates>-95, 35</coordinates>
        </Point>
      </geometricProperty>
    </geoFeature>
  </center> 
  <themes>  
    <theme name="LRS_THEME"/>
  </themes>
</map_request>

Thematic mapping refers to the drawing of spatial features based on their attribute values. The map visualization component uses thematic mapping to create maps in which colors or symbols are applied to features to indicate their attributes. For example, a Counties theme can be drawn using colors with different hues that map directly to the population density of each county, or an Earthquakes theme can be plotted with filled circles whose sizes map to the scale or damage of each earthquake.

To achieve thematic mapping, you must first create an advanced style that is suitable for the type of thematic map, and then create a theme for the features specifying the advanced style as the rendering style. In the styling rules for the theme, you must also specify attribute columns in the table or view whose values will be used to determine exactly how a feature will be rendered thematically by the advanced style.

For example, assume that you wanted to display a map in which the color used for each region reflects the level of sales for a particular product. To do this, create an advanced style that defines a series of individual range-based buckets (see Individual Range-Based Buckets), where each bucket contains a predefined range of sales values for a product, and each bucket has an associated rendering style. (Each region will be rendered using the style associated with the range in which that region's sales value falls.) Also specify the name of the column or columns that provide the attribute values to be checked against the ranges. In other words, the advanced style defines how to map regions based on their sales values, and the theme's styling rules tie together the advanced style and the attribute column containing the actual sales values.

Figure 2-13 shows the relationship between an advanced style and a theme, and how the style and the theme relate to the base table. In this figure, the advanced style named V.SALES defines the series of buckets. The predefined theme named SALES_BY_REGION specified the V.SALES style in its styling rules. The theme also identifies the SALES column in the REGIONS table as the column whose value is to be compared with the bucket ranges in the style. (Each bucket could be associated with a labeling style in addition to or instead of a rendering style, as explained in Specifying a Label Style for a Bucket.)

Figure 2-13 Thematic Mapping: Advanced Style and Theme Relationship

Description of "Figure 2-13 Thematic Mapping: Advanced Style and Theme Relationship"

In addition to the individual range-based buckets shown in Figure 2-13, the map visualization component supports other bucket styles, as explained in Bucket Styles. You can also use more than one attribute column for thematic mapping, such as when drawing pie charts.

The rest of this section presents additional examples of thematic mapping.

Example 2-41 is the XML definition for an Earthquakes theme.

Example 2-42 used the <VariableMarkerStyle> tag. The following examples use the <ColorSchemeStyle> tag in creating thematic maps of census blocks in California. Example 2-43 illustrates the use of a graduated color scale for a thematic mapping of population density. Example 2-44 is a thematic mapping of average household income using a graduated color scale. Example 2-45 is also a thematic mapping of average household income, but it uses a specific color style for each income range rather a graduated scale.

• m.esso gasstation, m.texaco gasstation, and the other style names have a space between the words in their names.

• The names are not case-sensitive. Therefore, be sure not to use case as a way of differentiating names. For example, m.esso gasstation and M.ESSO GASSTATION are considered the same name.

• A default collection bucket can be specified by using #DEFAULT# as its value. This bucket is used for any column values (gas station names) that are not specified in the other buckets.

A theme (theme_gasstation) is then defined that specifies the column (MERK) in the table that contains company names. The styling rules of the theme are shown in Example 2-47.

In this table, the GEOM column contains spatial geometries, and the MERK column contains company names (Shell, Esso, and so on).

The styling rules for the theme_gasstation theme specify that the marker (style v.gasstations) at a location specified by the content of the GEOM column is determined by the value of the MERK column for that row. The style v.gasstations (see Example 2-46) specifies that if the column value is Shell, use the style m.shell gasstation; if the column value is Esso, use the style m.esso gasstation; and so on, including if the column value is any one of Avia, Benzinex, Q8, Total, and Witte Pomp, use the style m.generic gasstation; and if the column value is none of the preceding, use the style m.default gasstation.

<?xml version="1.0" standalone="yes"?> 
<styling_rules theme_type="nature"> 
  <rule column="RICHTER_SCALE"> 
    <features style="v.earthquakes"> 
    </features> 
  </rule> 
</styling_rules>

<?xml version="1.0" ?> 
<AdvancedStyle> 
  <VariableMarkerStyle basemarker="m.circle" startsize="7" increment="4"> 
     <Buckets> 
          <RangedBucket seq="0"  label="less than 4"  high="4"/> 
          <RangedBucket seq="1"  label="4 - 5" low="4" high="5"/> 
          <RangedBucket seq="2"  label="5 - 6" low="5" high="6"/> 
          <RangedBucket seq="3"  label="6 - 7" low="6" high="7"/> 
          <RangedBucket seq="4"  label="7 and up" low="7"/> 
      </Buckets> 
  </VariableMarkerStyle> 
</AdvancedStyle> 

# ca pop density usbg_hhinfo 
<?xml version="1.0" standalone="yes"?> 
<styling_rules theme_type="political"> 
<rule column="densitycy"> 
   <features style="v.CA Pop density"> 
   </features> 
 </rule> 
</styling_rules> 

<?xml version="1.0" ?> 
<AdvancedStyle> 
  <ColorSchemeStyle basecolor="#ffff00" strokecolor="#00aaaa"> 
     <Buckets low="0.0" high="20000.0" nbuckets="10"/> 
  </ColorSchemeStyle> 
</AdvancedStyle> 

<?xml version="1.0" standalone="yes"?> 
<!-- # ca hh income theme  table = usbg_hhinfo  --> 
<styling_rules> 
<rule column="avghhicy"> 
   <features style="v.ca income"> 
   </features> 
 </rule> 
</styling_rules> 

<?xml version="1.0" ?> 
<AdvancedStyle> 
  <ColorSchemeStyle basecolor="#ffff00" strokecolor="#00aaaa"> 
  <!-- # income range with a color gradient --> 
     <Buckets> 
          <RangedBucket seq="0" label="less than 10k"  high="10000"/> 
          <RangedBucket seq="1" label="10-15k" low="10000" high="15000"/> 
          <RangedBucket seq="2" label="15-20k" low="15000" high="20000"/> 
          <RangedBucket seq="3" label="20-25k" low="20000" high="25000"/> 
          <RangedBucket seq="4" label="25-35k" low="25000" high="35000"/> 
          <RangedBucket seq="5" label="35-50k" low="35000" high="50000"/> 
          <RangedBucket seq="6" label="50-75k" low="50000" high="75000"/> 
          <RangedBucket seq="7" label="75-100k" low="75000" high="100000"/> 
          <RangedBucket seq="8" label="100-125k" low="100000" high="125000"/>
          <RangedBucket seq="9" label="125-150k" low="125000" high="150000"/>
          <RangedBucket seq="10" label="150-250k" low="150000" high="250000"/>
          <RangedBucket seq="11" label="250-500k" low="250000" high="500000"/>
          <RangedBucket seq="12" label="500k and up"   low="500000"/>
      </Buckets> 
  </ColorSchemeStyle> 
</AdvancedStyle> 

<?xml version="1.0" standalone="yes"?> 
<!-- # ca hh income theme  table = usbg_hhinfo  --> 
<styling_rules> 
<rule column="avghhicy"> 
   <features style="v.ca income 2"> 
   </features> 
 </rule> 
</styling_rules> 

<?xml version="1.0" ?>
<AdvancedStyle>
 <BucketStyle>
  <Buckets>
   <!-- # income ranges with specific colors -->
   <RangedBucket seq="0" label="less than 10k"  high="10000" style="c.rb13_1"/>
   <RangedBucket seq="1" label="10-15k" low="10000" high="15000" style="c.rb13_2"/>
   <RangedBucket seq="2" label="15-20k" low="15000" high="20000" style="c.rb13_3"/>
   <RangedBucket seq="3" label="20-25k" low="20000" high="25000" style="c.rb13_4"/>
   <RangedBucket seq="4" label="25-35k" low="25000" high="35000" style="c.rb13_5"/>
   <RangedBucket seq="5" label="35-50k" low="35000" high="50000" style="c.rb13_6"/>
   <RangedBucket seq="6" label="50-75k" low="50000" high="75000" style="c.rb13_7"/>
   <RangedBucket seq="7" label="75-100k" low="75000" high="100000" style="c.rb13_8"/>
   <RangedBucket seq="8" label="100-125k" low="100000" high="125000" style="c.rb13_9"/>
   <RangedBucket seq="9" label="125-150k" low="125000" high="150000" style="c.rb13_10"/>
   <RangedBucket seq="10" label="150-250k" low="150000" high="250000" style="c.rb13_11"/>
   <RangedBucket seq="11" label="250-350k" low="250000" high="350000" style="c.rb13_12"/>
   <RangedBucket seq="12" label="350k and up"   low="350000" style="c.rb13_13"/>
  </Buckets>
 </BucketStyle>
</AdvancedStyle>

<?xml version="1.0" ?> 
<AdvancedStyle> 
<BucketStyle> 
 <Buckets> 
  <CollectionBucket seq="0" label="Shell" style="m.shell gasstation"> 
   Shell 
  </CollectionBucket> 
  <CollectionBucket seq="1" label="Esso" style="m.esso gasstation"> 
   Esso 
  </CollectionBucket> 
  <CollectionBucket seq="2" label="Texaco"  style="m.texaco gasstation"> 
   Texaco 
 </CollectionBucket> 
  <CollectionBucket seq="3" label="BP"  style="m.bp gasstation"> 
   BP 
  </CollectionBucket> 
  <CollectionBucket seq="4" label="Other"  style="m.generic gasstation"> 
   Avia,Benzinex,Q8,Total,Witte Pomp 
  </CollectionBucket> 
  <CollectionBucket seq="5" label="DEFAULT" style="m.default gasstation">
   #DEFAULT#
  </CollectionBucket>
  </Buckets>
</BucketStyle> 
</AdvancedStyle> 

<?xml version="1.0" standalone="yes"?> 
<styling_rules> 
  <rule column="merk"> 
    <features style="v.gasstations"> 
    </features> 
    <label column="merk" style="t.SansSerif red 10"> 
      1 
    </label> 
  </rule> 
</styling_rules> 

• Thematic Mapping Using External Attribute Data
  

Some attributes of the <theme> element affect only the appearance of the map display, rather than determining the data to be associated with the theme. These appearance-related attributes control whether and how the theme is processed and rendered when a map is generated. Examples include the following attributes:

• min_scale and max_scale determine whether or not a theme is displayed at various map scales (levels of resolution). For example, if you are displaying a map of streets, there are certain map scales at which the streets would become too dense for a usable display, such as when viewing an entire state or province. In this case, you should create a theme for streets, and specify minimum and maximum scale values to ensure that individual streets affected by the theme are displayed when the scale is appropriate and otherwise are not displayed.

• labels_always_on determines whether or not labels for the theme will be displayed if they would overlap another label. By choosing appropriate labels_always_on values and choosing an appropriate order of themes to be processed within a map request, you can control how cluttered the labels might become and which labels have priority in getting displayed.

• fast_unpickle determines the unpickling (unstreaming) method to be used, which can involve a trade-off between performance and precision in the display.

• fixed_svglabel, visible_in_svg, selectable_in_svg, onclick, onmousemove, onmouseover, and onmouseout affect the appearance of SVG maps.

To specify any appearance-related attributes, use the <theme> element (described in [31.2.20]) with the XML API.

Map size is the height of the map in units of the map data space. For example, if the map data is in WGS 84 geographic coordinates, the map center is (-120.5, 36.5), and the size is 2, then the height of the map is 2 decimal degrees, the lower Y (latitude) value is 35.5 degrees, and the upper Y value is 37.5 decimal degrees.

Map scale is expressed as units in the user's data space that are represented by 1 inch on the screen or device. Map scale for the map visualization component is actually the denominator value in a popular method of representing map scale as 1/n, where:

• 1, the numerator, is 1 unit (1 inch for the map visualization component) on the displayed map.

• n, the denominator, is the number of units of measurement (for example, decimal degrees, meters, or miles) represented by 1 unit (1 inch for the map visualization component) on the displayed map.

For example:

• If 1 inch on a computer display represents 0.5 decimal degree of user data, the fraction is 1/0.5. The decimal value of the fraction is 2.0, but the scale value for the map visualization component is 0.5.

• If 1 inch on a computer display represents 2 miles of user data, the fraction is 1/2. The decimal value of the fraction is 0.5, but the scale value for the map visualization component is 2.

• If 1 inch on a computer display represents 10 miles of user data, the fraction is 1/10. The decimal value of the fraction is 0.1, but the scale value for the map visualization component is 10.

The min_scale and max_scale attributes in a <theme> element describe the visible scale range of a theme. These attributes control whether or not a theme is displayed, depending on the current map scale. The default scale value for min_scale is positive infinity, and the default value for max_scale is negative infinity (or in other words, by default display the theme for all map scales, if possible given the display characteristics).

• min_scale is the value to which the display must be zoomed in for the theme to be displayed. For example, if parks have a min_scale value of 5 and if the current map scale value is 5 or less but greater than the max_scale value, parks will be included in the display; however, if the display is zoomed out so that the map scale value is greater than 5, parks will not be included in the display.

• max_scale is the value beyond which the display must be zoomed in for the theme not to be displayed. For example, if counties have a max_scale value of 3 and if the current map scale value is 3 or less, counties will not be included in the display; however, if the display is zoomed out so that the map scale value is greater than 3, counties will be included in the display.

A high min_scale value is associated with less map detail and a smaller scale in cartographic terms, while a high max_scale value is associated with greater map detail and a larger scale in cartographic terms. (Note that the map visualization component meaning of map scale is different from the popular meaning of cartographic map scale.) The min_scale value for a theme should be larger than the max_scale value. Example 2-49 in Maps includes min_scale and max_scale values.

You also assign scale values for theme labels, to enable the showing or hiding of labels with values different from the base theme scales, by using the theme label scale parameters label_min_scale and label_max_scale. These parameters are similar to the min_scale and max_scale parameters, but the labels are shown if the map scale is in the visible range defined by label_min_scale and label_max_scale. (The label scale values are ignored if the theme is not in the visible scale range defined by min_scale and max_scale.) The following is a theme definition with label scale values; the labels will be shown when the map scale is between 5 and 2, but the theme features will be shown when the map scale is between 10 and 0:

<theme name="theme_us_states" min_scale="10" max_scale="0" 
     label_min_scale="5" label_max_scale="2"/>

To determine the current map scale for a map returned by the map visualization component, first find the map size, namely the height (vertical span) of the map in terms of the coordinate system associated with the map data. For example, assume that a map with a height of 10 (miles, meters, decimal degrees, or whatever unit of measurement is associated with the data) is requested, and that the map is drawn on a device with a size of 500 by 350 pixels, where 350 is the height. The map visualization component assumes a typical screen resolution of 96 dpi. Because 96 pixels equals 1 inch, the height of the returned map is 3.646 inches (350/96 = 3.646). In this example, the size of the map is 10, and therefore the map scale is approximately 2.743 (10/3.646 = 2.743).

Alternatively, you can request a map using a map scale value without specifying a unit, such as 50000 for a scale of 1:50000, by specifying the scale_mode theme attribute value as ratio. (If the scale_mode theme attribute value is screen_inch, the scale refers to a unit.) To use a scale defined without a unit, request the map specifying the center and ratio scale.

To find the equivalent map visualization component screen inch scale for a ratio scale, follow these steps:

1. Find the numerical fraction of a meter associated with one screen pixel. For example, if the screen resolution is 96 dpi (dots per inch), the number of meters on the screen for each screen pixel is 0.000265 (that is, 0.0254/96).

2. Find the map scale for one screen pixel (the mapdotScale value), as follows:

   • For projected data (meters), multiply the result of step 1 by the ratio scale. For example, if the ratio scale is 50000 (50 thousand) and the screen resolution is 96 dpi, the result is 13.25 meters for each pixel (50000 * 0.000265).

   • For geodetic data (degrees), multiply the result of step 1 by the number of meters (on the surface of the Earth) for each degree. (This number will depend on the coordinate system associated with the data.) For example, if one degree = 111195 meters and if the screen resolution is 96 dpi, the result is 29.466675 meters for each pixel (111195 * 0.000265).

   • For data using any other unit, use the approach for projected data using meters.

3. Because the map visualization component scale is per screen inch instead of per screen pixel, multiply the result of step 2 by the dpi value. For example, if the result of step 2 is 13.25 meters at 96 dpi, the number of meters for each screen inch is 1272 (13.25 * 96).

A map legend is an inset illustration drawn on top of the map and describing what various colors, symbols, lines, patterns, and so on represent. You have flexibility in specifying the content and appearance of the legend. You can:

• Customize the background, border style, and font

• Have one or more columns in the legend

• Add space to separate legend entries

• Indent legend entries

• Use any map visualization component style, including advanced styles

Example 2-50 is an excerpt from a request that includes a legend.

Figure 2-14 Map with Legend

Description of "Figure 2-14 Map with Legend"

Notes on Example 2-50 and Figure 2-14:

• This example shows a legend with a single column, although you can create multiple columns in a legend.

• Each entry in the column definition can identify label text and whether the text is the legend title (is_title="true"), a style name and associated text, or a separator (is_separator="true") for vertical blank space to be added (after the cities entry in this example).

As an alternative to specifying the legend content in one or more <column> elements, you can request an automatic legend based on the map request. With an automatic legend, you specify the legend header, and the map visualization component generates the legend based on the themes that have any interaction with the map area. Themes from the map request and from the base map are considered. (Some legend items might not be visible, though, such as if a theme interacts with the query window but no features of the theme are visible on the map.)

Example 2-51 is a map request that requests an automatic legend (because the <legend> element does not include any <column> elements).

Example 2-52 requests an automatic legend in which the <legend> elements specifies the themes to be used to generate the legend items. In this example, even if the map result shows more themes, the legend items are based on the THEME_COUNTIES_3397829 and THEME_US_AIRPORT themes specified in the <legend> element.

You cannot combine an automatic legend with the use of <column> elements. If the <legend> element contains any <column> elements, a column/entry legend is created.

The map visualization component uses the following considerations when it builds automatic legend items:

• Each legend column has a maximum of five entries (an advanced style is considered one entry).

• The legend text for simple rendering styles comes from the theme description if defined, otherwise from the theme name.

• If a rendering style is used in more than one theme, the style is repeated in the legend but with text related to the theme to which it applies.

• Labeling styles are not repeated in the legend. The style text for labeling styles comes from the style description.

• Advanced styles are not repeated in the legend.

If you also specify a map title, note, or logo (or any combination), be sure that the legend and the other features have different positions. (Map titles, notes, and logos are explained in Specifying Global Map Configuration Options.) The default position for a legend is SOUTH_WEST.

<?xml version="1.0" standalone="yes"?>
<map_request
             basemap="density_map"
             datasource = "mvdemo"
             width="640"
             height="480"
             bgcolor="#a6cae0"
             antialiase="false"
             format="PNG_STREAM">
  <center size="4.2">
     <geoFeature render_style="m.image134_bw">
         <geometricProperty typeName="center">
             <Point srsName="SDO:8307">
                 <coordinates>-121.2615, 37.5266</coordinates>
             </Point>
         </geometricProperty>
     </geoFeature>
  </center>
 
  <legend bgstyle="fill:#ffffff;fill-opacity:100;stroke:#a3a3a3" profile="MEDIUM" position="SOUTH_WEST">
          <column>
            <entry text="Legend" is_title="true" />
            <entry style="M.IMAGE134_BW" text="Center" />
            <entry style="M.ALL_CITY_L2" text="Cities" />
            <entry is_separator="true" />
            <entry style="L.S04_ROAD_INTERSTATE" text="Interstates" />
            <entry text="County population:" />
            <entry style="V.COUNTY_POP_DENSITY_8" tab="1" />
          </column>
  </legend>
 
  <!--
  <themes>
 
  </themes>
  -->
 
</map_request>

<?xml version="1.0" standalone="yes"?>
<map_request
             title="Automatic legend"
             datasource = "mvdemo"
             width="640"
             height="480"
             bgcolor="#a6cae0"
             antialiase="false"
             format="PNG_STREAM">
  <center size="4.5">
     <geoFeature >
         <geometricProperty typeName="center">
             <Point>
                 <coordinates>-122.2615, 37.5266</coordinates>
             </Point>
         </geometricProperty>
     </geoFeature>
  </center>
 
  <themes>
    <theme name="THEME_COUNTIES_3397829" />
    <theme name="THEME_US_ROAD1" />
    <theme name="THEME_US_AIRPORT" />
  </themes>
 
 <legend bgstyle="fill:#ffffff;fill-opacity:128;stroke:#ff0000;stroke-opacity:128" profile="medium" font="Courier">
  </legend>
 
</map_request>

<map_request
             title="Legend with themes defined"
             datasource = "mvdemo"
             width="640"
             height="480"
             bgcolor="#a6cae0"
             antialiase="false"
             format="PNG_STREAM">
  <center size="4.5">
     <geoFeature >
         <geometricProperty typeName="center">
             <Point>
                 <coordinates>-122.2615, 37.5266</coordinates>
             </Point>
         </geometricProperty>
     </geoFeature>
  </center>
 
  <themes>
    <theme name="THEME_COUNTIES_3397829" />
    <theme name="THEME_US_ROAD1" />
    <theme name="THEME_US_AIRPORT" />
  </themes>
 
 <legend bgstyle="fill:#ffffff;fill-opacity:128;stroke:#ff0000;stroke-opacity:128" profile="medium" font="Courier">
  <themes>
    <theme name="THEME_COUNTIES_3397829" />
    <theme name="THEME_US_AIRPORT" />
  </themes>
 </legend>
 
</map_request>

A catalog data source gets all of its data from local files. The local directory where the data files are stored is relative to where the mapViewerConfig.xml file is stored. From another perspective, a catalog data source does not need the Oracle database, because all necessary data (the spatial geometry data and its attributes, as well as the metadata for how to rend the spatial data, such as styles and themes) is stored in local files.

The following are the general steps for creating and using a catalog data source:

1. Export the Necessary Metadata from an Oracle Database

2. Export the Necessary Spatial Tables

3. Edit the Map Visualization Component Configuration File to Add the Catalog Data Source

4. Restart the Map Visualization Component Server

• Export the Necessary Metadata from an Oracle Database
  
• Export the Necessary Spatial Tables
  
• Edit the Map Visualization Component Configuration File to Add the Catalog Data Source
  
• Restart the Map Visualization Component Server
  

The USER_SDO_STYLES and ALL_SDO_STYLES views have the columns listed in Table 2-3.

Depending on the Oracle Database release, the ALL_SDO_STYLES view may contain sample styles owned by the MDSYS schema. If these styles are defined on your system, you can specify them in theme definitions and map requests, and you can examine the XML definitions for ideas to use in defining your own styles.

To specify a style (or other type of map visualization component object) that is owned by a schema other than the one for the current user, you must specify the schema name, and you must use a colon (:), not a period, between the schema name and the object name. The following excerpt from a <jdbc_query> element refers to the style named C.RED owned by the MDSYS schema:

<jdbc_query . . . render_style="MDSYS:C.RED">
. . .
 </jdbc_query>

Example 2-58 finds the names of all currently defined styles owned by the MDSYS schema, and it displays the type, description, and XML definition of one of the styles. (The example output is reformatted for readability.)

SELECT owner, name FROM all_sdo_styles 
  WHERE owner = 'MDSYS';
 
OWNER                            NAME
-------------------------------- --------------------------------
MDSYS                            C.BLACK
MDSYS                            C.BLACK GRAY
MDSYS                            C.BLUE
MDSYS                            C.COUNTIES
MDSYS                            C.FACILITY
. . .
MDSYS                            L.MAJOR STREET
MDSYS                            L.MAJOR TOLL ROAD
MDSYS                            L.MQ_ROAD2
MDSYS                            L.PH
MDSYS                            L.POOR_ROADS
MDSYS                            L.PTH
MDSYS                            L.RAILROAD
MDSYS                            L.RAMP
MDSYS                            L.SH
MDSYS                            L.STATE BOUNDARY
. . .
MDSYS                            M.REDSQ
MDSYS                            M.SMALL TRIANGLE
MDSYS                            M.STAR
MDSYS                            M.TOWN HALL
MDSYS                            M.TRIANGLE
MDSYS                            T.AIRPORT NAME
MDSYS                            T.CITY NAME
MDSYS                            T.MAP TITLE
MDSYS                            T.PARK NAME
MDSYS                            T.RED STREET
MDSYS                            T.ROAD NAME
MDSYS                            T.SHIELD1
MDSYS                            T.SHIELD2
MDSYS                            T.STATE NAME
MDSYS                            T.STREET NAME
. . .
 
-- Display the type, description, and XML definition of one style.
SET LONG 4000;
SELECT owner, name, type, description, definition 
  FROM all_sdo_styles WHERE name = 'L.PH';
 
OWNER   NAME     TYPE       DESCRIPTION
------  -----    ------     ------------------
MDSYS   L.PH     LINE       Primary highways
 
DEFINITION
---------------------------------------------------------------------------
<?xml version="1.0" standalone="yes"?>
<svg width="1in" height="1in">
<desc></desc>
<g class="line" style="fill:#33a9ff;stroke-width:4">
<line class="parallel" style="fill:#aa55cc;stroke-width:1.0"/>
</g>
</svg>

The USER_SDO_THEMES and ALL_SDO_THEMES views have the columns listed in Table 2-4.

The USER_SDO_MAPS and ALL_SDO_MAPS views have the columns listed in Table 2-5.

The USER_SDO_MAPS and ALL_SDO_MAPS views have the columns listed in Table 2-6.

For detailed information about using the USER_SDO_CACHED_MAPS view, see Map Tile Server Configuration.

Oracle Maps consists of the following main components:

• A map tile server that caches and serves pregenerated map image tiles upon a map image tile request

• A map server that generates maps form spatial data to the mapping client upon a client map image request

• A map data server that fetches spatial data from a spatial data provider to the mapping client

• An Ajax-based JavaScript mapping client. (Ajax is an acronym for asynchronous JavaScript and XML.) This client provides functions for browsing and interacting with maps, as well as a flexible application programming interface (API).

The map tile server (map image caching engine, described in Map Tile Server) automatically fetches and caches map image tiles rendered by the Oracle Spatial and Graph map visualization component or other web-enabled map providers. It also serves cached map image tiles to the clients, which are web applications developed using the Oracle Maps client API. The clients can then automatically stitch multiple map image tiles into a seamless large map. Because the map image tiles are normally pregenerated and cached, the application users will experience fast map viewing performance.

The JavaScript mapping client is a browser side map display engine that fetches map content from the servers, and presents it to client applications. It:

• Fetches map images tiles from a map visualization component server, from a third party map service provider, or from its local disk-storage

• Retrieves spatial data from a map visualization component server, from a third party spatial data provider, or from its local disk-storage and then renders the spatial data into map images by itself on the client side

• Provides customizable map-related user interaction controls, such as map dragging and clicking, for the application

• Provides other built-in features and utilities to customize the map contents and map layout design

The JavaScript mapping client can be easily integrated with any web application or portal.

Figure 2-15 shows the architecture of web mapping applications that are developed using Oracle Maps.

Figure 2-15 Architecture for Oracle Maps Applications

Description of "Figure 2-15 Architecture for Oracle Maps Applications"

Referring to Figure 2-15, applications interact with the Oracle Maps architecture as follows:

• The application is developed using JavaScript, and it runs inside the JavaScript engine of the web browser.

• The application invokes the JavaScript map client to fetch the map image tiles from the map tile server, and then it displays the map in the web browser.

• The application invokes the JavaScript map client to fetch the map image in other form of map services (such as WMS and WMTS) from the server and then displays the map image.

• The application invokes the JavaScript map client to fetch spatial data from the map data server and then renders the map image to display.

• The JavaScript map client controls map-related user interaction for the application.

• When the map visualization component server receives a map image request, the request can be one of its several supported types: a map image tile request to its map tile server, a map image request to its map server, a WMS map request to its WMS server, or a WMTS map image tile request to its WMTS server. Each request will be handled by the server accordingly.

  Example 1: When the map tile server receives a map image tile request, it first checks to see if the requested tile is already cached. If the tile is already in the cache, the cached tile is then returned to the client. If the tile is not in the cache, then the map tile server fetches the tile into the cache and returns it to the client. Tiles can be fetched either directly from the map visualization component map rendering engine or from an external web map service provider.

  Example 2: When the server receives a map image request (instead of a map tile request) to its map server, the map server renders the image and returns it to the client. Note that in contrast to the map tile server, the map server generates a map according to a specified data bounds and renders the data onto an image with specified dimension, but it does not cache the map image.

• When the map data server receives a map data request, it retrieves the spatial data and returns the spatial data, not map images, to the client.