MapViewer FAQ - Oracle€¦ · Once you have installed the Quick Start kit, you should download the...

MapViewer FAQ

Last Mo

dified:

11/200

4

Note: questions marked with have been updated or are new for version 10.1.2.

Introduction 1. What is MapViewer? 2. What is the easiest way to get started with MapViewer? 3. How is MapViewer licensed? 4. What are the prerequisites for using MapViewer? 5. Why is the Map Definition Tool (MDT) not part of the official release?

Installation 1. Where can I find MapViewer and the Map Definition Tool? 2. What's the minimum required JDK version? 3. I downloaded MapViewer from OTN some time ago. How do I find out which version it

is? 4. How do I specify the admin user/password for MapViewer after deploying it to Oracle

Application Server? 5. What's the MapViewer home page? 6. How do I log in as a MapViewer administrator? 7. Why can't I login to perform administrative tasks on linux? 8. How do I run MapViewer on a Unix/Linux server that does not have an X11 Display? 9. Is there any difference between the mapviewer.ear file that comes with Oracle

Application Server, and the one downloadable from OTN? 10. Is it possible to deploy MapViewer on a 3rd party application server such as JBoss?

Using MapViewer 1. MapViewer is set up. Just for fun, how do I show a point (x,y)? 2. I have a table with a geometry column. Now how do I view the spatial data using

MapViewer? 3. Can MapViewer display 3D data? 4. Can MapViewer view 3rd party spatial/GIS data? 5. Can I define a permanent data source for MapViewer?

6. Can I use the Container's data source as a MapViewer data source? 7. Can MapViewer display spatial data in different projections? 8. Can MapViewer display geometries in function-based indexes? 9. Can I save a complex query in its entirety for a dynamic (JDBC) theme? 10. How do I view large coverage data using a global projection? 11. When migrating the database used by MapViewer, what are the ways to move all the

styles, themes, and map definitions in the schema?

12. How do I create an SVG map with info-tips following mouse movement? 13. Why don't the zoom/pan tools work with my SVG maps? 14. Is MapViewer compatible with OpenGeospatial Consortium (OGC)'s WMS specification?

15. Can MapViewer display map layers generated from another WMS instance? 16. Can MapViewer display a theme based on a view? 17. How do I place a text label at a specific point on the map, without drawing the point

itself?

Development 1. Can MapViewer generate HTML image maps automatically? 2. Can I access MapViewer functions from a C|C++|Perl|PL/SQL program? 3. How can I add the MapViewer JSP tags to Oracle JDeveloper's Component Palette? 4. How do I view mapping metadata through JDeveloper's Connections Navigator? 5. I have just changed the definitions of some (styles/themes/basemaps). Why are my

maps still using the old definitions? 6. How do I disable certain themes from being cached? 7. How do I create a map with pie charts? 8. How do I dynamically add a style from my application?

9. How do I ensure that certain features ALWAYS get labeled on the map? 10. How do I use an Advanced Style in a JDBC theme? 11. How do I dynamically generate a map legend in its own image? 12. Can I use MapViewer with Oracle UIX pages? 13. What are the values of the "matrix" attribute in an xml map response's <xfm> element?

14. Can MapViewer generate maps with a transparent background?

15. Can MapViewer display versioned spatial data in a workspace? 16. How do I display spatial data stored in another schema? 17. How do I bound a map based on the MBR of a theme or dynamic query's results?

Performance and Administration

1. How can I improve the overall performance of MapViewer? 2. How do I control the number of database sessions used by MapViewer? 3. How do I define a data source that connects to an Oracle RAC (Real Application Cluster)

database?

Known Issues in version 9.0.4

1. Using dynamic styles across two MapViewer server instances 2. View-based themes with identical key_column values

Introduction

1. What is MapViewer?

MapViewer is a rendering service for geospatial data managed in Oracle Spatial. It is a component of the Oracle Application Server, and first shipped with the 9.0.2 version of 9iAS. MapViewer is a pure Java component written for the Oracle Container for J2EE (OC4J), although it can also be deployed to other J2EE containers such as JBoss.

2. What is the easiest way to get started with MapViewer?

Downloading the Quick Start kit of MapViewer 10.1.2 is the easiest way to get started. This kit includes a standalone OC4J (Oracle Container for J2EE) pre-configured with the latest version of MapViewer and ready for action. The kit is available from from MapViewer's OTN page at http://otn.oracle.com/products/mapviewer, under the Software section. This kit plus a Java SDK 1.4 or later installation is all you need to get going.

Once you have installed the Quick Start kit, you should download the demo data set for 10.1.2, and load the data into your Oracle Spatial database. After loading the data, go to the MapViewer's admin page and define a new data source named "mvdemo". This will tell MapViewer where you have loaded the demo data set. Now go to MapViewer's home page and try the cool demos listed there.

3. How is MapViewer licensed?

Starting with Oracle Application Server 10.1.2, MapViewer is part of the Oracle AS Java Edition, Standard Edition, and the Enterprise Edition. It is also included as part of your JDeveloper license for development purposes.

4. What are the prerequistes for using MapViewer?

Oracle database version 8i (8.1.6) or later, as well as Oracle Application Server 9i (9.0.2) or later. It's also possible to simply install a standalone version of Oracle Container for J2EE (OC4J) and deploy MapViewer to it.

For MapViewer version 10.1.2, you will need Java 2 SDK 1.4 or later.

5. Why is the Map Definition Tool (MDT) not part of the official release?

MDT is undergoing an extensive rewrite so that it can fully support all the functionalitity currently available in the MapViewer server. Since this is not completed yet, we are temporarily providing the first beta version of MDT (the one you currently are using) for download from OTN. This MDT lacked sufficient functionality and full support of MapViewer, and hence is not part of our official MapViewer release.

Installation

1. Where can I find MapViewer and the Map Definition Tool?

Officially, MapViewer is shipped as part of the Oracle Application Server Java, Standard and Enterprise editiions. For development purposes, you may download the MapViewer kit from Oracle Technet (www.oracle.com/technology). It is listed under the Oracle Spatial section (www.oracle.com/technology/products/spatial/content.html).

The Map Definition Tool is an unsupported tool that can be used to visually create database-backed definitions of map styles, themes and basemaps. It can be downloaded from the same page where the MapViewer kit is located.

2. What's the minimum required JDK version?

JDK 1.4 is the minimum version required. MapViewer will not work with JDK 1.3 or any earlier version. Also note that if you are using a standalone OC4J instance, you must start it using the Java executable that is under your JDK installation's top bin directory. The java executable under the jre/bin directory will NOT work with OC4J.

3. I downloaded MapViewer from OTN some time ago. How do I find out which version it is?

First, scroll all the way to the bottom of the home/welcome page of your MapViewer instance. If you see a line like Build: Ver9_0_4_B030829, that's the version and build number of your MapViewer instance. If you did not see such a line, chances are it is an older (pre 9.0.4) version of MapViewer. In any case, you can always navigate to the MapViewer's unpacked directory $MAPVIEWER/web/WEB-INF/lib/, and find the file named mvclient.jar. Now run the command "jar tvf mvclient.jar" and it will display a list of class files packaged inside. One of the files will have a name like "Ver902_*.class". This tells you the version and build number of your MapViewer instance.

4. How do I specify the admin user/password for MapViewer after deploying it to the Oracle Application Server?

