The Pivot Format Reader and Writer

Programming with JViews Maps > Introducing the Main Classes > Readers and Writers > The Pivot Format Reader and Writer

The Pivot Format Reader and Writer

The class relationship for the pivot format reader and writer is shown in Figure 1.4.

Figure 1.4 Pivot Format Reader and Writer UML Diagram

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

Saved Files Description

Saving a map can produce two files:

A mandatory.ivl file, containing all information about the map and all map objects (unless only the theme is saved, see Saving a Map).
An.img file, containing the map raster data in a proprietary format for fast access when reloading. This file is not produced if the map does not contain an image.

The .ivl File

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

The IlvManagerLayers of the manager, which themselves contain all of the graphic objects.
All additional IlvNamedProperty objects attached to the IlvManagerLayers.

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.

Saving a Map

Here are the steps to follow to save a map:

Create an IlvMapOutputStream object from a filename. This class extends the IlvOutputStream (see Input/Output Operations in The Essential JViews Framework) and provides the option of not saving the layers (and hence the graphic objects) contained in an IlvManager. You can choose to write the file in binary format, which is more compact, or in ASCII format, which is more readable.

String mapFilename = "myMap.ivl";

boolean binary = false;

IlvMapOutputStream mapOutput = new IlvMapOutputStream(mapFilename, binary);

Note that when using the above IlvMapOutputStream constructor, the name of the image file (see The .img File) is inferred from the specified map filename, by adding the .img extension or by replacing the ivl extension by .img. You can also create the IlvMapOutputStream with a different constructor, specifying a java.io.OutputStream to save the map contents to, and a different filename for the .img file. In this case, you must use the appropriate matching constructor of IlvMapInputStream when loading the map, see Reloading a Map for more information.

Optionally:

Save only the map theme. When reloading a theme file only, all IlvMapDataSource instances of the model are started again so that they can read data from their original files and reconstruct the map. This is useful if the original data sources (ESRI Shape, DTED and so on) are available when reloading the .ivl file (when working on the same machine for example, or on the same network if data formats are stored on a networked resource). The file produced is small, typically only a few tens of KB:

mapOutput.setWritingObjects(false);

Conversely, if you plan on distributing the map without the original data sources, or if you want to achieve higher reload performance, you should consider saving all the data in the file:

mapOutput.setWritingObjects(true);

Write the manager to the IlvMapOutputStream and clean up the remaining resources:

try {

  mapOutput.write(manager);

} catch (IOException ex) {

  // handle I/O exception here......

Reloading a Map

Here are the steps to follow to reload a map:

First, it is best is to clear the current manager, see Clearing Map Data.
Create an IlvMapInputStream and use it to read the map file. This takes care of reconnecting read data with the corresponding read map model (data sources, map layers and so on).

String mapFilename = "myMap.ivl";

IlvMapInputStream mapInputStream = new IlvMapInputStream (mapFilename);

try {

   mapInputStream.read(manager);

}  catch (Exception ex) {

   // handle reading exceptions here

Note that when using the above IlvMapInputStream constructor, the .img file that goes with the .ivl file (passed to IlvMapInputStream) must be in the same directory as the .ivl file or the stream will not be able to find it, leading to missing images on the map.

If you choose to specify a different name for the .img file when saving the map (see Saving a Map), you must also specify the filename to the IlvMapInputStream using the appropriate constructor as follows:

String ivlFilename = "myMap.ivl";

String imgFilename = "myImgFilename.img";

//Create the input stream for the .ivl file.

FileInputStream fis = new FileInputStream(ivlFilename);

//Create the IlvMapInputstream and specify the image file name.

IlvMapInputStream mapInputStream = new IlvMapInputStream(fis, imgFilename);

//Read the map as described previously.

   try {

     mapInputStream.read(manager);

     } catch (Exception ex) {

// Handle reading exceptions here.

PREVIOUS NEXT