Skip Headers
Oracle® Fusion Middleware User's Guide for Oracle MapViewer
11g Release 1 (11.1.1)

Part Number E10145-07
Go to Documentation Home
Home
Go to Book List
Book List
Go to Table of Contents
Contents
Go to Index
Index
Go to Master Index
Master Index
Go to Feedback page
Contact Us

Go to previous page
Previous
Go to next page
Next
PDF · Mobi · ePub

7 MapViewer XML Requests: Administrative and Other

The main use of MapViewer is for processing various map requests. However, MapViewer also accepts through its XML API various administrative (non-map) requests, such as to add a data source, as well as other (general-purpose) requests useful in developing applications, such as to list available themes and base maps. All MapViewer administrative requests require that you log in to the MapViewer administration (Admin) page, for which there is a link on the main MapViewer page; the general-purpose requests can be made from an application without the requirement to log in. This section describes the format for each request and its response.

All XML requests are embedded in a <non_map_request> element and all responses are embedded in a <non_map_response> element, unless an exception is thrown by MapViewer, in which case the response is an <oms_error> element (described in Section 3.5).

The administrative requests are described in sections according to the kinds of tasks they perform:

The section titles often indicate whether a request is administrative or general-purpose.

7.1 Managing Data Sources

You can add, remove, redefine, and list data sources. (For information about data sources and how to define them, see Section 1.5.2.14.)

7.1.1 Adding a Data Source (Administrative)

Note:

This request is typically used during development or testing, when you want to add a data source quickly and dynamically without creating a permanent one (which would involve editing the mapViewerConfig.xml file). For production use, or to take full advantage of what MapViewer provides with a data source, you should always use a permanent data source.

The <add_data_source> element has the following definition:

<!ELEMENT non_map_request  add_data_source>
<!ELEMENT add_data_source  EMPTY>
  <!ATTLIST add_data_source
   name              CDATA #REQUIRED
   container_ds      CDATA #IMPLIED
   jdbc_tns_name     CDATA #IMPLIED
   jdbc_host         CDATA #IMPLIED
   jdbc_port         CDATA #IMPLIED
   jdbc_sid          CDATA #IMPLIED
   jdbc_user         CDATA #IMPLIED
   jdbc_password     CDATA #IMPLIED
   jdbc_mode         (oci8 | thin) #IMPLIED
   number_of_mappers INTEGER #REQUIRED
               >

The name attribute identifies the data source name. The name must be unique among MapViewer data sources. (Data source names are not case-sensitive.)

You must specify a container data source name, a net service name (TNS name), or all necessary connection information. That is, you must specify only one of the following:

  • container_ds

  • jdbc_tns_name

  • jdbc_host, jdbc_port, jdbc_sid, jdbc_mode, jdbc_user, and jdbc_password

The container_ds attribute identifies a data source name that is defined in the J2EE container's Java Naming and Directory Interface (JNDI) namespace. For OC4J, it should be the ejb-location attribute of the data source defined in the data-source.xml file.

The jdbc_tns_name attribute identifies a net service name that is defined in the tnsnames.ora file.

The jdbc_host attribute identifies the database host system name.

The jdbc_port attribute identifies the TNS listener port number.

The jdbc_sid attribute identifies the SID for the database.

The jdbc_user attribute identifies the user to connect to (map).

The jdbc_password attribute identifies the password for the user specified with the jdbc_user attribute. Note that MapViewer does not change this password string in any way; no conversion to upper or lower case is performed. If the database uses case-sensitive passwords, the specified password must exactly match the password in the database.

The jdbc_mode attribute identifies the JDBC connection mode: thin or oci8. If you specify oci8, you must have Oracle Client installed in the middle tier in which MapViewer is running. You do not need Oracle Client if thin is used for all of your data sources.

The number_of_mappers attribute identifies the number of map renderers to be created (that is, the number of requests that MapViewer can process at the same time) for this data source. Any unprocessed map requests are queued and eventually processed. For example, if the value is 3, MapViewer will be able to process at most three mapping requests concurrently. If a fourth map request comes while three requests are being processed, it will wait until MapViewer has finished processing one of the current requests. The maximum number of mappers for a single data source is 64.

