Introduces you to the predefined reader/writer classes supplied with JViews Maps.

The predefined reader/writer classes supplied with JViews Maps are defined in subpackages of the ilog.views.maps.format package.

The class diagram for the pivot format reader and writer is shown in Pivot Format Reader and Writer UML Diagram.

Saving a map can produce two files:

The .ivl file

The .ivl format is the standard Rogue Wave® JViews file format used to save an IlvManager object, see Saving and reading in The Essential JViews Framework. The file basically contains:

For example, in JViews Maps 8.1, the entire map model, and all related information, is stored in the IlvManager as named properties, see Map-specific manager properties, and saved in the .ivl file.

The .img File

To deliver the map reload performance currently achieved by JViews Maps, raster data for image objects is not saved in the .ivl file because this would slow down the .ivl file read time. Instead, all raster data is saved in a separate .img file. When reloading the map, this file can be mapped directly in memory (if allowed by the operating system) for fast access and virtually no parsing time.

Note that if the map does not contain an image, no .img file is generated with the .ivl file.

Finally, the .ivl and .img file extensions are defined by the Map Builder, but you are free to use the API to give any filename you want to the map you are saving. It is up to you to be consistent between the saving and loading processes.

In JViews Maps 8.1, maps can be saved in the proprietary .ivl file format. This is basically the regular Rogue Wave® JViews format slightly modified to improve the loading performance of maps containing large amounts of raster data.

To save a map:

To reload a map:

The map export API makes it easier for the user to export a part of a map to different output formats.

Class for exporting selected map features

The main class is the IlvMapExportManager. This class is responsible for exporting selected map features of a map through specified export plug-ins known as IlvMapExportManager.IlvMapExporter implementations.

Exporters

IlvMapExportManager.IlvMapExporter is an interface that defines the expected methods of any object capable of writing map features in sequence.

Two kind of exporters can be set on the IlvMapExportManager:

They are set by calling the methods setVectorialExporter and setRasterExporter on an IlvMapExportManager instance.

A region of export can also be set on the IlvMapExportManager so that map features outside this region are not exported.

Once the two exporters of a IlvMapExportManager object are properly set and configured, an array of IlvMapLayer instances of the map may be exported with the method exportMapLayers.

The IlvMapExportDialog class

The IlvMapExportDialog is a user-friendly dialog box class that lets the user choose:

Vectorial and raster exporters are registered with this dialog box through the methods registerVectorExporter and registerRasterExporter, and similarly are removed by calling unregisterVectorExporter and unregisterRasterExporter methods.

Describes the shapefile reader and writer classes and data sources.

The shapefile reader and writer classes

The class diagram for the shapefile reader and writer is shown in Shapefile Reader and Writer UML Diagram.

These classes are based on the Shapefile Specifications listed in the ESRI (Environmental Systems Research Institute) document: ESRI Shapefile Technical Specifications - An ESRI White Paper - July 1998.

The Shapefile format is the exchange format for vector maps of the ESRI. This format supports polygons, arcs, lines, and points. Each Shapefile contains one single theme, meaning that all the objects in the file are of the same type (either line, point, polygon, or another type of object). In the Shapefile format, a theme is essentially described with four different files:

This format does not contain information concerning the coordinate system used to reference the position of the graphic objects. Objects in Shapefiles are often positioned within a geographic coordinate system ( IlvGeographicCoordinateSystem), but this is far from being the rule.

The Shapefile format comprises the following classes:

The complete source code for an ESRI shapefile demonstration can be found at <installdir> /jviews-maps/samples/shape/index.html

The shape data source

The IlvShapeDataSource class is a specialized data source that reads ESRI shapefiles.

Reading Shapefiles

The easiest way of reading shapefiles is to use the dedicated data source:

In this example, the data source is simply invoked and started. You have to use the setManager method to specify the manager into which the graphic objects are inserted. Graphic objects are instances of IlvMapPolyline, IlvMapGraphicPath or IlvMapPoint, depending on the feature contained in the shapefile. Additionally, the data source creates an IlvMapLayer. You can specify a IlvMapStyle to change the rendering of the graphic objects in this layer.

Filtering Shapefiles

If the shape file you read has an associated dbf file, you can filter a subset of the file content through the setfilter method. For example, the following code will only load the records which have a "NAME" property with a value "usa".

Modifying graphic object rendering

The following example shows how to modify the rendering of the graphic objects produced by this data source by changing the style of the IlvMapLayer of the data source.

If you are not sure of the type of objects contained in the shape file, you can use the setAttribute method on the layer style, for example:

Classes for reading the shape format

The ilog.views.maps.format.shapefile package includes the following classes:

The IlvSHPReader class

The geometries stored in Shapefiles are not necessarily 2-D objects. Each point that makes up a shape object can be associated with measurements, or with measurements and an elevation.

Measurements are stored in an attribute of type IlvAttributeArray, which itself is stored in the map feature attribute of index 0.

The following are the shape types that are associated with measurements:

Elevations are stored in an attribute of type IlvAttributeArray, which itself is stored in the map feature attribute of index 1.

The following are the shape types that are associated with measurements and elevations:

Since the JViews Maps package does not have a predefined geometry to represent shape objects of type MULTIPATCH, which are essentially used for 3-D rendering, these are ignored. It is possible, however, to modify this behavior by subtyping the class IlvShapeSHPReader. Since shape objects are read in protected methods, modifying the reader to include new geometries requires minimal effort.

The IlvDBFReader class

This reader is used exclusively for reading a file of the .dbf format. It can be used to iterate over a file as follows:

If the reader has been created from a file and not from a URL, you can access map feature attributes directly by specifying their record number:

The IlvShapeFileReader class

This reader reads the .shp file storing geometries and the .dbf file storing attributes simultaneously, and merges the information into a single IlvMapFeature object.

It can be instantiated in one of three ways:

Classes for writing the shape format

The ilog.views.maps.format.shapefile package contains the following classes for writing Shapefiles.

The class IlvSHPWriter is used to generate the geometry and index parts of a Shapefile ( .shp and .shx files), while the IlvDBFWriter is used to write the attribute file ( .dbf extension).

Like with feature iterator, writing map features to a Shapefile consists of writing repeatedly map features using the methods writeFeature and writeAttributes, then call the close method of writers to flush the data and write the headers.

The IlvSHPWriter class

The IlvSHPWriter class manages the writing of geometries to a Shapefile, with the creation of the Shapefile index that allows direct access to Shapefile records.

The following example shows how to use this class to write the contents of a feature iterator to a file foo.shp, creating the index file at the same time.

The IlvDBFWriter and IlvDBFAttributeInfo classes

The IlvDBFWriter and IlvDBFAttributeInfo classes manage the writing of DBase III+ files ( .dbf files). These files contain records corresponding to attributes of geometries contained within a Shapefile.

As .dbf files need records with fixed-size fields, it is important to choose a field size that is large enough to contain all data of a field, as well as a size small enough not to waste data.

The goal of the class IlvDBFAttributeInfo is to complement IlvAttributeInfoProperty for the definition of record fields.

The following example shows how to write the contents of an iterator to a set of .shp, .shx and .dbf files:

Once again, the writers must be closed to write the headers correctly.

Shapefile load-on-demand

The Maps package provides classes to perform load-on-demand on Shapefiles. This is achieved by the use of specific spatial index files. These files, usually having an .idx extension, store relations between tiles and object identifiers that belong to these tiles. A class and a tool example are provided to generate these spatial index files. A generic tile loader is also provided to minimize the amount of code needed to implement the load-on-demand mechanism using Shapefiles.

The load-on-demand mechanism involves two classes in addition to the shape reader and the dbf reader: the IlvShapeFileIndex class and the IlvShapeSpatialIndex class. A utility class is also provided to generate the spatial index for a given Shapefile: the IlvShapeFileTiler class.

The mechanism used to store and retrieve objects by tiles is illustrated in the following diagram:

The Spatial Index file holds objects identifiers for each tile. Objects identifiers are their ordinal place in the IndexFile. Geometries are retrieved in the Shapefile using the IndexFile. In the following example, the tile [2, 1] (tiles indices begin at 0) contains identifiers 2, 5 and 9 referring to the geometries g2 g5 and g9.

The classes used to perform load-on-demand on the Shapefiles are:

The IlvShapeFileIndex Class

This class allows you to directly access geometries in a Shapefile. The spatial index and the Shapefile must correspond to the same theme:

The IlvShapeSpatialIndex Class

This class stores tile information: tile size and count, and identifiers of the objects belonging to each tile. To retrieve objects from a tile specified by its row and column, use the getIdArray method:

The IlvShapeFileTiler Class

This class is used to generate tiling information from a given Shapefile. To use this class you have to provide the Shapefile to tile, the SpatialIndexFile to write to, and either the tile size or the number of rows and columns.

The above code extract produces a SpatialIndexFile named example.idx with a tile size of width 5 and height 10.

The above code extract produces a SpatialIndexFile of 600 tiles, 20 columns and 30 rows.

The IlvTiledShapeDataSource

The IlvTiledShapeDataSource is the tiled version of the IlvShapeDataSource. This means that it takes advantage of the tiling and load-on-demand mechanism. To read a tiled shapefile with such a data source, you can use the following code:

The IlvShapeFileTileLoader Class

This class implements load-on-demand for tiled Shapefiles. When associated with an IlvTiledLayer, this class automatically handles tile loading if the Shapefile file name, the IndexFile file name, and the SpatialIndexFile file name are provided. An optional Dbase file name can also be provided to load object attributes.

Describes the MID/MIF reading and rendering classes and data sources.

The MID/MIF classes

The class diagram for the mid/mif reader is shown in MID/MIF Reader UML Diagram.

This section describes the ilog.views.maps.format.midmif package, which allows you to read files provided in the MapInfo Interchange File (MIF) format.