Note 1: This question is only applicable to MapViewer production version 9.0.4 or later. Note 2: If you deployed MapViewer to a standalone OC4J, you do not need to do anything during deployment. For instructions on how to log in, check here.

After you deployed MapViewer, you will need to create an admin user for MapViewer in its OC4J container instance. This admin user then needs to be mapped to the MapViewer's "map_admin_role" security role. The following screenshots show an example of performing this task.

Step 1. First, go to the Oracle AS Enterprise Manager website, navigate to the OC4J instance running MapViewer, and select the "mapviewer" application. Now click on its "Security" link.

Step 2. Note that there are no existing security users or groups. So we will need to add a user for MapViewer.

Step 3. Provide the name and password for the new security user. Be sure to remember this password.

Step 4. Having created a new security user we must map it to MapViewer's built-in security role "map_admin_role".

Step 5. By choosing the newly created user to be mapped to the "map_admin_role".

Now if we go to the MapViewer's site, and try to perform certain restricted operations such as "add a datasource", we will be prompted for a user name and password. Use the newly created security user/password.

5. What's the MapViewer Home Page?

Throughout this FAQ, you will come across references to the MapViewer home page. This is the default page that you will see when you point your browser to the URL of the form http://host:port/mapviewer, where the host should be the name or IP address of the host running MapViewer, and port is the port number at which the Oracle Application Server is listening for web requests. It may also be the port on which OC4J is listening, if you only installed a standalone version of OC4J. With a full Oracle Application Server install, the port is usually 7779 or 7777. With a typical standalone OC4J install, the port is usually 8888.

The MapViewer home page serves many purposes. It provides many HTML forms for administrative purposes, and for submitting xml Map Requests. It also links to several on-line demos that you can experiment with.

It is usually a good idea, for security, to hide this home page from external users or applications when deploying MapViewer.

6. How do I log in as a MapViewer administrator?

Beginning with MapViewer production version 9.0.4, certain administrative operations such as adding or removing a datasource will require you to log in as an administrator. The admin user name and password depends on whether you deployed MapViewer in a standalone OC4J or a full Oracle Application Server install.

o If MapViewer is deployed in a standalone OC4J: The user name will be "admin", the password is the admin password you specified when you installed the OC4J instance (at the prompt after you type in "java -jar oc4j.jar -install"). If you have forgotten the password, you can cd into

OC4J's j2ee/home direcotry and type "java -jar oc4j.jar -install" again which will prompt for the new admin password.

o If MapViewer is deployed in a full Oracle Application Server: You should have created an admin user in the OC4J instance where MapViewer is running. This is done as specified in this answer to a previous question.

7. Why can't I login to perform administrative tasks on linux?

On Redhat Linux Enterprise version, there may be a login issue when running MapViewer with a standalone installation of OC4J (9.0.4). It occurs because the admin password that you specified when first installing OC4J was not recorded and thus not effective. So when you attempt to use that password to login to MapViewer's admin page it fails (the login dialog simply reappears even after you entered the "correct" password). The solution is to set the OC4J admin password again by issuing "java -jar oc4j.jar -install" for a second time from the OC4J home directory.

8. How do I run MapViewer on a Unix/Linux server that does not have an X11 Display?

On Linux or Unix systems, if you have installed Java JDK 1.4, then you can take advantage of its -Djava.awt.headless=true option to start OC4J without an X11 server running or the DISPLAY environment variable set. Here is an example of how to start up a standalone version of OC4J which contains MapViewer:

sh> java -Djava.awt.headless=true -jar oc4j.jar

9. Is there any difference between the mapviewer.ear file that comes with Oracle Application Server, and the one downloadable from OTN?

In terms of functionality, there is no difference. However, the packaging is different. The mapviewer.ear file that comes with a full installation of Oracle Application Server (located under the $ORACLE_HOME/lbs directory) is smaller than the one you download from OTN. The difference is sdovis.jar, which is not packaged inside the former, but is included with the latter.

As such, if you are deploying the native mapviewer.ear to the Oracle Application Server, you must explicitly add the sdovis.jar file (located under $ORACLE_HOME/lbs/lib) to its library path.

On the other hand, if you are deploying a mapviewer.ear file that is downloaded from OTN (either a production version or a preview version), you should skip the step that adds the sdovis.jar file.

sdovis.jar is the core rendering engine of MapViewer.

10. Is it possible to deploy MapViewer on a 3rd party application server such as JBoss?

This is not supported or recommended. However users have successfully deployed the mapviewer.ear file downloaded from OTN into a 3rd party J2EE compliant container, such as JBoss. You will need the Oracle JDBC driver (classes12.jar or ojdbc14.jar) and Oracle XML parser (xmlparserv2.jar) in the J2EE container's library path. The latest versions of both should work.

Note that for WebLogic, it appears that you must manually unpack the mapviewer.ear file and then deploy from the unpacked directory. If you deploy from the mapviewer.ear to WebLogic MapViewer will not initialize properly.

Using MapViewer

1. MapViewer is set up. Just for fun, how can I show a point located at (-100.5, 40.5)?

There are at least two ways to show a point. The following options all assuming you have defined a datasource named "mvdemo".

Option 1: Specifying the point to be the center of a map request. Here is such a sample (just note that the size attribute of the center element has no effect in this request):

<?xml version="1.0" standalone="yes"?>

<map_request datasource="mvdemo" format="GIF_STREAM">

<center size="1">

<geoFeature render_style="default">

<geometricProperty typeName="center">

<Point>

<coordinates>-100.5, 40.5</coordinates>

</Point>

</geometricProperty>

</geoFeature>

</center>

</map_request>

What you will get is a "map" like this:

Option 2: Using a map request, but specify the point through a dynamic theme using a SQL query. The SQL query itself basically constructs a temporary Point geometry and returns it. Here is the sample map request:


<map_request datasource="mvdemo" format="GIF_STREAM">

<themes>

<theme name="a point" >

<jdbc_query datasource="mvdemo">

SELECT mdsys.sdo_geometry(2001, null,

mdsys.sdo_point_type(-100.5, 40.5, null),

null, null)

FROM dual

</jdbc_query>

</theme>

</themes>

</map_request>

2. I have a table with a geometry column. Now how do I view the spatial data using MapViewer?

Go to the MapViewer home page, click on the demos link, then choose the jview.jsp demo. This is a simple utility that you can use to quickly view any spatial data stored in the database or created through Oracle Spatial's functions (such as the result of an sdo_buffer operation).

In the jview.jsp page, fill in a datasource name that you already defined, and then simply type a SQL query that will select the table's geometries in the text area named "query 1". Note: you should not end your query with ';'.

Click on the Submit button, and a map showing the geometries you just selected will appear.

The following screen shot shows a more sophisticated example of using jview.jsp, showing 3 queries involving two spatial tables: counties and cities. The first query simply selects all the geometries from the counties table where the state abbreviation is 'AL'. The Second query selects all the major cities from the cities table where the state abbreviation is also 'AL'. Note how you can also specify a label column as in the second query. The third query creates a buffer around each city, using Oracle Spatial's sdo_buffer function.

3. Can MapViewer display 3D data?

No, not yet.

4. Can MapViewer view 3rd party spatial/GIS data?

No, but it can use map images from a Webmap Server. MapViewer 10.1.2 supports a new theme type called WMS-Theme, which can be used to import a map layer generated by any 3rd party's OGC WMS 1.1 compliant server.

