MapViewer Technical FAQ

©2003 Oracle

Introduction

1. What is MapViewer?

   MapViewer is a rendering service for geospatial data managed in Oracle Spatial. It is a component of Oracle Application Server, which first started including MapViewer in the 9.0.2 version of 9iAS. MapViewer is a pure Java J2EE component written for the Oracle Container for J2EE (OC4J).

2. What are the prerequistes for using MapViewer?

   Since MapViewer draws data only from an Oracle database, you will need access to an Oracle Database with at least version 8i (8.1.6). Since MapViewer is a J2EE web service, you will also need have access to an Oracle Application Server 9i (9.0.2) or later. It's also possible to simply install a stand alone version of Oracle Container for J2EE (OC4J) and deploy MapViewer inside it.

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

   MDT is undegoing extensive rewriting so that it can fully support all the functionalities currently available in the MapViewer server. Since the re-write has not completed yet, we as a temporary measure are still providing the first beta version of MDT (the one you currently are using) for download from OTN. But in reality, this MDT lacked sufficient quality-control and full support of MapViewer, and as such it was 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 standard and enterprise editiion. For development purposes, you may download the MapViewer kit from Oracle Tech Net (otn.oracle.com). It is listed under the Oracle Spatial section (otn.oracle.com/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 also be downloaded from the same download page where the MapViewer kit is located.

2. 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 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.

3. How do I specify the admin user/password for MapViewer after deploying it to 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. Here we see that there are no existing security user or group to use. So we will need to add a user for MapViewer.

   Step 3. Here we provide the name and password for the new security user. Be sure to remeber this password.

   Step 4. Now that we have created a new security user, we need to map this user to MapViewer's built-in security role "map_admin_role".

   Step 5. We simply choose the newly created user to be mapped to the "map_admin_role".

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

4. What's the easiest way to get started?

   MapViewer can be deployed and run with the standalone version of OC4J, which can be downloaded from otn.oracle.com for development purposes. The steps are:

   • Download latest oc4j_extended.zip file from otn.oracle.com.
   • Unzip oc4j_extended.zip into a directory, for example c:\oc4j.
   • cd into c:\oc4j\j2ee\home\, then type java -jar oc4j.jar -install
   • Assuming you already have a copy of the mapviewer.ear file (the J2EE applicaiton file of MapViewer), you may now refer to the MapViewer User's Guide, Section 1.4.2, which describes how to modify the configuration file in oc4j to deploy this MapViewer file.
   • Restart oc4j.
   • Go to the MapViewer home page, which is usually at http://host:8888/mapviewer, where host is the host name of your machine, and have fun!

5. What's the MapViewer Home Page?

   Throughout this FAQ, you will come across references to the MapViewer home page. The MapViewer home page 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 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 forms for administrative purposes, as well as for submitting xml Map Requests. It also hosts several on-line demos that you can study with.

   It is usally a good idea 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 is determined based on whether you deployed MapViewer in a standalone OC4J or a full Oracle Application Server install.

   • 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.
   • If MapViewer is deployed in a full Oracle Application Server: You must have created an admin user in the OC4J instance where MapViewer is running, as specified in the answer to this question.
   
   

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

   On Redhat Linux Enterprise version, it seems that there is a login issue when running MapViewer with a standalone installation of OC4J (9.0.4). Mainly it's 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.

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:

           <?xml version="1.0" standalone="yes"?>
           <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 with this release.

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

   No. MapViewer works only with spatial data stored in Oracle Spatial.

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 clear-text password when it reads in the data source definition for the first time. Here is an example datasource definition that can be 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 MapViewer display spatial data in different projections?

   No. All the spatial data to be visualized by MapViewer must be in the same spatial reference system (SRS). If your data comes from different sources and they use different SRS's, you can use Oracle Spatial's coordinate system functions to transform them into a single reference system for viewing purposes. It is possible that in a future release of MapViewer, we will allow maps to be generated from themes in different SRS's.

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

8. 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.

         <?xml version="1.0" standalone="yes"?>
          <styling_rules>
            <rule>
              <features style="L.POOR_ROADS" asis="true">
                 select sdo_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
                            where sdo_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.

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

   It's very simple with MapViewer's built-in Azimuthal Equal Distance projection. Basically, 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 on-the-fly 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:

   • 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.
   • 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.
   • 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 proejcted.
   • 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).

Development

1. 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.

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

   The MapViewer ear file contains an JDeveloper extension kit that can be used to add the JSP MapViewer tags to its component palette, which provides an intuitive interface for using the tags when developing MapViewer applications using JSP.

   The one-time process is very 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 simply copy these two files to the extension directory of JDeveloper, normally $JDEV_HOME/jdev/lib/ext. Then restart JDeveloper, and you are all set. The following shows the component palette with the added MapViewer JSP tags in JDeveloper.

   

3. 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, you will first need to download the mvconnection.jar file from OTN's MapViewer site. This jar contains the code that defines a MapViewer connection type for JDeveloper. To install, simply drop this jar file to the JDeveloper extension directory, normally $JDEV_HOME/jdev/lib/ext. Then 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 basemap from any datasource of the MapViewer server. The following is an example screenshot of the Connections extension.

   

4. 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 ask MapViewer to reload the definitons for any cached styles/themes/basemaps, you can issue a non-map 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: ".

5. 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.

6. 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 will be 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 have 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', 
       '<?xml version="1.0" standalone="yes"?>
       <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 not effect on the resulting map. The literal string dummy (or any other string you choose) is just a place holder. 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:

     <?xml version="1.0" standalone="yes"?>
     <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.

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

   • 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.
   • 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.

   • Styles added dynamically through oracle.lbs.mapclient.MapViewer resides 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 MapViewer server were restarted then all such styles will be gone.
   • When 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.
   • It is a good practice to name your dynamic styles in 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.

8. 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.

   • For dynamic geofeatures added through the MapViewer java API, specify the labelAlwaysOn flag to true when calling methods such as addPointFeature() or addLinearFeature().
   • To always label all the features of a theme added through the MapViewer java API, call the setLabelAlwaysOn() method.
   • 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.

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

   Advanced styles always needs some attributes in order to be porperly applied to a spatial feature. These attributes must be in the SELECT list of the SQL query that is 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 labeling 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 attriebute 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, specificaly 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>
   
       

10. 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 effecient 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 one column
        legenddata[0] = new String[8][];    // column with 8 items
        for(int i=0;i<8;i++)
        {
          legenddata[0][i] = new String[5];   // description of each item
          legenddata[0][i][0] = null;      // text
          legenddata[0][i][1] = null;      // style
          legenddata[0][i][2] = "false";   // is title
          legenddata[0][i][3] = null;      // tab
          legenddata[0][i][4] = "false";   // is separator
        }
        
        // 
        legenddata[0][0][0] = "Map Legend"; // text
        legenddata[0][0][2] = "true";       // is title
        
        // 
        legenddata[0][1][0] = "center point";  // text
        legenddata[0][1][1] = "M.STAR";        // style
        
        // 
        legenddata[0][2][0] = "cities";        // text
        legenddata[0][2][1] = "M.CITY HALL";   // style
        
        // 
        legenddata[0][3][4] = "true";          // is separator
        
        // 
        legenddata[0][4][0] = "state boundary";         // text
        legenddata[0][4][1] = "C.ROSY BROWN STROKE";    // style
        
        // 
        legenddata[0][5][0] = "interstate highway";    // text
        legenddata[0][5][1] = "L.PH";                  // style
        
        // 
        legenddata[0][6][0] = "County population:";    // text
        
        // 
        legenddata[0][7][1] = "V.POP DENSITY";  // style
        legenddata[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.

11. 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.
    

    • 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.

        <!-- Define the Servlet for the UIX web application -->
        <servlet>
          <servlet-name>uix</servlet-name>
      
          <!-- Specify the Servlet class -->
          <servlet-class>oracle.cabo.servlet.UIXServlet</servlet-class>
      
          <!-- Specify the PageBroker -->
          <init-param>
            <param-name>oracle.cabo.servlet.pageBroker</param-name>
            <param-value>oracle.cabo.servlet.xml.UIXPageBroker</param-value>
          </init-param>
      
        </servlet>
      
        <!-- Define mappings for uix files -->
        <servlet-mapping>
          <servlet-name>uix</servlet-name>
          <url-pattern>/uix/*</url-pattern>
        </servlet-mapping>
      
        <servlet-mapping>
          <servlet-name>uix</servlet-name>
          <url-pattern>*.uix</url-pattern>
        </servlet-mapping>
      

    • 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.

12. What are the values of the "matrix" attribute in a map request'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 usre'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.

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 memeory. 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 = 
               '<?xml version="1.0" standalone="yes"?>
               <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 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_source 
                   name="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.

Last Modified: 2003/11