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, base maps, and tile layers. 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 either a <non_map_request> or <map_cache_admin_request> element, and all responses are embedded in a <non_map_response> or <map_cache_admin_response> element, respectively. However, for all requests an exception may occur, in which case the response is an <oms_error> or an <mcs_error> element (described in Section 3.1.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.6.2.15.)
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 Java EE container's Java Naming and Directory Interface (JNDI) namespace.
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. 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 5-1 adds a data source named mvdemo by specifying all necessary connection information.
Example 5-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.example.com"
jdbc_port="1521"
jdbc_sid="orcl"
jdbc_user="scott"
jdbc_password="password"
jdbc_mode="thin"
number_of_mappers="5"/>
</non_map_request>
Example 5-2 adds a data source named mvdemo by specifying the container data source name.
Example 5-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 5-3 removes a data source named mvdemo.
Example 5-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 5.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.example.com"
sid="orcl" port="1521" user="scott" mode="thin" numMappers="3"/>
<map_data_source name="geomedia" host="geomedia.example.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>
All tile layer administration requests are embedded in a <map_cache_admin_request> element. Their responses are embedded in a <map_tile_server_response> element except for <get_client_config>, where the format for the response document can vary. When an error occurs, the response returns an <mcs_error> element containing corresponding error messages.
Two tile layer administration requests, <get_client_config> and <get_cache_status>, can also be sent in a non-administrative mode, in which cases you do not need to log in to the administration console.
Tile layer management tasks include the following:
The <get_client_config> element returns the configuration of a specified tile layer from the client side. It has the following definition:
<!ELEMENT map_cache_admin_request (get_client_config)> <!ELEMENT get_client_config EMPTY> <!ATTLIST get_client_config map_cache_names CDATA #REQUIRED format (JSON|XML|OLD_JS) #IMPLIED >
The map_cache_names attribute lists the tile layer names for which configurations are requested.
The format attribute specifies the document format in the response.
The following example gets the configuration for one tile layer, MVDEMO.DEMO_MAP, in XML format:
<?xml version="1.0" standalone="yes"?> <map_cache_admin_request> <get_client_config map_cache_names="MVDEMO.DEMO_MAP" format="XML" /> />
The response may be the following:
<map_tile_server_response>
<map_tile_layer_config>
<map_tile_layer name="DEMO_MAP" data_source="MVDEMO" format="PNG" transparent="false">
<coordinate_system srid="8307" type="GEODETIC" distConvFactor="0.0" minX="-180.0" minY="-90.0" maxX="180.0" maxY="90.0"/>
<zoom_levels>
<zoom_level level="0" name="" scale="1.0E7" tile_width="4.285714285714286" tile_height="4.285714285714286" tile_image_width="189" tile_image_height="189"/>
<zoom_level level="1" name="" scale="3000000.0" tile_width="1.0843373493975903" tile_height="0.9608052463016623" tile_image_width="158" tile_image_height="140"/>
</zoom_levels>
</map_tile_layer>
</map_tile_layer_config>
</map_tile_server_response>
The <get_client_config> request also works in non-administrative mode, and the request can be sent over an xml_request string. For example:
http://localhost:7001/mapviewer/mcserver?xml_request=<map_cache_admin_request><get_client_config map_cache_names="MVDEMO.DEMO_MAP" format="XML" /></map_cache_admin_request>
The <get_cache_status> element lists the status of all tile layers on the server. It has the following definition:
<!ELEMENT map_cache_admin_request (get_cache_status)> <!ELEMENT get_cache_status EMPTY>
The following example lists the status of all tile layers on the server:
<?xml version="1.0" standalone="yes"?> <map_cache_admin_request> <get_cache_status/> </map_cache_admin_request>
The DTD for the response to a get_cache_status request has the following format:
<!ELEMENT map_tile_server_response (tile_server_status)> <!ELEMENT tile_server_status (cache_instance*)> <!ELEMENT cache_instance EMPTY> <!ATTLIST cache_instance data_source CDATA #REQUIRED name CDATA #REQUIRED type (internal|external) #REQUIRED base_map CDATA #REQUIRED zoom_levels PCDATA #REQUIRED status (ready|not ready) #REQUIRED online (true|false) #REQUIRED >
The name attribute identifies the name of the tile layer in that data source.
The type attribute indicates if the map source is an internal or an external map source.
The zoom_levels attribute indicates the total zoom levels in this tile layer.
The base_map attribute specifies the base map name used by this tile layer for generating map tiles, if the type is an internal map source.
The status attribute indicates if the tile layer is ready or not ready.
The online attribute indicates if the tile layer is online (true) or offline (false).
The following is an example of a get_cache_status response:
<map_tile_server_response>
<tile_server_status>
<cache_instance data_source="MVDEMO_PC" name="DEMO_MAP" type="internal" base_map="DEMO_MAP" zoom_levels="10" status="ready" online="true"/>
<cache_instance data_source="MVDEMO" name="WMTS" type="internal" base_map="WMTS" zoom_levels="15" status="ready" online="true"/>
</tile_server_status>
<map_tile_server_response>
The <get_cache_status> request also works in non-administrative mode, and the request can be sent over an xml_request string. For example:
http://localhost:7001/mapviewer/mcserver?xml_request=<map_cache_admin_request><get_cache_status /></map_cache_admin_request>
The <tile_admin_task> element can be used to request the server to clear the cached tiles, fetch tiles for caching, or refresh tiles (that is, delete any existing tiles and then fetch tiles). For these purposes, it has the following definition:
<!ELEMENT map_cache_admin_request (tile_admin_task)> <!ELEMENT tile_admin_task (schedule?)> <!ELEMENT schedule EMPTY> <!ATTLIST tile_admin_task operation (clear_tiles|fetch_tiles|refresh_tiles) #REQUIRED map_tile_layer CDATA #REQUIRED zoom_levels PCDATA #REQUIRED bounding_box PCDATA #REQUIRED > <!ATTLIST schedule start_time PCDATA #REQUIRED repeat_interval PCDATA #IMPLIED duration PCDATA #IMPLIED >
The operation attribute identifies the operation to be performed: clear_tiles, fetch_tiles, or refresh_tiles.
The map_tile_layer attribute indicates the tile layer name. It takes the data source name as its prefix, followed by a period (.) and then the tile layer name. For example: mvdemo.demo_map
The zoom_levels attribute specifies a list of zoom levels for which to perform the operation.
The bounding_box attribute defines a rectangular region within which to perform the operation.
The start_time attribute indicates when the scheduled task will start.
The repeat_interval attribute indicates how often, in minutes, this operation will be performed. A value of 0 (zero) indicates that it is a one-time operation.
The duration attribute indicates how long, in minutes, an operation will last. If this attribute is empty of not specified, the task will take as long as it needs to finish.
The following example sends a fetch_tiles request:
<?xml version="1.0" standalone="yes"?>
<map_cache_admin_request>
<tile_admin_task
operation="fetch_tiles"
map_tile_layer="mvdemo.demo_map"
zoom_levels="7,8"
bounding_box="-71.6,42.35,-71.58,42.37">
<schedule start_time="2013-03-20 9:00:00" repeat_interval="0" duration="" />
</tile_admin_task>
</map_cache_admin_request>
The DTD for the fetch_tiles response is as follows:
<!ELEMENT map_tile_server_response (request_status, request_id, estimates)> <!ELEMENT request_status (#CDATA)> <!ELEMENT request_id (#CDATA)> <!ELEMENT estimates EMPTY> <!ATTLIST estimates tile_remaining CDATA #REQUIRED time_remaining CDATA #REQUIRED disk_space_required CDATA #REQUIRED >
The tile_remaining attribute indicates the number of tiles remaining to be fetched.
The time_remaining attribute indicates the estimated time, in seconds, needed to fetch the remaining tiles.
The disk_space_required attribute indicates the estimated storage space, in bytes, for the remaining tiles.
For example:
<map_tile_server_response> <request_status>Submitted</request_status> <request_id>62</request_id> <estimates tile_remaining="144" time_remaining="288" disk_space_required="990576"/> </map_tile_server_response>
The <tile_admin_task> element can be used to request the server to generate a zip file containing map tiles for you to download. Its request definition is similar to a clearing, prefetching, or refreshing request (explained in Section 5.2.3), except that the operation attribute should set to export_tiles.
The following example sends a export_tiles request:
<?xml version="1.0" standalone="yes"?>
<map_cache_admin_request>
<tile_admin_task
operation=" export_tiles "
map_tile_layer="mvdemo.demo_map"
zoom_levels="5,6,7,8,9,10,11,12,14,14,15"
bounding_box="-71.6,42.35,-71.58,42.37">
</tile_admin_task>
</map_cache_admin_request>
The response includes the URL for downloading the zip file. The zip file includes the map tiles that are kept in the same tree structure as in the server's map tile cache for that tile layer.
The DTD for the export_tiles response is similar to that in Section 5.2.3, "Clearing, Prefetching, or Refreshing Cache", except that it has one additional child element: <zipped_cache_url>. The value of this element is the URL string for downloading the zip file.
For example, the response to the preceding request is:
<map_tile_server_response> <request_status>Submitted</request_status> <request_id>0</request_id> <zipped_cache_url> http://localhost:8088/mapviewer/images/zipcache/MVDEMO.DEMO_MAP_tozip1_6.zip </zipped_cache_url> <estimates tile_remaining="50" time_remaining="100" disk_space_required="238250"/> </map_tile_server_response> <map_tile_server_response>
The <tile_admin_task> element can be used to request the server to stop, resume, or remove tasks. For these purposes, it has the following definition:
<!ELEMENT map_cache_admin_request (tile_admin_task)> <!ELEMENT tile_admin_task EMPTY> <!ATTLIST tile_admin_task operations (stop_task|resume_task|remove_task) #REQUIRED task_id PCDATA #REQUIRED >
The operation attribute identifies the operation to be performed: stop_task, resume_task, or remove_task.
The task_id attribute indicates the task identifier for which to perform the operation.
The following example sends a request to stop a task:
<?xml version="1.0" standalone="yes"?>
<map_cache_admin_request>
<tile_admin_task
operation="stop_task"
task_id="12">
</tile_admin_task>
</map_cache_admin_request>
The DTD for the stop_task response to a request is as follows:
<!ELEMENT map_tile_server_response (#CDATA)>
For example:
<map_tile_server_response>Succeeded.</map_tile_server_response>
The <get_admin_request_status> element shows the status of a previously sent administrative request. It has the following definition:
<!ELEMENT map_cache_admin_request (get_admin_request_status)> <!ELEMENT get_admin_request_status EMPTY> <!ATTLIST get_admin_request_status data_source CDATA #REQUIRED map_tile_layer CDATA #REQUIRED >
The following example gets the administrative request status of a specified tile layer:
<?xml version="1.0" standalone="yes"?> <map_cache_admin_request> <get_admin_request_status data_source="mvdemo" map_tile_layer="demo_map"/> </map_cache_admin_request>
The DTD for the response to a get_admin_request_status request has the following format:
<!ELEMENT map_cache_admin_request (tile_admin_task)> <!ELEMENT tile_admin_task (bound, schedule?, task_progress)> <!ELEMENT bound (gml:Box)> <!ELEMENT schedule EMPTY> <!ELEMENT task_progress (zoom_level+)> <!ELEMENT zoom_level EMPTY> <!ATTLIST tile_admin_task id PCDATA #REQUIRED type (CLEAR, PREFETCH, REFRESH) #REQUIRED data_source CDATA #REQUIRED map_tile_layer CDATA #REQUIRED zoom_levels PCDATA #REQUIRED > <!ATTLIST schedule start_time PCDATA #REQUIRED repeat_interval PCDATA #IMPLIED duration PCDATA #IMPLIED cron_string CDATA #IMPLIED > <!ATTLIST zoom_level level PCDATA #REQUIRED total_tile_number PCDATA #REQUIRED processed_tile_number PCDATA #REQUIRED failed_tile_number PCDATA #REQUIRED tile_x PCDATA #REQUIRED tile_y PCDATA #REQUIRED >
The level attribute indicates the current zoom level of this task.
The total_tile_number attribute indicates the total number of tiles of this task.
The processed_tile_number attribute indicates the already processed number of tiles.
The failed_tile_number attribute indicates the number of tiles that have failed in the operation.
The tile_x and tile_y attributes indicate the last processed tile's coordinates (x, y) in the tile mesh code coordinate system. A value of -1 indicates that the task has not been started.
For example:
<tile_admin_task id="67" type="PREFETCH" data_source="MVDEMO" map_tile_layer="DEMO_MAP" zoom_levels="8,9">
<bound>
<gml:Box xmlns:gml="http://www.opengis.net/gml" srsName="SDO:8307">
<gml:coordinates decimal="." cs="," ts=" ">
-71.60,42.35 -71.58,42.37
</gml:coordinates>
</gml:Box>
</bound>
<schedule repeat_interval="0" duration="0" start_time="2015-03-20 09:00:00" cron_string=""/>
<task_progress>
<zoom_level level="8" total_tile_number="144" processed_tile_number="0" failed_tile_number="0" tile_x="-1"tile_y="-1"/>
<zoom_level level="9" total_tile_number="1122" processed_tile_number="0" failed_tile_number="0" tile_x="-1"tile_y="-1"/>
</task_progress>
</tile_admin_task>
The <tile_admin_task> element can be used to request the tile layer server to create or redefine a cache instance. For these purposes it has the following definition:
<!ELEMENT map_cache_admin_request (create_cache_instance, redefine_cache_instance)> <!ELEMENT create_cache_instance (cache_instance)> <!ELEMENT redefine_cache_instance (cache_instance)> <!ELEMENT cache_instance (internal_map, cache_storage?|tile_storage?, coordinate_system, tile_image, zoom_levels)> <!ELEMENT internal_map_source EMPTY> <!ELEMENT cache_storage EMPTY> <!ELEMENT coordinate_system EMPTY> <!ELEMENT tile_image EMPTY> <!ELEMENT zoom_levels EMPTY> <!ATTLIST create_cache_instance data_source CDATA #REQUIRED > <!ATTLIST cache_instance name CDATA #REQUIRED image_format (PNG|GIF|JPG)"PNG" > <!ATTLIST internal_map_source base_map CDATA #REQUIRED > <!ATTLIST cache_storage root_path CDATA #IMPLIED > <!ATTLIST coordinate_system srid PCDATA #REQUIRED minX PCDATA #REQUIRED maxX PCDATA #REQUIRED minY PCDATA #REQUIRED maxY PCDATA #REQUIRED > <!ATTLIST tile_image width PCDATA #REQUIRED height PCDATA #REQUIRED > <!ATTLIST zoom_levels levels PCDATA #REQUIRED min_scale PCDATA #REQUIRED max_scale PCDATA #REQUIRED >
The srid attribute specifies the projection (coordinate system) of this tile layer.
The minX, maxX, minY, and maxY attributes specify the data bounds of this tile layer in the specified projection.
The width and height attributes specify the tile image width and height.
The levels attribute specifies the number of zoom levels of this tile layer.
The min_scale and max_scale attributes specify the smallest and largest values of the scale denominators. Zoom 0 is always assigned with the largest scale denominator, thus, a tile covers a larger geographic region with coarse map details.
The <remove_cache_instance> element removes a tile layer instance from the server. It has the following definition:
<!ELEMENT map_cache_admin_request (remove_cache_instance)> <!ELEMENT remove_cache_instance EMPTY> <!ATTLIST remove_cache_instance map_cache_name CDATA #REQUIRED clean_disk (true|false) "false" remove_permanently (true|false) "false" >
The clean_disk attribute indicates if the already cached tiles are to be deleted.
The remove_permanently attribute indicates if tile layer is to be deleted from the USER_SDO_CACHED_MAPS view.
The following example removes a tile layer instance from the server.
<?xml version="1.0" standalone="yes"?>
<map_cache_admin_request>
<remove_cache_instance
map_cache_name="mvdemo.demo_map"
clean_disk="true" remove_permanently="false"/>
The DTD for the remove_cache_instance response is as follows:
<!ELEMENT map_tile_server_response (#CDATA)>
For example:
<map_tile_server_response>Succeeded.</map_tile_server_response>
The <restart_cache_server> element restarts the tile layer server. It has the following definition:
<!ELEMENT map_cache_admin_request (restart_cache_server)> <!ELEMENT restart_cache_server EMPTY>
The following example restarts the server:
<?xml version="1.0" standalone="yes"?> <map_cache_admin_request> <restart_cache_server /> </map_cache_admin_request>
The <take_cache_offline> element takes a tile layer instance offline from the server, and the <bring_cache_online> element brings an offline tile layer instance back online. The following is the DTD definition:
<!ELEMENT map_cache_admin_request (take_cache_offline, bring_cache_online)> <!ELEMENT take_cache_offline EMPTY> <!ATTLIST take_cache_offline map_cache_name CDATA #REQUIRED > <!ATTLIST bring_cache_online map_cache_name CDATA #REQUIRED >
The following example takes a tile layer instance offline:
<?xml version="1.0" standalone="yes"?> <map_cache_admin_request> <take_cache_offline map_cache_name="mvdemo.demo_map" /> </map_cache_admin_request>
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.
The <get_style_definition> element returns the definition of a style in a data source. This element has the following definition:
<!ELEMENT non_map_request get_style_definition> <!ELEMENT get_style_definition EMPTY> <!ATTLIST get_style_definition data_source CDATA #REQUIRED style CDATA #REQUIRED >
The following example gets the definition of the M.AIRPORT style in the mvdemo data source:
<?xml version="1.0" standalone="yes"?> <non_map_request> <get_style_definition data_source="mvdemo" style="M.AIRPORT"/> </non_map_request>
The following example shows the response to the preceding request:
<non_map_response>
<style name="M.AIRPORT">
<svg width="1in" height="1in">
<desc/>
<g class="marker" style="width:23;height:15;font-family:Dialog;font-size:12;font-fill:#FFFFFF">
<image x="0" y="0" width="1" height="1" markerType="gif" href="dummy.gif"/>
</g>
</svg>
</style>
</non_map_response>
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 a standalone Java EE container or in a nonclustered WebLogic Server 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 5.10).
In general, the safest method for restarting the MapViewer server is to restart its container instance. However, if you are running MapViewer in a standalone environment, or if the container 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 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>