A MapInfo Interchange Format consists of a MIF file containing the geometries and rendering attributes, and a MID file containing the attributes attached to each geometry.

The MIF file is an ASCII text file that describes the geometry data associated with rendering attributes such as pen and brush styles, font, and color that should be used to transform geometries into graphic objects. The reader classes provided with the JViews Maps package allow you to use either the information contained in the MIF file or your own rendering attributes.

The MID file contains attributes, which are nongraphical additional information associated with the geometries contained in the MIF file.

The MID/MIF Reader contains the following classes:

The MIDMIF data source

The IlvMIDMIFDataSource class is a specialized data source that reads MIDMIF files. It wraps all MIDMIF file rendering processes.

The IlvMIFDMIFDataSource produces a IlvMapLayer for objects having the same geometries and similar graphic attributes. If, however, a MIDMIF file contains lines whose color attributes are different, for example, red and blue, two layers are created, one for the blue lines and one for the red lines.

Classes for reading the MapInfo Interchange File format

The JViews Maps package provides all the necessary classes to read data provided in the MapInfo Interchange File (MIF) format. In addition to these classes, the JViews Maps package also provides the IlvGraphic classes needed to render specific MIF objects.

The classes used to read MapInfo Interchange files are:

The IlvMIDMIFReader class

This class reads both MIF file and MID file by providing a MIF file name and a MID file name. If the MID file name is set to null, no attribute is loaded. If the MID file name corresponds to a valid MID file, the attributes are read from the file and attached to the IlvMapFeature returned by the reader.

The IlvMIFReader class

This is the class that reads a single MIF file, providing a MIF file name or a reader to the constructor. You can then iterate to obtain the IlvMapFeatures of the file, but you can also obtain information about the MIF file you are reading, such as:

Note that the coordinate system returned by the reader can be null even if the MapInfo specifications consider the geometries to be in the Geographic coordinate system if none is specified in the MIF file.

The IlvMIDReader class

This class reads a MID file. You must have previously opened the corresponding MIF file, in order to build the second argument of the MID reader ( IlvAttributeInfoProperty) that is provided in the MIF file.

Classes for rendering the MapInfo Interchange File format

Since the MIF file can contain rendering information, the JViews Maps package provides classes to use this rendering information directly. This includes a ready-to-use IlvFeatureRenderer suitable to render geometries found in the MIF file and a factory to create IlvMapLineRenderingStyle.

In addition to these rendering classes, the JViews Maps package also provides a set of specific IlvGraphic objects to display the MID/MIF geometries. These IlvGraphic objects are needed by the MID/MIF specifications but can also be used outside a MID/MIF context.

The IlvMIFFeatureRenderer Class

This class is a subclass of the IlvDefaultFeatureRenderer that dispatches on the appropriate renderer with the rendering styles found in the MIF file. This is the IlvFeatureRenderer returned by the getDefaultFeatureRenderer method of the IlvMIFReader class. The rendering styles found in the MIF file are attached to the IlvMapFeature as properties by the reader and interpreted in the renderer.

The IlvMIFPenFactory Class

This class is a factory to create an IlvMapLineRenderingStyle by specifying a MID/MIF pattern identifier.

The IlvMIFCoordinateSystemFactory Class

This class is a factory to translate a MID/MIF coordinate system into a Maps coordinate system.

Specialized Graphics

The IlvGraphic objects needed to render MID/MIF geometries include the following classes:

Coordinate System Support

Along with objects and attribute information, MIF files also contain information on the coordinate system used to store the graphic objects of a defined file.

The possible coordinate systems in MID/MIF are:

The JViews Maps package fully supports projected coordinates defined in a MID/MIF file. The supported projections are listed in List of Supported MID/MIF Projections:

JViews Maps supports all ellipsoids and nearly all datums from MapInfo (see the MID/MIF file format specification for the full list of ellipsoids and datums).

You can use the DTED® file reader to read Digital Terrain Elevation Data (DTED format) files. The DTED read format is a map format for representing terrain elevations published by the U.S. National Imagery and Mapping Agency (NIMA). The DTED files contain digital terrain models as rasters. A raster is a georeferenced grid containing a value in each of its cells. In the case of DTED, and a digital terrain model in general, the value indicates the average elevation in the cell. However, this value can indicate any other attribute: surface temperature, surface pressure, nitrogen rating of the soil, and so on.

The DTED reader provided in this package is based on the specification document MIL-PRF-89020A of 19 April 1996. DTED files are available with various precision levels, called DTED0, DTED1, and DTED2. A DTED file contains a digital terrain model raster that covers a zone of one degree by one degree. The cell size of the raster depends on the DTED level:

The complete source code for a DTED demonstration can be found at

<installdir> /jviews-maps/samples/dted/index.html.

The DTED raster reader

The following code shows how to use an IlvRasterDTEDReader to load a single DTED file using the IlvMapDataSource:

The following code shows how to read a set of DTED files using an IlvTiledRasterDataSource. This produces an IlvMapLayer containing an IlvTiledLayer holding the tiles.

Classes for reading the DTED format

The main class for reading DTED formats is IlvDTEDReader. This class implements the IlvMapFeatureIterator interface and returns only one IlvMapFeature object, which is the raster corresponding to the digital terrain model (DTM) stored in the file. The geometry of this map feature is of type IlvMapRaster. The map feature has no attribute. The projection of the reader is the source projection of the DTED data, that is, the geographic projection.

The IlvDTEDLayer class defines load-on-demand for the DTED format. Load-on-demand is implemented on a DTED-level basis from the corresponding file name or URL. In other words, the size of a tile in a JViews Maps tiled layer corresponds to the size of a DTED tile. This specific implementation of load-on-demand works exclusively with maps drawn with the geographic projection. Specifying a URL allows you to access one of the NIMA CDs directly from their website. For an example, see the DTED demonstration at the following location:

<installdir> /jviews-maps/samples/dted/index.html.

The formats handled by the generic image file reader, which are GIF, PNG and JPEG, are supported by the Java™ Platform, Standard Edition. An image coded in one of these formats does not contain any geo-referencing information, so this information has to be known before loading this kind of image. This is also true for TIFF images that do not contain GeoTIFF tags. Below you can find a description of the IlvRasterBasicImageReader, the IlvImageReader class and IlvImageTileLoader class.

The IlvRasterBasicImageReader class

The IlvRasterBasicImageReader class is a GIF, JPG, PNG or TIFF reader that creates reprojectable, stylable, and pixel-on-demand images.

Creating an image reader

You need first to create an image reader, and add the image file to be read:

As these images have no longitude or latitude information, you need to geo-reference this image. The easiest way to do this is to set the image bounds in longitude and latitude. This obviously works only for images that have a spatial coverage along lines of longitude and latitude. For advanced management of more complex images, the Map Builder provides an image transformation model that manages reprojection and image interpolation ( ImageControlModel class).

In the example below, you set the image to cover the entire earth:

Creating a data source

Once you have created the reader, you need to create a data source, which should be integrated into the manager properties:

Reading the data

You can then start reading your data:

Starting the data source creates the necessary tiled layers, tile managers and IlvRasterIcon instances to manage the pixel-on-demand feature and the progressive display of the new geo-referenced image.

You can also create a subsampled preview of an image, using code such as:

The IlvImageReader class

If you do not need image the reprojection, styling or pixel-on-demand features, but simply want to insert and geo-reference a single GIF, JPG or PNG image, you can use the IlvImageReader class.

This class implements the IlvMapFeatureIterator interface. It returns only one IlvMapFeature object, which is the image stored in the file.

The geometry of this map feature is of type IlvMapImage. The map feature has no attributes. To use this reader you have to provide a file name and the coordinates of this image.

The IlvImageTileLoader class

If you do not need image reprojection, styling or pixel-on-demand features, but have access to a set of images, you can use the IlvImageTileLoader class.

This class is used to read a set of images that are part of a larger image. This tile loader allows an application to load only the images that are visible at a given time, each image corresponding to a tile. Each file must be named so that it is possible to construct its file name knowing the row index and column index of the corresponding tile. To use this tile loader, you must provide the information needed to reconstruct the file name for a given tile: a pattern that matches the file naming scheme and two formatting strings.

The pattern argument must contain one ‘%r’ and one ‘%c’ conversion specifier. The %r conversion specifier is used to convert the row index of the tile, and the %c conversion specifier is used to convert the column index of the tile. These conversion parameters are replaced accordingly with the rowFormatString and the colFormatString parameters. This format string is used to construct two java.text.DecimalFormat strings.

Describes the IBM spatial databases (DB2 and Informix) reader classes, how to use them through data sources, and how to use tiling and multithreading.

The IBM spatial database reader classes

The class diagram for the IBM® spatial database reader is shown in the following IBM spatial database readers UML diagram.

The IBM database spatial readers allow you to retrieve information from IBM® DB2® Spatial Extender and IBM® Informix® Spatial DataBlade™ georeferenced databases, and the use of such map data in a Rogue Wave® JViews application.

Using the DB2 spatial data source

The IlvDB2DataSource class is an IlvMapDataSource for reading georeferenced objects from a DB2® spatial database. It wraps up all operations (connecting to database, reading features, rendering them to graphic objects) in a convenient way.

To read a map stored in an DB2 spatial database:

Using the Informix spatial data source

The IlvInformixDataSource class is an IlvMapDataSource for reading georeferenced objects from an Informix® spatial datablade. It wraps up all operations (connecting to database, reading features, rendering them to graphic objects) in a convenient way.

To read a map stored in an Informix spatial datablade:

Getting a list of layers

To get a list of layers available in an IBM®spatial database, you need first to set up your connection, and then:

Describes the Oracle® reader and writer classes, using data sources, how to use tiling, multithreading and exporting to an SDO database.

The Oracle spatial reader and writer classes

