6 OracleAS MapViewer Administrative Requests

The main use of OracleAS MapViewer is for processing various map requests. However, OracleAS MapViewer also accepts various administrative (non-map) requests, such as to add a data source, through its XML API. For all OracleAS MapViewer administrative requests except for those that list base maps, themes, or styles, you must log in to the OracleAS MapViewer administration (Admin) page, for which there is a link on the main OracleAS MapViewer page. This section describes the format for each administrative request and its response.

All administrative requests are embedded in a <non_map_request> element, while all administrative responses are embedded in a <non_map_response> element, unless an exception is thrown by OracleAS 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:

Managing Data Sources
Listing All Maps
Listing Themes
Listing Styles
Managing Cache
Editing the OracleAS MapViewer Configuration File
Restarting the OracleAS MapViewer Server

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

6.1.1 Adding a 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 OracleAS 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.

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 OracleAS 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 OracleAS 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, OracleAS 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 OracleAS MapViewer has finished processing one of the current requests. The maximum number of mappers for a single data source is 64.

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

Example 6-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="tiger"
        jdbc_mode="thin"
        number_of_mappers="5"/>
</non_map_request>

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

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

6.1.2 Removing a Data Source

The <remove_data_source> 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 OracleAS MapViewer).

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

Example 6-3 removes a data source named mvdemo.

Example 6-3 Removing a Data Source

<?xml version="1.0" standalone="yes"?>
<non_map_request>
  <remove_data_source data_source="mvdemo" jdbc_password="tiger"/>
</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>

6.1.3 Redefining a Data Source

For convenience, OracleAS 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 6.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>

6.1.4 Listing All Data Sources

The <list_data_sources> element lists all data sources known to the currently running OracleAS 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, all data source information except the password for the database user is returned.

The following example is a response that includes information about two data sources.

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

6.1.5 Checking the Existence of a Data Source

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>

6.2 Listing All Maps

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>

6.3 Listing Themes

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.

6.4 Listing Styles

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.

6.5 Managing Cache

OracleAS MapViewer uses two types of cache:

Metadata cache for mapping metadata, such as style, theme, and base map definitions
Spatial data cache for theme data (the geometric and image data used in generating maps)

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

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

6.5.1 Clearing Metadata Cache for a Data Source

As users request maps from a data source, OracleAS MapViewer caches such mapping metadata as style, theme, and base map definitions for that data source. This prevents OracleAS MapViewer from unnecessarily accessing the database to fetch the mapping metadata. However, modifications to the mapping metadata do not take effect until OracleAS MapViewer is restarted.

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

The <clear_cache> element clears the OracleAS 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 OracleAS MapViewer metadata cache.

The following example clears the metadata for the mvdemo data source from the OracleAS 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>

6.5.2 Clearing Spatial Data Cache for a Theme

OracleAS 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. (OracleAS MapViewer does not cache 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 OracleAS MapViewer is still using copies of the data from the cache. To view the modified theme data without having to restart OracleAS 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>

6.6 Editing the OracleAS MapViewer Configuration File

The <edit_config_file> element lets you edit the OracleAS 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 OracleAS 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 OracleAS 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 OracleAS 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 OracleAS MapViewer server (see Section 6.7).

6.7 Restarting the OracleAS MapViewer Server

In general, the safest method for restarting the OracleAS MapViewer server is to restart its containing OC4J instance. However, if you are running OracleAS 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 OracleAS 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>