Here is a sample XML map request for MapViewer that includes a WMS theme. Note you can also add WMS themes through the Java API. Note the parameters specified in the WMS theme are for illustration only.

<?xml version="1.0" standalone="yes"?><map_requesttitle="wms theme" datasource="mvdemo"width="675" height="337"bgcolor="#0000ff" antialiase="true"format="PNG_STREAM"

><center size="7.0"><geoFeature><geometricProperty typeName="center"><Point><coordinates>-120.0,38.0</coordinates>

</Point></geometricProperty>

</geoFeature></center><themes><theme name="THEME_DEMO_HIGHWAYS" /><theme name="THEME_DEMO_CITIES" />

<theme name="wmstheme1" timeout="20000" ><wms_getmap_request isBackgroundImage="true" >

<service_url>http://gisdata.my_corp.net/servlet/com.esri.wms.Esrimap

</service_url><version>1.1.0</version><format>image/png</format><srs>EPSG:4326</srs><bgcolor>0xa6cae0</bgcolor><transparent>false</transparent><exceptions>application/vnd.ogc.se_inimage</exceptions><layers>

GTOPO60+Color+Shaded+Relief</layers><vendor_specific_parameters>

<vsp><name>ServiceName</name><value>WMS_GTOPO</value>

</vsp></vendor_specific_parameters>

</wms_getmap_request></theme>

</themes></map_request>

Note that in the above map request, in addition to the two vector themes, we are also requesting a theme named "wmstheme1" to be plotted in the result map. MapViewer will issue a WMS GetMap request based on the specified parameters, and the current viewing window, to the WMS server named in the theme. The returned image from the external server is plotted as a background image in this case, but it can also be plotted in the same order as in the theme list. The timeout value specifies how many milliseconds MapViewer will wait for the external server to respond. The timeout parameter currently only applies to a WMS theme and not to predefined or JDBC themes.

5. Can I define a permanent data source for MapViewer?

Yes. Simply add your data source definition in the mapViewerConfig.xml. Make sure you prefix your database user's password with "!", so that MapViewer will obfuscate the cleartext password when it reads in the data source definition for

the first time. Here is an example datasource definition placed in mapViewerConfig.xml.

<map_data_source name="mvdemo"

jdbc_host="mapsrus.my_corp.com"

jdbc_sid="orcl"

jdbc_port="1521"

jdbc_user="scott"

jdbc_password="!tiger"

jdbc_mode="thin"

number_of_mappers="3"

/>

6. Can I use the Container's data source as a MapViewer data source?

Yes. When defining a new data source, you can use the container_ds attribute instead of specifying detailed connection information through jdbc_host/jdbc_sid/jdbc_port/jdbc_user/jdbc_password/jdbc_mode. The value for the container_ds attribute should be the same as that of the ejb-location in your container's data source definition.

Here is one example of map data source definition that is reusing a container data source:

<map_data_source name="mvdemo"container_ds="jdbc/OracleDS"number_of_mappers="3"

/>

Note that if you want to use container_ds in a permanent data source stored in mapViewerConfig.xml file, you must start your OC4J instance with the -userThreads option (java –jar oc4j.jar –userThreads), which instructs OC4J to make its datasource names known to user thread context. You can however always use the container_ds attribute if you are adding or redefining a data source through MapViewer's Admin Page, even if OC4J is started without the -userThreads option.

7. Can MapViewer display spatial data in different projections?

Yes.

Prior to version 10.1.2, all the spatial data rendered by MapViewer had to be in the same spatial reference system (SRS). If your data comes from different sources and they use different SRS's, you had to explicitly use Oracle Spatial's coordinate system functions to transform them into a single reference system for viewing purposes.

Starting with 10.1.2, MapViewer can now perform on-the-fly projection of your spatial data. To enable this, you must specify a master srid in your map request. If a theme being requested has a different srid for its data, MapViewer will invoke Spatial's coordinate transformation functions to transform that theme's data into the master srid. The transformation is done in the database server as part of the query. The result is sent to MapViewer for rendering. The original data in the database will not be modified.

8. Can MapViewer display geometries in function-based indexes?

Yes. For instance, you can query geometries with a function-based index and display them by defining a dynamic JDBC theme.

9. Can I save a complex query in its entirety for a dynamic (JDBC) theme?

Yes, you can specify a complete SQL query instead of simple sql condition in a predefined theme's styling rule. For instance, the following is the definition of a theme's styling rule where the complete query for selecting the geometries of this dynamic theme is specified.


<styling_rules>

<rule>

<features style="L.POOR_ROADS" asis="true">

selectsdo_lrs.clip_geom_segment(geometry,start_measure,end_measure)

geometry

from (select /*+ no_merge use_hash(a b) */

a.street_id, name, start_measure, end_measure,geometry

from (select /*+ no_merge */ a.street_id, name,geometry

from philly_roads a

wheresdo_filter(geometry,mdsys.sdo_geometry(2002,41124,null,

mdsys.sdo_elem_info_array(1,2,1),

mdsys.sdo_ordinate_array(?,?,?,?)),

'querytype=window')='TRUE') a,

philly_road_conditions b

where condition='POOR' and a.street_id = b.street_id)

</features>

</rule>

</styling_rules>

Note that in the above query, the user already specified a sdo_filter operator but with four question marks as place holder for the search/viewing window. MapViewer will automatically fill in those values at run time when this theme is viewed. Also note that this theme, with its definition saved in the database permanently just like a predefined theme, is still treated as a JDBC theme when used by MapViewer. So, all JDBC theme characteristics still apply; for instance, its geometries will never be cached in memory by MapViewer. For more details, refer to the MapViewer User's Guide, Section 2.3.2.1.

10. How do I view large coverage data using a global projection?

It's very simple with MapViewer's built-in Azimuthal Equal Distance projection. If your data is in a geodetic coordinate system, and covers a large area (such as at the continental or global level), then you can enable MapViewer's "use_globular_projection" option, which instructs MapViewer to project your data as you are viewing them.

Here is where in the mapViewerConfig.xml file you can enable this option:

<global_map_config>...<rendering allow_local_adjustment="false"

use_globular_projection="true" /></global_map_config>

Once you restart MapViewer with the above "use_globular_projection" set to true, you will see that maps that cover large areas will be automatically projected. The projection is completely transparent; for instance, all of the zoom/pan functions in MapViewer will still work with any code changes in your application. The following is an illustration of the mapclient.jsp demo viewing a world map with this option turned on.

A few notes regarding the use_globular_projection option:

o This feature is experimental in this release. Some aspects of a map request, such as map size, may not be strictly honored when this option is turned on due to the nature of the projection. Also note that this option affects all datasources and any map that may contain geodetic data based themes.

o The map projection will always be Azimuthal Equidistant in the spherical form. The characteristics of this projection include: all directions or azimuths are correct when measured from the map center; all distances are also at true scale when measured between the map center and any other point on the map.

o Your data must be in one of the geodetic spatial reference systems (such as those with srid 8265, 8307, et al), in order for them to be projected.

