Oracle MapViewer

Finding sales offices within a certain distance of a customer

2011-09-21T22:04:00.004-04:00

In this post lets do a simple demo that shows all the customers (from the MVDEMO's customers table) on the map. Now, when you click on a customer marker, I want to display all the cities that are within 50 miles radius of the customer. I mentioned sales office in the title to make it sound more interesting, but our small MVDEMO sample data set does not have such a table, so we will use the readily available cities table instead.

Basically, we want to run a query like following when you click on any given customer marker:

select city, state_abrv, location from cities
where sdo_within_distance(location,
sdo_geometry(2001, 8307, sdo_point_type(:1, :2, null), null, null),
:3)='TRUE';

And display the query result as a new theme on the map. Note the three binding parameters in the above query. The first two should be the longitude and latitude of the customer location. The 3rd parameter is a Oracle Spatial WITHIN_DISTANCE operator parameter, typically in the form of 'distance=50 unit=mile'. So a properly bound query looks like this (you can execute it in the mvdemo schema).

select city, state_abrv, location from cities
where sdo_within_distance(location,
sdo_geometry(2001, 8307, sdo_point_type(-122, 37.5, null), null, null),
'distance=50 unit=mile')='TRUE';

We could use a dynamic-query based theme to display the above query result. But, ever mindful of safety and efficiency, we will instead create a pre-defined theme in the mvdemo schema. The trick is to add a query condition that contains these binding variables and disable the default (window-based) spatial filter for the new theme. Below is a screenshot of such a theme (cities_near_customer) and its query condition:

Now that we have the theme defined, we can work on the actual demo itself. The demo page source is found below. Just copy and paste it into an html file, save it in your web server where MapViewer is deployed, and you are all set (assuming the usual mvdemo datasource exists in the MapViewer instance).



<html>
<head>
<META http-equiv="Content-Type" content="text/html" charset=UTF-8">
<TITLE>Map Cache Server/Map Client</TITLE>
<link rel="stylesheet" type="text/css" href="../t.css" />
<script language="Javascript" src="/mapviewer/fsmc/jslib/oraclemaps.js"></script>

<script language=javascript>
  var mapview;
  var nearestCitiesTheme;
  
  function showMap() 
  { 
    var baseURL  = "http://"+document.location.host+"/mapviewer";
    var mapCenterLon = -122.45;
    var mapCenterLat =  37.7706;
    var mapZoom      =  3;       
    var mpoint = MVSdoGeometry.createPoint(mapCenterLon,mapCenterLat,8307);
    mapview = new MVMapView(document.getElementById("map"), baseURL);
    mapview.addMapTileLayer(new MVMapTileLayer("mvdemo.demo_map"));   
    mapview.setCenter(mpoint);   
    mapview.setZoomLevel(mapZoom);    
    
    var customersTheme = new MVThemeBasedFOI('themebasedfoi1','mvdemo.customers') ;
    
    customersTheme.setBringToTopOnMouseOver(true);
    
    customersTheme.attachEventListener(MVEvent.MOUSE_CLICK, foiClick);
    mapview.addThemeBasedFOI(customersTheme);
                      
    mapview.display();
  }     

  function foiClick(pointOfClick,foi)
  {
    alert("Locating all cities within 50 mile radius.");
    
    if(nearestCitiesTheme)
    {
        mapview.removeThemeBasedFOI(nearestCitiesTheme);
    }
    
    nearestCitiesTheme = new MVThemeBasedFOI('cities-theme', 'mvdemo.cities_near_customer');
    
    //set the binding variable for this theme.
    var x = foi.x;  // :1
    var y = foi.y;  // :2
    var distanceParam = "distance=50 unit=mile";  // :3
    
    nearestCitiesTheme.setQueryParameters(x,y, distanceParam);      
    
    nearestCitiesTheme.setBringToTopOnMouseOver(true);
    mapview.addThemeBasedFOI(nearestCitiesTheme);
  }
</script>
</head>

<body onload="javascript:showMap()">
<h3>Oracle Maps example - finding cities closest to a customer </h3>
   <div id="map" style="left:0px; top:10px;width:100%; height:60%"></div> 

</body>

</html>

The main things I want to point out here are:

1. It uses a mouse-click listener on the customers theme, so that we can do the magic when user clicks on a customer marker.

2. in the mouse click function (foiClick), we create a new theme-based FOI layer for the cities_near_customers theme. Then we set the 3 binding variables this theme's query condition is expecting, using setQueryParameters().

3. In the demo I want to find out all the cities that are within 50 mile distance of a customer; you can easily use a different distance by changing the value of the distanceParam variable above.

That's all for this post.

-LJ

iOS support in Oracle Maps API

2011-07-25T10:55:00.002-04:00

With the latest patch release (version11.1.1.5.1 found here ), MapViewer's Oracle Maps JavaScript API now fully supports iPhone/iPad map interaction using touch events such as pinch to zoom out, double tap to zoom in and other general touch events. Your existing application will automatically get these support once you upgrade to the 11.1.1.5.1 version of MapViewer's oraclemaps.js lib.

In addition to the iOS support, we are also looking into Android support in the future.

Deploying MapViewer on IBM WebSphere 7

2011-07-18T19:28:00.010-04:00

I just finished deploying MapViewer (the 11.1.1.5.1 patch release found here ) on IBM WebSphere 7, using the main steps outlined below. Overall I would say it is just a typical process of deploying any J2EE enterprise applications on WebSphere.

1. Log into WebSphere console, and pick the server instance to deploy MapViewer.

2. Start deploying MapViewer by creating a new enterprise application.

3. Download and save the mapviewer.ear file to your local file system if not already done so. Then select this EAR file when prompted. You do not need to unpack this .ear file.

4. Go through the necessary steps by accepting all the defaults as instructed, but note the following special instructions.

At step 7 "Map context roots for web modules", make sure the context root is set to "/mapviewer".

Then at Step 8 "Map security roles to users or groups", make sure the admin user (virtuser in my case) is mapped to the map_admin_role defined by MapViewer. You can ignore the secure_maps_role which is for demo purpose only. Alternatively, you can also map other WebSphere users/groups to this map_admin_role. Later you will use the mapped user or group to log into MapViewer's Admin page.

5. You should get a summery page like below at the end of the deployment steps.

Now save the configuration and finish the deployment process. You should see MapViewer in the applications list, as illustrated below.

6. Next, you need to find where WebSphere stores the mapviewer.ear's unpacked contents. The easiest way to do so, is to start MapViewer and log in to its admin page (by clicking on the Admin button from the home page at /mapviewer). Click the Management tab, then Configuration. Near the top of the page, you will see a line indicating where the mapViewerConfig.xml file was loaded from. In my case, it is:

/opt/IBM/WebSphere/AppServer/profiles/AppSrv01/installedApps/AppSrv01_Cell01/OracleAS MapViewer.ear/web.war/WEB-INF/conf/mapViewerConfig.xml

This tells us that WebSphere has expanded the mapviewer.ear file into the directory:

/opt/IBM/WebSphere/AppServer/profiles/AppSrv01/installedApps/AppSrv01_Cell01/OracleAS MapViewer.ear/.

7. Now, we need to modify MapViewer's libraries in order for it to work properly in WebSphere 7.

8. Go to MapViewer's web.war/WEB-INF/lib folder, and physically remove the two jars: jsf-api.jar and jsf-impl.jar. This ensures all MapViewer web pages (which are written in JSF 1.0) work properly in WebSphere, since WebSphere already comes with a set of JSF 1.2 jars, and we don't want our (older) JSF jar files to conflict with these.

9. From your Oracle 11g database install, copy the two JDBC driver related jars, ojdbc5.jar and orai18n.jar, and put them in MapViewer's web.war/WEB-INF/lib folder. Alternatively, you can download these two jars from Oracle's JDBC OTN web page. I used version 11.2.0.2 jars, but earlier versions of these jars should work too.

10. Now, go to WebSphere console and restart the MapViewer application.

From this point on, you will just need to perform typical MapViewer configuration tasks such as adding a new data source et al.

Final note, if before performing step 8 above (where you removed the two jsf jars), you already tried visiting some of the MapViwer pages, then it is likely you will have seen errors related to JSP exceptions. What you need to do (after performing step 8), is go to MapViewer's web.war folder, and touch every .jspx file so that their last modified timestamp gets changed. Do the same for the .jspx files under web.war/admin folder too. This will force WebSphere to re-compile all the .jspx files (using the JSF 1.2 jars that came with WebSphere).

Sending command-line admin requests to MapViewer

2010-10-08T10:12:00.004-04:00

As you already know, MapViewer has several web pages where you can (after logging in) perform various admin tasks using XML requests. These tasks range from managing mapviewer's metadata cache, data sources, to tile layer pre-fetching.

Sometimes one may have the need to perform these tasks from a command line or script. This is especially helpful if you need to automate certain aspects of managing a MapViewer instance (such as periodically clearing its tile layer cache or metadata cache).

A while back we uploaded a simple tool that enables just that. If you are interested, please go to MapViewer's download page on OTN:

http://www.oracle.com/technetwork/middleware/mapviewer/downloads/index.html

and look for the Oracle Fusion Middleware MapViewer Admin Tool. It comes with a detailed readme describing how to use this tool to send admin requests to MapViewer server from a command line or from a script.

Basically this tool allows you to specify the user name and password for the MapViewer admin URLs, and a XML document containing the admin request itself. It will then authenticate to the MapViewer and post the request doc to the server for processing.

MapViewer performance tuning tips - part 4

2010-09-14T12:08:00.006-04:00

In this post we will discuss best practices that deal with overall MapViewer deployment and configuration. We will also briefly touch base on how to monitor a running MapViewer instance to find troubling themes.

Deployment and Configuration

MapViewer is a J2EE application that runs in all modern J2EE containers. Deploying MapViewer is no different from deploying other J2EE applications.

Ideally MapViewer should be deployed to a dedicated JVM. In Oracle iAS world, this will be a dedicated OC4J instance, and in the WebLogic Server (WLS) world, this will be a dedicated server in a domain.

The reason is simple, MapViewer, while having a small foot print itself, often requires large amount of memory and CPU resources at run time depending on the work load. So it is best to deploy MapViewer to a JVM instance that runs only MapViewer (and minimum amount of other J2EE supporting services), so that unnecessary contentions or even interruptions with other applications can be minimized. It will also be easier to monitor MapViewer's performance when it is the only application running in the JVM.

Note however there is nothing inherently wrong to deploy and run MapViewer with other J2EE applications in a shared JVM.

JVM heap size

One of the key factors that will affect mapViewer performance is the amount of Heap memory allocated to the JVM. A minimum of 512 MB is recommended. On 32 bit operating systems, the maxium heap memory should not exceed 1.5GB (or 1500 MB). A typical MapViewer install will run happily with 1GB of heap memory.

You set heap memory via JVM's -Xmx option.

Another important memory allocation parameter is the young generation size within the JVM. Young generation is a pool of memory reserved for short-lived objects. A typical map request will result in MapViewer creating many such objects (for instance, to represent geographic features in memory), so a sufficiently large young generation within the heap is crucial in preventing the JVM spending too much time on garbage collection.

The young generation size can be set via the JVM parameter:
-XX:newSize=80M
and
-XX:maxNewSize=200M

The first parameter specifies a starting young generation size of 80MB, while the second parameter indicates a maximum young generation size of 200M.

Typically the young generation size should not be more than 10 to 20 percent of the total heap size.

Spatial data cache
MapViewer lets you optionally configure an in-memory geometry data cache via the "spatial_data_cache" tag in mapViewerConfig.xml. This cache is used to buffer geometry features generated for themes whose caching mode is either set to ALL or NORMAL. (Note that you set a theme's caching mode in Map Builder's theme editor, in the Advanced tab).

When a theme's caching mode is set to ALL, MapViewer will load all of its features upon first request, and store the data in the cache. It also creates an in-memory R-Tree index on the features. All subsequent requests for this theme will be satisfied out of this cache, with no trips to the database.

When a theme's caching mode is set to NORMAL, MapViewer will store the theme's features as they are loaded. Note that MapViewer still queries the database every time such a theme is requested, but, in the event a feature is already in the cache, the un-marshaling or parsing of the database formatted geometry object is skipped, and the corresponding Java geometry object is reused out of the cache.

Our recommendation regarding theme caching, is to use caching mode ALL for small amount of themes that are based on small to medium sized tables (with couple hundred to tens of thousands of features) with static contents. And turn off NORMAL caching for all other themes. In other words, a pre-defined geometry theme should have its cache mode set to either NONE or (in rare cases) ALL.

The reason we do not recommend using the NORMAL caching mode is that it does not save much resource or time, in fact, it makes memory usage go up without much benefit at all. We could even argue that if too many theme features are cached the JVM may start doing more and more garbage collections which can adversely affect performance.

It is especially important to turn themes' caching off (by setting caching mode to NONE) before you start a tile pre-fetching task. During a tile prefetching, large amount of map requests will be sent to the MapViewer, and any cached geometries will soon become out dated, or rather, out of the region of interest.

Alternatively, prior to a large tile prefetching task, you can simply set the spatial data cache's max_cache_size to 0, which then automatically disables the caching of any theme's features.

We recommend the spatial_data_cache to have a max size of no more than 200MB (on a 32 bit OS), or 15 percent of total heap memory. In fact, we often found a performance boost by simply turning this cache off (setting its max size to zero)!

Note that when you have themes with caching mode ALL, mapViewer may not be able to fit all of its data in the cache, in which case it automatically switches the theme's cache mode to NORMAL (which as we mentioned earlier is not very ideal). So you need to carefully monitor any exception or error messages in the MapViewer log files to see if it failed to load all the data for themes with caching mode ALL. In the event this happens, you should simply set the theme's cache mode to NONE.

Note further that this internal memory cache will likely undergo major changes in MapViewer 11g R2 to truly boost performance.

Monitoring theme processing time
When you notice a slow map response time, the first thing you do is open the URL /mapviewer/admin.html, and check for slow themes.

This URL is only available in MapViewer version 11g R1 and later. It will require admin log in. Once logged in, you will see the Top Theme Queries text field, which you can submit to check which theme(s) are taking the most time to process. This can be very useful in quickly catching themes that are taking too long to return data from the database (indicating either a database performance issue, or a badly defined theme), or are returning too many rows/features, or both.

You can use the Reset Top Theme Queries form to wipe out existing top theme statistics, and MapViewer will automatically start collecting new stats for future map requests. This is useful if you have made changes to some themes and want to see if they are still the top (bad) themes.

You can also use the same URL to check the status of your MapViewer, such as how many active DB connections/sessions are being used currently.

new public APIs for GeoCoding & Routing

2010-05-19T15:26:00.003-04:00

Some of you probably already know or are using various XML APIs to interact with our hosted LBS service at elocation.oracle.com. These XML APIs can be used to geocode your street addresses and get driving directions between two addresses, and also to get maps.

Recently we have published a new set of simple JavaScript APIs for geocoding and routing. These APIs, or rather JavaScript libraries, are hosted on the same public elocation.oracle.com server, and are very easy to use from your HTML/AJAX applications.

You can find more details about the new GeoCoding and Routing APIs in a presentation given during the Oracle Spatial User Conference held in Phoneix, Arizona last month. Please download the presentation here:

http://download.oracle.com/otndocs/products/spatial/pdf/osuc2010_presentations/osuc2010_geocoder_sravada.pdf

The presentation itself actually covers a lot of ground on Spatial's geocoding and routing capabilities. The new JS APIs and sample codes start from page 78.

For more presentations on both Spatial and MapViewer from this user conference (which was a smashing success), visit here:
http://www.oracle.com/technology/products/spatial/htdocs/spatial_conf_1004_idx.html

Out of memory when pre-fetching tiles on Linux?

2010-03-25T14:20:00.002-04:00

If you suspect that your MapViewer instance is having memory related issues when pre-fetching large number of map tiles for a tile layer, and your OS is Linux, then maybe this tip will help you.

Basically on Linux, the underlying file system itself will often aggressively use memory to cache file handles et al. When you start a large tile pre-fetching task, it is not uncommon for MapViewer to create hundreds of thousands of files (map tile images) in a short period. If the OS keeps caching these file system related "things" in memory, sooner or later your system will experience memory shortages, and this may cause MapViewer instance's JVM to crash or throw OutOfMemory exceptions.

Fortunately there is an easy workaround (thanks to Ji who found and tested it). All you (or your system admin) need to do is execute the following shell command as root:

#> sync; echo 3 > /proc/sys/vm/drop_caches

This command will force the Linux kernel to release file system related caches. It is best to run this script periodically (by using a cron job) like every 3 hours.

MapViewer performance tuning tips - part 3

2010-02-03T14:24:00.018-05:00

Middletier (MapViewer) side of things

Lets now look at various factors within MapViewer itself that may affect overall performance. There are also settings in the J2EE container level that can affect both performance and scalability, which we will also touch upon later.

Types of map requests

In order to properly tune MapViewer performance and size your hardware for deployment, you need to first understand where and how MapViewer spends its resources. Because MapViewer resources are primarily spent on processing map requests, it is critical to understand the types of requests that MapViewer may receive.

XML map request

The most basic type of request is simply a single XML document containing a complete map request posted to a MapViewer server’s URL directly. In this request doc, you can specify a base map, one or more additional themes (pre-defined or dynamic), a map query window, and a response format, among many other things. When MapViewer receives such a request, it breaks down the basemap (if specified) into a list of composing themes, and then adds those additional themes to form a final theme list. It then queries and fetches data for all the themes on the list, rendering their data into one or more images. The result images are either directly streamed back to the client, or saved to the disk (in which case it is the URLs to the saved image files that are sent back to the client).

WMS requests

MapViewer can also act as a WMS (Web Mapping Service) server. When it receives an incoming WMS request, the request is first converted into an XML map request, followed by the same workflow as if the client had just sent the XML request directly.

Oracle Maps requests

With the Oracle Maps JavaScript API, a typical “map” displayed by your application is often composed of one or more map tile layers, plus one or more Feature Of Interest (FOI) layers. Whenever such a map is displayed or refreshed, the Mapviewer server will receive one FOI request for each visible FOI layer, plus multiple map tile image requests.

For each FOI request, you can think of it as a simplified XML map request containing just a single theme. Once the features of this theme are loaded, MapViewer can either render them into individual FOI images (one small image for each feature), or combine all the features into a single image equal to the size of the application map window (when the whole-image option is enabled on the FOI layer).

For each map tile request, if the tile (an image file stored on the server) does not already exist, MapViewer will need to generate it on the fly, by issuing itself an XML map request that contains just the name of the base map of the tile layer. The query window of this XML map request will be the data coverage area for this particular tile. The normal workflow then follows, and the result image is always stored to a specific folder on the server. It then serves this tile image file to the client.

Note that once a map tile is generated and saved, all subsequent requests to that tile can be fulfilled extremely quickly, because MapViewer no longer needs to process/render it. Serving 100s of tile images per second is a typical performance. Whether your browser can load and display that many images quickly enough however is another matter and depends on such factors as your network connection speed.

Because on the fly rendering of map tiles is expensive, you should consider tile pre-fetching by issuing an admin request to MapViewer when it is not under load (or on a non-production server). When MapViewer receives a pre-fetching request, it simply issues many concurrent map tile requests to itself, which are basically XML map requests as mentioned earlier.

JavaBean API requests

If your application uses the JavaBean API of MapViewer, what happens is that as soon as you call oracle.lbs.mapclient.MapViewer’s run, pan or zoom method, it will construct a XML request document based on the information you have provided (name of basemap, themes you added, et al), and send it to the MapViewer server for processing.

In the end it's all XML

So as you can see, no matter which API your application uses, all that the MapViewer rendering engine sees are XML map request docs. From now on we will shorten the verbose “XML map request doc” to just “map request”. Note that client side map actions (clicking, zooming, panning et al) may or may not result in a map request to the server. And sometimes one action on the client side may even lead to multiple map requests (such as when zooming an Oracle Maps map with multiple visible FOI layers).

While the structure of MapViewer’s XML map request document can be very complex (the DTD for which can be found in the MapViewer User Guide), for simplicity we can think of it simply as a flat list of themes that MapViewer needs to process. Sometimes this list contains just one theme, and yet other times it may contain dozens or even hundreds of themes.

Given the above understanding, let’s now look at how MapViewer processes the themes for a single map request.

Rendering themes of a map request

When MapViewer processes a theme, it begins by issuing a query to the database to load the data for that theme (for Spatial based themes anyway). This query typically contains a spatial filter so that it only fetches data within the current viewing window. In the first two posts we have already covered how to speed up this phase by reducing the database time.

Note that the rendering phase does not actually start until all the themes’ loading phases have completed. In other words, if your map request contains 10 themes, the rendering phase will not start until all 10 themes have finished loading their data from the database. In other words, all the data for all the themes will be held in memory until the map request itself is completed. This is why it is important to consciously limit the number of features MapViewer might load for any given theme. When a map request is completed (the final image rendered and saved or streamed back to the client), then all the loaded theme data and temporary shapes et al. are released from memory.

During the actual rendering process, MapViewer iterates through all the loaded features of each theme, converting each geometry object from its raw database format into a Java representation when necessary, followed by the creation of a Java2D shape or point. Any necessary viewport transformation is also carried out at this stage.

If a theme requires text annotation, then the labeling process occurs after all the themes have completed the shape-rendering phase. Note that rendering follows the order of themes as they are listed in the map request, but for labeling the order is actually reversed. In other words, the last theme in the list is always labeled first.

To summarize, the total time (excluding the database time) MapViewer spends on processing a single map request is affected by the following factors, roughly in decreasing order of significance:

The number of features loaded by each theme, and total number of features loaded.
The cost of rendering and labeling a single feature; this is in turn dictated by how complex each rendering and labeling style is, how detailed (in terms of number of vertices) are the geometries on average, et al.
The raw speed of the server’s disk, CPU and memory access
Whether anti-aliasing is requested
The amount of heap memory allocated to MapViewer
The version of JDK being used

Note that the first item (number of total features loaded) also has the biggest impact on MapViewer’s memory usage.

While understanding how MapViewer works on a single map request certainly helps, in a real world scenario your MapViewer instance is often flooded with many concurrent map requests initiated by a variety of applications and clients using different APIs. In order to improve the scalability of MapViewer and properly size its hardware platform, one needs to understand how MapViewer handles concurrent map requests. This is discussed next.

Database sessions, number of mappers and concurrent map requests

Prior to MapViewer version 10.1.3.3, themes in a single map request load their data in parallel. In other words, if a map request is composed of 10 themes, then 10 database connections are obtained right off the bat, each executing the query of one theme. This “liberal” usage of database sessions often leads to scalability issues while providing marginal if any performance gain.

Starting with MapViewer version 10.1.3.3, SQL execution of themes’ queries are carried out in a serial fashion within each map request. A theme cannot start loading its data until the theme before it in the list has finished its query execution and data loading. The end result is that only one database connection is ever needed when processing a map request, no matter how many themes may be involved.

For a given data source, the maximum number of concurrent map requests MapViewer will accept is determined by the number of mappers specified for that data source. In other words, if a data source’s number_of_mapper attribute is set to 10 (in the MapViewer config file), then a maximum of 10 concurrent map requests can be processed (for that data source) at any given time. Because each map request will use one database connection, there can be a maximum of 10 active database sessions for the data source schema. When the 11th map request arrives it must wait in the queue until a free mapper becomes available.

You may recall that in MapViewer’s data source definition, there is also a max_connection parameter. Starting with version 10.1.3.3, this parameter is no longer needed actually. This is because the maximum number of connections out there for a given data source is always bound by the number_of_mapper parameter.

Understanding the above, you may come to the conclusion that in order to increase the scalability you simply increase the number of mappers specified for a data source. The problem is that as you increase this number, you are also increasing the number of potential concurrent database sessions, the memory usage inside MapViewer and the amount of raw data it needs to push through its rendering pipeline. Finally, if you have multiple data sources defined, then the total concurrent map requests that can potentially arrive at the MapViewer is the sum of all the data sources' maximum concurrent requests.

In the end, it is difficult to provide a clear-cut formula for determining what level of hardware you will need for your MapViewer instances. For instance, to determine roughly how much heap memory you need to allocate to a MapViewer instance, you need to look through each defined data source, finding out the average number of features each theme will load into memory and their geometric complexity, the number of themes in a typical map request, and the maximum concurrent map requests you wish to sustain. You also need to factor in things such as the in-memory geometry cache which are permanent. The best approach is to simply perform load tests against your application and monitor various logs and stats from your database and MapViewer instances to see if they are being saturated.

In the next post we will dig in further and provide a number of practical tips on tuning MapViewer performance.

MapViewer performance tuning tips - part 2

2010-01-14T16:25:00.012-05:00

This is the second post of the performance tuning tips series.

Finding bottlenecks in your Oracle database

When you identify a theme with an unusually high "database time", it's time to look for database fixes. While typical database query optimization tips and tricks still apply, spatial queries have some unique characteristics, especially when the base table of your 'troubling' theme contains a large number of rows.
From my own observations over the years, in many cases the "database time" of a MapViewer theme is actually database idle time or wait time. To be more specific, it is time the database spent waiting on disk I/Os. This is probably nothing shocking given that many MapViewer theme queries can fetch a lot of data in terms of pure volume (as measured in total bytes), especially when polygon or polyline type geometries are involved. Compared with a theme query, your typical shopping cart query that fetches a product listing is almost negligible as far as result data volume is concerned. With a huge base table, chances are the database buffer cannot easily cache all the data, so it often needs to read physical disk blocks in order to fetch and return data for a query.

When diagnosing database bottlenecks such as disk I/O waits , there are two powerful tools that come with Oracle database 10g and later versions. They are AWR (Advanced Workload Repository) and ADDM (Automated Database Diagnostic Monitor). I found them invaluable in finding out why your MapViewer application is running slow, as they can not only identify I/O bottlenecks, but also many other kind of bottlenecks in the database. Note however they do not replace other tuning tools such SQL Tuning Adviser. In fact ADDM will often suggest you run SQL Tuning Adviser on specific SQL queries it deemed problematic.

Let's jump right into action already. The following are the basic steps of using these two tools.

Step 1 Login as DBA, then create a "before" snapshot of the database:
SQL> exec dbms_workload_repository.create_snapshot;

Step 2 Run your MapViewer application load tests. When done,

Step 3 Create an "after" snapshot of the database, using the same command:
SQL> exec dbms_workload_repository.create_snapshot;

With these two snapshots, you can now execute the AWR and ADDM scripts to generate very informative and detailed reports on what happened inside the database during these two snapshots. Keep in mind that the stats gathered by AWR and ADDM cover all database activities for all sessions, not just sessions created by MapViewer to perform theme queries.

Step 4 Generate an AWR report.
To create an AWR report, execute the following as DBA:

SQL> @$ORACLE_HOME/rdbms/admin/awrrpti.sql

When prompted, use HTML as the report format, and pick the two snapshots that you just created.

After exiting SQL*Plus, you will see an HTML file containing the AWR report. Open it in your browser, and you will be greeted with a rich set of database activity reports.
One of the interesting tables is titled "Top 5 Timed Foreground Events". For instance, this is the result from a recent AWR report generated for my spatial database:

As you can see, it shows that the database spent a whopping 96.55% of time waiting for User I/Os (db file sequential reads) ! You can also check out several other tables such as "SQL ordered by Elapsed Time" and "SQL ordered by User I/O Wait Time" et al. It is also quite easy to find out which SQL is causing the most User I/Os, so on and so forth. Of course, your report may not show user I/O as an issue, but you get the idea.

While AWR is very useful in providing you with a detailed break down of the database events and timings, it is best complemented by the adviser tool, ADDM, which reads off the same set of stats between the two snapshots, but can provide you with concrete advices on how to fix the bottlenecks in your database.

Step 5 Generate an ADDM report.

While you can always use EM to view the ADDM report, here we just want to generate a simple text report using SQL*Plus by running the following command as DBA:

SQL> @$ORACLE_HOME/rdbms/admin/addmrpt.sql;

Again this script will prompt you for the before and after snapshots' IDs. Then it generates a .lst file which you can open with any text editor. In this text report you can find some very insightful suggestions. For instance, in one of my reports it detected that the disk containing the database data file of a large theme's base table has a below-average I/O speed, and suggested file striping as one way to reduce I/O waits. This is exactly the kind of advices that can immediately provide a performance boost.

While I have been stressing the negative impact of heavy user I/Os, please note that your situation may very well be a different one. For instance you may not have an I/O bottleneck at all, so please be open minded when reading these two reports and be prepared to wrestle with other kind of issues within your database.

Reorganizing your large tables

Let's say you indeed find yourself in a similar situation where you see a lot of User I/O wait events, especially on your large tables (those with hundreds of thousands or millions of rows). Then how do you tackle this issue? One of the most obvious remedies is to partition both your data tables and associated spatial indexes, if they are not already partitioned.

The other tip, which will be described in detail now, is to reorganize the table rows based on the proximity of the geometry column. The basic idea is to store rows in neighboring database blocks if their geometries are close to each other spatially. When stored this way, rows that are to be returned for a theme query will more likely be found in neighboring data blocks on the disk, thus significantly reducing disk reads. This re-org will help most spatial queries with predicates such as SDO_FILTER or SDO_RELATE. MapViewer for instance always uses SDO_FILTER for normal map panning/zooming and WMS type map requests, thus can benefit from such a table wide re-org, sometimes tremendously.

Lets first see what happens if you do not reorganize your table. Lets say each disk block has capacity for 100 rows. In a ‘uniform but random storage’ case, for any given query window, each "hit" block may only have 10 rows that are within this window. Now lets say a particular map request’s query window interacts with 1000 rows according to the spatial index. Assuming the table is so big and the incoming query windows change so often that the database data buffer is basically useless. What the database will end up doing then is reading 100 blocks from the disk in order to fetch these 1000 rows based on their ROWIDs produced by the spatial index. Reading so many blocks for a single query is very expensive. Now imagine 20 concurrent incoming map requests, each having a different viewport, and you can easily imagine why the database spends majority of its time waiting for disk reads. As a result, the overall throughput of MapViewer plummets.

Script for Reorganizing a large table

So how do you reorganize row storage? The following script is actually documented in the “Pro Oracle Spatial for Oracle Database 11g” book, Chapter 16. It uses a linear tessellation key to re-order the geometries stored in a table. For those of you don’t have access to this book, here are the (slightly modified to fix several typos in the book) scripts you can copy and use.

First, create a package in the MDSYS schema (it won't work in any other database schema!) :

CREATE OR REPLACE PACKAGE clusterit
AS

FUNCTION linear_key(location sdo_geometry, diminfo sdo_dim_array)
RETURN RAW deterministic;
END;
/

CREATE OR REPLACE PACKAGE BODY clusterit
AS
FUNCTION linear_key
(
location sdo_geometry,
diminfo sdo_dim_array
)
return RAW deterministic
AS
ctr sdo_geometry;
rval raw(48);
lvl integer;
BEGIN
ctr := sdo_geom.sdo_pointonsurface(location, diminfo);
lvl := 8;
rval:=
MD.HHENCODE(
ctr.sdo_point.x, diminfo(1).sdo_lb, diminfo(1).sdo_ub, lvl,
ctr.sdo_point.y, diminfo(2).sdo_lb, diminfo(2).sdo_ub, lvl);
return rval;
END;

END;
/

Next, log into the proper schema, and make a backup copy of the problem base table ‘my_table’ (drop its spatial index first):

SQL> rename my_table to my_table_dup;

Add a linear key column:

SQL> alter table my_table_dup add (linear_key raw);

Then pre-compute and store the linear keys:

SQL> update my_table_dup a set linear_key =
mdsys.clusterit.linear_key(a.geometry,
(select diminfo from user_sdo_geom_metadata where table_name='MY_TABLE’ and column_name='GEOMETRY'));

Finally, re-create the original table with proper storage order:

SQL> create table my_table as select * from my_table_dup where rownum <1;
SQL> insert into my_table select * from my_table_dup order by linear_key;
SQL> commit;
SQL> drop table my_table_dup;

Don’t forget to recreate the spatial index on my_table.

Now re-run your MapViewer tests and see if this reorganization has helped its overall performance. In one internal and not so rigorous experiment, after reorganizing a large table using the above approach, we observed as much as 300% increase in overall MapViewer throughput.

In summary, AWR and ADDM are two of the more useful tools at your disposal when diagnosing high database times, and pay special attention to excessive database reads. This blog also assumes that your typical MapViewer theme is a pre-defined geometry theme with relatively simple query conditions. If your theme uses super complex dynamic SQL queries, then chances are you have more than disk reads to worry about. In any case, database tuning in general, and Spatial SQL tuning in particular, is a very deep topic in itself, and I'm really in no position to offer any authoritative advice; so please don't blame me if my little tip above did not actually reduce your database time :)

MapViewer performance tuning tips - Part 1

2010-01-13T22:31:00.006-05:00

This is the first of a series of blogs on MapViewer performance tuning.

Overview

When your MapViewer application performs poorly, there are many possible causes. Maybe your application is trying to (unnecessarily) display way too many features on a map or layer. Maybe your database query (for dynamic themes) is too complicated and poorly optimized. Or maybe the database is doing too many disk I/Os when fetching the result set for a theme. It could also be due to a poorly configured MapViewer in-memory cache, an overwhelmed J2EE container (overloaded with many other applications), or just a very slow middle-tier box. It could be all of the above. The symptom however is always the same: when a user clicks on the map to pan or zoom, she will wait a long time before the map completely refreshes itself.

So how to find the true bottleneck? Where do you start when diagnosing a slow mapping application? The short answer, is to first identify the most time consuming theme(s) in your application, by looking at the log file.

To do so set MapViewer's logging to the "finest" level, restart MapViewer, and run the application just long enough (or manually submit a single XML map request) to generate some meaningful logs. When scanning the freshly created MapViewer log file, for each theme you should see several log records like the following:

FINER: [ THEME_DEMO_HIGHWAYS ] sql exec time: 585ms, total time loading 8 features: 2679ms.
FINER: time to render theme THEME_DEMO_HIGHWAYS with 8 styled features: 72ms
FINER: time to label theme THEME_DEMO_HIGHWAYS with 8 styled features: 112ms

In the first log record, pay special attention to the last number, 2679ms. This number (in milliseconds) indicates how long it took the database to execute the theme query, fetch result rows from data blocks, and transmit the result set over the network to MapViewer. For simplicity we will call this the "database time". Likewise let's call the combined rendering and labeling time indicated by the second and third log records the "MapViewer time"; after all that is how long MapViewer actually spent doing something useful instead of just waiting for and receiving data from the database.

In many cases, the database time will be the dominant one, so you will need to poke around the database and speed things up there. We will get into it later.

If the MapViewer time is high, we will need to find out why. One recommended approach is to run a CPU profiling of the MapViewer instance. Again we will provide more details in a later post.

Reducing these two types of time will have a positive impact on your application's performance regardless of which MapViewer API you are using.

Note that starting with MapViewer 11g R1 there is another way to easily spot themes with excessive "database time". To do so you must first log in as the MapViewer
admin user. Then manually open the /mapviewer/admin.html page in your browser. You will see a "Top theme queries" text area with a Submit button underneath it. Click on the submit button to see a list of top (database) time-consuming queries. It's a good idea to first click the "Reset top theme queries" button so that MapViewer clears any existing list of themes and starts gathering fresh stats for you.

Sometimes you may find that all of your themes are loaded and rendered quickly, but your application still takes a long time to display the map. Let's simply call this the "user time", since it is the time a user spent staring at a spinning clock or progress bar. When the sum of the "database time" and "MapViewer time" accounts for only a small portion of the "user time", we suggest you use a FireFox addon called "FireBug" to find out what exactly is happening on the wire and in your browser. For instance, is your Oracle Maps application overwhelming the remote web server with too many HTTP requests for map tile and FOI images? Maybe you should look into using the Whole-Image option for your FOI layer(s) to avoid transmitting many small pieces from MapViewer to the client every time a user pans or zooms the map. We will provide more tips like this in a later blog as well.

To be continued...

MapViewer 11g patch 1 (11.1.1.2) available

2010-01-06T17:56:00.002-05:00

We are pleased to announce the first patch of MapViewer 11g R1 release. This patch, officially versioned 11.1.1.2, includes many bug fixes and incremental enhancements.

Please download the new patch here.

The release notes can be found here.

Use Mapviewer to cache WMS maps as map tiles

2009-11-12T10:13:00.005-05:00

Warning: Not all map services providers(WMS included) allow their maps to be cached by others. Before using MapViewer to cache maps served by any third party map services provider, you should consult the map services provider to make sure you're allowed to cache their maps.

With the use of map source adapter, you can let MapViewer cache maps rendered by an external map services provider as map tiles and use them in your Oracle Maps application.

A map source adapter is basically a Java class that is called by MapViewer to construct requests understood by the external map services provider. MapViewer calls the map source adapter to construct map requests, send them to the map services provider, fetch the maps and cache them as map tiles. Mapviewer is shipped with a map source adapter for WMS, which you can use to cache maps served by a WMS server. To better understand how the map source adapter works, you can take a look at the source code of the WMS adapter, which can be found at $mapviewer_deploy_home/web/WEB-INF/tileserver/mvadapter/mcsadapter/WMSAdapter.java.

Here are the steps to create a map tile layer using the WMS adapter.

1. Login MapViewer's web admin page.

2. Enter the tile layer creation interface. Choose "External" when being asked for the the type of map source.

3. On the tile layer creation page, you need to provide the configuration information for the map tile layer. Besides regular tile layer configuration options such as name, data source, coordinate system, zoom level definition and etc, you also need to provide the following information specific to an external map tile layer.

Map service URL: The URL of the external map services provider. In the case of WMS, it should be the URL of the WMS server, e.g. http://www.myhost.com/mywms.
Adapter class: The path of the WMS adapter class. It should be mcsadapter.WMSAdapter.
Jar file location: the full path of the file mvadapter.jar, which is under $mapviewer_deploy_home/web/WEB-INF/tileserver/mvadapter.
Check "Adapter properties".
Add WMS parameters(name and value) for your map requests. Example:


    name         value
    -----------  -----
    version      1.1.1
    srs          EPSG:4326
    layers       Countries,Borders
    format       image/png 
    transparent  true

4. Click "Submit" to create the tile layer.

Google maps tiles in a MapViewer app

2009-10-22T10:06:00.003-04:00

Earlier this year I posted an article on how to display MapViewer generated tiles in a Google Maps application. In this post I will discuss how to display Google Maps tiles in a MapViewer/Oracle Maps application.

Starting with MapViewer 11g Release 1, a built-in Google Maps tile layer class has been added to the MapViewer's JavaScript API. It is called MVGoogleTileLayer. Unfortunately it is not officially documented for 11g Release 1 (but will be in the upcoming patch and future releases).

This API class is a thin wrapper of the official Google Maps API, and as such you will need to get your own Google Maps key for your application.

The basic steps for displaying Google Maps in your Oracle Maps application are:

Step 1. Import the Google Maps JavaScript library

<script src="http://maps.google.com/maps?file=api&v=2&key=[your-Google-Maps-API-key]"
type="text/javascript"></script>

Again you will need to get your own Google Maps key from Google and set it in the above script tag.

Step 2. Add a Google Maps tile layer to the MVMapView object

mapview = new MVMapView(document.getElementById("map"), baseURL);
baseMap = new MVGoogleTileLayer() ;
mapview.addMapTileLayer(baseMap);

That's all it takes to display a basic Google Maps map in your MapViewer application.

You can also change the type of map you get from Google Maps. Here is an example:

var mapType = G_HYBRID_MAP;
basemap.setMapType(mapType) ;

Where basemap is a MVGoogleTileLayer instance. Note that G_HYBRID_MAP is a constant defined by the imported Google Maps API library and represents a hybrid Google Maps type. The full description for this method is:

setMapType(mapType)
This method sets the type of the map, which can be one of the following predefined Google Map types, G_NORMAL_MAP, G_SATELLITE_MAP, G_HYBRID_MAP and G_PHYSICAL_MAP.

The only other method defined on the MVGoogleTileLayer class is getMapType(), which returns the current map type of the Google Maps being displayed.

Finally, as part of your application cleanup, please call Google Maps' clean-up method GUnload() (such as in the HTML page's unload event listener).

displaying table of longitude and latitude points

2009-10-05T10:35:00.007-04:00

While in most cases your location data are stored in an Oracle database as SDO_GEOMETRY type, sometimes you may have certain point data stored simply as two numeric columns in a table (as longitude/latitude for instance). So how can you display these points using MapViewer? In this article I will present one of the more elegant options, namely using function-based index.

The overall steps are:
1. Create a database function that returns a SDO_GEOMETRY object from two numeric values.

2. Treat this function as a SDO_GEOMETRY column by creating an entry in the USER_SDO_GEOM_METADATA view.

3. Create a Spatial index on this function

4. Create a pre-defined theme in Map Builder for this function.

5. Profit.

Lets say we have an existing table CITIES in the schema SCOTT.

SQL> desc cities;
Name Null? Type
------------------------------- -------- ----------------------------
ID NUMBER
NAME VARCHAR2(100)
ALIASE VARCHAR2(500)
COUNTR VARCHAR2(100)
POP NUMBER
LON NUMBER
LAT NUMBER

Where the two columns LON and LAT represent each city's location.

So the first step is to create a function that generates an actual SDO_GEOMETRY object when supplied with a pair of (lon, lat).

Step 1. Create function

Execute the following while logged in as SCOTT:

create or replace function get_geometry(lon in number,
lat in number)
return SDO_GEOMETRY deterministic is
begin
return sdo_geometry(2001, 8307, sdo_point_type(lon, lat, NULL),NULL, NULL);
end;
/

Note that the function must be deterministic.

Step 2. Populate Spatial metadata view

Now that we have a function, we need to make Spatial and MapViewer treat it as if it's a real SDO_GEOMETRY column. All we need to do is insert an entry for this function in the USER_SDO_GEOM_METADATA view. Again execute the following as SCOTT:

insert into user_sdo_geom_metadata values('CITIES',
'scott.get_geometry(lon,lat)',
sdo_dim_array(
sdo_dim_element('Longitude', -180, 180, 0.005),
sdo_dim_element('Latitude', -90, 90, 0.005)),
8307);

commit;

Step 3. Create a Spatial index:
We now need to create a Spatial index on the function, just like with any SDO_GEOMETRY columns. Without a Spatial index, your SQL spatial queries won't work, and MapViewer cannot display them easily.

create index CITIES_SDX on
CITIES(get_geometry(lon,lat))
indextype is mdsys.spatial_index;

Step 4. Create a Map Builder theme

Open Map Builder, click Show Data to open the data navigator. You should find the CITIES table under the user SCOTT. Right click it and choose "Create Geometry Theme". You should see that the function we just created is already picked up as the Spatial column, as illustrated in this screen shot:

Go through the normal process and complete the theme creation. You now have a pre-defined MapViewer theme that can be used to display those (X,Y) data. You can also add this theme to your AJAX map as a FoI (Feature Of Interest) layer.

Why am I getting "Request string is too long for Oracle Maps' non-AJAX remoting"?

2009-09-18T16:09:00.015-04:00

You may get this error when your application is running in a web domain that is different from the one where mapviewer is running, e.g. your application is running on hostA and your MapViewer is running on hostB. Please note that different http ports on the same host are also two different domains.

Oracle Maps client relies on AJAX to exchange data with the MapViewer server. In the scenario described above, when the client needs to send an AJAX request to the Mapviewer server, it is sending the request across domain, which is prohibited by all major web browsers. This is known as the cross-domain constraint.

We implemented our own non-AJAX remoting mechanism to overcome this so that the Oracle Maps client can talk to the MapViewer in a different domain. This workaround has one limitation - the length of the non-AJAX remoting request can not exceed certain limit. If the requests are within the limit, everything will work great. That's why in most cases Oracle Maps application works fine across domain out of box.

But things are not always that simple. If your application displays some complex theme based FOI layers, especially those with JDBC queries and/or dynamic styles, the underlying FOI requests might become too long to be handled by the non-AJAX remoting mechanism. As the result, you will get the error message mentioned in the title.

To solve this problem, you have two options.

Option 1

---------

Deploy a MapViewer to the same domain where your application is running. You don't have to configure this MapViewer to do any real mapping. You'll only need its proxy servlet, which can forward all requests from the client to the remote MapViewer that does the real mapping. The client will send all AJAX requests to the proxy servlet, which will then forward the requests to the remote MapViewer. Because the servlet is in the same domain as the application, there will be no cross-domain constraint when the client talks to the proxy.

In your application code, you need to call MVMapView.enableXMLHTTP(true) at the beginning of your showMap function.

function showMap()
{
MVMapView.enableXMLHTTP(true);
var baseURL = "http://hostB/mapviewer";

mapview = new MVMapView(mapDiv, baseURL) ;
...
}

Option 2

---------
Configure a reverse proxy in your HTTP server to forward requests sent to it to the remote MapViewer. This reverse proxy should accept requests sent to http://hostA/mapviewer/* and forward them to http://hostB/mapviewer/*. If your HTTP server is Apache, then this can be done by adding the following two lines inside mod_proxy section in httpd.conf.

ProxyRequests Off

Order deny,allow

Deny from 127.0.0.1

Allow from all

</Directory>

ProxyPass /mapviewer/ http://hostB/mapviewer/

ProxyPassReverse /mapviewer/ http://hostB/mapviewer/

</IfModule>

Your application code should act as if the MapViewer is in the local domain, because the proxy is acting as a local MapViewer instance. For better performance, you should explicitly specify the remote tile server URL when creating a tile layer. By doing so, you're telling the Oracle Maps client to get the map tiles directly from the remote MapViewer, not via the proxy, which also means better performance.

function showMap()
{

var baseURL = "http://"+document.location.host+"/mapviewer" ;
mapview = new MVMapView(mapDiv, baseURL) ;

tileLayer = new MVMapTileLayer("myds.my_map", "http://hostB/mapviewer/mcserver");

...
}

display labels with superscripts and subscripts

2009-07-31T10:37:00.003-04:00

My colleague Albert Godfrind just sent me a nice tip on how to display map labels containing subscripts and superscripts. Thought I will share it with you all.

I found the following to work for me. I create a table (using a NVARCHAR2 column for storing the label), then I populate it with two rows: one using the standard label, one using the sub/superscript notation.

create table labels (
id number,
label nvarchar2(30),
geom sdo_geometry
);

insert into labels (id, label, geom)
values (
1,
'm3 CH4 / min',
sdo_geometry (2001, null, sdo_point_type (1,1,null), null, null)
);
insert into labels (id, label, geom)
values (
2,
unistr('m\00B3 CH\2084 / min'),
sdo_geometry (2001, null, sdo_point_type (1,2,null), null, null)
);
commit;

insert into user_sdo_geom_metadata values (
'LABELS',
'GEOM',
sdo_dim_array (
sdo_dim_element ('x', 0, 100, 0.05),
sdo_dim_element ('y', 0, 100, 0.05)
),
null
);
commit;
create index labels_sx on labels (geom) indextype is mdsys.spatial_index;

Mapviewer then nicely renders the super/sub scripts as illustrated!

Java API: setting array-type binding variables for a theme

2009-07-28T15:32:00.003-04:00

MapViewer supports pre-defined themes that contain query conditions with one or more binding variables. For instance, we can define a theme COUNTIES_BY_STATES that displays all the counties whose State abbreviations are in a list supplied by user at run time.

The query condition for this theme may look like the following:

( state_abrv in (select column_value from table(:1)) )

In other words, when this theme is to be displayed, it will require a list of State abbreviations such as 'CA', 'WA', 'NY' as the value for its query's binding variable. Note that this binding variable itself requires a SQL TABLE type.

So how do you supply such an array of state abbreviation codes to the MapViewer from your Java application? The following shows the sample code that does just that.

String [] values = { "MA","NY","ME","NH" }; //list of state abbreviations
ArrayParameter states = new ArrayParameter("MV_STRINGLIST",values);
Object [] values = new Object[1]; //array containing all binding variable values
values[0] = states;
mapViewer.setThemeBindingParameters("COUNTIES_BY_STATES", values);

Note that basically you must use MapViewer's public ArrayParameter class to supply the list of states (or list of any strings/numbers) for a single table-type binding variable. Because in this case there is only one binding variable in this theme's query, the values array contains only one element, the ArrayParameter instance.

Note also MV_STRINGLIST is a SQL list/table type created by MapViewer automatically in each data source (database schema). Please check the 11g MapViewer user's guide on more information about this pre-created type.

multi-line labels

2009-07-28T15:09:00.002-04:00

MapViewer supports labels or annotations that contain a newline char (ASCII char code 10). However by default such characters are ignored by MapViewer during the map text labeling process, and the label text appears in a single line (unless there is a text wrap width specified.)

To force MapViewer to honor the newline chars in a theme's label texts, the theme must use a TEXT labeling style with the "Honor Newline" attribute set to true. This can be done from MapBuilder's TEXT style editor, by simply selecting the Honor newline check box. Now any theme that uses this TEXT style will automatically display any label text containing newline characters with multiple lines.

If your application is written using the MapViewer Java API, and you need to add individual geo-features with multi-line text labels to your map, then additional caution must be taken when constructing the label text with the newline char. Namely, the label text for a feature must be constructed like this:

String textLabel = "LINE 1" + "%26#10;" + "LINE 2";

Typically in an XML document (the Java API eventually will convert your current map request into an XML request before sending it to the MapViewer server), one uses 
 to represent the newline char(10). Because we are sending the entire map request string using HTTP POST from map client to the server, the character '&' itself must be escaped as '%26', hence the odd-looking string %26#10; representing an HTTP-safe newline character.

So this is how you can construct a new feature with this text as its label:

mapViewer.addPointFeature(centreX, centreY, 8265, "C.RED", textLabel, "MY_TEXT_STYLE",
null, null, true);

where MY_TEXT_STYLE should be a TEXT type style with "Honor newline" enabled.

MapViewer 11g R1 production kit released

2009-07-06T10:27:00.003-04:00

We are excited to announce that as part of Oracle's Fusion Middleware 11g R1 release, MapViewer 11g R1 is now available for download! Please navigate to OTN MapViewer home page here: http://www.oracle.com/technology/products/mapviewer/index.html. The 11g R1 software can be found under the Software link on the right side of the page.

Note that this release includes all the features and bug fixes of MapViewer patch 10.1.3.3 for WebLogic server, and we strongly encourage users to upgrade to the 11g R1 release to take advantage of the many new enhancements and a more stable Oracle Maps JavaScript API.

It supports not only WebLogic server (and Oracle AS/OC4J 10.1.3.x), but also Tomcat 6.x and JBoss 4.x. The full certification matrix can be found here:
http://www.oracle.com/technology/products/mapviewer/htdocs/j2ee_server_support.html

For the complete list of all the new and enchanced features of MapViewer 11g R1, please check out the New and Changed section of the MapViewer User's Guide, also downloadable from the OTN MapViewer home.

Running MapViewer on a WebLogic server cluster

2009-06-19T16:02:00.005-04:00

This post describes how to deploy and run MapViewer version 11g R1 on a basic WebLogic cluster.

For information and instructions on how to setup a simple WebLogic cluster, please check out this excellent blog post. If you followed his instructions, you will have a WebLogic domain that contains a cluster of 3 managed servers. Lets call this the main domain. You will also create a second domain that contains a load balancing servlet (HttpClusterServlet) deployed as its only web application. Lets call this the proxy domain. The main domain's managed servers will be listening on ports 7003,7004 and 7005, while the proxy domain will be listening on 7001. You will deploy MapViewer to the main domain (specifically, to its cluster which is composed of the 3 managed servers), but access MapViewer via port 7001 such as http://localhost:7001/mapviewer. Each web session accessing MapViewer will be redirected to one of the 3 managed server's in a round-robin fashion.

Load balancing servlet's web.xml
While following Andrejus' instructions, when it's about time to deploy the load balancing servlet to the proxy domain, you will need to create a web.xml file for the servlet. You can use the sample web.xml, however for MapViewer to function completely, I have attached my own web.xml below. The main difference is that in my example I added url patterns for .jspx, .png, .gif and .jpeg so these files also get redirected to the managed servers from the proxy servlet.

<!DOCTYPE web-app PUBLIC "-//Sun Microsystems, Inc.//DTD Web Application 2.3//EN" "http://java.sun.com/dtd/web-app_2_3.dtd";>

<web-app>

<servlet>
<servlet-name>HttpClusterServlet</servlet-name>
<servlet-class>
weblogic.servlet.proxy.HttpClusterServlet
</servlet-class>

<init-param>
<param-name>WebLogicCluster</param-name>
<param-value>
localhost:7003|localhost:7004|localhost:7005
</param-value>
</init-param>

</servlet>

<servlet-mapping>
<servlet-name>HttpClusterServlet</servlet-name>
<url-pattern>/mapviewer</url-pattern>
</servlet-mapping>

<servlet-mapping>
<servlet-name>HttpClusterServlet</servlet-name>
<url-pattern>*.jsp</url-pattern>
</servlet-mapping>

<servlet-mapping>
<servlet-name>HttpClusterServlet</servlet-name>
<url-pattern>*.htm</url-pattern>
</servlet-mapping>

<servlet-mapping>
<servlet-name>HttpClusterServlet</servlet-name>
<url-pattern>*.html</url-pattern>
</servlet-mapping>

<servlet-mapping>
<servlet-name>HttpClusterServlet</servlet-name>
<url-pattern>*.js</url-pattern>
</servlet-mapping>

<servlet-mapping>
<servlet-name>HttpClusterServlet</servlet-name>
<url-pattern>*.png</url-pattern>
</servlet-mapping>

<servlet-mapping>
<servlet-name>HttpClusterServlet</servlet-name>
<url-pattern>*.jspx</url-pattern>
</servlet-mapping>

<servlet-mapping>
<servlet-name>HttpClusterServlet</servlet-name>
<url-pattern>*.gif</url-pattern>
</servlet-mapping>

<servlet-mapping>
<servlet-name>HttpClusterServlet</servlet-name>
<url-pattern>*.jpeg</url-pattern>
</servlet-mapping>

</web-app>

Deploy MapViewer
Deploying MapViewer to a cluster is actually no different from deploying it to a regular WebLogic server. Basically, follow these simple steps (for more details, please check out the MapViewer User's Guide which has a step-by-step guide):

Create a WebLogic JDBC data source for your spatial database schema. Deploy (install) this data source to the cluster! This container data source will be the basis of the MapViewer data source to be created in step 3.
Unpack mapviewer.ear and setup the required directory tree structure (again details can be found in MapViewer's User's Guide). This will be the working directory tree for MapViewer! Every WLS clustered server will start its own MapViewer instance out of this directory. Each started MapViewer instance will then load the config file from the WEB-INF/conf folder, as well as saving all generated map images and tiles into this same directory tree. If your managed servers span different physical machines, then this folder needs to be on a shared network drive accessible by all the managed servers.
Modify the MapViewer config file, located in the WEB-INF/conf/ folder, to set a proper logging level. Most importantly, you need to create a MapViewer data source based on the container data source you created in step 1. A simple example of such a data source looks like this:
<map_data_source name="mvdemo"
container_ds="jdbc/mvdemo"
number_of_mappers="7"
allow_jdbc_theme_based_foi="true"
/>
Another thing you must modify in the config file, is the <save_images_at> element. Make sure the url attribute is set to a URL that points to the proxy domain, for instance "http://localhost:7001/mapviewer/images". And change the path attribute to "../../images".
Go to the console web page of the main domain, and deploy MapViewer from the exploded directory tree. Note that when presented with the "Soure accessibility" page during deployment, make sure you select the last option ("I will make the deployment accessible from the following location")! This is extremely important, as it ensures the MapViewer files are shared by all managed servers, and generated tiles/maps are shared also.
After deployment is done, simply access MapViewer from your browser http://localhost:7001/mapviewer. Everything should work just fine as if you are accessing a normal MapViewer server.
Verify that there are 3 MapViewer instances are running. Go to the exploded MapViewer folder, and change into the directory mapviewer.ear/web.war/WEB-INF/conf/. There you should see a file mv_proc.id. Open it in any text editor, and you should see a number 3. This means MapViewer has acknowleged there are 3 separate instances running.

You now have a MapViewer deployed and running on a cluster of managed WebLogic servers. Each MapViewer instance will be accessing the same database schema using the same cluster-wide container data source for optimal usage of the JDBC connections. MapViewer will intelligently and automatically avoid file name conflicts when generating and saving map images, FOI images as well map tiles. This is critical in a clustered environment since all MapViewer instances share a single physical working directory tree (the exploded MapViewer folder).

Using OpenStreetMap tiles with Oracle FMW MapViewer

2009-05-29T10:25:00.004-04:00

The recently uploaded tutorial on using DigitalGlobe's online imagery delivery platform with MapViewer
(http://www.oracle.com/technology/sample_code/products/mapviewer/index.html) discuss the MVCustomMapTileLayer interafce for accessing 3rd party tile providers. This post consists of sample code showing how it can be used with OSM tiles from {tiles|tah}.openstreetmap.org.

The sample html code is listed below.

<html>
<head>
<META http-equiv="Content-Type" content="text/html" charset=UTF-8">
<TITLE>OpenStreetMap as external tile layer</TITLE>

<link rel="stylesheet" type="text/css" href="http://sdolnx2.us.oracle.com:7777/mapviewer/fsmc/tutorial/t.css" />



<script language="Javascript" src="http://sdolnx2.us.oracle.com:7777/mapviewer/fsmc/jslib/oraclemaps.js"></script>

<script language=javascript>

// set up a map tile configuration so MapViewer knows the tiling scheme, i.e.
// the number of zoom levels (20), tile size (256x256)
// the tile width & height in real world coordinates at each zoom level
// the coordinate system (Spherical Mercator EPSG:3785), and
// tile image file format (PNG)
var mapConfig=
{
"mapTileLayer":"OSM_MERCATOR",
"format":"PNG",
"coordSys":
{
"srid":3785,
"type":"PROJECTED",
"distConvFactor":1.0,
"minX":-2.0037508E7,"minY":-2.0037508E7,
"maxX":2.0037508E7,"maxY":2.0037508E7
},
"zoomLevels":
[
{"zoomLevel":0,"name":"","tileWidth":4.00750166855785E7,"tileHeight":4.00750166855785E7,"tileImageWidth":256,"tileImageHeight":256},
{"zoomLevel":1,"name":"","tileWidth":2.0037508E7,"tileHeight":2.0037508E7,"tileImageWidth":256,"tileImageHeight":256},
{"zoomLevel":2,"name":"","tileWidth":1.0018754E7,"tileHeight":1.0018754E7,"tileImageWidth":256,"tileImageHeight":256},
{"zoomLevel":3,"name":"","tileWidth":5009377.0,"tileHeight":5009377.0,"tileImageWidth":256,"tileImageHeight":256},
{"zoomLevel":4,"name":"","tileWidth":2504688.5,"tileHeight":2504688.5,"tileImageWidth":256,"tileImageHeight":256},
{"zoomLevel":5,"name":"","tileWidth":1252344.25,"tileHeight":1252344.25,"tileImageWidth":256,"tileImageHeight":256},
{"zoomLevel":6,"name":"","tileWidth":626172.125,"tileHeight":626172.125,"tileImageWidth":256,"tileImageHeight":256},
{"zoomLevel":7,"name":"","tileWidth":313086.0625,"tileHeight":313086.0625,"tileImageWidth":256,"tileImageHeight":256},
{"zoomLevel":8,"name":"","tileWidth":156543.03125,"tileHeight":156543.03125,"tileImageWidth":256,"tileImageHeight":256},
{"zoomLevel":9,"name":"","tileWidth":78271.515625,"tileHeight":78271.515625,"tileImageWidth":256,"tileImageHeight":256},
{"zoomLevel":10,"name":"","tileWidth":39135.7578125,"tileHeight":39135.7578125,"tileImageWidth":256,"tileImageHeight":256},
{"zoomLevel":11,"name":"","tileWidth":19567.87890625,"tileHeight":19567.87890625,"tileImageWidth":256,"tileImageHeight":256},
{"zoomLevel":12,"name":"","tileWidth":9783.939453125,"tileHeight":9783.939453125,"tileImageWidth":256,"tileImageHeight":256},
{"zoomLevel":13,"name":"","tileWidth":4891.9697265625,"tileHeight":4891.9697265625,"tileImageWidth":256,"tileImageHeight":256},
{"zoomLevel":14,"name":"","tileWidth":2445.98486328125,"tileHeight":2445.98486328125,"tileImageWidth":256,"tileImageHeight":256},
{"zoomLevel":15,"name":"","tileWidth":1222.992431640625,"tileHeight":1222.992431640625,"tileImageWidth":256,"tileImageHeight":256},
{"zoomLevel":16,"name":"","tileWidth":611.4962158203125,"tileHeight":611.4962158203125,"tileImageWidth":256,"tileImageHeight":256},
{"zoomLevel":17,"name":"","tileWidth":305.74810791015625,"tileHeight":305.74810791015625,"tileImageWidth":256,"tileImageHeight":256},
{"zoomLevel":18,"name":"","tileWidth":152.87405395507812,"tileHeight":152.87405395507812,"tileImageWidth":256,"tileImageHeight":256},
{"zoomLevel":19,"name":"","tileWidth":76.43702697753906,"tileHeight":76.43702697753906,"tileImageWidth":256,"tileImageHeight":256}
]
};

// create a custom map tile layer based on the above tile configuration
// the second argument is a function that implements the getTileURL
// interface for this particular map tile service
var osmBasemap = new MVCustomMapTileLayer(mapConfig, getOSMMapTileURL);


var baseURL = "http://sdolnx2.us.oracle.com:7777/mapviewer" ;
var mapview;
var oraTheme = null ;
var oraTileLayer = null;

function showMap()
{
mapview = new MVMapView(document.getElementById("map"), baseURL);
mapview.addMapTileLayer(osmBasemap);
// near london -36793, 6679715 in SRID 3785
var mpoint = MVSdoGeometry.createPoint(-36793.89, 6679715.42, 3785); // near london 0.1,51.5,8307

mapview.setCenter(mpoint);
mapview.setZoomLevel(10);

mapview.addNavigationPanel() ;
mapview.display();
}

function showMapTileLayer(layerName)
{
mapview.removeMapTileLayer(osmBasemap) ;
eval("mapview.addMapTileLayer("+layerName+"Basemap)") ;
}

function getOSMMapTileURL(tx, ty, tw, th, level)
{
var x = (tx-mapConfig.coordSys.minX)/mapConfig.zoomLevels[level].tileWidth ;
// Mapviewer's tile The tile numbering scheme, or mesh codes, for Oracle Maps’
// (see Section 8.2 of the MapViewer User Guide for more details) tiles is similar
// to that for Google Maps. There only difference is that the Y origin is
// at the lower left rather than the upper left, as is the case for Google tiles
var y = (mapConfig.coordSys.maxY-ty)/mapConfig.zoomLevels[level].tileHeight-1 ;
// use mapnik rendered tiles
//return "http://tile.openstreetmap.org/"+(level)+"/"+x+"/"+y+".png";
// use osmarender instead
return "http://tah.openstreetmap.org/Tiles/tile/"+(level)+"/"+x+"/"+y+".png";
}

</script>
</head>

<body onload="javascript:showMap()">
<h3>Oracle Maps example - Custom map tile layer</h3>
This sample shows how the Oracle Maps GetMapTileURL interface could be used to display OSM map tiles.
It implements code samples and technical details described on OSM sample code pages.
This code is purely a sample explaining how to use the GetMapTileURL interface.<br>
<div id="map" style="width:800px;height:600px"></div>
</body>
</html>

Storing your redline geometries in a database

2009-05-01T14:20:00.009-04:00

MapViewer's JavaScript API provides a simple Red-line tool that you can use to let user draw simple shapes on the map. The tool can also return the coordinates of the shape, but there is no built-in mechanism to persistently store these shapes.

In this article I will show you how to easily store such hand drawings in a database table, then display them on the map at a later time just as easily.

The mains steps are:

1. Create a database table with a SDO_GEOMETRY column (to store the geometries). Also create spatial index on it so we can query and display the table contents on our map later on.

2. Create a very simple JSP page that will handle the task of storing a single geometry. It will take an geometry in a simple string format, then store it in the table using JDBC.

3. Create a simple HTML-based Oracle Maps demo page, where user can create a shape on the map using a Redline tool. After getting hold of the Redline geometry, the page will issue an AJAX request to the JSP page, passing various aspects of the geometry (such as its type, SRID, and coordinates) as URL parameters.

4. Display the table as a dynamic theme in the same HTML page.

For more details, please download the zip file that includes the following 3 files:

readme.txt: Instructions for running this demo.
store.jsp: The JSP page that handles geometry storage.
store.html: The main demo page that lets you draw things and display stored geometries.

The complete instructions are in the readme.txt file.

If you have the built-in Oracle Maps tutorials running, this demo should be very easy to set up and run. To run the dmeo, simply open the store.html page in your browser. Post your comments below if you run into any issues. The following is a screenshot of the demo:

Finally, note that you can easily expand the demo to store more fields besides the geometry itself. It is also trivial to display these fields as attributes in the info-tip window when user clicks on any geometry displayed on the map.

Rotating map symbols using oriented points

2009-03-26T15:03:00.008-04:00

Oracle Spatial supports the notion of oriented points, which are sdo_geometry points that contain additional coordinates of the end point for the orientation vector from the point itself, with values between -1 and 1. For instance, you can create an oriented point using the following SQL statement:

INSERT INTO cola_markets VALUES(
91,
'oriented_point',
SDO_GEOMETRY(
2001,
NULL,
NULL,
SDO_ELEM_INFO_ARRAY(1,1,1, 3,1,0),
SDO_ORDINATE_ARRAY(12,14, 0.3,0.2)));

The 12,14 identifies the physical coordinates of the point; and the 0.3,0.2 identifies the x and y coordinates (assuming 12,14 as the origin) of the end point of the orientation vector. The resulting orientation vector slopes upward at about a 34-degree angle, as illustrated in this figure:

(The above description and figure are copied from the Oracle Spatial User's Guide).

MapViewer has built-in support for such oriented points. What this means, is that if you apply a MARKER or TEXT style to such points (via a theme defined on the points table for instance), the MARKER (map symbol) or text itself will be oriented on the map according to the angle of its underlying data point, for every displayed data point.

To better illustrate this support, I have created a simple Oracle Maps demo that displays the included oriented_points table in your MVDEMO sample data set, using a pin symbol.


<html>
<HEAD>
  <META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=utf-8">
  <META NAME="GENERATOR" CONTENT="JDBC Demo">
<link rel="stylesheet" type="text/css" href="../t.css" />

<script language="Javascript" src="/mapviewer/fsmc/jslib/oraclemaps.js"></script>
<SCRIPT TYPE="text/javascript">
  var mapview;
  var orientedtheme;
  var baseQuery;
  var baseURL  = "http://"+document.location.host+"/mapviewer";
  var mapCenterLon = -122.49;
  var mapCenterLat =  37.5106;
  var mapZoom      =  3;  
  var mpoint = MVSdoGeometry.createPoint(mapCenterLon,mapCenterLat,8307);     
  function on_load_mapview() 
  {
    mapview = new MVMapView(document.getElementById("map"), baseURL);
    var basemap = new MVMapTileLayer("mvdemo.demo_map");
    mapview.addMapTileLayer(basemap);   
    mapview.setCenter(mpoint);   
    mapview.setZoomLevel(mapZoom);  
 
    orientedtheme= createOrientedTheme();
    
    mapview.addThemeBasedFOI(orientedtheme);
 
 var nav = new MVNavigationPanel() ;
    var navPan = new MVMapDecoration(nav,0,0,null,null,4,4) ;
    mapview.addMapDecoration(navPan) ;

    mapview.display();
  }
 
  var pinMarker = "M.CYAN PIN" ;
  
  function createOrientedTheme()
  {
    baseQuery= "select shape from oriented_points";
    var theme = "<themes><theme name='a_dynamic_theme' >" +
                "<jdbc_query asis='true' spatial_column='shape' jdbc_srid='8307' " +
                "render_style='"+pinMarker+"' datasource='mvdemo'>" + baseQuery +
                "</jdbc_query></theme></themes>" ; 
    var theme = new MVThemeBasedFOI('oriented-theme',theme);    
    theme.setBringToTopOnMouseOver(true);
 return theme;
  }
  
</SCRIPT>
</HEAD>

<BODY onload= javascript:on_load_mapview()>
<h3>Displaying oriented points</h3>
<div id="map" style=" width: 90%; height: 100%;">

</BODY>
</html>

If you save the above code as an HTML file in your MapViewer web directory, then open it from a browser, you will see four pin symbols, rotated according to the angles of the four oriented points from the table.

Creating a separate Admin account for MapViewer (part 2: WLS)

2009-03-16T16:16:00.004-04:00

In an earlier blog post I described how to create a separate admin user for the MapViewer admin account in an Oracle Application Server 10.1.3.* installation. This post follows up with instructions for WebLogic Server (version 9 and later).

To set up an admin user account for MapViewer in WLS, you first create a new user in WebLogic, then map this user to the MapViewer admin role in MapViewer's deployment descriptor file (weblogic.xml).

So first lets create a new WLS user. This is done using the WebLogic Admin Console.

Creating a user:

1. In the left pane select Security Realms.
2. On the Summary of Security Realms page select the name of the realm (for example, myrealm) that your MapViewer-deployed domain uses.
3. On the Settings for Realm Name page select Users and Groups > Users.

The User table displays the names of all users defined in the Authentication provider.
4. Click New.
5. In the Name field of the Create New User page enter the name of the user.
User names are case sensitive and must be unique.
6. (Optional) In the Description field, enter a description. The description might be the user's full name.
7. In the Provider drop-down list, select the Authentication provider for the user.

If multiple WebLogic Authentication providers are configured in the security realm, they will appear in the list. Select which WebLogic Authentication provider’s database should store information for the new user.
8. In the Password field, enter a password for the user.

The minimum password length for a user defined in the WebLogic Authentication provider is 8 characters. Do not use the username/password combination weblogic/weblogic in production.
9. Re-enter the password for the user in the Confirm Password field.
10. Click OK to save your changes.

The user name appears in the User table

Assigning the new user to the MapViewer built-in admin role:

1. go to the exploded Mapviwer directory, find weblogic.xml under $MAPVIEWR_HOME/mapviewer.ear/web.war/WEB-INF/
2. open weblogic.xml in a text editor. You will see something like following:

<?xml version = '1.0' encoding = 'US-ASCII'?>

<weblogic-web-app xmlns="http://www.bea.com/ns/weblogic/90">

<security-role-assignment>

<role-name>map_admin_role</role-name>

<principal-name>weblogic</principal-name>

</security-role-assignment>

<security-role-assignment>

<role-name>secure_maps_role</role-name>

<principal-name>weblogic</principal-name>

</security-role-assignment>

</weblogic-web-app>

Replace the strings "weblogic" with the new user name. In my case I used "maplogic" as the new user name:

<?xml version = '1.0' encoding = 'US-ASCII'?>

<weblogic-web-app xmlns="http://www.bea.com/ns/weblogic/90">

<security-role-assignment>

<role-name>map_admin_role</role-name>

<principal-name>maplogic</principal-name>

</security-role-assignment>

<security-role-assignment>

<role-name>secure_maps_role</role-name>

<principal-name>maplogic</principal-name>

</security-role-assignment>

</weblogic-web-app>

Save this file. Then restart the domain. Now you will be able to use the new user and password to log into MapViewer's admin page.

Displaying MapViewer tile layers over Google Maps

2009-03-09T13:49:00.019-04:00

A lot of folks have asked how to display a MapViewer tile layer in a Google Maps application. My colleague Jayant Sharma recently wrote a very nice note on this subject, using Google Maps' custom tile layer support. The following are the detailed instructions form his note. They can also be used with other map services such as Microsoft Virtual Earth.

Overview

There are 3 high-level steps involved:

Preparing your Oracle Spatial data by creating the EPSG:3785 coordinate system and transforming the data.
Creating a MapViewer tile layer for your data.
Displaying the MapViewer tile layer over Google Maps using its custom tile layer mechanism.

Adding the EPSG:3785 coordinate system definition

The Google Maps are projected and rendered in a coordinate system known as Spherical Mercator (EPSG id 3785). So the data stored in an Oracle database and rendered by MapViewer into map tiles must also be in that coordinate system. This section describes the steps to add this new EPSG coordinate system definition into an Oracle database.

Note: This requires a 10.2.0.4 database. Earlier versions do not have the required patch that enables transformations (SDO_CS.TRANSFORM) between this (3785) and other (e.g. WGS84 or BNG) coordinate systems.

Note 2: You may want to verify that the SRID 3785 does NOT already exist in the database. To verify, you can run the SQL query "select srid from mdsys.cs_srs where srid=3785" from any database user. If a row is returned, then you already have this SRID, and you should SKIP this section. With the latest 11g Oracle database this SRID does indeed exist out of the box.

Connect to your 10.2.0.4 database instance (with Spatial or Locator installed and enabled) as a privileged user (e.g. a user with the DBA role) and issue the following SQL statements.

insert into MDSYS.SDO_ELLIPSOIDS (

ELLIPSOID_ID,

ELLIPSOID_NAME,

SEMI_MAJOR_AXIS,

UOM_ID,

INV_FLATTENING,

SEMI_MINOR_AXIS,

INFORMATION_SOURCE,

DATA_SOURCE,

IS_LEGACY,

LEGACY_CODE)

VALUES (

7059,

'Popular Visualisation Sphere',

6378137,

9001,

1.0000E+12,

NULL,

null,

'EPSG',

'FALSE',

null);

insert into MDSYS.SDO_DATUMS (

DATUM_ID,

DATUM_NAME,

DATUM_TYPE,

ELLIPSOID_ID,

PRIME_MERIDIAN_ID,

INFORMATION_SOURCE,

DATA_SOURCE,

SHIFT_X,

SHIFT_Y,

SHIFT_Z,

ROTATE_X,

ROTATE_Y,

ROTATE_Z,

SCALE_ADJUST,

IS_LEGACY,

LEGACY_CODE)

VALUES (

6055,

'Popular Visualisation Datum',

'GEODETIC',

7059,

8901,

null,

'EPSG',

NULL,

'FALSE',

NULL);

insert into MDSYS.SDO_COORD_REF_SYSTEM (

SRID,

COORD_REF_SYS_NAME,

COORD_REF_SYS_KIND,

COORD_SYS_ID,

DATUM_ID,

geog_crs_datum_id,

SOURCE_GEOG_SRID,

PROJECTION_CONV_ID,

CMPD_HORIZ_SRID,

CMPD_VERT_SRID,

INFORMATION_SOURCE,

DATA_SOURCE,

IS_LEGACY,

LEGACY_CODE,

LEGACY_WKTEXT,

LEGACY_CS_BOUNDS,

is_valid,

supports_sdo_geometry)

VALUES (

4055,

'Popular Visualisation CRS',

'GEOGRAPHIC2D',

6422,

6055,

NULL,

null,

'EPSG',

'FALSE',

NULL,

'TRUE',

'TRUE');

INSERT INTO sdo_coord_ops (

coord_op_id,

coord_op_name,

coord_op_type,

source_srid,

target_srid,

coord_tfm_version,

coord_op_variant,

coord_op_method_id,

UOM_ID_SOURCE_OFFSETS,

UOM_ID_TARGET_OFFSETS,

information_source,

data_source,

show_operation,

is_legacy,

legacy_code,

reverse_op,

is_implemented_forward,

is_implemented_reverse)

VALUES (

19847,

'Popular Visualisation Mercator',

'CONVERSION',

null,

'',

null,

9804,

null,

'FALSE',

null,

1);

insert into MDSYS.SDO_COORD_OP_PARAM_VALS (

COORD_OP_ID,

COORD_OP_METHOD_ID,

PARAMETER_ID,

PARAMETER_VALUE,

PARAM_VALUE_FILE_REF,

UOM_ID)

VALUES (

19847,

9804,

8801, -- Latitude of natural origin

NULL,

9102);

insert into MDSYS.SDO_COORD_OP_PARAM_VALS (

COORD_OP_ID,

COORD_OP_METHOD_ID,

PARAMETER_ID,

PARAMETER_VALUE,

PARAM_VALUE_FILE_REF,

UOM_ID)

VALUES (

19847,

9804,

8802, -- longitude of natural origin

NULL,

9102);

insert into MDSYS.SDO_COORD_OP_PARAM_VALS (

COORD_OP_ID,

COORD_OP_METHOD_ID,

PARAMETER_ID,

PARAMETER_VALUE,

PARAM_VALUE_FILE_REF,

UOM_ID)

VALUES (

19847,

9804,

8805, -- scale factor at natural origin

NULL,

9201);

insert into MDSYS.SDO_COORD_OP_PARAM_VALS (

COORD_OP_ID,

COORD_OP_METHOD_ID,

PARAMETER_ID,

PARAMETER_VALUE,

PARAM_VALUE_FILE_REF,

UOM_ID)

VALUES (

19847,

9804,

8806, -- false easting

NULL,

9001);

insert into MDSYS.SDO_COORD_OP_PARAM_VALS (

COORD_OP_ID,

COORD_OP_METHOD_ID,

PARAMETER_ID,

PARAMETER_VALUE,

PARAM_VALUE_FILE_REF,

UOM_ID)

VALUES (

19847,

9804,

8807, -- false northing

NULL,

9001);

INSERT INTO sdo_coord_ref_system (

srid,

coord_ref_sys_name,

coord_ref_sys_kind,

coord_sys_id,

datum_id,

geog_crs_datum_id,

source_geog_srid,

projection_conv_id,

cmpd_horiz_srid,

cmpd_vert_srid,

information_source,

data_source,

is_legacy,

legacy_code,

legacy_wktext,

legacy_cs_bounds,

is_valid,

supports_sdo_geometry)

VALUES (

3785,

'Popular Visualisation CRS / Mercator',

'PROJECTED',

4499,

null,

6055,

4055,

19847,

Null,

null,

'FALSE',

null,

'TRUE',

'TRUE');

-- create the tfm_plans, i.e. transformation rule.

-- Note: This will result in an incorrect conversion since it ignores a datum shift

-- between the ellipsoid and the sphere. However the data will match up better

-- on google maps

-- first for wgs84 (8307)

call sdo_cs.create_pref_concatenated_op( 83073785, 'CONCATENATED OPERATION 8307 3785', TFM_PLAN(SDO_TFM_CHAIN(8307, 1000000000, 4055, 19847, 3785)), NULL);

-- 4326 is the EPSG equivalent of 8307

call sdo_cs.create_pref_concatenated_op( 43263785, 'CONCATENATED_OPERATION_4326_3785', TFM_PLAN(SDO_TFM_CHAIN(4326, 1000000000, 4055, 19847, 3785)), NULL);

-- similarly for os bng (oracle srid 81989 or epsg 27700 it is

call sdo_cs.create_pref_concatenated_op( 819893785, 'CONCATENATED OPERATION 81989 3785', TFM_PLAN(SDO_TFM_CHAIN(81989, -19916, 2000021, 1000000000, 4055, 19847, 3785)), NULL);

-- 27700 is the EPSG equivalent of 81989

call sdo_cs.create_pref_concatenated_op( 277003785, 'CONCATENATED_OPERATION_27700_3785', TFM_PLAN(SDO_TFM_CHAIN(27700, -19916, 4277, 1000000000, 4055, 19847, 3785)), NULL);

commit;

Next transform existing data, or a copy of it, into 3785 and use it for generating the tiles. Otherwise the data will be transformed on the fly and that’ll slow down tile generation. The next section will use the MVDEMO sample data set to illustrate the steps.

Setting up a Oracle map tile layer for Google Maps

The MVDEMO sample dataset has tables named counties, cities, interstates, and states and the data is in WGS84 (srid = 8307). There’s also a set of styles, themes, basemaps, and map tile caches defined. These definitions are stored in the USER_SDO_STYLES, SUER_SDO_THEMES, USER_SDO_MAPS, and USER_SDO_CACHED_MAPS views.

The first step is to create a set of tables with the data transformed to 3785.

create table states_3785 as select * from states;

create table interstates_3785 as select * from interstates;

create table cities_3785 as select * from cities;

create table counties_3785 as select * from counties;

update states_3785 set geom = sdo_cs.transform(geom, 3785);

update interstates_3785 set geom = sdo_cs.transform(geom, 3785);

update cities_3785 set location = sdo_cs.transform(location, 3785);

update counties_3785 set geom = sdo_cs.transform(geom, 3785);

commit;

-- insert metadata

insert into user_sdo_geom_metadata values('STATES_3785', 'GEOM',

sdo_dim_array(sdo_dim_element('X', -20037508.3427, 20037508.3427, 0.05), sdo_dim_element('Y', -20037508.3427, 20037508.3427, 0.05)), 3785);

insert into user_sdo_geom_metadata values('INTERSTATES_3785', 'GEOM',

sdo_dim_array(sdo_dim_element('X', -20037508.3427, 20037508.3427, 0.05), sdo_dim_element('Y', -20037508.3427, 20037508.3427, 0.05)), 3785);

insert into user_sdo_geom_metadata values('COUNTIES_3785', 'GEOM',

sdo_dim_array(sdo_dim_element('X', -20037508.3427, 20037508.3427, 0.05), sdo_dim_element('Y', -20037508.3427, 20037508.3427, 0.05)), 3785);

insert into user_sdo_geom_metadata values('CITIES_3785', 'LOCATION',

sdo_dim_array(sdo_dim_element('X', -20037508.3427, 20037508.3427, 0.05), sdo_dim_element('Y', -20037508.3427, 20037508.3427, 0.05)), 3785);

-- create spatial indexes

create index states_3785_sidx on states_3785(geom) indextype is mdsys.spatial_index;

create index interstates_3785_sidx on interstates_3785(geom)

indextype is mdsys.spatial_index;

create index counties_3785_sidx on counties_3785(geom)

indextype is mdsys.spatial_index;

create index cities_3785_sidx on cities_3785(location)

indextype is mdsys.spatial_index parameters(‘layer_gtype=point’);

The second step is to create the themes for these tables and after that a basemap made of these newly created themes. This can be done with MapBuilder or using SQL statements to copy the theme definitions while changing the referenced table names by appending a _3785 to the theme and table name.

insert into user_sdo_themes select name || ‘_3785’, description,

base_table || ‘_3785’, geometry_column, styling_rules

from user_sdo_themes where base_table in (‘STATES’, ‘INTERSTATES’,

‘COUNTIES’, ‘CITIES’) and length(name) < 27

commit;

-- if a theme name is > 27 chars long modify it individually

-- It’ll has to be manually modified in the basemap definition

-- too. E.g there may be one name new_theme_demo_highways_line

-- that can be named theme_demo_highways_line_3785 instead

Next define a basemap using these themes. You can use the following SQL statements to manually create a new basemap named DEMO_MAP_3785 that is similar to DEMO_MAP, then update its referenced theme names and map scales:

insert into user_sdo_maps select ‘DEMO_MAP_3785’, description,definition

from user_sdo_maps where name=’DEMO_MAP’;

update user_sdo_maps set definition=
'<?xml version="1.0" standalone="yes"?>
<map_definition>
<theme name="THEME_DEMO_STATES_3785" />
<theme name="THEME_DEMO_COUNTIES_3785" min_scale="3000000.0" max_scale="0.0" scale_mode="RATIO"/>
<theme name="THEME_DEMO_STATES_LINE_3785" min_scale="3000000.0" max_scale="0.0" scale_mode="RATIO"/>
<theme name="THEME_DEMO_HIGHWAYS_3785"/>
<theme name="THEME_DEMO_CITIES_3785" min_scale="6000000.0" max_scale="0.0" scale_mode="RATIO"/>
<theme name="THEME_DEMO_BIGCITIES_3785"/>
</map_definition>'
where name='DEMO_MAP_3785';
commit;

The third step is to create a map tile layer. Navigate to MapViewer’s Admin console (i.e. go to http://localhost:8888/mapviewer/ , click on the Admin button, log in as a oc4jadmin) and then on the Manage Map Tile Layers tab. Then on Create link in the left panel and then the Continue button. Name the map tile layer, e.g. demo_map_3785, choose mvdemo as the data source and demo_map_3785 as the basemap. Check the transparent checkbox next to the Background color selection box. The default color will be ignored and the map tiles will be rendered on a transparent background. Then set # Zoom Levels to 20 (the number used by Google Maps), ignore the scale level settings, SRID to 3785, Min X to -20037508.3427, Max X to 20037508.3427, Min Y to -20037508.3427, and Max Y to 20037508.3427. Leave the tile size as 256 by 256 and format as PNG. Do NOT click submit. Click XML Mode instead.

To workaround a bug in the UI, which does not let you enter specific tile sizes, we will manually enter this information in XML mode. So click on XML mode and copy and paste the following XML fragment over the existing <zoom levels> … </zoom_levels> fragment. (Note: the following values have been revised and are correct as of April 09 2009)

<zoom_levels levels="20" min_scale="0.0" max_scale="0.0" min_tile_width="76.43702697753906" min_tile_height="4.0075016E7">
<zoom_level level="0" name="" description="" scale="0.0" tile_width="4.0075016E7" tile_height="4.0075016"/>
<zoom_level level="1" name="" description="" scale="0.0" tile_width="2.0037508E7" tile_height="2.0037508E7"/>
<zoom_level level="2" name="" description="" scale="0.0" tile_width="1.0018754E7" tile_height="1.0018754E7"/>
<zoom_level level="3" name="" description="" scale="0.0" tile_width="5009377.0" tile_height="5009377.0"/>
<zoom_level level="4" name="" description="" scale="0.0" tile_width="2504688.5" tile_height="2504688.5"/>
<zoom_level level="5" name="" description="" scale="0.0" tile_width="1252344.25" tile_height="1252344.25"/>
<zoom_level level="6" name="" description="" scale="0.0" tile_width="626172.125" tile_height="626172.125"/>
<zoom_level level="7" name="" description="" scale="0.0" tile_width="313086.0625" tile_height="313086.0625"/>
<zoom_level level="8" name="" description="" scale="0.0" tile_width="156543.03125" tile_height="156543.03125"/>
<zoom_level level="9" name="" description="" scale="0.0" tile_width="78271.515625" tile_height="78271.515625"/>
<zoom_level level="10" name="" description="" scale="0.0" tile_width="39135.7578125" tile_height="39135.7578125"/>
<zoom_level level="11" name="" description="" scale="0.0" tile_width="19567.87890625" tile_height="19567.87890625"/>
<zoom_level level="12" name="" description="" scale="0.0" tile_width="9783.939453125" tile_height="9783.939453125"/>
<zoom_level level="13" name="" description="" scale="0.0" tile_width="4891.9697265625" tile_height="4891.9697265625"/>
<zoom_level level="14" name="" description="" scale="0.0" tile_width="2445.98486328125" tile_height="2445.98486328125"/>
<zoom_level level="15" name="" description="" scale="0.0" tile_width="1222.992431640625" tile_height="1222.992431640625"/>
<zoom_level level="16" name="" description="" scale="0.0" tile_width="611.4962158203125" tile_height="611.4962158203125"/>
<zoom_level level="17" name="" description="" scale="0.0" tile_width="305.74810791015625" tile_height="305.74810791015625"/>
<zoom_level level="18" name="" description="" scale="0.0" tile_width="152.87405395507812" tile_height="152.87405395507812"/>
<zoom_level level="19" name="" description="" scale="0.0" tile_width="76.43702697753906" tile_height="76.43702697753906"/>
</zoom_levels>

Now click the Submit button.

Click on the Manage link and you should see the Existing Map Tile Layers list. Select demo_map_3785 and click on View Map / Manage Tiles. Enter –12000000 for Center X, and 5000000 for Center Y and Show Map. Or just click show map and pan to the left. You should see tiles being generated and displayed. Click return. Below is a screenshot of this new tile layer:

The actual display code

The following sample code uses the tile served up by MapViewer in a Google Maps application. You should save it as tileoverlay-simple.html.

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xmlns:v="urn:schemas-microsoft-com:vml">
<head>
<title>Google Maps JavaScript API Example: Tile Overlays</title>
<script src="http://maps.google.com/maps?file=api&v=2&key=ABQIAAAA9WYjhAcvlemZrWK0oPA3ZBSN0IHl8d7gGlihtYuSKk78QOdoAhRRFH3M5iCXxdFN-KENpX8NdJwm0Q"
type="text/javascript"></script>
<script type="text/javascript">
function initialize() {
if (GBrowserIsCompatible()) {

// Set up the copyright information
// Each image used should indicate its copyright permissions
var myCopyright = new GCopyrightCollection("(c) ");
myCopyright.addCopyright(new GCopyright('Demo',
new GLatLngBounds(new GLatLng(-90,-180),
new GLatLng(90,180)), 0,'?2007 Google'));

// Create the tile layer overlay and
// implement the three abstract methods
var tilelayer = new GTileLayer(myCopyright);

tilelayer.getTileUrl = function(tile, zoom) {
var req=null;
req = "http://stadb32.us.oracle.com:7001/mapviewer/mcserver?" +
"request=gettile&format=PNG&"+
"zoomlevel="+(zoom)+"&mapcache=mvdemo.demo_map_3785&mx="
+(tile.x)+"&my="+(Math.pow(2,zoom)-1-tile.y)+"&";
return req;};

tilelayer.isPng = function() { return true;};
tilelayer.getOpacity = function() { return 0.75; }

var myTileLayer = new GTileLayerOverlay(tilelayer);
var map = new GMap2(document.getElementById("map_canvas"));
map.setCenter(new GLatLng(33.4419, -90.1419), 4);
map.addControl(new GSmallMapControl());
map.addOverlay(myTileLayer);
}
}
</script>
</head>
<body onload="initialize()" onunload="GUnload()">
<div id="map_canvas" style="width: 800px; height: 600px"></div>
</body>
</html>

The relevant (modified) code is the getTileUrl function. Google Maps passes in the tile coordinates for the requested tile and the current zoom level. The parameter “tile” is a GPoint object with “x” and “y” attributes. So tile.x is the x-coordinate for the tile. This is same for Oracle Maps since it also goes from left to right. The y-coordinate value however needs to be recomputed since Google’s Y values increase top to bottom while Oracle’s increase bottom to top. In both cases there are 2^Nx2^N tiles at zoom level N. So the Y value for the Oracle Maps tile will be (2^N –1 – tile.y).

You should modify the Google Maps key as well as the MapViewer server URL in the above code. Save the code as tileoverlay-simple.html, then open it from a browser, and you should see a Google Maps map with the MapViewer tile layer overlay.

Final note, while this article presented how to display MapViewer tiles in a Google Maps mash-up application, the up-coming release of MapViewer (11g R1) will include built-in support for displaying Google Maps and Microsoft Virtual Earth tiles from within your Oracle Maps application. A blog about such support will be posted here as soon as MapViewer 11g R1 is released (which hopefully is just around the corner).

Heat map support in MapViewer 11g

2009-01-26T10:17:00.007-05:00

One of the many new features of Oracle MapViewer 11g (which is now in the final testing stage) is heat maps. If you don't know what exactly is a heat map, it is a color based 2D representation of a point data set's distribution pattern. It is great at revealing clusters of points or events that occur in a study region.

Here is a screen shot of such a heat map fully integrated with the Oracle Maps JavaScript API.

The above map displays the CITIES table in MapViewer's MVDEMO data set as a heat map. The color gradients (from white to green to orange and finally to red) shows the distribution pattern (clusters) of cities and towns of US. In MapViewer terms, the CITIES theme is rendered using a HEAT MAP style. Internal tests have shown MapViewer can easily generate a heat map from hundreds of thousands of points, on the fly.

Here is another screen shot, this time showing the distribution of pizza restaurants across the states.

Creating a separate MapViewer admin account

2009-01-21T10:51:00.009-05:00

By default MapViewer borrows the same admin account that you use to log into the Application Server admin web page. For OracleAS 10.1.3.* this is typically the user named "oc4jadmin", and for WebLogic it's typically "weblogic".

In some cases however you may want to create a separate admin account just for MapViewer,such as when you do not wish to give away the middleware's master admin account information. Basically, this new account can only be used to log into MapViewer's admin page and perform all of its management tasks. It cannot be used to log into the middleware's master admin web site (the /em URL for OracleAS 10.1.3.* or the /console URL for WebLogic Server).

So how do you do that? We will show you the steps for both OracleAS 10.1.3 and WebLogic Server 10.

Oracle Application Server 10.1.3.*

Lets first assume you already have MapViewer deployed to one of the OC4J instances in your OracleAS 10.1.3.* installation. If MapViewer is not deployed yet, you should go ahead and deploy it.

Step 1. Log onto App Server's admin web site (/em).
Step 2. Find the OC4J instance that contains MapViewer. Then click on its Administration tab.
Step 3. Find the Security - Security Providers row, then click the Go to Task icon. This is shown in the following screen shot.

Step 4. Click the "Instance Level Security" button
Step 5. Select the Realms tab
Step 6. Click the number in the Users column of the row starting with "jazn.com".
Step 7. Click the Create button.
Step 8. Enter the user name and password for the new user to be created for MapViewer. For example I entered mapadmin as the user name.
Step 9. On the same page, from Available Roles, select and move "oc4j-app-administrators" to the Selected Roles box. Click Ok. You should see a confirmation page showing the new user and its assigned roles (oc4j-app-administrators).

The above steps create a new admin user for MapViewer with the assigned role of oc4j-app-administrators. We now need to modify Mapviewer's deployment descriptor so that it will accept this role for administration purposes.

Modify MapViewer's deployment descriptor

Before performing the following step, I typically shutdown the entire OracleAS instance; however it may also work if you just shut down the OC4J instance that contains MapViewer.

Once the OC4J instance is down, edit the following MapViewer deployment descriptor file:

AS_HOME/j2ee/home/application-deployments/mapviewer/web/orion-web.xml

where AS_HOME is the home directory of your OracleAS install. If your MapViewer is NOT deployed to the "home" OC4J instance, then you will also need to replace "home" with the directory name of the actual OC4J instance containing MapViewer. If your OC4J is named "mapper" for instance, then the direcorry is typically AS_HOME/j2ee/oc4j_mapper/...

Once the orion-web.xml file is opened in an editor, locate the XML element <security-role-mapping name="map_admin_role">. Add a new child <group> element
<group name="oc4j-app-administrators">. In other words, the entire element should look like this:

<security-role-mapping name="map_admin_role">
<group name="oc4j-app-administrators"/>
<group name="oc4j-administrators"/>
<group name="administrators"/>
</security-role-mapping>

You may also find another tag <security-role-mapping name="secure_maps_role"> in the same file, leave that one alone (it is used for the secure mapping demos).

By making the above change, we are telling MapViewer that any App Server user with the role "oc4j-app-administrators" should also be considered a MapViewer admin user.

Save the file. And restart OC4J or OracleAS instance.

Now you should be able to log into MapViewer's admin page using the newly created user (mapadmin in my case). All the admin tasks of MapViewer should go through as usual. You will not be able to log into the App Server admin site (/em) using mapadmin. You can however, still log into MapViewer's admin page using the oc4jadmin account (after all it is the master admin for the entire OracleAS instance).

WebLogic Server

To be added later...

Official MapViewer white paper: a primer

2008-11-24T13:58:00.002-05:00

Just FYI the official MapViewer Primer article can be found here:

http://www.oracle.com/technology/products/mapviewer/mapviewer_training_index.html

It provides a good and concise introduction on MapViewer.

Creating a web map from raster image files

2008-11-19T11:16:00.017-05:00

This article outlines the steps needed to create a "slippy" web map from a set of raster image files on your disk. The main steps are:

load the image files into Oracle Spatial and store them as a GeoRaster table

create a MapViewer theme and base map for the GeoRaster table

create a MapViewer map tile layer so that the AJAX mapping client can display the data as a slippy map in the browser

Lets now go through these steps with a bit more detail.

Loading image files into Oracle Spatial

For this we will use the Map Builder tool. If you don't have the latest version of Map Builder, you can get it from OTN MapViewer page. The latest kit is MapViewer version 10.1.3.3 for WebLogic.

Fire up Map Builder, then go to Tools > Import Image. You will be prompted to enter the name for a GeoRaster table to be created (if you are importing an image for the first time), and a few other things including the raster data table name and georaster column name. You should jot down these names as you will need to enter them again when importing a second image and so forth.

Click Next. You can accept default values for all the fields. Note that the SRID for the georaster data is set to 999999 by default, you should change it if you know the exact Oracle SRID for the image files you are importing. If you do not know the SRID, you should set it to 262148 here. SRID 262148 is a meter-based local coordinate system, and will ensure you can create a tile layer in the last step. Note that you can always update it later to a more accurate SRID.

Click Next. Then click Finish. Map Builder will start uploading the image file to the database.

After the image is uploaded and stored in the GeoRaster table, Map Builder will automatically prompt you to create a GeoRaster theme based on the table. A GeoRaster theme is required by MapViewer to visualize your image data. So click Next if this is the first image you just uploaded and there is no GeoRaster theme exists for it.

Enter a name for your new GeoRaster theme, then click Next. Click Next also on the 2nd and 3rd screen of this dialog. Then click Finish. You now have a GeoRaster theme for the image you just uploaded. You can preview this theme in Map Builder to ensure everything so far is working (in other words, you should see your image which is now stored in the database).

If you have more than one image files, just repeat the above steps. Note that you should use the same GeoRaster table name, column name and Raster Data Table name for all subsequent image files. This will ensure that all the image files are stored in the same GeoRaster table in Oracle Spatial. It will also make sure Map Viewer automatically "stitch" your image files when visualizing them. After finishing uploading each image file, MapBuilder will prompt again and ask if you want to create a GeoRaster theme. Click Cancel here since you already created the theme, which will automatically see new image data added to the GeoRaster table.

Creating a MapViewer base map

Now that all of your image files are stored neatly as a GeoRaster table in Oracle Spatial, and MapViewer is (partially) happy because you created a theme based on that table, there remains two more steps for the data to be displayable in a "slippy" map in your browser. First, we need to create a MapViewer Base map that includes/references this theme. Second we need to create a map tile layer which is what the slippy mapping client is expecting.

To create a base map, we will again use Map Builder. Right click on the Base Maps node in the left panel of Map Builder. In the ensuing dialog, enter a name for the new base map. Click Next. In the second screen as shown below, find and select the theme we just created, and click the button with a "+" icon to add the theme to the new base map.

Click Next and Finish. This will create a MapViewer base map that contains just the GeoRaster theme. Again you should be able to preview the base map inside Map Builder and see the same image data.

Creating a Map Tile Layer

The slippy Oracle Maps map cannot directly display a MapViewer base map for legacy reasons. It expects a MapViewer tile layer instead. So we need to create a map tile layer out of the base map. For this you will need to use the MapViewer Admin web page. So point your browser to the MapViewer home page, click the Admin icon/button, and login to the Admin page. Click the Management tab, then Manage Map Tile Layers. Click Create, select Internal. Click Continue. And you will see a web page that defines all aspects of the new Tile Layer, such as its name, what is the base map, and so forth. This is illustrated in the following screen shot:

Note that you will need to make sure proper values are entered for the fields Min X, Min Y, Max X, Max Y, Minimum Map Scale, Max Map Scale and SRID. The fields Min X, Min Y, Max X and Max Y define the coordinates of an imaginary bounding box that covers all the imported images. You should be able to get these values by checking the coordinates in the TFW files. Or you can use Map Builder's preview feature to get a rough estimate since the preview panel displays the coordinate info too.

Min and Max Map Scale define the smallest and largest map scales that the map images should be displayed (or will display reasonablly well in terms of clarity). They are true map scales and you can experiment with different values to get a sense of how they affect the user experience. A value of 1000 means the map scale is 1:1000, which in turn means a unit of distance (say an inch) on the screen represents 1000 same units (inches) on the ground.

The other field, # Zoom Levels, defines how many steps to go from zoomed way out (Max Map Scale) to way in (Min Map Scale). Again, it is okay to experiment with all of these values in case you didnt get it all right the first time. It's not a big deal to delete the current one and start over with a new map tile layer.

Finally, the SRID field should contain the same SRID value you entered when importing images in Map Builder.

Testing your map

So how do you actually know if your map tile layer is created properly? You display it in a simple HTML page! The easiest way is to copy and modify one of the existing Oracle Maps tutorials (each tutorial is one very simple HTML/JavaScript page). Simply replace the map tile name with the one you just created, and set the proper map center point and zoom level for your data. Open the page in your browser and you should see a draggable slippy map showing your image data!

draggable magnifying glass on your map

2008-11-04T14:00:00.003-05:00

My colleague Ji Yang recently developed some neat code to implement a movable magnifying glass or "microscope" that reveals more details on any spot on the map, without zooming into the map itself.

You can download the simple HTML page that implements this effect here. And here is the icon referenced in the page. The demo works off the sample MVDEMO data set.

The code simply uses the MVMapDecoration and other standard Oracle Maps JavaScript API. The basic idea is to create a duplicate set of MVMapView handle and theme-based FOI layers for the DIV container that serves as the microscope window. Then add this window as a movable Map Decoration object to the main map. The map and themes in the microscope window show things at a different zoom level from the main map to achieve the "amplifying" effect.

Anyway, here is a quick screen shot with the magnifying glass spotlighting on two different locations on the same map.

Generating map legends

2008-10-29T14:43:00.009-04:00

In this article we will show at least 3 different ways of generating a map legend. The first two are based on MapViewer's XML API, while the 3rd one is pure HTML and the most flexible. All the examples have been tested against the sample MVDEMO data source.

Approach 1: manually specifying legend entries

In this approach, we create a map legend image by specifying a map legend element in MapViewer's XML request. Inside the element, we add one legend entry for each style to be displayed as well as some description text. The trick here is to leave MapViewer nothing else to render: no center point, no map bounding box, and no base map or themes either. When MapViewer sees such an otherwise empty map request, it will know to generate an image that is just big enough to contain all the legend entries.

The following is one such sample XML request.

<?xml version="1.0" standalone="yes"?>
<map_request datasource="mvdemo" format="PNG_STREAM">
<legend bgstyle="fill:#ffffff;stroke:#ff0000" profile="MEDIUM" position="SOUTH_EAST">
<column>
<entry text="Map Legend" is_title="true" />
<entry style="M.STAR" text="center point" />
<entry style="M.CITY HALL 3" text="cities" />
<entry style="M.CITY HALL 4" text="big cities" />
<entry style="C.ROSY BROWN STROKE" text="state boundary" />
<entry style="L.PH" text="interstate highway" />
<entry style="L.FERRY" text="ferry" />
<entry is_separator="true" />
<entry text="County population:" />
<entry style="V.COUNTY_POP_DENSITY" tab="1" />
</column>
</legend>

</map_request>

The above request results the following legend image:

Approach 2: Fully automatic embedded map legend

In this approach, we want to display a map legend as part of the map itself, while without specifying any legend entries. Lets look at the such a map request:

<?xml version="1.0" standalone="yes"?>
<map_request
title="Oracle LBS MAP"
basemap="demo_map"
datasource = "mvdemo"
width="640"
height="480"
bgcolor="#a6cae0"
antialiase="false"
format="PNG_STREAM">
<center size="0.15">
<geoFeature render_style="m.star"
radius="1600,4800"
label="A Place"
text_style="t.Street Name" >
<geometricProperty typeName="center">
<Point srsName="SDO:8307">
<coordinates>-122.2615, 37.5266</coordinates>
</Point>
</geometricProperty>
</geoFeature>
</center>

<legend bgstyle="fill:#ffffff;stroke:#ff0000" profile="MEDIUM" position="SOUTH_EAST">
</legend>

</map_request>

As you can see, the above request specifies a legend element without any actual legend entries inside it. So how will MapViewer create the legend in this case? It actually will look up all the themes that are visible on the result map, and displays all the styles that are used by these themes in the legend area. This is great if you are just feeling lazy and would rather MapViewer handle everything for you. The following is the map with the automatic legend:

For more information about these two approaches and the (sometimes limited) customization options, please check out MapViewer's User Guide.

Approach 3: Full manual mode

If you are an advanced user, you most likely will want more than the two approaches we just mentioned. No worries. In the 3rd approach, we will leverage a new MapViewer request to achieve complete control of legend customization and layout. Basically, with a recent MapViewer release (such as 10.1.3.3 for WebLogic), you can now request a 'sample' image of any style from Mapviewer. A typical request URL for a style image looks like this:

http://sdolnx2.us.oracle.com:7777/mapviewer/omserver?sty=M.STAR&w=25&h=25&ds=mvdemo

For the above URL, MapViewer will generate and stream back an image 25 pixels wide and high that shows the style named "M.STAR" from the "mvdemo" data source.

With this kind of style image URL, we can use the regular HTML table and <img> tags to fully customize what, where and how legend entries are displayed. For instance, to replicate the sample legend in Approach 1, we can use the following simple HTML table (you can also use CSS constructs to achieve much fancier layout if you so desire):

<TABLE>
<TR>
<TD>
<Font size="+1" color="blue">Basic Features:</FONT>
</TD>
<TD>
</TD>
</TR>
<TR>
<TD>
<img src="http://sdolnx2.us.oracle.com:7777/mapviewer/omserver?sty=M.STAR&w=25&h=25&ds=elocation">
</TD>
<TD>
map center
<TD>
</TR>
<TR>
<TD>
<img src="http://sdolnx2.us.oracle.com:7777/mapviewer/omserver?sty=M.CITY+HALL+3&w=25&h=25&ds=mvdemo">
</TD>
<TD>
cities
</TD>
</TR>
<TR>
<TD>
<img src="http://sdolnx2.us.oracle.com:7777/mapviewer/omserver?sty=M.CITY+HALL+4&w=25&h=25&ds=mvdemo">
</TD>
<TD>
big cities
</TD>
</TR>
<TR>
<TD>
<img src="http://sdolnx2.us.oracle.com:7777/mapviewer/omserver?sty=C.ROSY+BROWN+STROKE&w=34&h=34&ds=mvdemo">
</TD>
<TD>
state boundary
</TD>
</TR>
<TR>
<TD>
<img src="http://sdolnx2.us.oracle.com:7777/mapviewer/omserver?sty=L.PH&w=45&h=15&ds=mvdemo">
</TD>
<TD>
interstate highway
</TD>
</TR>
<TR>
<TD>
<img src="http://sdolnx2.us.oracle.com:7777/mapviewer/omserver?sty=L.FERRY&w=45&h=15&ds=mvdemo">
</TD>
<TD>
ferry
</TD>
</TR>
<TR> 
<TD>
<img src="http://sdolnx2.us.oracle.com:7777/mapviewer/myicons/t.gif" height="15" width="1">
</TD>
<TD>

</TD>
</TR>
<TR>
<TD colspan="2">
<FONT size="+1" color="blue">County Population Density:</FONT>
</TD>
</TR>
<TR>
<TD>
<img src="http://sdolnx2.us.oracle.com:7777/mapviewer/omserver?sty=V.COUNTY_POP_DENSITY&w=180&h=175&ds=mvdemo">
</TD>
<TD>
</TD>
</TR>
</TABLE>

The following is what you will see in a browser:

MapViewer for WebLogic kit updated

2008-10-21T14:23:00.003-04:00

The latest MapViewer release, version 10.1.3.3 for WebLogic, just saw an update yesterday. Please go to http://www.oracle.com/technology/software/products/mapviewer/index.html for immediate download.

This kit is released under the same bundle name (mapviewer10133wls.zip) but the MapViewer component (mapviewer.ear) in it has been updated to include a few last minute bug fixes. If you have experienced issues with Oracle Maps when doing very fast zooming operations, such as FOI features throwing errors or base map tiles disappearing, then you want to download and deploy this latest kit.

Note again that while this kit is certified on WebLogic Servers, you can also deploy it to all 10.1.3.* versions of OC4J standalone and Oracle App Server. This kit also supersedes all previously released MapViewer 11g previews in functionality and stability.

thanks

LJ

Displaying labels on your FOI objects

2008-10-06T15:38:00.008-04:00

You probably noticed that by default, none of the clickable Feature of Interest objects displayed on your map has any label text on it. So how to add labels to your FoIs? There are different approaches based on how your FOI objects are created, and also their geometric types.

Adding an index label to your markers

If your theme-based FOI layer is composed of exclusively Point-type objects (markers), you have an option to automatically attach a sequence number or letter to each marker displayed on the map. This is very useful if all you want to do is to index each marker object and be able to cross-reference them in a list that shows the same objects in a tabular form. The method you will use is MVThemeBasedFOI.enableMarkerSequence( enabled, type). Please check out the online API doc for details on this method. The following screenshot shows how such a map looks like:

Note that in order to make the index number or letter inside each marker visible, you need to make sure the Marker style used by your theme is big enough for the label. Also make sure the color of the text is set to a different color of the marker itself. In the above map, the theme uses a circle Marker style, and it is filled with red color. So you need to make sure it does not use a red color for its text. To change the text color (and font/size if needed), open the Marker style in Map Builder, click the Marker Text button and change the text color. This is shown in the following screen shot:

Individual marker FOI objects

If you manually create and place individual FOI objects on the map, for instance by using the MVFOI.createMarkerFOI() and mapview.addFOI() methods, then it is very easy to add label text to each marker. It is shown in the built-in Oracle Maps tutorial mapviewer/fsmc/tutorial/samples/FOIMarker.html. Look for the statement containing setHTMLElement("#1",20,20), which is the exact method you will use to set a label on top of the marker you are creating.

Theme-based FOI layer

If you are displaying a pre-defined theme based FOI layer, and you want to display a label on each feature of interest, there is a method on MVThemeBasedFOI that does just that: enableLabels(true). Note that this method will work provided the following conditions are met:
1. The theme has label enabled (in other words, if you submit this theme in a plain XML map request the resulted map image should display labels on your theme).
2. The features are of polygon type. If your FOIs are of linestring or point type, the method enableLabels() does nothing for you, unless you enable whole-image rendering for the FOI layer.

Dynamic theme based FOI layer

If you are displaying a JDBC/Dynamic theme based FOI layer, and want to display a label on each feature, simply call the same MVThemeBasedFOI.enableLabels(true) method on your FOI layer. You just need to make sure that your dynamic theme actually contains a label column in its SELECT list, and tell MapViewer the name of that label column as well as the labeling style to be used. As an example, I modified the buffer theme in the built-in tutorial /mapviewer/fsmc/tutorial/samples/jdbcThemeBasedFOI.html to display the label "A1" on each buffer zone:

function updateBuffer()
{
...

baseQuery = "select 'A1' as label, sdo_geom.sdo_buffer(A.location, "+radius+
", 0.005, 'unit=mile arc_tolerance=0.005') location "+
" from "+theme+" A" ;
var theme = '<themes>' +
'<jdbc_query asis="true" spatial_column="location" jdbc_srid="8307" ' +
'render_style="'+bufferStyle+'" datasource="mvdemo" label_column="label" label_style="T.CITY NAME" >' + baseQuery +
'</jdbc_query></theme></themes>' ;
buffertheme = new MVThemeBasedFOI('buffertheme',theme);
buffertheme.setBringToTopOnMouseOver(true);
buffertheme.enableLabels(true);
mapview.addThemeBasedFOI(buffertheme);

...
}

APEX, Oracle Maps and Secure Mapping

2008-09-30T16:40:00.010-04:00

One interesting feature in the latest MapViewer kit (10.1.3.3 for WebLogic Server) is the built-in support for secure mapping.

So what is it? Basically, it is a way for you to pass the name of an authenticated Web user to a database context where a theme's query will be executed. Your database session can then utilize this piece of information to filter or modify what the theme's query returns. As you probably already know, every MapViewer theme (pre-defined or JDBC/dynamic) results in a SQL query being executed in the database. More specifically, MapViewer obtains a JDBC connection from the connection pool associated with a data source and executes the query in the session of that connection.

Since it is a shared connection pool, how do you pass a web user's name to each theme's connection or DB session? The way MapViewer does it, is to always execute a 'before' and an 'after' PL/SQL procedure around the actual execution of the theme query. In the 'before' PL/SQL procedure, MapViewer passes in the currently logged in Web user's name (or role, or any piece of info you desire). What the PL/SQL procedure does with this piece of information, is up to you, the author of this PL/SQL procedure. You could, for instance, set up some VPD policy or a view that filters the query result based on the web user name. The 'after' procedure simply lets you do some clean-up if necessary.

So where does MapViewer get this authenticated Web user in the first place? Typically it gets this piece of information from an authenticated J2EE session (that MapViewer can access with each and every incoming map request). Now, what happens if your user authenticates to APEX (Oracle Application Express), then communicates directly with the MapViewer server? In this case, there is no separate authentication with the J2EE server that MapViewer is running on, and the APEX authenticated user is not visible to the J2EE server (hence MapViewer). Don't worry, MapViewer also lets you pass an authenticated Web user's name through a Cookie. So in order to pass the APEX authenticated user's name to MapViewer, you simply setup a cookie within the APEX context so that this cookie accompanies every request going to MapViewer.

So how do you tell MapViewer to pick up this web user name from a named cookie (instead of the default place which is a J2EE session)? You do so by adding a few attributes to the MapViewer data source definition. In fact, you also mention the PL/SQL package name (containing the "before" and "after" procedures) in the same data source definition. Here is an example:

<map_data_source name="mvdemo"
jdbc_host="stadb32.us.oracle.com"
jdbc_sid="mv"
jdbc_port="25650"
jdbc_user="mvdemo"
jdbc_password="!mvdemo"
jdbc_mode="thin"
number_of_mappers="5"
allow_jdbc_theme_based_foi="true"
plsql_package="web_user_info"
web_user_type="MON_USER"
/>

The first bold-typed attribute, plsql_package, tells MapViewer which database package it should execute around theme queries. The second bold attribute, web_user_type, tells MapViewer where to pick up the authenticated Web user name.
The possible values for the web_user_type attribute are:
"J2EE_USER" : tells MapViewer to get the authenticated user name from a J2EE session
"OSSO_USER" : tells MapViewer to get the authenticated user from an OSSO (Oracle Single Sign On) session
"<Cookie Name>" : tells MapViewer to get the authenticated user from a cookie; cookie name is case insensitive. In the above example, the name of the cookie containing the authenticated user name is "MON_USER".

So that's the gist of it. For more detailed explaination on this new MapViewer feature, please check out the MapViewer User's Guide (section 1.8) that comes with MapViewer version 10.1.3.3 for WebLogic. Note that this version of MapViewer works equally well with Oracle App Server 10g or standalone OC4J even though it says "for WebLogic Server".

A secure MVDEMO mapping demo

If you want to run an actual secure mapping demo based on the MVDEMO data set, you should check out this short article describing all the required steps and how to run the demo itself. Note this demo runs in a standalone OC4J or Oracle App Server environment, not in APEX, although you can make simple modifications so that it works in APEX or any other environment. Note also that you will need to use the MVDEMO data set that comes with the latest MapViewer kit mentioned above as it includes the necessary setup scripts for this demo.

Setting up a cookie with user name in Apex

My colleague Carsten Czarski sent me this tip in case you are wondering how to actually setup a cookie in Apex so that it contains the login user name. Basically your Set Username Cookie process in Apex login page 101 should look like this:

begin
owa_util.mime_header('text/html', FALSE);
owa_cookie.send(
name=>'LOGIN_USERNAME_COOKIE',
value=>lower(:P101_USERNAME));
owa_cookie.send(
name => 'MON_USER',
value => :P101_USERNAME,
path => '/mapviewer',
domain => 'myhost.com');
exception when others then null;
end;

The above bold text creates a cookie named MON_USER in the current Apex session. This cookie will be sent to MapViewer along with every map/FOI request. Note especially the pieces about path and domain as they are very important, without these the cookie MON_USER won't reach MapViewer since it is likely running on a different path and domain from APEX.

Note also this will make sure the default LOGIN_USERNAME_COOKIE is still there (in case other pages of your APEX application depends on this cookie).

Displaying map tiles in your Java Swing app

2008-09-29T10:43:00.003-04:00

Recently I was asked about how to display map tiles served by a remote MapViewer server in a Swing desktop application. I have since written a simple Swing application that does just that. You can get the complete source code here. The sample application connects directly to our hosted eLocation server (elocation.oracle.com) and displays an initial map of the continental USA. You can use double-click (or + and - keys) to zoom in/out, and the 4 arrow keys to navigate or pan the map. Here is a snapshot:

When you download the source code bundle, you will find the following files (in various sub-directories):

SwingMapViewer.jws : the Oracle JDeveloper workspace file. If you have the latest (11g tech preview 4) version of JDeveloper, you can just double click this file to open the entire project and compile/run this sample. If you are using another Java IDE, simply make sure the mvclient.jar (described below) is in your project's class/library path.

Main.java : the main driver class. it asks for a few command-line params (such as where is your MapViewer instance and what map tile layer you want to display) and sets up the configuration for the rest of the application.

MapConfig.java : this class configures the application for such things as MapViewer URL, map tile layer name, data source name, initial map display center and zoom level as well as SRID et al. By default it reads such info from the mapconfig.properties file so you just need to edit that file if you want to display your own map tiles.

MapPanel.java : this class provides the display area in the form of a Java JPanel. It also registers a few listeners to handle events such as mouse click and key presses (for simple navigation).

MapDelegate.java : this is the most important class. It uses the MapViewer Java bean API to communicate with the remote MapViewer instance in response to events from the MapPanel class. So all the actual display/zoom/pan actions are implemented in this class. In truth this class simply delegates everything to the MapViewer bean API (composed of a single class oracle.lbs.mapclient.MapViewer) which is doing all the heavy lifting.

mvclient.jar : this is the Jar file containing the MapViewer Java bean API classes. Make sure it is on your project classpath.

Photos from Oracle Openworld

2008-09-26T12:04:00.007-04:00

As promised, here are a few quick snapshots from this year's Openworld held at the Moscone Center in downtown San Francisco. It is one of the largest Oracle user conferences with over 40k attendees. The two Spatial/MapViewer booths received a steady flow of visitors and it was great meeting a lot of customers and partners!

Billboards all over the conference area:

As usual, Oracle had to completely take over a few street blocks in order to have enough space for everyone to sit and meet :)

A nice lunch area in the garden near Moscone center:

Some indoor snapshots:

Wednesday we had a night of entertainment on the Treasure island:

This year there were 4 bands doing live music, Seal (my personal favorite), Elvis Costello, UB 40 and Allan Jackson.

Latest MapViewer kit released

2008-09-24T19:25:00.002-04:00

Just want to let you know that we posted the latest MapViewer kit for WebLogic server on OTN. Just go to otn.oracle.com then search for "MapViewer" and you will find the kit under the software section of the MapViewer page.

This kit is identical to the previously released (but short-lived) 10g patch 5 kit. We want to emphasize the support for WebLogic server so that's why we pulled the patch 5 kit and re-packaged it as MapViewer 10.1.3.3 for WebLogic. Note that even though it is "branded" as for WebLogic, it works just fine with your existing 10g versions of Oracle App Server or OC4J standalone.

Note also that this kit contains all the features that were available in various MapViewer 11g preview kits. So if you are currently using MapViewer 11g preview, upgrade now to this latest official kit!

Finally, I'm at the Oracle OpenWorld conference this week in San Francicso. This year we have two booths in the exhibition hall, one for Spatial and one for MapViewer! Traffic has been steady and it was fun meeting a lot of MapViewer/Spatial users in person. I hope to upload some conference photos later after I get back home.

regards

LJ

Oracle MapViewer: a primer

2008-09-19T16:18:00.001-04:00

I just finished up a primer article introducing basic concepts and setups of MapViewer. Feel free to check it out here. Hope it helps people that are new to MapViewer; it even includes a mini introduction to Oracle Spatial!

World mercator projection used by Oracle's eLocation site

2008-09-18T15:38:00.002-04:00

World Mercator (srid 54004) is a projection coordinate system widely used by tile based online mapping services. Map tiles (elocation.world_map) served by elocation.oracle.com are rendered in this coordinate system. However Oracle Database products prior to version 11g R2 does not support this coordinate system out of box. To add support for this coordinate system to your database, you need to execute the following SQL statements when connect as a DBA user.

INSERT INTO sdo_coord_ops ( coord_op_id, coord_op_name, coord_op_type,
source_srid, target_srid, coord_tfm_version, coord_op_variant,
coord_op_method_id, UOM_ID_SOURCE_OFFSETS, UOM_ID_TARGET_OFFSETS,
information_source, data_source, show_operation, is_legacy,
legacy_code, reverse_op, is_implemented_forward, is_implemented_reverse)
VALUES ( 54004, 'World Mercator', 'CONVERSION', null, null, '', null,
9804, null, null, null, null, 1, 'FALSE', null, 1, 1, 1);

insert into MDSYS.SDO_COORD_OP_PARAM_VALS (
COORD_OP_ID, COORD_OP_METHOD_ID, PARAMETER_ID, PARAMETER_VALUE,
PARAM_VALUE_FILE_REF, UOM_ID) VALUES (
54004, 9804, 8801, 0,
NULL, 9102);

insert into MDSYS.SDO_COORD_OP_PARAM_VALS ( COORD_OP_ID,
COORD_OP_METHOD_ID, PARAMETER_ID, PARAMETER_VALUE,
PARAM_VALUE_FILE_REF, UOM_ID) VALUES (
54004, 9804, 8802, 0, NULL, 9102);

insert into MDSYS.SDO_COORD_OP_PARAM_VALS ( COORD_OP_ID,
COORD_OP_METHOD_ID, PARAMETER_ID, PARAMETER_VALUE,
PARAM_VALUE_FILE_REF, UOM_ID) VALUES (
54004, 9804, 8805, 1, NULL, 9201);

insert into MDSYS.SDO_COORD_OP_PARAM_VALS ( COORD_OP_ID,
COORD_OP_METHOD_ID, PARAMETER_ID, PARAMETER_VALUE,
PARAM_VALUE_FILE_REF, UOM_ID) VALUES (
54004, 9804, 8806, 0, NULL, 9001);

insert into MDSYS.SDO_COORD_OP_PARAM_VALS ( COORD_OP_ID,
COORD_OP_METHOD_ID, PARAMETER_ID, PARAMETER_VALUE,
PARAM_VALUE_FILE_REF, UOM_ID) VALUES (
54004, 9804, 8807, 0, NULL, 9001);

INSERT INTO sdo_coord_ref_system ( srid, coord_ref_sys_name,
coord_ref_sys_kind, coord_sys_id, datum_id, geog_crs_datum_id,
source_geog_srid, projection_conv_id, cmpd_horiz_srid, cmpd_vert_srid,
information_source, data_source, is_legacy, legacy_code, legacy_wktext,
legacy_cs_bounds, is_valid, supports_sdo_geometry) VALUES (
54004, 'World Mercator', 'PROJECTED', 4499, null, 6326, 4326, 54004,
Null, Null, null, null, 'FALSE', null, null, null, 'TRUE', 'TRUE');

COMMIT ;

How to read the logs generated by MapViewer

2008-09-16T11:35:00.002-04:00

The log records generated by MapViewer at the server side are crucial when you need to diagnose any MapViewer issues. A while ago I wrote a short piece trying to explain what the log records look like and how to interpret them. You can grab it here.

For 11g we are also working on a web-based log viewer that can be accessed right from MapViewer's home page.

Oracle Maps and APEX

2008-09-16T11:18:00.003-04:00

I recently wrote a short white paper on how to integrate MapViewer/Oracle Maps with Oracle Applicatin Express, the quick and easy database application development environment. You can find the white paper here.

GeoRSS support in Oracle Maps

2008-09-12T15:08:00.003-04:00

Starting with the latest Mapviewer kit (10g patch 5, a.k.a 10.1.3.3 for WebLogic), you can easily display an external GeoRSS feed as a FOI layer on top of your tile layer. In fact, your MapViewer installation comes with some GeoRSS tutorials, such as tutorial #58. Its full URL is http://<host>:<port>/mapviewer/fsmc/tutorial/samples/georss-demo.html.

That page displays the United States continental states. Below the map you will see a text field where you can enter a custom URL to some external GeoRSS feed. If you want to see a feed that contains pictures (who doesn't!), you can try this Flickr photo stream feed:

http://api.flickr.com/services/feeds/geo/?id=35468159852@N01

(My colleague Jayant sent me this feed so you will have to ask him why this particular feed is chosen).

You will see a map like this (after zooming into the San Francisco city area):

Note that if your MapViewer is running behind a firewall, you will need to setup the web proxy stuff in mapViewerConfig.xml (check the User's Guide on instructions).

Cross-domain Oracle Maps scripting

2008-09-10T21:00:00.003-04:00

First, yes you can use Oracle Maps (the JavaScript/Ajax API) in a cross domain fashion. In other words, the script in your application page can interact or connect to a remote MapViewer server that is on a different domain than where your application page originates from.

Beware though you must be using the 10g Patch 4 (10.1.3.3 patch 4) or 10g Patch 5 (10.1.3.3 patch 5) versions of MapViewer. The original MapViewer production release (10.1.3.1) does not support cross-domain usage out of the box!

Assuming you have the correct version of MapViewer server installed, here is how to do cross-site Oracle Maps scritping. First let's assume your application page is accessed as http://www.fooA.com/myapp.html. And the proper version of mapViewer server is accessed via http://www.fooB.com/mapviewer/.

1. Always import the oraclemaps.js that comes from the correct MapViewer server. Do not use any cached or old copy of oraclemaps.js that is from an older version of MapViewer. You should copy the oraclemaps.js file from the mapviewer site and host it on your application page's web server, then import this library into your code.

2. Specify the MapViewer server URL in your map tile layer and theme-based FOI layer constructor.
This is the key. In order to interact with a MapViewer server that is running on
a different domain from where your application page is hosted, you must explicitly
specify the URL of the MapViewer tile server (for map tile layers) and FOI server (for
theme-based FOI layers) in your code where you construct the tile layer or FOI
layer. For example:

mapview.addMapTileLayer(new MVMapTileLayer("mvdemo.demo_map",
"http://www.fooB.com/mapviewer/mcserver"));

var customers = new MVThemeBasedFOI('foitheme1','mvdemo.customers',
'http://www.fooB.com/mapviewer/foi');

And that's all you need to do! For more info, check out the JSDoc for the MVMapTileLayer and
MVThemeBasedFOI classes.

Getting more diagnostic info out of MapViewer

2008-09-10T20:01:00.008-04:00

There are a few undocumented tricks that you can use to get more diagnostic info out of MapViewer.

In-memory geometry cache status

One area is about the health or general status of the internal geometry cache. As you probably know MapViewer usually caches geometry data of pre-defined themes as they go through the rendering pipeline. The status (such as total bytes of data being cached) of this in-memory only geometry data cache can be obtained by adding a "report_stats" attribute to the <spatial_data_cache> tag of the mapViewerConfig.xml file:

<spatial_data_cache max_cache_size="64"
report_stats="true"
/>

After restarting mapViewer, you will see periodic dumps of the in-memory geometry cache status in the MapViewer log file.

Connection pool status

As you know mapViewer uses a JDBC connection pool for each data source. You can obtain information about these connection pools such as number of active connections. To do so, simply add an element to the <logging> tag in mapViewerConfig.xml:

<logging log_level="finest" log_thread_name="false"
log_time="true">
<log_output name="System.err" />


<log_output name="../log/mapviewer.log" />

<monitor_data_sources value="true" interval="120" />
</logging>

After restarting Mapviewer, you will see a dump of the connection pool info for each data source every two minutes (120 seconds) in the log file.

Usage of mappers and connections

[Note: this trick only works with the 10g Patch 5 release of MapViewer]

Sometimes you want to know if you have configured enough number of mappers for a particular data source, and/or if you have enough connections to serve your map requests. There is a simple XML request that you can send to a running MapViewer to find out. You can send this request from a custom application of yours via standard HTTP Post, or simply use the built-in request forms that comes with your Mapviewer installation.

To do so, point your browser to the MapViewer home page. Then click the Requests tab. In the big text area, clear out everything and paste the following xml request:

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

then click Submit. This will send MapViewer your request. The server will respond with a breakdown of the free/in-use mappers and connections for each defined data source, at the exact moment your request is receved!

MapViewer 10g Patch 5 released

2008-09-10T17:00:00.002-04:00

Grab it from OTN here:
http://download.oracle.com/otn/other/mapviewer/mapviewer10133p5.zip

This is the latest MapViewer release. It supersedes all (previously downloadable) 11g preview or early access kits. We are no longer allowed to post 11g preview kits on OTN per Oracle's new policy.

The main things in this patch that worth mentioning are:
1. Certified on WebLogic server version 9, 10 and 10.3 (preview);
2. Works with Apple Safari desktop browser.
3. And many bug fixes to the JavaScript API (and other areas of MapViewer also). Full fixed bug list is in the patch note.

The patch note file is inside the zip file; the zip file itself is about 45 MB.

The included User's Guide has detailed instructions on how to deploy this latest MapViewer on WebLogic Server.

MapViewer web resources

2008-09-02T14:15:00.002-04:00

The official web site for MapViewer (to get documentation, software et al) is here:
http://www.oracle.com/technology/products/mapviewer/index.html

The official discussion forum (shared with Oracle Spatial) is here:

http://forums.oracle.com/forums/forum.jspa?forumID=76

Other Oracle MapViewer related blogs:

A great blog by colleague Bernhard Fischer-Wasels: http://oracle-maps.blogspot.com/ (mostly in German).

eLocation: a public show case of MapViewer

2008-09-02T13:50:00.004-04:00

Oracle's own online mapping server:

http://elocation.oracle.com/elocation/ajax

The above is an online mapping site powered by Oracle's own GeoSpatial products such as Oracle Spatial and MapViewer.

Specifically, the mapping is all done by MapViewer. It uses MapViewer's map tile server to generate and cache map tiles. The map look and feel is created using the Map Builder desktop tool that is part of the MapViewer product.

The geocoding and routing (driving directions) are powered by the GeoCoder and Router component of Oracle Spatial.

Most of the data are purchased from Navteq. All the data are loaded into an Oracle database; this includes all the base map layers such as streets and boundaries/parks/lakes/POIs.

Please be aware that this is an experimental site provided primarily for Oracle's internal use. The site consists of 2 not-so-fast Linux boxes so please be gentle and understanding if it cannot keep up with your requests from time to time :)

New Oracle MapViewer blog

2008-09-02T13:15:00.003-04:00

Welcome to my blog on Oracle MapViewer.

My name is Liujian (LJ) Qian and I'm the development manager of the MapViewer product.

Now, a brief introduction on MapViewer.

MapViewer is a web mapping product designed to work with Oracle's Spatial database technologies. It is a middle-tier component that runs inside Oracle's middleware, such as the WebLogic server. You can however deploy MapViewer to other J2EE containers such as JBoss or Tomcat.

We are currently finishing up the next major release of MapViewer which is 11g. As usual it will be released as part of Oracle's Fusion Middleware 11g product, which is currently scheduled for first half of CY 2009.

We are also preparing a new 10g patch for MapViewer which will be available through metalink and OTN.

On the backend, MapViewer connects to one or more Oracle databases where your spatial data are managed. On the frontend, MapViewer provides a comprehensive JavaScript/AJAX mapping API. MapViewer also provides Java and XML APIs. Inside each MapViewer middletire process there is a core rendering engine, a map tile server and a Feature of Interest (FOI) server.

So what distinguishes MapViewer from other online mapping server products? Here are a few that come to mind:

SQL query driven data layers. A map produced by MapViewer may contain many layers (themes), and each theme is based on a SQL query. MapViewer places no restriction on what kind of query you can have. As long as the query returns spatial data (with or without regular attribute data), MapViewer will treat it as a valid theme and display it.
Full support of Oracle Spatial database technologies: advanced spatial data models such as Topology, Network Data Model, GeoRaster. Full support of the concept of Workspace (for long transactions), Partitioning, as well as RAC (Real Application Cluster) and Label based security et al.
A powerful desktop map authoring tool called Map Builder. Map Builder is a Java desktop application. You use it to connect to a database schema and it will discover all the spatial data stored in there. You can then create base maps, themes and rendering styles that suit your business mapping needs. Definitions of such metadata (including styles themselves) are all stored in the database and shared among all MapBuilder and MapViewer instances that connect to the same database schema.
A very capable Web2.0 JavaScript mapping API that provides interactive draggable map as well as Feature of Interest (FOI) layers that are fully clickable with customizable info window.
Full integration with many other Oracle products, such as BIEE and Oracle Apps. A native application development wizard is also being built right inside Oracle JDeveloper 11g.
Takes full advantage of Oracle Middleware features, such as WebLogic's clustering and management functions.