The class diagram for the Oracle® spatial reader and writer is shown in Oracle Spatial Reader and Writer UML Diagram.

Oracle SDO, or Oracle Spatial, is the spatial extension of Oracle in its version 7.3. This extension has been renamed to Spatial Cartridge in the version 8.0 and has been renamed again to Oracle Spatial in the version 8i.

The classes are based on the relational implementation of Oracle Spatial available since Oracle 7.3. It contains classes that facilitate the use of map data (stored in an Oracle database) in an Rogue Wave® JViews application. 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 intersect a specific polygon.

Oracle has written two implementations of Oracle Spatial:

The Oracle reader of JViews Maps supports reading and writing data in the relational and the object relational model of Oracle Spatial through two different packages:

The Oracle Spatial Reader and Writer comprises the following classes:

The complete source code for an Oracle Reader demonstration can be found at <installdir> /jviews-maps/samples/oracle/index.html.

Using the Oracle SDO data source

The IlvSDODataSource class is an IlvMapDataSource for reading georeferenced objects from an Oracle® SDO (formerly Oracle Spatial) database. It relies on the Oracle SDO API that was introduced in former versions of the JViews Maps product, but wraps up all operations (connecting to database, reading features, rendering them to graphic objects) in a more convenient way.

To read a map stored in an Oracle SDO database:

Using tiling and multithreading

To benefit from Rogue Wave® JViews Maps advanced image tiling capabilities and multithreading, use IlvTiledRasterDataSource in the place of IlvSDODataSource

To use a tiled data source:

Getting a list of layers

To get a list of layers available in the Oracle® database, you can do as follows:

Relational model classes

Classes for reading data from an Oracle spatial relational model database

The reader classes for Oracle® SDO relational model (package ilog.views.maps.format.oracle) are:

The IlvSDOFeatureIterator class

The IlvSDOFeatureIterator class reads data from the result of an SQL query to a relational Oracle Spatial layer and converts them into IlvMapFeature objects. JViews Maps applications can handle Oracle Spatial data using this class in a transparent manner.

The following example of Java™ code performs a query, loading data from an Oracle Spatial layer named ROADS_SDOGEOM. It includes classes from the java.sql package:

The connection variable is a java.sql.Connection object.

The query orders the result using the following three criteria, which must be given in the order indicated:

The ResultSet of any query to an Oracle Spatial layer can be used to initialize an IlvSDOFeatureIterator, but all the SDO columns must be in the resultSet (columns defining the GID, ESEQ, ETYPE, SEQ, and the coordinates).

The features returned by this iterator have no attributes. However, the GID of the Oracle Spatial geometry is used as the identifier of each feature and this identifier can be used to retrieve additional attributes from the database. See the method getId.

The IlvSDOLayer class

This class implements load-on-demand for a relational Oracle Spatial data source. The default implementation takes an Oracle Spatial layer for which a spatial indexation has been performed and reads its content with a tiling equivalent to the Oracle Spatial tiling.

The following example creates an IlvSDOLayer on an Oracle Spatial layer named ROADS:

The IlvSDOTileLoader class

This class offers additional possibilities when retrieving data from an Oracle Spatial database. These possibilities are meant as a supplement to the default behavior of IlvSDOLayer. For example, you may want to add filters to a layer or to have a tiling definition that is different than the Oracle tiling.

The example in the file <installdir> /jviews-maps/samples/oracle/index.htmlshows how to implement a subclass IlvSDOTileLoader that uses spatial queries to retrieve data for a JViews Maps tile.

The IlvDefaultSDOTileLoader class

This class is a subclass of IlvSDOTileLoader and is used by the IlvSDOLayer. It has some optimizations. For example, the setTileGroupingCount method allows you to set the number of tiles that are grouped in one unique query to the database. In fact, each tile corresponds to a Spatial Query. If you have an average of n tiles to load each time you want to load on demand, you should use setTileGroupingCount(n), where all the n queries are grouped into one unique query that is sent to the database.

Class for writing data to an Oracle spatial relational model database

The IlvSDOWriter class allows you to write map features into a relational Oracle Spatial database.

The IlvSDOWriter class

The IlvSDOWriter class can write any IlvMapFeatureIterator whose features have a geometry supported by the relational model of Oracle Spatial and write them to the database as in the following example:

The write() method of the IlvSDOWriter does not write the attributes of the features. If you want to write the attributes of the features, you can subtype the writeFeature() method of the IlvSDOWriter, after calling super.writeFeature(feature).

The geometries supported by the Oracle Spatial writer are:

Object relational model classes

Since version 8.1.7, Oracle® Spatial allows spatial data to be georeferenced. Geometries can be georeferenced by associating a spatial reference ID (SRID) to each geometry. Coordinate systems associated to these SRIDs are defined in the table MDSYS.CS_SRS.

JViews Maps can import these reference systems using their OpenGIS WKT (Well Known Text) specifications, found in the MDSYS.CS_SRS table. If your data is not georeferenced, there is no need to change anything. The JViews Maps classes in the objectmodel package handle both georeferenced and nongeoreferenced data.