o The graticule is automatically generated by MapViewer, and is always centered at the current map center, with an equal spacing of 15 decimal degrees between two adjacent parallels or meridians. The graticule can have complex curves due to the nature of the projection. Currently there is no way to turn the graticule off. However the graticule will not be displayed for any map covering less than 45 degrees of data (although the map itself will always be projected as long as it's in the geodetic coordinate system).

11. When migrating the database used by MapViewer, what are the ways to move all the styles, themes, and map definitions in the schema?

For entries in the user_sdo_styles, user_sdo_themes and user_sdo_maps you should create three temporary tables that can be exported. After importing the data into the new database you would insert the records into the three dictionary tables by selecting the data from your temporary tables. Below is an example:

create table my_styles as select * from user_sdo_styles;create table my_themes as select * from user_sdo_themes;create table my_maps as select * from user_sdo_maps;

-- Export the tables and import them into the new database.

insert into user_sdo_styles select * from my_styles;insert into user_sdo_themes select * from my_themes;insert into user_sdo_maps select * from my_maps;

If the schema name changes from one database to the other then you may need to perform a global replace of the style owner defined in the styling_rules of the user_sdo_themes table. For example, if the data was exported from the SCOTT user you may have the following styling rule:

<?xml version="1.0" standalone="yes"?><styling_rules ><rule ><features style="SCOTT:C.ROSY BROWN STROKE"> </features><label column="STATE" style="SCOTT:T.STATE NAME"> 1 </label>

</rule></styling_rules>

Note that the feature style and label style are prefixed with the schema name that owns the style. If you then import the data into a schema called SPATIAL then you need to change the styling_rules to reflect the new owner of the style. You would accomplish this by using the REPLACE function in SQL. For example:

update user_sdo_themes set styling_rules = replace(styling_rules,'SCOTT:', 'SPATIAL:');

12. How do I create an SVG map with popup information following mouse movement?

In general, generating an SVG map from MapViewer is no different from generating maps in other formats such as PNG. Whereas for a PNG map you specify the format to be either PNG_URL or PNG_STREAM, for SVG maps you specify the format to be SVG_URL or SVG_STREAM.

One unique and very useful feature of SVG maps is to be able to associate attributes with spatial features being displayed, and as you move the cursor over the features, the attributes are automatically displayed in a pop-up window that follows the cursor movement. The following figure illustrates such a SVG map (click on the Info button then move cursor around):

To create such a map, specify <hidden_info> elements in your theme's styling rule. In the above svg example, the theme for the counties has three <hidden_info> elements corresponding to three attribute columns from its base table. Here is the actual styling rule for the counties theme:

update user_sdo_themes set styling_rules='<?xml version="1.0" standalone="yes"?><styling_rules >

<hidden_info><field column="county" name="Name"/><field column="state" name="State"/>

<field column="totpop" name="Population"/></hidden_info>

<rule ><features style="C.FUNNY COLOR"> </features><label column="COUNTY" style="T.CITY NAME"> 1 </label>

</rule></styling_rules>' where name='COUNTIES';

Note that the three columns from the base table are listed in the <hidden_info> element : "county", "state", "totpop". For each column, you can also assign a more user-friendly display name to be used in the popup window. The display names are specified through each field's name attribute.

The above example showed <hidden_info> elements in a predefined theme. The following example is a complete map request with a dynamic (JDBC) theme that includes <hidden_info> elements.

<?xml version="1.0" standalone="yes"?><map_request

title="svg req"datasource = "tilsmenv"width="500" height="500"bgcolor="#a6cae0"antialiase="true"format="SVG_URL">

<box srsName="SDO:8265"><coordinates> -122.0, 36.0 -120.0 38.0 </coordinates>

</box><themes><theme name="county_theme1"><jdbc_query

spatial_column="geom" render_style="C.FUNNY COLOR"jdbc_srid="8265"

datasource="tilsmenv">SELECT geom, county, totpop from counties

<hidden_info><field column="county" name="Name"/><field column="totpop" name="Population"/>

</hidden_info>

</jdbc_query></theme>

<theme name="THEME_US_ROAD1" /><theme name="THEME_US_AIRPORT" />


Additional notes about SVG maps. The following MapViewer features are not yet supported in a SVG map:

o Line style with parallel lines; only the center line style will be preserved in an svg map.

13. Why don’t the zoom/pan tools work with my SVG maps?

You may also have seen an error message that reads "map is not defined" when you click on the SVG map. Please check the following possible causes.

o You are not using Microsoft IE browser. Unfortunately at the time no other browser supports full integration with Adobe's SVG plugin which is required to view the SVG maps. We expect this situation to improve but currently IE is required to navigate the SVG maps. Also check the SVG plugin version by right-clicking on the SVG map. It should be at least 3.0.

o If you are using IE, and you have the latest Adobe SVG plugin (minimum version should be 3.0) installed, then read on. You need to check the URL that you used to access your web page with the SVG map, and the result svg map's url generated by MapViewer. The host name in both URLs should be exactly the same. For example, if the svg map url generated by MapViewer is "http://my-pc.us.mycompany.com:8888/mapviewer/images/omsmap28.svgz", then the url that you use to access the web page should also look like "http://my-pc.us.mycompany.com:8888/.../mysvgmap.jsp". If you use "http://my-pc:8888/.../mysvgmap.jsp" instead, you'll see the undefined map error.

14. Is MapViewer compatible with Open Geospatial Consortium (OGC)'s WMS specification?

Yes. Starting with MapViewer 10.1.2, you can configure MapViewer to act as a WMS 1.1.1 compatible server. For more information, please refer to the MapViewer User's Guide.

15. Can MapViewer display map layers generated from another WMS server?

Yes with 10.1.2. For details please see the answer to this question.

That solution will not work if you are using MapViewer version 9.0.4 or earlier. You can, however, employ the following partial solution. MapViewer lets you specify an arbitrary URL to a background image, through the bgimage attribute of a map request. Construct a valid GetMap request to a WMS server, and use it as the value of the bgimage attribute. MapViewer will then display the result map as its background. For example:

<map_requesttitle="MapViewer + WMS"datasource = "wms"bgimage="http://foo.com/cgi-bin/wmserv.exe?

REQUEST=GetMap&map=cntryBound.map&LAYERS=world&VERSION=1.1.0&BBOX=-125,35,-105,45&WIDTH=640&HEIGHT=320&FORMAT=image/png"

width="640"height="320"format="PNG_STREAM">

<box srsName="SDO:8265"><coordinates>-125,35,-105,45</coordinates>

</box><themes><theme name="world"/><theme name="highways"/><theme name="bigcities"/>


Here bgimage is pointing to a result map returned from the external wms server. Note that you must escape the '&' char in the wms request to '&'.

MapViewer does not support transparent map layers from external wms servers. This will likely be supported in a future version of MapViewer.

16. Can MapViewer display a theme based on a view?

Yes. When defining a theme that is based on a view, you will first need to register the view's geometry column in user_sdo_geom_metadata. Use the view name as the table_name value when inserting into user_sdo_geom_metadata. If your view is a join view (based on more than one base tables), you must also manually modify the theme's styling_rules to specify a key_column attribute. This attribute tells MapViewer the name of the column in the view that can serve as the id column for the geometries. By default, a predefined theme will use ROWID as the key column when caching/referencing geometries for that theme. With a join view however there is no ROWID. Here is an example of such a theme's styling_rules:

update user_sdo_themes set styling_rules='<?xml version="1.0" standalone="yes"?><styling_rules key_column="gid"><rule>

<features style="L.PH" /><label column="label" style="M.SHIELD1">1</label>

</rule></styling_rules>' where name='MY_VIEW_BASED_THEME1';

17. How do I place a text label at a specific point on the map, without drawing the point itself?

The trick here is to use a color style that is completely transparent as the rendering style for the point. When that color style is used to render the point, it will be invisible. The text label will still be rendered however, using the text style that is specified for the feature.

For instance, here is how to manually create a transparent color style:

insert into user_sdo_styles values ('C.TRANSPARENT','COLOR', 'Transparent Color',

'<?xml version="1.0" standalone="yes"?><svg width="1in" height="1in"><desc></desc><g class="color" style="stroke:#cccccc;stroke-

opacity:0;fill:#cccccc;fill-opacity:0"><rect width="50" height="50"/></g>

</svg>', null, null) ;

Development

1. Can MapViewer generate HTML image maps automatically?

Starting with 10.1.2, yes. You can now ask MapViewer to generate HTML image map tags for a point or polygon theme, which when displayed in an HTML page will have "hot" areas that you can define custom actions for or have info-tips displayed in a pop-up window. Note that this approach is more generic than the SVG-based approach mentioned here, as it works on most browsers and platforms.

To see HTML image maps in action, you can try the mapinit.jsp demo from MapViewer's Welcome page, and then choose "Image with dynamic info" option. After a map has been displayed, you can then select a theme to be "clickable" and submit a new request. The next displayed map will have accompanying html image map areas that interact with your mouse cursor movement. The following is a screenshot of this demo in action. Note here the Counties theme is clickable and has associated HTML image areas.

Browse the jsp file name dmap.jsp in the MapViewer's demo directory for details on how this is achieved.

Essentially you need to send a separate SVG fragment map request, for which the server responds with an SVG document containing generalized coordinates for the requested themes. You then call the Java client API's getThemeAsHTMLAreas() method to obtain the HTML image areas for a theme. Then just append the image areas tags in your final HTML page.

2. Can I access MapViewer functions from a C|C++|Perl|PL/SQL program?

Yes you can, although you will have to manually construct every map request and process every map response your program received from MapViewer server. MapViewer server communicates using the standard HTTP protocol. The map request and response are encoded in XML, whose DTD is documented in the MapViewer User's Guide. As a result, as long as your program can open a URL connection and send/receive data using HTTP Post, it can then talk to MapViewer.

For example, in the MapViewer User's Guide, Section 3.1.9, there is a program written in PL/SQL that shows how to connect to a MapViewer service and issue a map request, then process and output the result map image URL, all while running inside an Oracle database.

3. How can I add the MapViewer JSP tags to Oracle JDeveloper's Component Palette?

The MapViewer ear file contains an JDeveloper extension kit used to add JSP MapViewer tags to its component palette. This provides an intuitive interface for

using the tags when developing MapViewer applications using JSPs in JDeveloper.

The one-time process is simple. First, locate two files in the unpacked MapViewer directory: mvpalette.jar under the directory jdevext/, and the mvclient.jar under the directory web/WEB-INF/lib. Then copy these two files to the extension directory of JDeveloper, usually $JDEV_HOME/jdev/lib/ext. Now restart JDeveloper, and you are all set. The following shows the component palette with the added MapViewer JSP tags in JDeveloper.

4. How do I view the mapping metadata through JDeveloper's Connections Navigator?

We have developed an Oracle JDeveloper extension that lets you browse the available list of styles, themes and basemaps defined in a datasource through JDeveloper's Connections Navigator. To do this, first download the mvconnection.jar file from OTN's MapViewer site. This jar contains code that defines a MapViewer connection type for JDeveloper. To install, drop this jar file to the JDeveloper extension directory, usually $JDEV_HOME/jdev/lib/ext. Now restart JDeveloper, and you are all set.

To define a new MapViewer connection (which establishes a HTTP connection to the MapViewer server instance), simply right click the "Connections" root node in the JDev Connections Navigator, and choose "New MapViewer Connection..." to start the wizard. Note that you should always use "/mapviewer/omserver" as the Server URL in step 1 of the wizard. Once you have such a connection defined, you can browse the names of the available styles, predefined themes and basemaps from any datasource of the MapViewer server. The following is an example screenshot of the Connections extension.

5. I have just changed the definitions of some (styles/themes/basemaps). Why is MapViewer not showing the changes?

This is most likely because you have not refreshed the mapping metadata cache of MapViewer. To force MapViewer to reload the definitions for any cached styles/themes/basemaps, issue a clear cache request from the MapViewer home page. The sample form can be found under the title "Managing caches - Clear cached style/theme/basemap definitions in a data source: ".

6. How do I disable certain themes from being cached?

In general, MapViewer will cache the spatial data (geometries) of a predefined theme as it is being viewed by the client. This, however, may cause a problem if you or someone is also editing that theme's geometries, since MapViewer will always render them using their cached version. For such cases, you may disable the caching of the predefined theme by setting its caching mode to "NONE". This can be achieved by manually updating the styling rules of the predefined theme in the user_sdo_themes view, as illustrated below:

SQL> update USER_SDO_THEMES set styling_rules =

'<?xml version="1.0" standalone="yes"?>

<styling_rules caching="NONE">

<rule>

<features style="C.FUNNY COLOR">

</features>

<label column="name" style="T.RED STREET">

1

</label>

</rule>

</styling_rules>'

where name='MY_THEME1'

Note that dynamic themes (or JDBC themes) are NEVER cached.

7. How do I create a map with pie charts?

The overall process, as with any thematic mapping in MapViewer, is to first create an advanced style that will be applied to individual features. The second step is to create a theme that will make use of the advanced style. Finally (optional), you may create a basemap that includes such a theme. Once these steps are done, you can then issue map requests just you would for a "normal" map. Below are the detailed instructions for each step.

1. First you need to create an Advanced style that defines the "template" of pie-charts to be used. Here is an example showing how to manually create such a style:

SQL> insert into USER_SDO_STYLES values(

'V.PIECHART1', 'ADVANCED', null,

'<?xml version="1.0" ?>

<AdvancedStyle>

<PieChartStyle pieradius="10">

<PieSlice name="A" color="#ffff00" />

<PieSlice name="B" color="#000000" />

<PieSlice name="H" color="#ff00ff" />

<PieSlice name="I" color="#0000ff" />

<PieSlice name="W" color="#ffffff" />

</PieChartStyle>

</AdvancedStyle>', null, null);

Note that the above style, when applied to a geographic feature, will create a pie-chart with 5 slices. Each slice can have its own color defined as in the above example. Each slice also has a name attribute which is ignored by MapViewer in this release.

The overall size of the pie charts when displayed on a map can be specified using the pieradius attribute. In this example it is set to a radius of 10 pixels. The radius unit is always pixel.

2. Create a new theme that takes advantage of the newly defined PieChart style. Here is an example showing how to manually insert the new theme definition:

insert into user_sdo_themes values(

'THEME_PIE_CHART', null, 'COUNTIES', 'GEOM',


<styling_rules >

<rule column="asian,black,hispanic,indian,white" >

<features style="C.RED"> </features>

<label column="''dummy''" style="V.PIECHART1"> 1 </label>

</rule>

</styling_rules>');

First note the pie chart style name "V.PIECHART1" is specified in the <label> element of the theme's styling rule. This is because you are really using the Pie charts to label each associated geometry. Note that the column="''dummy''" attribute in the <label> element is necessary although it has no effect on the resulting map. The literal string dummy (or any other string you choose) is just a placeholder. In this example it is enclosed by two single qutoes at both ends because in Oracle SQL you have to escape single-quote ' with ''. Caution: If you do not specify a column attribute in the <label> element, the theme will not be labeled at all, which means no pie-charts will show up in the map.

Also note that since the piechart style defined above has 5 slices, you must specify 5 columns to supply the value for each slice. The column list here is specified in the <rule> element, which in the above example is:

column="asian,black,hispanic,indian,white"

Note that the base table of the theme must have these five columns defined. The columns must have numeric datatypes.

3. Issue a map request that uses the new theme. For instance:


<map_request datasource = "mvdemo"

format="PNG_STREAM">

<themes>

<theme name="THEME_PIE_CHART" />

</themes>

</map_request>

4. Hopefully, you will see a map with "baby" pie charts all over it.

8. How do I dynamically add a style from my application?

MapViewer 10g (9.0.4) supports adding all types of styles dynamically through the MapViewer client API (oracle.lbs.mapclient.MapViewer).

o You can dynamically create and add color/marker/area/line/text styles to a running MapViewer server's style cache from the MapViewer client Java API. Specifically you will be calling such method as addColorStyle(...) of oracle.lbs.mapclient.MapViewer.

o For advanced styles, you can now also dynamically create them (for instance color schemes with dynamic low/high ranges) and add them to the MapViewer server's style cache. Consult the MapViewer client API JavaDoc for corresponding methods.

A few notes on dynamically added styles. (applies only to 9.0.4!)

o Styles added dynamically through oracle.lbs.mapclient.MapViewer reside only in the corresponding MapViewer's in-memory style cache. If the admin clears the MapViewer's metadata cache it will remove all dynamic styles. Also if the MapViewer server is restarted then all such styles will be gone.

o When such a style is added, it is available to all map renderers regardless of which datasource they are connecting to. In other words, the styles added dynamically by one client are shared among all map renderers and thus all clients.

o It is a good practice to name your dynamic styles using a unique naming scheme (such as based on the current session id). Also, make sure you delete the dynamically added styles once your session ends or when the styles are no longer needed.

Note: Starting with MapViewer 10.1.2, the behaviour regarding dynamically added styles have changed in the server side. The main change is that in 10.1.2, the server no longer keeps the dynamic styles beyond the current map request. Dynamic styles added using the MapViewer client bean are created only temporarily in the server that processes the request. After the request is done, all the dynamic styles are discarded from the server.

Note however your client bean still holds the definitions of those dynamically added styles; so when you issue a new request that reuses those styles, you do not need to call the various add*Style() methods again. Whenever your client bean sends a map request, any dynamic styles that you added up to that time will have their xml definitions appended to the end of the XML map request and sent to the server.

This change is necessary in order for dynamic styles to work across multiple backend mapviewer servers. See the related issue here. An added benefit is that you no longer need to worry about naming conflicts between styles dynamically added in multiple sessions. Each dynamic style is visible to the server only in the context of a single map request.

9. How do I ensure that certain features ALWAYS get labeled on the map?

Normally MapViewer labels features based on first come first serve basis. As a result, a feature may not always be labeled if its label text will overlap with other features' labels or markers that have already been drawn on the result map. Sometimes, however, it is required that certain "high-priority" features be always labeled. This is now possible with MapViewer. Here are the options.

o For dynamic geofeatures added through the MapViewer java API, specify the labelAlwaysOn flag to true when calling methods such as addPointFeature() or addLinearFeature().

o To always label all the features of a theme added through the MapViewer java API, call the setLabelAlwaysOn() method.

o If you construct the XML map request manually, you can specify the label_always_on attribute to true for any <theme> element, as well as for any <geoFeature> elements.

10. How do I use an Advanced Style in a JDBC theme?

Advanced styles always need some attributes in order to be properly applied to a spatial feature. These attributes must be in the SELECT list of the SQL query in a JDBC theme. Note that a JDBC theme's sql query may also select a label column (whose name must be explicitly specified in the same JDBC theme element) to provide the label text for each geometry. As a rule of thumb, MapViewer treats any selected column that is neither a geometry column nor a label column as an attribute column. The order among the geoemtry column, label column and the attribute column(s) are not important. However, the order among the attribute columns themselves is important, as that will be the order in which the advanced style consumes their values.

Example. Assuming we have defined an advanced style that is a pie chart style named V.PIECHART2 (see this question for more information), which will draw 3 pie slices representing the percentage of the number of trainers, sales and service personnel. So this style, when applied to a feature, will require 3 attribute values representing the number of trainers, sales and services workers, in that order. Now let's look at a JDBC theme definition, specifically its SQL query:

<theme name="support_center">

<jdbc_query spatial_column="geom" datasource="tilsmenv"label_column="dummy_col",label_style="V.PIECHART2">

SELECT geom, 'dummy' dummy_col, training, sales,service

FROM support_centers</jdbc_query>

</theme>

11. How do I dynamically generate a map legend in its own image?

When issuing a map request that contains only a legend spec with no drawable map data (not specifying any basemap/themes/features), MapViewer will generate a map image that contains only the map legend. You can then get the URL of this legend image and show the legend somewhere in your web application external to the map images generated. This is more efficient than embedding a legend in every generated map.

The following code illustrates how to dynamically create a legend spec and send it to MapViewer for rendering.

import oracle.lbs.mapclient.MapViewer;...mapViewer = new

MapViewer("http://my_corp.com:7777/mapviewer/omserver");mapViewer.setImageFormat(MapViewer.FORMAT_PNG_URL);

String [][][]legenddata = new String[1][][]; // legend with onecolumn

legenddata[0] = new String[8][]; // column with 8 itemsfor(int i=0;ilegenddata[0][0][0] = "Map Legend"; // textlegenddata[0][0][2] = "true"; // is title

//legenddata[0][1][0] = "center point"; // textlegenddata[0][1][1] = "M.STAR"; // style

//legenddata[0][2][0] = "cities"; // textlegenddata[0][2][1] = "M.CITY HALL"; // style

//legenddata[0][3][4] = "true"; // is separator

//legenddata[0][4][0] = "state boundary"; // textlegenddata[0][4][1] = "C.ROSY BROWN STROKE"; // style

//legenddata[0][5][0] = "interstate highway"; // textlegenddata[0][5][1] = "L.PH"; // style

//legenddata[0][6][0] = "County population:"; // text

//legenddata[0][7][1] = "V.POP DENSITY"; // stylelegenddata[0][7][3] = "1"; // tab

mapViewer.setMapLegend("#ffffff","255","#ff0000","MEDIUM","NORTH_EAST",legenddata);

try{boolean res = mapViewer.run();if(res){

System.out.println("legend image is saved at: "+mapViewer.getGeneratedMapImageURL());

}}catch(Exception ex){}

Note that behind the scene, the MapViewer client API code quietly creates an XML legend spec and sends it to the MapViewer server for rendering. It is also possible to forumate your own XML legend spec (the DTD of which is specified in the MapViewer User's Guide), and call the client API's setMapLegend(String xmlLegend) method with the XML legend string. For instance:

String legend = "<legend bgstyle=\"fill:#ffffff;fill-opacity:128;stroke:#ff0000\" "+

"profile=\"medium\" position=\"SOUTH_WEST\">\n"+"<column>\n"+"<entry text=\"Legend:\" is_title=\"true\" />\n"+"<entry style=\"M.STAR\" text=\"center point\" />\n"+"<entry style=\"M.CITY HALL 3\" text=\"cities\" />\n"+"<entry style=\"M.CITY HALL 4\" text=\"big cities\" />\n"+"<entry is_separator=\"true\" />\n"+"<entry style=\"C.ROSY BROWN STROKE\" text=\"state

boundary\" />\n "+"<entry style=\"L.PH\" text=\"interstate highway\" />\n"+"<entry text=\"County population density:\" />\n"+"<entry style=\"V.POP DENSITY\" tab=\"1\" />\n"+

"</column>\n"+"</legend>\n";

mapViewer.setMapLegend(legend);

Finally, it is also possible to set the xml map legend through the MapViewer JSP tag, as illustrated in the demo code tagmap.jsp that comes with your MapViewer install.

12. Can I use MapViewer with Oracle UIX pages?

Yes. In fact MapViewer 10g (9.0.4) ships with a demo that is built using UIX and the MapViewer JSP taglib. Here is a brief description of the demo (assuming you have deployed MapViewer in a standalone OC4J instance).

The demo shows how one can use UIX JSP tags and MapViewer JSP tags together to build a web application. It is identical in scope and content to tagmap.jsp.

Files required. The jsp files are mapadminuixtags.jsp and mappageuixtags.jsp. The help files that correspond to these are helpmapadmin.uix and helpmapnav.uix. They are located in the $MAPVIEWER_HOME/web/demo direcotry.

Prerequisites. The demo requires UIX 2.2.1 or later. This must be installed in your OC4J instance.

There are a few other requirements.

o The uix.tld file should be placed in $MAPVIEWER_HOME/web/WEB-INF and the web.xml file in this directory should be modified to include the following lines.

o

o 

o <servlet>

o <servlet-name>uix</servlet-name>

oo 

o <servlet-class>oracle.cabo.servlet.UIXServlet</servlet-class>

oo 

o <init-param>

o <param-name>oracle.cabo.servlet.pageBroker</param-name>

o <param-value>oracle.cabo.servlet.xml.UIXPageBroker</param-value>

o </init-param>

oo </servlet>

oo 

o <servlet-mapping>


o <url-pattern>/uix/*</url-pattern>

o </servlet-mapping>

oo <servlet-mapping>


o <url-pattern>*.uix</url-pattern>

o </servlet-mapping>

o The resource files for uix must be placed in $MAPVIEWER_HOME/web. That is unzip uix2-install.zip in $MAPVIEWER_HOME/web. All the resource files will then be in the directory named $MAPVIEWER_HOME/web/cabo

Running the demo. Use mapadminuixtags.jsp as the starting page. That is, use http://<hostname>[:port]/mapviewer/demo/mapadminuixtags.jsp and supply the requested parameters. If you wish to use mappageuixtags.jsp directly then modify the hard coded parameters in it.

13. What are the values of the "matrix" attribute in an xml map response's <xfm> element?

The matrix values are the parameters for an AffineTransform that you can use to convert a screen coordinate (such as user's mouse click position on the returned map image) back to the coordinate in user's data space.

To make use of this transformation, simply parse the space separated values into a floating point array and then construct a Java AffineTransform object from the array, as shown here:

double[] params = new double[6];// ... parse the values in the matrix attribute and save them in

params[]// ... in the order they are listed.AffineTransform xfm = new AffineTransform(params);

Note that this transformation is automatically handled for you if you are using the Java API (the oracle.lbs.mapclient.MapViewer class). It is recommended that you use the Java API, since in the future the XML response syntax may change.

14. Can MapViewer generate maps with a transparent background?

Starting with 10.1.2, yes. MapViewer can now generate PNG maps with a transparent background. Specifically, you must specify the map format to be either "PNG_*" or "PNG8_*", and set the "transparent" attribute to be true in your map request.

<map_requesttitle="a transparent layer/map"datasource="tilsmenv"bgcolor="#a6caf0"transparent="true"antialiase="true"mapfilename="tilsct12_vec_marker"format="PNG_URL">

When PNG8_* format is specified, MapViewer generates 8-bit indexed PNG images, whereas PNG_* results in 24-bit PNG images. Note that MapViewer supports only palette based transparency in all PNG maps it generates. Specifically, the background color provided in your map request is the color that made completely transparent in the result map. Alpha based transparency in the result map image is not supported. Also be aware that there is a known issue with IE which fails to display 24-bit transparent PNG images.

15. Can MapViewer display versioned spatial data in a workspace?

Yes, support for Oracle workspace manager (WM) is added in MapViewer 10.1.2. For any theme (predefined or dynamic) whose base table is version enabled, you can view its latest modifications in any workspace (and save point within that workspace) by specifying the workspace name (and optionally the savepoint) for the theme. For instance, here is a map request with a dynamic theme that shows the spatial data in a workspace named "ws_1".

<map_request...<themes><theme name="theme_1" workspace_name="ws_1">

<jdbc_queryspatial_column="GEOM"render_style="C.RED"jdbc_srid="8307"datasource="mvdemo"asis="false">

select GEOM,NAME from PARCELS</jdbc_query>

</theme></themes>...</map_request>

Note that if a predefined theme has its caching mode set to "ALL", then the workspace attribute will be ignored. For other predefined themes, any existing cached data will be ignored when viewing the theme through a workspace. Ideally you should set a predefined theme's caching mode to "NONE" before viewing it in a workspace. Dynamic (JDBC) themes are never cached so there is no extra concern when specifying workspace parameters.

16. How to display spatial data stored in another schema?

Prior to version 10.1.2, the only way to view spatial data stored in a user B's schema from user A is by granting select permission on B's tables to A, then create views in schema A, and populate its user_sdo_geom_metadata with metadata for those views. You can then create themes for these views and display them from MapViewer.

Starting with version 10.1.2, you have two more options. One is to define public synonyms for tables in schema B, and then populate A's user_sdo_geom_metadata view for those synonyms, similar to the above view-based approach.

Another option is to simply create themes in schema B, define a new data source for schema B. Then you can import B's themes in any MapRequest as long as you specify the proper data source name for them. In fact this approach lets you integrate spatial data from as many schemas as you want.

17. How to bound a map based on the MBR of a theme or query's results?

You can use the bounding_themes element in a map request. When a map request does not specify center/size or box, but has the bounding_themes element instead, then the result map will be automatically centered/sized to optimally contain the query results of the specified "bounding" themes. For more details please refer to the MapViewer User's Guide section 3.2.2.

Note that you can set bounding themes from the MapViewer Java API as well.

Performance

1. How can I improve the overall performance of MapViewer?

The limiting factors of MapViewer performance include: cpu speed/JVM speed, JDBC speed (fetching large amounts of data from db), amount of heap memory and spatial cache allocated to MapViewer.

Always make sure you have allocated enough memory when starting the oc4j Java process. For instance, the JVM option -Xmx512M will ensure that MapViewer can obtain as much as 512 MB of heap memory when needed. Large amounts of memory are necessary if you will be rendering lots of data for certain map requests, or if you have allocated many renderers for each datasource defined.

MapViewer scales well in a multi-processor environment. On such a system MapViewer's capability to handle concurrent map requests will be dramatically improved, automatically. You can also set up a cluster of MapViewer instances to handle big workloads.

Another option is to pin frequently accessed predefined themes entirely in the memory. This can be achieved by setting the caching mode of a predefined theme to "ALL" in the theme definition. These themes will have all of their spatial and attribute data cached in memory, and no database round-trips will ever be needed when rendering such themes for any map request. To enable this option for a theme, you will need to manually (using SQL) add the caching="ALL" attribute to your theme's styling_rules column. The following shows how do update a theme definition with such a cache mode:

SQL> update USER_SDO_THEMES set styling_rules =


<styling_rules caching="ALL">

<rule>

<features style="C.FUNNY COLOR">

</features>

<label column="name" style="T.RED STREET">

1

</label>

</rule>

</styling_rules>'

where name='MY_CACHED_THEME'

Themes with no explicit cache mode set will have their spatial data cached gradually as user views different portions of it. For each request, a database query will ALWAYS be issued to retrieve the associated style/label columns as well as any non-spatial attribute columns needed.

Make sure you have a large enough spatial data cache to hold most of the frequently accessed spatial data in memory. The size of the in memory cache size is set through the following section in the mapViewerConfig.xml file:

<spatial_data_cache max_cache_size="64"

max_disk_cache_size="512"

disk_cache_path="../cache"

/>

The max_cache_size refers to the size of the in-memory spatial data cache. This is the most the crucial attribute for your MapViewer instance's performance.

To monitor the growth and size of the spatial data cache, you can add an attribute report_stats="true" to the above spatial_data_cache element. With this option on, MapViewer will periodically output a snapshot report of such information as the current cache size and number of cached objects.

Other performance considerations include: using PNG instead of GIF for the map output format; generalizing/simplifying your densely digitized geometry data for smaller scale maps; cleaning up previously generated/saved map images frequently.

2. How do I control the number of database sessions used by MapViewer?

When MapViewer renders a map, it connects to the datasource (an Oracle spatial database) to fetch any data that reside in the database. The connections are managed by the MapViewer server. For a given data source, the maximum number of connections that will be present is determined by the complexity of the map requests and how many mappers are specified for a datasource.

For instance, when requesting a map with n predefined themes, MapViewer will automatically create n connections in n threads to load the themes' data in parallel. For performance reasons, these connections are not closed at the end of the request. Rather they are placed back in a connection pool maintained by MapViewer for that data source. As such, you may observe a large number of sessions open against a particular database user after a series of concurrent complex map requests. The default maximum number of sessions that will remain open on any data source is 100.

If you must limit the number of sessions to a smaller number for a data source, you should use the max_connections attribute when defining it. Below is an example data source definition with a maximum connection number of 5. You can specify this attribute in any place a data source is defined or redefined.

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

<add_data_sourcename="mvdemo"jdbc_host="mycorp.com"jdbc_port="1521"jdbc_sid="orcl"jdbc_user="scott"jdbc_password="tiger"jdbc_mode="thin"max_connections="5"number_of_mappers="3" />

</non_map_request>

Note that in this case, there will be a maximum of 5 connections open against the data source at any given time. So what if you issue a map request with 10 predefined themes? In this case, 10 connections will still be created temporarily to meet the demand. 5 of them, however, will be closed immediately upon the completion of the request. In other words, MapViewer dynamically creates database connections in order to meet the peak demand; but the number of permanently open database connections will never exceed the value specified in "max_connections" or "number_of_mappers", whichever is greater. The latter plays a role because currently each mapper will require a dedicated database

connection during its life period (this requirement will most certainly be removed in a future version).

From the performance perspective, specifying a small max_connections number will almost certainly impact the time it takes to process a map request, mainly because opening a new database connection is a costly operation.

When you remove a datasource, any connections currently associated with it will be closed.

3. How to define a data source that connects to an Oracle RAC (Real Application Cluster) database?

MapViewer can obtain connections from its J2EE Container's data source, in this case OC4J's container datasources, which can support connection to RAC. So this is a two-step process, where you first define a container datasource in oc4j/j2ee/home/config/data-sources.xml file that connects to a RAC, and then define a MapViewer datasource that uses the container datasource.

Here is how to add a RAC datasource in OC4J's j2ee/home/config/data-sources.xml file:

<data-sourceclass="com.evermind.sql.DriverManagerDataSource"name="OracleDS"location="jdbc/OracleCoreDS"xa-location="jdbc/xa/OracleXADS"ejb-location="jdbc/OracleRacDS"connection-driver="oracle.jdbc.driver.OracleDriver"username="scott"password="tiger"url="jdbc:oracle:thin:@(DESCRIPTION =

(ADDRESS = (PROTOCOL = TCP)(HOST = dglx11.us.oracle.com)(PORT =1521))

(ADDRESS = (PROTOCOL = TCP)(HOST = dglx12.us.oracle.com)(PORT =1521))

(LOAD_BALANCE = yes)(CONNECT_DATA =

(SERVER = DEDICATED)(SERVICE_NAME = rac)

))"inactivity-timeout="300"connection-retry-interval="2"max-connect-attempts="60"max-connections="60"min-connections="10"

/>

Once you made the above definition, you need to restart OC4J to have the new datasource created. Note that its ejb-location is "jdbc/OracleRacDS", which will be used in defining a MapViewer datasource. For details about this step please see the answer to this question.

Known Issues in version 9.0.4

1. Using dynamic styles across two MapViewer server instances

When creating dynamic styles using the Java client API, if the MapViewer server is deployed and running on an OC4J instance with more than one OC4J processes (JVMs), the styles may not be available on all MapViewer server processes. For instance, when the client first issues a request to create a dynamic Ranged Bucket style, that request may be routed by the load balancer to the OC4J process A, and the style is created only inside the MapViewer server running in that process. Now if the client then issues a map request that uses the newly created style, and if that request is being routed to oc4j process B, then the map generated will be incorrect since there is no such style in process B.

This issue is fixed in 10.1.2. The workaround for 9.0.4 will be to limit the OC4J process number to 1 (the default).

2. View-based themes with identical key_column values

There is a bug in MapViewer 9.0.4 that will mistakenly treat geometries associated with one theme as if they are from another theme, and result in incorrect maps. This bug will appear only when ALL of the following conditions are met:

- Your map request involves 2 or more themes that are based onJoin or Union-All views.

- For each of these themes, you enabled caching and explicitlyspecified a "key_column".

- The underlying views of these themes have the same set ofkey_column values.

The simplest workaround is to append the theme name (or any unique string among themes) to the "key_column" in a theme's definition. For instance, if you previously had the following styling_rules definition for a theme named "MY_PARCEL":

<?xml version="1.0" standalone="yes"?><styling_rules key_column="OBJECTID"><rule><features style="C.DARKGREEN"> </features>


where the column named "OBJECTID" is serving as the key column. You may now want to change it to:

<?xml version="1.0" standalone="yes"?><styling_rules key_column="OBJECTID||''MY_PARCEL''"><rule><features style="C.DARKGREEN"> </features>


The values serving as keys will now be the values from the OBJECTID column with the string "MY_PARCEL" appended to them.

Or, you can simply disable the caching for the themes involved. Please see this question for how to do that.

MapViewer FAQ - Oracle€¦ · Once you have installed the Quick Start kit, you should download the...

Documents

Transcript of MapViewer FAQ - Oracle€¦ · Once you have installed the Quick Start kit, you should download the...