Background support

The background API

The background API allows you to integrate various types of background in the network and equipment components. It is made up of the following classes (see Background class relationships and Background support classes for an illustration of the class relationships).

IlpBackground

Backgrounds are implementations of the IlpBackground interface. This interface is part of the ilog.cpl.graph.background package where all background classes reside.

An IlpBackground implementation is usually associated with a specific background format. JViews TGO provides implementations of this interface that cover the most used background formats. See the table below for a complete list:

Supported background formats

Background format	Background class	Background file extension
Scalable Vector Graphics	`IlpSVGBackground`	SVG
GZIP Scalable Vector Graphics	`IlpSVGZBackground`	SVGZ
Raster Images	`IlpImageBackground`	GIF, PNG, JPEG and JPG
Tiled Raster Images	`IlpImageTileBackground`	GIF, PNG, JPEG and JPG
ESRI Shape	`IlpShapeBackground`	SHP, DBF, SHX and IDX
MID/MIF	`IlpMIDMIFBackground`	MIF and MID
JViews Vector Graphics	`IlpIVLFrameworkBackground`	IVL and ILV
JViews Vector Graphics	`IlpIVLMapBackground`	IVL with Map Themes

If the background format you are interested in is not listed here, please see Advanced support.

The IlpBackground interface defines two key methods: create and dispose . The method create produces the representation of the background itself; the method dispose disposes of the constructs that compose the representation of the background.

The ultimate representation of an IlpBackground is made up of instances of IlvGraphic objects that are part of the Rogue Wave JViews Framework. These graphics typically reside on one or more instances of IlvManagerLayer which compose the actual background representation. An IlpBackground implementation is responsible for appropriately processing the data in a given background format, creating IlvGraphic instances that appropriately represent the background data and populating one or several IlvManagerLayer instances with these IlvGraphic instances. Each IlvManagerLayer instances is accessible through the IlpBackground.getManagerLayer method.

IlpAbstractBackground

The IlpAbstractBackground class is the recommended base class that implements the common methods of the IlpBackground that should be used when introducing new IlpBackground types. It implements the IlvBatchable interface in order to minimize the performance side effects of property changes in a given background instance. For more information on how to use this interface, see the IlvBatchable and IlpAbstractBackground API.

IlpBackgroundSupport

Instances of IlpBackground are managed by an implementation of the IlpBackgroundSupport interface. JViews TGO provides a predefined implementation that is used by default, namely the IlpDefaultBackgroundSupport.

The IlpBackgroundSupport is in charge of providing all background-related functionality that graphic components like IlpNetwork and IlpEquipment may need. For example, it allows you to add, remove, move and reload backgrounds as well as access the added backgrounds and their constructs.

IlpBackgroundSupport is also the entity that handles the lifecycle of IlpBackground instances. It determines when the graphical representation of IlpBackground instances is created or disposed of. The following diagram illustrates the possible states and interactions involved when switching between them:

The following table summarizes the interactions where the IlpBackground API is triggered by the IlpBackgroundSupport :

Interactions between IlpBackground and IlpBackgroundSupport

IlpBackground method	Invoked
`create`	when a background is added to the graphic component when a background is reloaded in the graphic component (preceded by a call to dispose)
`dispose`	when a background is removed from the graphic component when a background is reloaded in the graphic component (followed by a call to create)

Although not optimal, it is nonetheless legal to use a given implementation of IlpBackgroundSupport.moveBackground to remove, then add again a given IlpBackground at the appropriate index in order to move a background. For information on the default implementation of this method, see IlpDefaultBackgroundSupport.moveBackground .

IlpMapDataSourceBackground

The IlpMapDataSourceBackground is an interface that allows you to integrate additional background formats provided in Rogue Wave JViews Maps via its Map DataSource API. It extends the IlpBackground interface by defining two additional methods that are necessary to establish the integration with JViews TGO: IlpMapDataSourceBackground.createMapDataSource to create the IlvMapDataSource that will handle the background file and IlpMapDataSourceBackground.getMapDataSource to provide access to the IlvMapDataSource of the background.

See Limitations for limitations related to the functionality provided by the IlpMapDataSourceBackground .

IlpAbstractMapDataSourceBackground

JViews TGO provides an abstract base class implementation of the IlpMapDataSourceBackground interface that allows the integration of new IlvMapDataSource implementations to take place with minor effort. This class is called IlpAbstractMapDataSourceBackground.

This class handles all the logistics involved in integrating IlvMapDataSource -based backgrounds within JViews TGO. It leaves as abstract the IlpMapDataSourceBackground.createMapDataSource which must be implemented by the concrete type. It introduces a new method, IlpAbstractMapDataSourceBackground.createRenderer , which returns an IlvFeatureRenderer that can be used to install a custom feature renderer to be used during the creation of the IlvGraphic instances for the provided IlvMapDataSource .

