Perforce JViews Maps Sample: Connecting to an Oracle Geo-Database

Description

This sample shows how you can use Perforce JViews Maps with GIS Map Servers such as Oracle Spatial, also known as Oracle SDO (Object model).

How to Use the Sample

To run this demo, an Oracle driver for Java is required (you can find the free thin driver at the Oracle site: here ).
For more information, contact your Oracle DB administrator (who can help you define the correct connection parameters).
This sample uses the ilog.views.maps.format.oracle package for relational implementation, available since Oracle 7.3, and ilog.views.maps.format.oracle.objectmodel that is based on the object implementation of Oracle Spatial, available since Oracle 8.0.
It has been run on Oracle version 7.3 to 10.2 databases using the 'thin' driver. This driver requires no particular Oracle Client on the client machine.
You will then need to do the following:
- Edit the <installdir>/samples/mapbuilder/build.xml file, in order to specify the jar library containing the Oracle driver for JDBC. Check that the driver you want to use is compatible with your database, then add the driver jar filename to the 'jviews.manifest.classpath' entry in the <installdir>/samples/ibmdb/build.xml file. For example for Windows:
```
    <property name='jviews.sample.manifest.classpath'
              value='file:///d:/oracle/java/ojdbc-14.jar'/>
```
  For example for Linux and Unix:
```
    <property name='jviews.sample.manifest.classpath'
              value='file://opt/oracle/java/ojdbc-14.jar'/>
```
- To be able to retrieve raster data from your database, you need the oracle xdb.jar and xmlparserv2.jar libraries.
  They are part of Oracle XDK 10g installation, that is available here.
  Copy these 2 jar files from your Oracle XDK 10g installation (in the /lib folder) into the <JVIEWS_INSTALL_DIR>/jviews-maps900/lib/external/ folder. Jar names must be xdb-10.2.0.1.0.jar and xmlparserv2-10.2.0.1.0.jar.
  If your Oracle XDK 10g installation contains newer versions of these libraries, you must edit the build.xml file of this sample to specify their names instead.
- Clean and rebuild the sample by calling clean.bat followed by build.bat
To be able to import Oracle Spatial layers, you must have access to an Oracle Server with the Spatial Option and certain privileges that allow you to write to your Oracle database and retrieve data. You also need an Oracle account with read/write access to the SDO packages.
For more information, contact your Oracle DB administrator (who can help you define the correct connection parameters).

How to Run the Sample as an Application

This sample can be run as an application. The installation directory contains an executable JAR file, oracle.jar, that allows you to execute the sample with a double click from a file browser. Note that if you are using Internet Explorer, you can open the installation directory and execute the JAR file from the browser. This technique may not work in other Web browsers.

Alternatively, you can run the sample application from the command line. First check that the Ant utility is properly configured. If not, see the instructions on how to configure Ant for Perforce JViews.

Then, go to the installation directory of the sample and type:

ant run

Topics Covered

Loading Oracle Spatial records.
Saving Oracle Spatial records.

Detailed Description

This sample shows how you can use Perforce JViews Maps with GIS Map Servers such as Oracle Spatial, also known as Oracle SDO (Object model).

This sample provides source code that shows you how to:

Export vector data read by a Perforce JViews Maps Reader to an Oracle Spatial database. For example you can export ESRI Shapefiles (a vectorial map format read by Perforce JViews), but not .ivl files, which are not a map format.
Import vector data from an Oracle Spatial Database into Perforce JViews.
Implement load-on-demand with data imported from an Oracle Spatial database.

The specific parts of the Oracle Spatial sample UI are:

: Loads a shapefile using an ESRI shape data source (IlvShapeDatasource).

: Saves the current map file to a Spatial layer.

: Loads a Spatial layer (full load or on-demand).

: Closes any open connection to Oracle Database.
This sample uses the package ilog.views.maps.format.oracle.objectmodel (based on the object implementation of Oracle Spatial, and available since Oracle 8.0). It has been run on Oracle 9.0.1 and 10.1.0 databases using the 'thin' driver which requires no particular Oracle Client on the client machine. Note that the objectmodel package has been optimized (it can operate up to 2 times faster,) for the use of the Oracle thin driver supplied with version 8.1.7 and later.

About Oracle Spatial

Oracle Spatial (or Oracle SDO) is the spatial extension of Oracle in version 7.3.
This extension was renamed to Spatial Cartridge in the 8.0 version, and has been renamed again to Oracle Spatial in the 8i version.
Oracle Spatial allows you to store georeferenced objects in an Oracle database and to perform spatial queries, such as getting the list of objects that intersects a specific polygon, and so on.

The implementation of Spatial is much simpler in the Object model: all you need is a table ("layerName") that contains at least one Geometry column of type MDSYS.SDO_GEOMETRY. The existence of a spatial index is mandatory for load-on-demand through the IlvObjectSDOLayer class. For more information about this extension, refer to the Oracle online documentation.

How Does It Work?

The IlvSDOWriter class can transfer the data from any Perforce JViews Maps reader implementing the IlvMapFeatureIterator interface to an Oracle layer. The only constraint is that the geometric objects returned by the map reader must be supported in Oracle. They must be line strings, polygons, or points. For example, you can load an ESRI Shapefile into the sample and choose to save the created layer to the Oracle DB. The SDO layer will be named after the map layer created from the shapefile. You can change it by editing the layer tree node.
The IlvObjectSDOWriter class supports the Object model and some new geometries such as multipoint, multilinestring, and multipolygon.

The IlvSDOFeatureIterator and IlvObjectSDOFeatureIterator classes can import the result of an Oracle Spatial query into Perforce JViews Maps. They implement the IlvMapFeatureIterator interface of the Perforce JViews Maps reader framework, and can then be used like any other Perforce JViews Maps source. For example, you can load all the data contained in an SDO layer by choosing the "Load layer from DataBase" menu in the sample.

Note that the sample has a debug function: the SQL Traces, which can be enabled to show all SQL queries before they are sent to the DB.