Example 7-1 adds a data source named mvdemo by specifying all necessary connection information.

Example 7-1 Adding a Data Source by Specifying Detailed Connection Information

<?xml version="1.0" standalone="yes"?>
<non_map_request>
  <add_data_source 
        name="mvdemo" 
        jdbc_host="elocation.us.oracle.com"
        jdbc_port="1521"
        jdbc_sid="orcl"
        jdbc_user="scott"
        jdbc_password="password"
        jdbc_mode="thin"
        number_of_mappers="5"/>
</non_map_request>

Example 7-2 adds a data source named mvdemo by specifying the container data source name.

Example 7-2 Adding a Data Source by Specifying the Container Data Source

<?xml version="1.0" standalone="yes"?>
<non_map_request>
  <add_data_source 
        name="mvdemo" 
        container_ds="jdbc/OracleDS"
        number_of_mappers="5"/>
</non_map_request>

The DTD for the response to an add_data_source request has the following format:

<!ELEMENT non_map_response add_data_source>
<!ELEMENT add_data_source  EMPTY>
<!ATTLIST add_data_source
   succeed   (true | false) #REQUIRED
   comment   CDATA #IMPLIED
>

The comment attribute appears only if the request did not succeed, in which case the reason is in the comment attribute. In the following example, succeed="true" indicates that the user request has reached the server and been processed without any exception being raised regarding its validity. It does not indicate whether the user's intended action in the request was actually fulfilled by the MapViewer server. In this example, the appearance of the comment attribute indicates that the request failed, and the string associated with the comment attribute gives the reason for the failure ("data source already exists").

<?xml version="1.0" ?> 
 <non_map_response> 
     <add_data_source succeed="true" comment="data source already exists"/> 
</non_map_response>

7.1.2 Removing a Data Source (Administrative)

The <remove_data_source> element can be used to remove a permanent data source or a dynamically added data source. This element has the following definition:

<!ELEMENT non_map_request remove_data_source>
<!ELEMENT remove_data_source  EMPTY>
<!ATTLIST remove_data_source
   data_source    CDATA #REQUIRED
   jdbc_password  CDATA #REQUIRED
>

The data_source attribute identifies the name of the data source to be removed.

The jdbc_password attribute identifies the login password for the database user in the data source. jdbc_password is required for security reasons (to prevent people from accidentally removing data sources from MapViewer).

Removing a data source only affects the ability of MapViewer to use the corresponding database schema; nothing in that schema is actually removed.

Example 7-3 removes a data source named mvdemo.

Example 7-3 Removing a Data Source

<?xml version="1.0" standalone="yes"?>
<non_map_request>
  <remove_data_source data_source="mvdemo" jdbc_password="password"/>
</non_map_request>

The DTD for the response to a remove_data_source request has the following format:

<!ELEMENT non_map_response remove_data_source>
<!ELEMENT remove_data_source  EMPTY>
<!ATTLIST remove_data_source
   succeed  (true | false) #REQUIRED
>

For example:

<?xml version="1.0" ?> 
 <non_map_response> 
    <remove_data_source succeed="true"/> 
</non_map_response>

7.1.3 Redefining a Data Source

Note:

You should use request only during development or testing, and not for production work.

For convenience, MapViewer lets you redefine a data source. Specifically, if a data source with the same name already exists, it is removed and then added using the new definition. If no data source with the name exists, a new data source is added. If an existing data source has the same name, host, port, SID, user name, password, mode, and number of mappers as specified in the request, the request is ignored.

The <redefine_data_source> element has the following definition:

<!ELEMENT non_map_request redefine_data_source>
<!ELEMENT redefine_data_source  EMPTY>
<!ATTLIST redefine_data_source
   name              CDATA #REQUIRED
   container_ds      CDATA #IMPLIED
   jdbc_tns_name     CDATA #IMPLIED
   jdbc_host         CDATA #IMPLIED
   jdbc_port         CDATA #IMPLIED
   jdbc_sid          CDATA #IMPLIED
   jdbc_user         CDATA #IMPLIED
   jdbc_password     CDATA #IMPLIED
   jdbc_mode         (oci8 | thin) #IMPLIED
   number_of_mappers INTEGER #REQUIRED