In addition, this type has a utility method, getMapStyle() , which provides access to the IlvMapStyle used by the underlying IlvMapDataSource .

This type is naturally the recommended base type for integrating new implementations of background formats that use the JViews Maps IlvMapDataSource API.

IlpAbstractIVLBackground

JViews TGO uses implementations of IlpAbstractIVLBackground to integrate backgrounds defined in IVL files. Besides the standard IlpBackground functionality, this type also allows users to add and remove IlvManagerLayer instances directly to and from the IlpAbstractIVLBackground instance through the IlpAbstractIVLBackground.addManagerLayer and IlpAbstractIVLBackground.removeManagerLayer , respectively.

The added IlvManagerLayer instances are treated just like another layer that was originated from the source IVL file, meaning that the background properties are propagated to these layers. Thus, the properties of the IlpBackground (like visibility ) are applied to the added layers as the state of the IlpAbstractIVLBackground changes.

See Limitations for limitations related to the functionality provided by the IlpAbstractIVLBackground implementations.

There are two implementations of IlpAbstractIVLBackground : IlpIVLFrameworkBackground and IlpIVLMapBackground.

IlpIVLFrameworkBackground should be used to read standard IVL files that contain only JViews Framework content. For more information, see IlpIVLFrameworkBackground in the Java™ API Reference Documentation.

IlpIVLMapBackground should be used to read IVL files that contain JViews Maps content. For more information, see IlpIVLMapBackground in the Java API Reference Documentation.

Background class relationships illustrates the background classes.

Background class relationships

Background support classes illustrates the background support classes.

Background support classes

Configuring the background

Backgrounds can be configured at two different levels:

the component level
the individual background level

Component backgrounds

As described earlier, you can use the IlpBackgroundSupport interface to manage backgrounds programmatically. You can add, remove, reload and access backgrounds. See How to add a background to the network component for a sample on how to add a background to the network component.

You can also specify the precise background configuration through CSS. For more details, see the CSS configuration of backgrounds in The Backgrounds rule.

Individual background

Each IlpBackground instance has a set of predefined properties that can be retrieved or set at runtime through the methods IlpBackground.getProperty or IlpBackground.setProperty . Each IlpBackground implementation defines the properties that are available to customize its behavior and representation. See the IlpBackground interface for general background properties.

You can also specify the precise properties for a given background through CSS. For more details, see the CSS configuration of backgrounds in The Backgrounds rule.

The following table lists the properties that are available and supported by each IlpBackground implementation:

IlpBackground properties

Name	Type	Default	Sample	Supported backgrounds	Description
`url`	String	`null`	`url:”sf-bayarea.png”;`	ALL	Defines the URL of the file that contains the background. This is a read-only property.
`visible`	boolean	`true`	`visible: ”true”`	ALL	Determines whether the background is visible or not.
`loadOnDemand`	boolean	`false`	`loadOnDemand: “false”`	-Shape (shp) -Image (gif, png and jpg)	Determines whether the background uses load-on-demand or not.
`threaded`	boolean	`false`	`threaded: ”true”`	-Image (gif, png and jpg) -Image Tile (gif, png and jpg)	Determines whether the internal processing of the background uses a multithreaded approach to improve performance.
`tileHeight`	integer	`300`	`tileHeight: “100”`	Image (gif, png and jpg)	Determines the height, in pixels, of the tile to be created. This property is taken into account only when the `loadOnDemand` property is set to `true` .
`tileWidth`	integer	`300`	`tileWidth: “100”`	Image (gif, png and jpg)	Determines the width, in pixels, of the tile to be created. This property is taken into account only when the `loadOnDemand` property is set to `true` .
`mapThemed`	boolean	`true`	`mapThemed: ”true”`	JViews Vector Graphics (ivl)	Determines whether the provided IVL file contains Map Themes.

Map themes

The background support provided by JViews TGO has become more interactive. Users can now specify a Map Theme to be associated with backgrounds.

A Map Theme is composed of several background-related features such as, but not limited to:

Map Styles - Allows to modify the background graphical representation according to map scale.
Areas of Interest - Bookmarks areas in the view that are of interest.
Coordinate System - The coordinate system that matches the background map.
Display Preferences - Preferences that affect the display of cartographic data as backgrounds and background-related beans.
Map Labeling - Allows the labeling of background data.

These features are provided by the underlying JViews Maps framework and exposed in JViews TGO. You can find more information on each of these features in the JViews Maps Documentation, Using the Map Builder, section Map Themes and Zoom Levels.