For more information, see the Oracle Spatial documentation (Coordinate Systems section) and Handling spatial reference systems.

Classes for reading data from an Oracle Spatial object relational model database

The reader classes for Oracle Spatial object relational model included in the package ilog.views.maps.format.oracle.objectmodel are:

The IlvObjectSDOFeatureIterator class

This class reads data from the result of an SQL query to a relational Oracle Spatial layer and converts the data into IlvMapFeature objects. The JViews Maps package applications can handle Oracle Spatial data using this class in a transparent way. The following example performs a query, loading data from an Oracle Spatial layer named ROADS:

The result set of any query to an Oracle Spatial layer can be used to initialize an IlvObjectSDOFeatureIterator, but the column containing the geometry must be in the result set.

The features returned by the iterator can have attributes and coordinate systems attached.

The IlvObjectSDOLayerMetaData and IlvObjectSDODimElement classes

These two classes correspond to two data structures defined in Oracle Spatial.

The IlvObjectSDOLayerMetaData class corresponds to the data contained in each row of the (XXX_)SDO_GEOM_METADATA view. This view contains information, called metadata, about Spatial layers. Each Spatial user has the following views available in the schema associated with that user (in Oracle 8.1.6+):

Each metadata view has the following definition:

In addition, the ALL_SDO_GEOM_METADATA and DBA_SDO_GEOM_METADATA views have an OWNER column identifying the schema that owns the table specified in TABLE_NAME.

You do not need to build metadata by hand: the IlvObjectSDOUtil method can help you retrieve the metadata directly from the database. For instance, if a Spatial layer is called ROADS, then you can retrieve its metadata as follows:

The IlvObjectSDOLayerMetaData class is then composed of the following elements that match the (XXX_)SDO_GEOM_METADATA view: the table name (the name of the Spatial layer), the geometry column name (called COLUMN_NAME in the view, the name of the column of type MDSYS.SDO_GEOMETRY ), the owner name, the optional SRID if the Spatial layer is georeferenced, and an array of IlvObjectSDODimElement (called DIMINFO in the view).

The IlvObjectSDODimElement corresponds to the MDSYS.SDO_DIM_ELEMENT data type. The MDSYS.SDO_DIM_ELEMENT data type is defined in Oracle as:

The DIM element data type describes, for each Spatial Layer, its extent for each dimension. For instance, for typical two-dimensional geometries, the DIM element array of the metadata table has two entries. The first entry describes the first dimension (x, longitude), the second one describes the second dimension (y, latitude).

The IlvObjectSDOKeyExtractor and IlvDefaultObjectSDOKeyExtractor classes

The IlvObjectSDOKeyExtractor class is an interface associated with feature iterators and tile loaders. Its main purpose is to associate an object with the map feature read by the iterator or the tile loader.

This object is supposed to be unique, so that the next time the feature iterator meets the object, it is not process the geometry in the corresponding row, considering that this geometry has already been loaded.

The goal is to avoid multiple loading of the same geometry. This interface extracts a key from a ResultSet using the extractKey(java.sql.ResultSet) method. The object returned can be extracted from one Table column or multiple columns as soon as it constitutes a unique object.

The red rectangle belongs to the tile (2, 2) and (2, 3). When the load method of the tile (2, 2) is called, it loads the rectangle. When the load method of the tile (2, 3) is called, the rectangle is loaded again as soon as it intersects with this tile too, and the tile loader has no way to know that this geometry has already been loaded. You can avoid this by using the IlvObjectSDOKeyExtractor class.

The IlvDefaultObjectSDOKeyExtractor is a default class that implements the key extraction behavior from one Table column. For example, given the previous schema let us suppose that the Spatial Layer is:

The IlvDefaultObjectSDOKeyExtractor used with this layer can be easily obtained in the following way:

Then, this extractor can be associated with an IlvObjectSDOLayer, or an IlvDefaultObjectSDOTileLoader.

The IlvObjectSDOLayer class

This class implements load-on-demand for an object Oracle Spatial data source. The default implementation takes an Oracle Spatial layer for which a spatial indexation has been performed and reads its content.

The following example creates an IlvObjectSDOLayer on an Oracle Spatial layer named ROADS:

The IlvDefaultObjectSDOTileLoader class

This class is a subclass of IlvSDOTileLoader and is used by the IlvObjectSDOLayer. It has some optimizations.

For example, the method setTileGroupingCount allows you to set the number of tiles that are grouped in one unique query to the database. In fact, each tile corresponds to a Spatial Query, and if you have an average of n tiles to load each time you want to load on demand, you should use setTileGroupingCount(n), where all the n queries are grouped into one unique query that is sent to the database once.

Another interesting method of this class is the setRequestParameters method.

This method allows you, for instance, to set the spatial operator used to query the layer. The default operator is SDO_FILTER.