>

The attributes and their explanations are the same as for the <add_data_source> element, which is described in Section 7.1.1.

The DTD for the response to a redefine_data_source request has the following format:

<!ELEMENT non_map_response redefine_data_source>
<!ELEMENT redefine_data_source  EMPTY>
<!ATTLIST redefine_data_source
   succeed  (true | false) #REQUIRED
>

For example:

<?xml version="1.0" ?> 
 <non_map_response> 
   <redefine_data_source succeed="true"/> 
</non_map_response>

7.1.4 Listing All Data Sources (Administrative or General-Purpose)

The <list_data_sources> element lists all data sources known to the currently running MapViewer. It has the following definition:

<!ELEMENT non_map_request list_data_sources>
<!ELEMENT list_data_sources  EMPTY>

For example:

<?xml version="1.0" standalone="yes"?>
<non_map_request>
  <list_data_sources/>
</non_map_request>

The DTD for the response to a list_data_sources request has the following format:

<!ELEMENT non_map_response map_data_source_list>
<!ELEMENT map_data_source_list  (map_data_source*) >
<!ATTLIST map_data_source_list
   succeed      (true|false) #REQUIRED
>
<!ELEMENT map_data_source  EMPTY>
<!ATTLIST map_data_source
   name         CDATA #REQUIRED
   container_ds CDATA #IMPLIED
   host         CDATA #IMPLIED
   sid          CDATA #IMPLIED
   port         CDATA #IMPLIED
   user         CDATA #IMPLIED
   mode         CDATA #IMPLIED
   numMappers   CDATA #REQUIRED
   >

For each data source:

  • If the user issuing the request is logged in as a MapViewer administrator, all data source information except the password for the database user is returned.

  • If the user issuing the request is not logged in as a MapViewer administrator, only the data source name is returned.

The following example is a response that includes information about two data sources when the request is issued by a MapViewer administrator.

<?xml version="1.0" ?> 
<non_map_response> 
<map_data_source_list succeed="true"> 
   <map_data_source name="mvdemo" host="elocation.us.oracle.com"
       sid="orcl" port="1521" user="scott" mode="thin" numMappers="3"/> 
   <map_data_source name="geomedia" host="geomedia.us.oracle.com"
       sid="orcl" port="8160" user="scott" mode="oci8" numMappers="7"/> 
</map_data_source_list> 
</non_map_response>

The following example is a response when the same request is issued by a user that is not a MapViewer administrator.

<?xml version="1.0" ?> 
<non_map_response> 
<map_data_source_list succeed="true"> 
   <map_data_source name="mvdemo"/>
   <map_data_source name="geomedia"/>
</map_data_source_list> 
</non_map_response>

7.1.5 Checking the Existence of a Data Source (General-Purpose)

The <data_source_exists> element lets you find out if a specified data source exists. It has the following definition:

<!ELEMENT non_map_request data_source_exists>
<!ELEMENT data_source_exists  EMPTY>
<!ATTLIST data_source_exists
   data_source   CDATA #REQUIRED
>

For example:

<?xml version="1.0" standalone="yes"?>
<non_map_request>
  <data_source_exists data_source="mvdemo"/>
</non_map_request>

The DTD for the response to a data_source_exists request has the following format:

<!ELEMENT non_map_response data_source_exists>
<!ELEMENT data_source_exists  EMPTY>
<!ATTLIST data_source_exists
   succeed   (true | false) #REQUIRED
   exists    (true | false) #REQUIRED
>

The succeed attribute indicates whether or not the request was processed successfully.

The exists attribute indicates whether or not the data source exists.

For example:

<?xml version="1.0" ?> 
<non_map_response>
   <data_source_exists succeed="true" exists="true"/> 
</non_map_response>

7.2 Listing All Maps (General-Purpose)

The <list_maps> element lists all base maps in a specified data source. It has the following definition:

<!ELEMENT non_map_request list_maps>
<!ELEMENT list_maps  EMPTY>
<!ATTLIST list_maps
   data_source   CDATA #REQUIRED
>

The following example lists all base maps in the data source named mvdemo.

<?xml version="1.0" standalone="yes"?>
<non_map_request>
  <list_maps data_source="mvdemo"/>
</non_map_request>

The DTD for the response to a list_maps request has the following format:

<!ELEMENT non_map_response map_list>
<!ELEMENT map_list  (map*) >
<!ATTLIST map_list
   succeed   (true | false) #REQUIRED
>
<!ATTLIST map
   name      CDATA #REQUIRED
>

The succeed attribute indicates whether or not the request was processed successfully.

The name attribute identifies each map.

For example:

<?xml version="1.0" ?> 
<non_map_response>
<map_list succeed="true">
  <map name="DEMO_MAP"/> 
  <map name="DENSITY_MAP"/> 
</map_list>
</non_map_response>

7.3 Listing Themes (General-Purpose)

The <list_predefined_themes> element lists either all themes defined in a specified data source or all themes defined in a specified data source for a specified map.

The DTD for requesting all themes defined in a data source regardless of the map associated with a theme has the following definition:

<!ELEMENT non_map_request list_predefined_themes>
<!ELEMENT list_predefined_themes  EMPTY>
<!ATTLIST list_predefined_themes
   data_source   CDATA #REQUIRED
>

The following example lists all themes defined in the data source named mvdemo.

<?xml version="1.0" standalone="yes"?>
<non_map_request>
  <list_predefined_themes data_source="mvdemo"/>
</non_map_request>

The DTD for requesting all themes defined in a data source and associated with a specific map has the following definition:

<!ELEMENT non_map_request list_predefined_themes>
<!ELEMENT list_predefined_themes  EMPTY>
<!ATTLIST list_predefined_themes
   data_source CDATA #REQUIRED
   map         CDATA #REQUIRED
>

The following example lists all themes defined in the data source named tilsmenv and associated with the map named QA_MAP.

<?xml version="1.0" standalone="yes"?>
<non_map_request>
  <list_predefined_themes data_source="tilsmenv" map="QA_MAP"/>
</non_map_request>

The DTD for the response to a list_predefined_themes request has the following format:

<!ELEMENT non_map_response predefined_theme_list>
<!ELEMENT predefined_theme_list  (predefined_theme*) >
<!ATTLIST predefined_theme_list
   succeed   (true | false) #REQUIRED
>
<!ELEMENT predefined_theme  EMPTY>
<!ATTLIST predefined_theme
   name   CDATA #REQUIRED
>

The succeed attribute indicates whether or not the request was processed successfully.

The name attribute identifies each theme.

For example:

<?xml version="1.0" ?> 
<non_map_response>
<predefined_theme_list succeed="true">
  <predefined_theme name="THEME_DEMO_CITIES"/> 
  <predefined_theme name="THEME_DEMO_BIGCITIES"/> 
  <predefined_theme name="THEME_DEMO_COUNTIES"/> 
  <predefined_theme name="THEME_DEMO_COUNTY_POPDENSITY"/> 
  <predefined_theme name="THEME_DEMO_HIGHWAYS"/> 
  <predefined_theme name="THEME_DEMO_STATES"/> 
  <predefined_theme name="THEME_DEMO_STATES_LINE"/> 
</predefined_theme_list>
</non_map_response>

Note that the order of names in the returned list is unpredictable.

7.4 Listing Styles (General-Purpose)

The <list_styles> element lists styles defined for a specified data source. It has the following definition:

<!ELEMENT non_map_request list_styles>
<!ELEMENT list_styles  EMPTY>
<!ATTLIST list_styles
   data_source   CDATA #REQUIRED
   style_type   (COLOR|LINE|MARKER|AREA|TEXT|ADVANCED)  #IMPLIED
>

If you specify a value for style_type, only styles of that type are listed. The possible types of styles are COLOR, LINE, MARKER, AREA, TEXT, and ADVANCED. If you do not specify style_type, all styles of all types are listed.

The following example lists only styles of type COLOR:

<?xml version="1.0" standalone="yes"?>
<non_map_request>
  <list_styles data_source="mvdemo"  style_type="COLOR"/>
</non_map_request>

The DTD for the response to a list_styles request has the following format:

<!ELEMENT non_map_response style_list>
<!ELEMENT style_list  (style*) >
<!ATTLIST style_list
   succeed   (true | false) #REQUIRED
>
<!ELEMENT style  EMPTY>
<!ATTLIST style
   name   CDATA #REQUIRED
>

The following example shows the response to a request for styles of type COLOR:

<?xml version="1.0" ?> 
 <non_map_response> 
 <style_list succeed="true"> 
   <style name="SCOTT:C.BLACK"/> 
   <style name="SCOTT:C.BLACK GRAY"/> 
   <style name="SCOTT:C.BLUE"/> 
   <style name="SCOTT:C.CRM_ADMIN_AREAS"/> 
   <style name="SCOTT:C.CRM_AIRPORTS"/> 
</style_list> 
</non_map_response>

Each style name in the response has the form OWNER:NAME (for example, SCOTT:C.BLACK), where OWNER is the schema user that owns the style.

7.5 Listing Styles Used by a Predefined Theme (General-Purpose)

The <list_theme_styles> element lists all the rendering styles that are referenced in a predefined theme. This is particularly useful if you want to build a legend for a theme yourself, where you need to know which styles are actually being used in that theme. This element has the following definition:

<!ELEMENT non_map_request list_theme_styles>
<!ELEMENT list_theme_styles  EMPTY>
<!ATTLIST list_styles
   data_source   CDATA #REQUIRED
   theme CDATA #REQUIRED
>

The following example requests the styles used by the THEME_DEMO_STATES predefined theme:

<non_map_request>
   <list_theme_styles data_source="mvdemo" theme="THEME_DEMO_STATES"  />
</non_map_request>

The following example shows the response to the preceding request:

<non_map_response>
  <theme_style name="C.US MAP YELLOW" type="COLOR" render="true" label="false" 
    highlight="false" description="Primary color for US maps."/>
  <theme_style name="T.STATE NAME" type="TEXT" render="false" label="true" 
    highlight="false" description="name for states"/>
</non_map_response>

The DTD for the response to a list_theme_styles request has the following format:

<!ELEMENT non_map_response (theme_style*)>
<!ELEMENT theme_style EMPTY>
<!ATTLIST theme_style
    name CDATA #REQUIRED
    type   CDATA (COLOR|LINE|MARKER|AREA|TEXT|ADVANCED)  #REQUIRED
    render CDATA (true|false)  #REQUIRED
    label CDATA (true|false)  #REQUIRED
    highlight CDATA (true|false) #REQUIRED
    description CDATA #IMPLIED
>

In the preceding DTD:

7.6 Managing In-Memory Caches

MapViewer uses two types of in-memory cache:

The use of these caches improves performance by preventing MapViewer from accessing the database for the cached information; however, the MapViewer displays might reflect outdated information if that information has changed in the database since it was placed in the cache.

If you want to use the current information without restarting MapViewer, you can clear (invalidate) the content of either or both of these caches. If a cache is cleared, the next MapViewer request will retrieve the necessary information from the database, and will also store it in the appropriate cache.

7.6.1 Clearing Metadata Cache for a Data Source (Administrative)

As users request maps from a data source, MapViewer caches such mapping metadata as style, theme, and base map definitions for that data source, as well as the SRID value for SDO_GEOMETRY columns in tables (such as when rendering a theme for the first time). This prevents MapViewer from unnecessarily accessing the database to fetch the mapping metadata. However, modifications to the mapping metadata, such as those you make using the Map Builder tool, do not take effect until MapViewer is restarted.

If you want to use the changed definitions without restarting MapViewer, you can request that MapViewer clear (that is, remove from the cache) all cached mapping metadata and cached table SRID values for a specified data source. Clearing the metadata cache forces MapViewer to access the database for the current mapping metadata.

The <clear_cache> element clears the MapViewer metadata cache. It has the following definition:

<!ELEMENT non_map_request clear_cache>
<!ELEMENT clear_cache  EMPTY>
<!ATTLIST clear_cache
   data_source  CDATA #REQUIRED
>

The data_source attribute specifies the name of the data source whose metadata is to be removed from the MapViewer metadata cache.

The following example clears the metadata for the mvdemo data source from the MapViewer metadata cache:

<?xml version="1.0" standalone="yes"?>
<non_map_request>
  <clear_cache data_source="mvdemo"/>
</non_map_request>

The DTD for the response to a clear_cache request has the following format:

<!ELEMENT non_map_response clear_cache>
<!ELEMENT clear_cache  EMPTY>
<!ATTLIST clear_cache
   succeed   (true | false) #REQUIRED
>

For example:

<?xml version="1.0" ?> 
<non_map_response>
 <clear_cache succeed="true"/> 
</non_map_response>

7.6.2 Clearing Spatial Data Cache for a Theme (Administrative)

MapViewer caches spatial data (geometries or georeferenced images) for a predefined theme as it loads the data from the database into memory for rendering, unless it is told not to do so. (MapViewer does not cache the data for dynamic or JDBC themes.) Thus, if a predefined theme has been frequently accessed, most of its data is probably in the cache. However, if the spatial data for the theme is modified in the database, the changes will not be visible on maps, because MapViewer is still using copies of the data from the cache. To view the modified theme data without having to restart MapViewer, you must first clear the cached data for that theme.

The <clear_theme_cache> element clears the cached data of a predefined theme. It has the following definition:

<!ELEMENT non_map_request clear_theme_cache>
<!ELEMENT clear_theme_cache  EMPTY>
<!ATTLIST clear_theme_cache
   data_source CDATA #REQUIRED
   theme       CDATA #REQUIRED
>

The data_source attribute specifies the name of the data source. The theme attribute specifies the name of the predefined theme in that data source.

The following example clears the cached spatial data for the predefined theme named STATES in the mvdemo data source:

<?xml version="1.0" standalone="yes"?>
<non_map_request>
  <clear_theme_cache data_source="mvdemo" theme="STATES"/>
</non_map_request>

The DTD for the response to a clear_theme_cache request has the following format:

<!ELEMENT non_map_response clear_theme_cache>
<!ELEMENT clear_theme_cache  EMPTY>
<!ATTLIST clear_theme_cache
   succeed  (true | false) #REQUIRED
>

For example:

<?xml version="1.0" ?> 
<non_map_response>
 <clear_theme_cache succeed="true"/> 
</non_map_response>

7.7 Editing the MapViewer Configuration File (Administrative)

The <edit_config_file> element lets you edit the MapViewer configuration file (mapViewerConfig.xml). It has the following definition:

<!ELEMENT non_map_request edit_config_file>
<!ELEMENT edit_config_file  EMPTY>

Note:

Use the <edit_config_file> element only if you are running MapViewer in the standalone OC4J environment or in a nonclustered OC4J instance with only one process started. Otherwise, the modifications that you make will be applied only to one MapViewer instance, and inconsistencies may occur.

Specify the request as follows:

<?xml version="1.0" standalone="yes">
<non_map_request>
  <edit_config_file/>
</non_map_request>

After you submit the request, you are presented with an HTML form that contains the current contents of the MapViewer configuration file. Edit the form to make changes to the content, and click the Save button to commit the changes. However, the changes will not take effect until you restart the MapViewer server (see Section 7.8).

7.8 Restarting the MapViewer Server (Administrative)

In general, the safest method for restarting the MapViewer server is to restart its containing OC4J instance. However, if you are running MapViewer in a standalone OC4J environment, or if the OC4J instance is not clustered and it has only one Java process started, you can use the <restart> element to restart MapViewer quickly without restarting the entire OC4J instance. The <restart> element has the following definition:

<!ELEMENT non_map_request edit_config_file>
<!ELEMENT restart  EMPTY>

Specify the request as follows:

<?xml version="1.0" standalone="yes">
<non_map_request>
  <restart/>
</non_map_request>