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.
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.)
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 themapViewerConfig.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>
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>
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>
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>
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>
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>
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.
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.
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:
The name attribute identifies the name of the style.
The type attribute identifies the MapViewer style type.
The render attribute indicates whether or not the style is used as a rendering style by the theme.
The label attribute indicates whether or not the style is used as a labeling style.
The highlight attribute indicates whether or not the style is used as only a highlight style.
The description attribute identifies the description as specified in the style definition.
MapViewer uses two types of in-memory cache:
Metadata cache for mapping metadata, such as style, theme, and base map definitions, and the SRID value for SDO_GEOMETRY columns in tables in the cache
Spatial data cache for predefined themes (the geometric and image data used in generating maps)
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.
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>
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>
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).
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>