Tiles shows a Spatial layer using a fixed tiling of level 2. The red rectangle is the area queried by the tile loader. If the SDO_FILTER operator is used (default case), all the geometries belonging to the Oracle Spatial Tiles intersecting with the red rectangle fit the request. In the case of Tiles, all the geometries belonging to the tiles (2,2), (2,3), (3,2), and (3,3), for example the line, the point, the triangle, the circle, and the rectangle are retrieved.

You may not want to retrieve the geometries that do not explicitly intersect with the red rectangle (for example, the circle and the rectangle geometries here). In this case, you have two choices.

Finally, note that the SDO_RELATE Spatial operator is slower than the SDO_FILTER operator.

Class for writing data to an Oracle Spatial object relational model database

This section presents the IlvObjectSDOWriter class, which allows you to write map features into an Object Oracle Spatial database.

The class IlvObjectSDOWriter can write any IlvMapFeature or any IlvMapFeatureIterator whose features have a geometry supported by Oracle Spatial 8i (vectorial geometries) and write them to the database as in the following example:

The writeFeature method of the IlvObjectSDOWriter can also write the attributes of the feature.

The method writeFeature has a second argument that can be set to true to save the attributes of the specified map feature. This requires that the map feature has an IlvAttributeInfoProperty correctly set, describing the attributes that match the Oracle Spatial layer column names. This also requires that map feature has an IlvFeatureAttributeProperty IlvFeatureAttributeProperty that fits its IlvAttributeInfoProperty and has correct values.

For instance, if you have an Oracle Spatial layer called ROADS that has the following description in the database:

 

The third argument of the writeFeature() method allows you to set the SDO_SRID value of the written SDO_GEOMETRY. The value of the SDO_SRID is exactly one of the SRID values of the MDSYS.CS_SRS table, and it represents the corresponding coordinate system for the written geometry.

The following code extract shows how to write features with a unique attribute into the database:

The writer can update rows in the SDO layer. This is based on a key mechanism, where the row(s) having the value of the given key are updated. The update is done through the following methods from the IlvObjectSDOWriter class:

Oracle SDO export

In addition to the IlvSDOWriter and IlvObjectSDOWriter classes used to store georeferenced objects to an Oracle® database (see The Oracle spatial reader and writer classes), you can export part of a map to a SDO database using the map export API (see Map Export API). To do so, you just need to set an IlvSDOExporter as the vectorial exporter on the IlvMapExportManager.

The GeoTIFF reader (see GeoTIFF format) is based on some extension packages such as Batik Apache™ TIFF Reader, an open source API included in the JViews Maps jar files.

The GeoTIFF format is an extension of the TIFF (Tagged Image File Format) format. The TIFF format is an image file format that allows tags to be inserted in the file. These tags give information about the image contained in the file, such as the resolution, the number of samples per pixel, and so on. The GeoTIFF extension adds specific cartographic tags that give geographic information about the image contained in the file, such as the coordinate system in which the image is represented, and the location of the image in this coordinate system.

The official TIFF specification can be found on http://partners.adobe.com/public/developer/tiff/index.html.

More information about the GeoTIFF format can be found at:

The source code for the Map Builder demonstration, which contains all of the code described in this section, can be found at <installdir> /jviews-maps/samples/mapbuilder/index.html

The IlvRasterGeoTiffReader class

The IlvRasterGeoTiffReader class is a GeoTIFF file reader that creates reprojectable, stylable, and pixel-on-demand images.

Creating an image reader

You need first to create an image reader, and then add the image file to be read:

The geo-reference information is decoded from the GeoTIFF file, by means of an IlvGeotiffReader.

Creating a data source

Once you have created the reader, you need to create a data source, which should be linked with the manager properties by inserting it into the data source tree:

Reading the data

You can then start reading your data:

Starting the data source creates the necessary tiled layers, tile managers, and IlvRasterIcon instances to manage the pixel-on-demand feature and the progressive display of the geo-referenced image.

The IlvGeotiffReader class

The IlvGeotiffReader class implements the IlvMapFeatureIterator interface. The getNextFeature method returns an IlvMapImage geometry which contains a TIFFImage object. The TIFF image can then be rendered by the IlvDefaultImageRenderer to produce an IlvIcon, or be transformed by data sources into a tiled IlvRasterIcon.

The TIFF reader can take two parameters as arguments: the TIFF file name and a file that contains a connection between the tag describing the coordinate system used by the image and the corresponding WKT string. The reader retrieves the coordinate system of the image in a WKT format if the image contains the appropriate tag, and then retrieves the IlvCoordinateSystem through the IlvWKTCoordinateSystemDictionary class. This coordinate system is then available through the getCoordinateSystem method.

The default constructor, however, only takes the TIFF file name parameter and uses an internal WKT file (wktdictionary.txt) found in Rogue Wave® JViews jar files.

The reader can be used in the same way as any reader that conforms to the Maps reader framework:

