Describes load-on-demand and how to use it.

JViews Maps offers a mechanism that lets you load into memory only the data that you want to display in a manager view. This mechanism, known as load-on-demand, is extremely valuable, especially when very large maps are concerned. Consider a database storing maps of the whole world with a scale of 1/25,000. If these maps were scanned with a resolution of 300 DPI, the required storage space would be as follows:

Given the volume of this data, it is crucial to have a load-on-demand mechanism that will load and display only the portion of a map of direct interest.

The IlvTiledLayer Class

The IlvTiledLayer IlvTi extends the IlvManagerLayer class and allows the loading of large sets of data, for example, large maps. It is divided into a number of rectangular areas called tiles (organized into grid cells or into a list of specified areas) and provides a notification mechanism to load only the graphic objects that are required by the application, because a tile is visible in one of the views of the manager or because it has been explicitly required by the application.

An IlvTiledLayer is associated with three important objects:

When an IlvTiledLayer is saved into an .ivl file, it does not save the graphic objects it contains. It saves its tiling parameters (loader, cache, tile controller, tiling structure).

The IlvTileController Class

The IlvTileController class manages the load-on-demand mechanism. It divides the space into a number of rectangular areas called tiles, in two different fashions according to its mode:

The tiling mode for an IlvTileController is set at creation time and can not be modified afterwards.

Each time a tile becomes visible in a view of the manager to which it is attached, the tile controller notifies a loader (called tile loader) to load the data attached to this tile. A cache releases the invisible tiles (called the cached tiles) when it is necessary to free memory.

The IlvTileLoader Interface

The IlvTileLoader interface is used to load a tile for an IlvTileController or an IlvTiledLayer.

The following example shows a tile loader that fills a tile with a generated list of graphic objects.

The file is: <installdir> /jviews-maps/codefragments/srs/src/Sample2.java

The IlvTileCache Class

The IlvTileCache class is used to manage the cached tiles of one or more tile controllers. A cached tile is a tile that is not visible in any view and that is not locked by any application object. An IlvTileCache object releases the cached tiles to free memory when necessary.

The IlvTile Class

A tile represents an elementary rectangular area that is loaded or released when needed by the application. Tiles are managed by an IlvTileController.

In most cases, the tile controller will be associated with an IlvTiledLayer. This means that the tiles represent areas that must be filled with graphic objects when they become visible due to the user of the application scrolling or zooming on a view.

More sophisticated applications can use a tile controller without attaching it to a layer, for example, to load data that is needed to process an area that becomes visible.

For example, to define a geographic coordinate system expressing latitude and longitude with grads, instead of degrees, you can use the following code:

The IlvFreeTile Class

This class is similar to the IlvTile, except that instead of being part of a regular grid (and therefore indexed by line and column), its bounds can be freely specified. This is particularly useful when overlapping areas are needed, for example, in case of a projected map. Note that although IlvFreeTile is a subclass of IlvTile (for compatibility reasons), the member variables row and column are not relevant in terms of tile location. They are used to locate a superclass IlvTile instance on a grid, but given that IlvFreeTile objects have bounds of their own, there is no need for line and column properties.

A tiled layer is a type of manager layer specifically designed to support load-on-demand. If the IlvTileController associated with this layer works in indexed mode, the layer is divided into a set of rectangular tiles of identical size that form a tiling grid (note that a constructor of IlvTiledLayer takes a mode as a parameter).

The tiling grid is defined by its origin tile that is located at the intersection of the row and column of index 0, see Tiling grid in indexed mode.

The other tiles in the grid are identified by their column and row number, starting from the origin tile. The following code example displays the status of the tile that is at the intersection of column 10 and row 5:

You can see in the above code example that the getTile method can sometimes return a null value. Because the potential number of tiles can be very great—the number of tiles is even virtually infinite—the IlvTile objects are allocated only if the tile is loaded or is in the cache.

The complete source code of this example can be found in the following file:

<installdir> /jviews-maps/codefragments/lod/src/TileStatus.java.

You can set the size of the tiling grid using the following method:

The rectangle that delimits the tiling grid is expressed in the manager coordinates. Only the tiles that intersect with this rectangle can be loaded. You can see an example of a tiling grid whose size has been defined in the debug view illustrated in Load-on-demand debug view.

When the IlvTiledLayer is set to free mode (or its associated IlvTileController), the structure is not a grid (unlike indexed mode described in Structure of the tiling grid (indexed mode only)), but a list of rectangular areas that must be added to the IlvTileController.

These areas can have any bounds and can even overlap.

The size of the tiled layer is simply the union of all tile bounds.

You can create a debug view to display the state of the tiles in a tiled layer using the following method:

As its name suggests, this debug view is particularly useful for debugging operations when implementing load-on-demand for a new cartographic format.

A tile can have three different states. It can be:

The debug view is of the IlvManagerView type, and must be attached to a tiled layer. The debug view does not increment nor decrement the tile lock counters. This is the role of the tile controller. It just displays the tiles in color according to their state, as in Load-on-demand debug view.

The tiles whose lock counter is greater than 1 appear in blue. They are visible in at least one view. The tiles whose counter equals to 0 appear in yellow. They are cached. The white tiles are not loaded.

In the previous example, an IlvManagerMagViewInteractor was associated with the debug view. It is this interactor that displays a little yellow square inside the blue tile. The square shows the zone displayed by the main view.

The following is an example of code that creates a debug view for a layer.

The complete source code of this example can be found in the following file:

Using visibility filters to control load-on-demand

If you do not want to use the dynamic styles provided by the IlvMapStyleController class, you can use scale visibility filters to control the display of tiles in a manager layer.

When a scale visibility filter has been set for a tiled layer, this layer will be displayed if the scale factor set for its manager view is within specified scale limits. Otherwise, it will be hidden. When a tiled layer is visible because the zoom factor of the manager view allows it, visible tiles are automatically locked and thus loaded into memory. In the same way, when a tiled layer is hidden because the zoom level of its view exceeds a certain value, all the locks set on visible tiles are released and the tiles are removed.

Scale visibility filters are generally used to activate load-on-demand for zoom factors between a minimum and a maximum scale value. Let us consider a map scanned with a scale of 1/1,000,000, you can set visibility filters so that its layer is visible for scale factors ranging from 1/2,500,000 to 1/500,00.

Setting tile locking filters

You can use the IlvTileLockFilter class to dynamically prevent a tile from being loaded when it becomes visible in a view. To do so, you associate an IlvTileLockFilter object with a tile controller using the following method:

If the tile controller possesses a lock filter, it calls the method isLockAllowed of the lock filter each time a tile becomes visible in a view. If this method returns false, the counter of the tile is not incremented.

Using a lock filter, you can prevent the loading of data displayed at a small scale (when a map is zoomed out greatly, for example) while leaving the tiles that were already loaded visible.

Loading tiles using the API

The load-on-demand mechanism is event-driven in that cartographic data is loaded or unloaded following user’s actions, such as zooming or panning. You can, however, use the lockTile() method for example—to preload a tile corresponding to a map zone that is visited frequently or to prevent the tile from being unloaded.

The lockTile() method shown below increments the tile lock counter:

If the tile lock counter is equal to zero, the tile is loaded into memory and will not be unloaded as long as the lock is not released—with the IlvTileController.unlockTile method, for example.

Updating all the visible tiles in a view

Sometimes you may need to update immediately all the tiles that are currently viewed by an IlvManagerView. You can then use the updateView method. It can be useful when you reactivate a view that was ignored until then by the load-on-demand mechanism.

The load-on-demand mechanism might generate errors when the map cannot be entirely loaded due to memory problems, absence of data, loss of connection to a server and so on. Graphic applications must catch these errors to inform the user that the map being viewed is not complete.

To be notified of these events, and any other events related to load-on-demand, you can set a TileListener to an instance of the IlvTileController class. This listener is notified of all changes to the tiles, for example, the beginning or end of loading, moving tiles into the cache, or out of the cache for reuse, loading errors, and so on.

The following example displays all the events related to load-on-demand:

By default, the tile controller displays a message on the screen if an error occurs while a tile is being loaded. You can deactivate this behavior using the following method:

The different types of events sent to the tile listeners are:

When an event in a view causes an action to be performed on a tile, the tile controller notifies the tile listener of the action. If this event provokes a series of transitional events, these are transmitted to the listener as a group. Therefore, modifying a scale factor can cause new tiles to be loaded and other tiles to be cached. Grouping events allows an action to be performed only when all the transitional events it causes are completed. The isAdjusting() method of the class TileEvent returns true if the event is part of a series of events. The NO_CHANGE event is sent once the last event in a series is processed and the isAdjustmentEnd() method returns true.

The tile cache is the place where tiles whose lock counter has returned to 0 are stored. The tiles in the cache are eligible for unloading if memory is needed for loading new tiles.

The cache can be shared among several layers, which means that loading a tile in a layer can cause that tile to be unloaded in another layer.

The IlvDefaultTileCache class implements a cache algorithm consisting of a simple LRU (Least Recently Used) structure that unloads first the tiles that have been visited the least recently.

You can, however, implement another algorithm that will be more efficient with respect to the specific nature of your application. Here are a few criteria you might take into account when implementing a new backup cache algorithm.

An example of a simplified cache algorithm is given in Writing a new cache algorithm.

A layer has a number of associated parameters. Some parameters such as named properties, visibility filters, and names are common to all layers, whether they are tiled layers or just normal layers. Other parameters are specific to tiled layers. These are the tiling parameters, the lock filter and the tile loader, introduced in the previous sections.

Unlike normal layers, when you save a tiled layer to an .ivl file, only its attached parameters are saved with the layer, not the objects it holds.

This section explains how to write a custom cache algorithm to meet specific application requirements. The example in this section is a simplified version of the class IlvDefaultTileCache provided in the JViews Maps library.

The complete source code for this example can be found in the following file:

The class SimpleTileCache extends the class IlvTileCache.

cacheSize defines the maximum number of tiles that can be stored in the cache.

The following constructor creates an instance of the default cache with the specified size (in this example, 5).

The following constructor reads the cache from the provided input stream. Caches created using this constructor implement the IlvPersistentObject interface and can thus be saved with an IlvTiledLayer object.

The write() method writes the cache to an output stream.

The following method belongs to the IlvTileCache interface. It is called when a tile is cached. In this implementation, the tile is added at the end of the internal tile list.

The following method belongs to the IlvTileCache interface. It is called when a tile is removed from the cache and locked again. With this implementation, the tile is removed from the internal tile list.

The following method belongs to the IlvTileCache interface. It is called when a tile is about to be loaded. With this implementation, if the number of tiles in the cache exceeds the cache size, the least recently used tiles, at the top the internal tile list, will be unloaded to make room for new tiles.

The following method belongs to the IlvTileCache interface. It is called when a tiled layer is taken out of the manager to remove the tiles managed by its tile controller from the cache.

To implement load-on-demand for a new data source, all you have to do is write a specific tile loader that implements the IlvTileLoader or the IlvMapTileLoader interface. Notice, however, that for the predefined map formats supplied with JViews Maps, load-on-demand has been implemented in a subclass of IlvTiledLayer that defines both the tile loader (as a private class) and the tiling parameters appropriate for the concerned format. The IlvMapTileLoader class and the predefined formats are described in Readers and writers.

For your tile loader to be fully efficient, the following requirements should be satisfied:

The following example of a tile loader simulates the loading of two graphic objects, a rectangle and a label.

Its load() method takes the tile to be loaded as its parameter. It generates the graphic objects to be displayed within the tile and adds them to the tiled layer by calling the tile.addObject() method. When loading is complete, it calls the tile.loadComplete method to notify the listeners that the data in the tile is ready for use.

Its release() method is invoked when the tile cache releases a tile. The tile.deleteAll method clears the tile.

The complete source code of this example can be found in the following file:

To write a new IlvMapDataSource for a format of your own using the load-on-demand mechanism, you should inherit from the IlvTilableDataSource class. This class performs all of the steps required to create the appropriate tiles, and to configure tiled layers to make efficient use of load-on-demand. You can choose the number of rows and columns into which to divide the map, or even deactivate the tiling mechanism if you prefer. However, you need to implement two abstract methods:

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

Creating tiled layers

The createTiledLayers method is called by the startmethod of the IlvMapDataSource. Its role is to create the tiled layers that make up this data source. For example, if your data source sorts map features into different layers, all of the tiled layers must be created by this method.

Here is a sample implementation of this method:

Reading map features

The createTiledIterator method returns a feature iterator over map features located in a specified region of interest. The tile loaders of the layers use this iterator to load the tiles when they become available on screen. That is, they read the map features of the tiles in the region of interest only.

Here is a basic implementation of this method:

If multiple tiled layers are created by the createTiledLayers method in Creating tiled layers, a different iterator might be returned for each layer (hence the layer parameter in the createTiledIterator() method), see Data tiling.