Integration

Map Themes integration into JViews TGO is available through the use of IVL background files generated from the JViews Maps Map Builder (more specifically through the use of IlpIVLMapBackground ).

The typical steps for integrating Map Themes created in the Map Builder are:

Load the background formats of interest.
Edit the various Map features of interest (Map Theme).
Save the configured background and its Map Theme as an IVL file.

Use this IVL file as a standard background within JViews TGO:

Backgrounds {
 background[0]: @+background0;
}
Subobject#background0 {
 class: "ilog.cpl.graph.background.css.IlpBackgroundCSSConfiguration";
 url: "background/backgroundWithMapTheme.ivl";  
 mapThemed : true;
}

Note

After editing the background and its Map Theme in the Map Builder, you can also save the Map Theme only in an IVL file. Then you can use the created IVL Map Theme file (which does not contain the background itself) as a standalone background in JViews TGO.

For more information on the JViews Maps Map Builder, see Using the Map Builder in the JViews Maps documentation.

See Limitations for limitations of the Map Theme functionality.

Background beans

IlpBackgroundPanel

This bean allows you to integrate into your user interface the ability to load, reorder, and save backgrounds for an IlpNetwork or IlpEquipment .

IlpBackgroundPanel Bean

A background located at the top has higher priority (drawing-wise) than the background below it. In the figure above, the europe.jpg background has the lowest priority of all and will be drawn below all other backgrounds. Whereas paris-subway.svg will be drawn on top of all backgrounds (highest priority).

The IlpBackgroundPanel bean provides the following features:

	Load a CSS file that contains a background configuration
	Save the current background configuration
	Add a background to the current configuration
	Remove the selected background from the current configuration
	Provide more information on the selected background
	Move the selected background up
	Move the selected background down

You can customize the background files that are filtered by this bean, by setting the getBackgroundExtensions method. You can also specify the default directory where it looks for backgrounds, by using the setDefaultDirectory method. Lastly, you can show or hide both the Add Background and the Remove Background buttons at runtime by using the showAddBackgroundButton and showRemoveBackgroundButton property accessors of IlpBackgroundPanel .

See the IlpBackgroundPanel Java API for additional information.

Some quick facts

When the view is zoomed, the background map is also zoomed.
The objects and the background map do not change positions during zoom operations.
Backgrounds are stacked according to their indices, where the background at index 0 is the bottommost background, that is, it has the lowest priority drawing-wise. However, keep in mind that index i does not necessarily correspond to the IlvManagerLayer index i, because some backgrounds span over more than one layer.

Advanced support

JViews TGO provides advanced support of the following:

memory management
configuring backgrounds through XML
integration of background formats not supported natively

Memory management

Some of the IlpBackground implementations allow you to configure the policy used to handle the management of the resources needed to represent its format.

This is the case in particular with the IlpImageBackground which leverages the advanced performance features provided by JViews Maps. More specifically, it takes advantage of the IlvRasterMappedBuffer which allows you to specify the memory management policy used to handle the rasters that ultimately represent the backgrounds.

By default, JViews TGO enforces the in-memory policy which stores the resources in memory. But you can also take advantage of the disk-mapped policy which stores pixel information on disk-mapped memory.

Important

The disk-mapped policy is not supported in applets.

For more details on this topic, see:

The Rogue Wave JViews Maps Documentation, Programming with JViews Maps, section Raster Image Management.
The IlvRasterMappedBuffer Java API.

XML background format

In addition to the natively supported background formats (see Supported background formats ), JViews TGO also provides the ability to configure backgrounds via XML.

The XML format allows you to configure one or more background files and specify some of the properties that each background uses to configure itself. This format is typically used if you need an image tile background and need to specify its configuration statically. Image tile backgrounds consist of a rectangular array of JPG, GIF, or PNG files, each with a filename denoting the column number and the row number. For a sample of how to make use of this format and configure an image tile background, see How to specify a tiled image background using the XML format.

Note

The XML format does not support all the parameters, such as offsets and built-in projections, that a given background may internally use.

Unless you have specific needs, the recommended way to configure your backgrounds is through CSS which allows nearly any type of customization.

Integration of unsupported background formats

If you want to use of a background format that is not supported natively by JViews TGO (for example, TIGER Line maps), the recommended approach is to check if this format is supported by the underlying JViews Maps product that JViews TGO makes use of. If this map format is supported by JViews Maps, then you should follow these steps:

Use the JViews Maps Map Builder to load and customize the map as needed.
Export the map as an IVL file.
Use this IVL file as an IVL background file that contains JViews Maps content in JViews TGO, as described in Integration.

For more information on the JViews Maps Map Builder, see Using the Map Builder in the JViews Maps documentation.

If the map format is supported neither by JViews TGO nor by JViews Maps, then it is recommended to export the unsupported format into one of the formats supported by JViews Framework, JViews Maps or JViews TGO, so that the standard or above integration can take place.

Limitations

The following table lists the limitations of backgrounds in JViews TGO:

Background limitations

Area	Description
Map Themes - Multiple backgrounds	Loading a background that contains a map theme may overwrite some or all of the map theme settings of a previously loaded background. The recommended approach will be to: 1. Load all the backgrounds of interest in the JViews Maps Map Builder. 2. Customize the map theme of all these backgrounds. 3. Save the map theme as a whole (as opposed to individually). 4. Load the global map theme as a standard IVL background.
`IlpMapDataSourceBackground`	Access to the `IlvCoordinateSystem` of an `IlvMapDataSource` from an `IlpMapDataSourceBackground` is read-only. If you set the coordinate system of the `IlvMapDataSource` for a given `IlpMapDataSourceBackground` through the method `IlvMapDataSource.setCoordinateSystem()` , it will not take effect because the `IlvMapDataSource` is recreated during a background reload. If you need to customize the map data source with a custom `IlvCoordinateSystem` , the recommended approach is to overwrite the `IlpAbstractMapDataSource.createDataSource` method to return an `IlvMapDataSource` that already has the `IlvCoordinateSystem` of interest set on it.
`IlpAbstractIVLBackground`	When you add `IlvManagerLayer` instances manually to an `IlpAbstractIVLBackground` , these instances will not be restored during a background reload. If reload support is required, it is recommended to create an additional `IlpAbstractIVLBackground` that points to an IVL file containing the additional graphics, or to add again the additional `IlvManagerLayer` instances after the background has been reloaded.

How to add a background map in MIF format

URL url = context.getURLAccessService().getFileLocation("world.mif");
networkComponent.addBackgroundURL(url);

How to add a background to the network component

IlpNetwok network = …;

URL backgroundURL = context.getURLAccessService().getFileLocation("backgrounds/
world.png");

How to specify a tiled image background using the XML format

<?xml version="1.0" encoding="UTF-8"?>
<background 
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:noNamespaceSchemaLocation="ilog/cpl/schema/background.xsd"
  type="ImageTile">
 <property name="pattern">jpp%c%r.jpg</property>
 <property name="tileWidth">400</property>
 <property name="tileHeight"400</property>
</background>

How to add an IVL background to the underlying IlvManager

The appropriate approach is to use an IlpAbstractIVLBackground , which gives you direct access to the underlying IlvManager that hosts the network (or equipment) component. If this approach does not satisfy your needs, you can (although this is not advised):

Obtain the IlpNetwork or ( IlpEquipment ) underlying IlvManager by calling network.getView().getManagerView().getManager()
Make sure that the needed number of IlvManagerLayer instances is inserted in this IlvManager (so that your background does not corrupt any of the existing IlvManagerLayer instances).

You can add more IlvManagerLayer instances by calling IlvManager.addLayer(0)
Call IlvManager.read to read the IVL file.

How to find out the georeferencing configuration needed for my IlpGeographicPositionconverter

If your background is georeferenced, you will likely be using several advanced Map background settings that are required when configuring the IlpGeographicPositionConverter .

These settings can typically be found in the IlvCoordinateSystem associated with a given background.

If you use an IlpMapDataSourceBackground , you can access its IlvMapDataSource and from there you can find the IlvCoordinateSystem .
If you use a non IlpMapDataSourceBackground , the information is typically configured manually by setting it explicitly on the underlying IlvManager or indirectly through a Map Theme (in an IVL file). Either way, you can access the IlvCoordinateSystem through the call IlvCoordinateSystemProperty.getCoordinateSystem() .

Note that if you have different coordinate systems for which you want to find out an IlvMathTransform , you can use an IlvCoordinateTransformation .

Lastly, note that the different types of IlvCoordinateSystem provide different types of settings. For example, an IlvProjectedCoordinateSystem provides access to a possibly needed IlvProjection . So assuming that the background map has an IlvProjectedCoordinateSystem , to find out the IlvProjection used by it, you can do the following:

IlpMapDatasourceBackground background = …;
IlvCoordinateSystem coordinateSystem =
    background.getMapDataSource().getCoordinateSystem();
if(coordinateSystem instanceof IlvProjectedCoordinateSystem) {
    IlvProjectedCoordinateSystem projectedCoordinateSystem = 
        (IlvProjectedCoordinateSystem)coordinateSystem;
IlvProjection projection = projectedCoordinateSystem.getProjection()
…
}