The acronym TIGER® comes from Topologically Integrated Geographic Encoding and Referencing, which is the name for the system and digital database developed at the U.S. Census Bureau to support its mapping needs for the Decennial Census and other Bureau programs.

The TIGER/Line files are a digital database of geographic features, such as roads, railroads, rivers, lakes, legal boundaries, census statistical boundaries, and so on, covering the entire United States. The database contains information about these features, such as, their location in latitude and longitude, the name of the feature, the type of feature, address ranges for most streets, the geographic relationship to other features, and other related information. TIGER/Line® files are a public product created from the TIGER database of the Census Bureau.

The source code for the Map Builder demonstration, which contains all of the code described in this section, can be found at <installdir> /jviews-maps/samples/mapbuilder/index.html.

The IlvTigerDataSource class

The IlvTigerDataSource class is a data source that reads TIGER/Line files. This data source is filtered so that only selected features can be read from the file, the others being ignored. These features can be supplied in code as an array of strings or can be retrieved from a IlvFeatureSelectorPanel configured with the TigerFeaturesEN.txt file. This file contains the list of the Census Feature Class Codes (CFCCs) and a description of the corresponding features. Use the following lines to supply the CFCCs in the code:

To retrieve the CFCC codes from an IlvFeatureSelectiorPanel, you can use the following code, which creates, instantiates and starts a TIGER/Line data source with the selected features:

The IlvTigerReader class

The IlvTigerReader class reads TIGER/Line files. It can be used independently, but it is usually created through the use of a IlvTigerDataSource. The method recordMatches can be overridden to select features to be read or discarded by the TIGER/Line reader.

List of CFCC codes

See http://www.census.gov/geo/www/tiger.

There are two ways of reading DXF format files:

The source code for the Map Builder demonstration, which contains all of the code described in this section, can be found at <installdir> /jviews-maps/samples/mapbuilder/index.html.

To read the DXF features and create vector data using the DXF readerobject:

To read DXF features and create vector data using the DXF data source:

Describes the KML reader and writer and exporting KML files.

The KML reader and writer

There are two ways of reading KML/ KMZ files:

The source code for the Map Builder demonstration, which contains all the code described in this section, can be found at <installdir> /jviews-maps/samples/mapbuilder/index.html.

To read KML features and create vector data using the IlvKMLReader object:

To read KML features and create vector data using the IlvKMLDataSource:

Exporting KML files

You can export part of a map to a KML (or KMZ) file using the Map Export API (see Map Export API). To do so, set an IlvKMLExporter as the vectorial exporter on the IlvMapExportManager. You can also use the raster exporter, if you want to export an overlaid image.

GTOPO30 is a global digital elevation model (DEM) with a horizontal grid spacing of 30 arc seconds (approximately 1 kilometer). It covers the full extent of latitude from 90 degrees south to 90 degrees north, and the full extent of longitude from 180 degrees west to 180 degrees east. The vertical units represent elevation in meters above mean sea level. In the DEM, ocean areas have been masked as "no data" and have been assigned a value of -9999.

A full sample of a GTOPO30 database can be downloaded from: http://edcdaac.usgs.gov/gtopo30/gtopo30.asp.

The source code for the Map Builder demonstration, which contains all of the code described in this section, can be found at <installdir> /jviews-maps/samples/mapbuilder/index.html.

The IlvGTopo30Reader class is a file reader that creates reprojectable, stylable and pixel-on-demand images that can provide altitude data.

To create images:

Starting the data source creates the necessary tiled layers, tile managers and IlvRasterIcon instances to manage the pixel-on-demand feature and the progressive display of the geo-referenced image.

This icon associates altitude properties that can be used as altitude data sources, see Using the altitude provider property.

The OpenGIS® Web Map Service (WMS standard) Implementation Specification produces maps of spatially referenced data dynamically from geographic information. This international standard defines a map to be a portrayal of geographic information as a digital image file suitable for display on a computer screen. The OpenGIS standard provides three operations ( GetCapabilities, GetMap, and GetFeatureInfo ) in support of the creation and display of registered and superimposed map-like views of information that come simultaneously from multiple remote and heterogeneous sources. For more information about the OpenGIS standard, see http://www.opengeospatial.org/.

There are two ways of reading images from a Web Map Server (WMS):

The source code for the Map Builder demonstration, which contains all the code described in this section, can be found at <installdir> /jviews-maps/samples/mapbuilder/index.html.

The IlvWMSReader class reads image features from a specified Web Map Server URL. It implements the IlvMapFeatureIterator interface to iterate over the read features.

The IlvWMSDataSource class provides a convenient way of creating a set of layers containing images retrieved from a Web Map Server in a manager.

To read WMS features from a Web Map Server using the IlvWMSReader class and create raster data:

To read WMS features using the IlvWMSDataSource class:

There are two ways of reading SVG files:

The source code for the Map Builder demonstration, which contains all of the code described in this section, can be found at <installdir> /jviews-maps/samples/mapbuilder/index.html.

To read SVG features and create vector data:

To read SVG features and create vector data: