Describes the services that are available for a network: view services, adapter services, and handler services.

The services that are available for a network are of three kinds:

The IlpNetwork allows you to associate behavior with the network view as a whole and with the business objects it contains. JViews TGO provides predefined view interactors to manage the behavior of the network view. See View interactors.

With the default view interactors, you can:

Each view interactor works with one network view only and is managed by the network controller. A network view can have several interactors, but only one interactor is active at a time.

View interactors have two modes of operation:

In transient mode, the view interactor removes itself from the network view when it has performed its action.

In permanent mode, the view interactor remains in the view until the controller removes it.

By default, view interactors are permanent.

View interactors can display a pop-up menu.

A view interactor has a context implemented through IlpViewInteractionContext. When a user gesture is completed, the network view clones this context and makes it accessible through IlpViewActionEvent.

The predefined view interactors are in the ilog.tgo.interactor package and are subclasses of IlvManagerViewInteractor. When one of these interactors is installed, it must be wrapped in an IlpViewsViewInteractor.

How to wrap a predefined view interactor when installing it

Setting the view interactor

The method setViewInteractor allows you to set the view interactor, that is, the object-independent interactor, which is active at a given moment in the view. This interactor is replaced whenever the end user activates a different interactor. Such activation occurs, for example, when the user clicks a toolbar button.

Some interactors are one-shot interactors, that is, they have the attribute permanent:false in CSS. When such an interactor finishes its interaction, it is replaced by the default view interactor.

To customize through CSS, refer to The Interactor rule.

View interactor and default view interactor

When you use the setViewInteractor method you are attaching the specified interactor directly to the view. On the other hand, the setDefaultViewInteractorallows you to define the interactor that will be attached when the current interactor is detached from the view and no other interactor is attached. The default interactor is not attached automatically to the view, so it will not be available immediately.

The following example combines both methods:

In this example, you define the default view interactor through the call to setDefaultViewInteractor, and you activate it through the call to setViewInteractor so that it is immediately available.

How to associate an action with a mouse event and modifier in the network view

You can associate actions with mouse events, with or without modifiers, by using either CSS or the API.

The following extract shows how to customize the default view interactor in CSS:

The same configuration can be achieved through the API, as follows:

You can also customize the actions that are associated with the interactors defined in the network component toolbar. This configuration is done with the toolbar button definition.

How to associate an action with a mouse event for a network ToolBar button interactor

You can associate actions with mouse events when one of the interactors defined in the network component toolbar is active. The following CSS extract illustrates this configuration:

In this configuration, the action ActionImplementation is triggered when a double-click event occurs while the selection interactor is set in the network view. You can define any list of actions associated with gestures by using the indexed property action. To be accepted by the CSS customization, the action class must be a JavaBean™.

The CSS to associate an action with a mouse event and a modifier is slightly different:

You can find out whether this event occurred on an IlpObject by means of the following code (which should be in your Action implementation):

How to check whether a given action occurred in the network view interactor

How to associate an action with a keyboard event in the network view

You can associate actions with keyboard events by using either CSS or the API.

The following extract shows how to proceed in CSS:

The same configuration can be achieved through the API, as follows:

You can also customize the keystroke actions that are associated with the interactors defined in the network component toolbar. This configuration is performed with the toolbar button definition. The following CSS extract illustrates how this can be achieved:

How to associate an action with a keyboard event for a network toolbar button interactor

You can associate actions with keyboard events when one of the interactors defined in the network component toolbar is active. The following CSS extract illustrates this configuration:

In this configuration, the action " IlpSelectAllObjectsAction " is triggered when a Control-A keyboard event occurs while the selection interactor is set in the network view. You can define any list of actions associated with keyboard events by using the indexed property action. To be accepted by the CSS customization, the action class must be a JavaBean.

How to define a pop-up menu factory for the network view

You can customize a pop-up menu factory for the network view either through CSS or through the API.

The following extract shows how to add a pop-up menu factory through CSS:

The same configuration can be achieved through the API, as follows:

The following code shows you how to associate the defined pop-up menu factory with the network component:

How to associate a pop-up menu factory with the network component

You can also customize a pop-up menu factory that is associated with the interactors defined in the network component toolbar. This configuration is performed with the toolbar button definition. The following CSS extract illustrates how this can be achieved:

How to define a pop-up menu factory for a network toolbar button interactor

The following CSS extract illustrates this configuration:

The pop-up menu factory is customized using property popupMenuFactory in the button configuration. To be accepted during the CSS customization, the pop-up menu factory class must be a JavaBean.

Selection interactor

The IltSelectInteractor class allows you to select, move, and interact directly with objects. You can:

If setUsingObjectInteractor(true) is called on the interactor, then you can also:

You can configure the selection interactor to use Ctrl-click instead of Shift-click for multiple selection.

How to configure the selection interactor for multiple selection in the network view

In CSS, use the following rules:

In the API, use the following code:

Group reshape interactor

The IltEditGroupInteractor class allows you to change the shape of rectangular, polygonal, and linear groups ( IltGroup, IltLinearGroup, IltRectGroup and IltPolyGroup). Clicking an object starts shape editing interaction. Clicking the background ends it.

For polygonal and linear groups:

Make rectangular node interactor

The IltMakeRectGroupInteractor class creates a node with a rectangular shape ( IltRectGroup). One corner of the rectangle is denoted by the point where the cursor is located when the mouse button is released. Make sure that you do really move the mouse between the time when you press and the time when you release the mouse button. Otherwise, the shape is created empty and the node might be invisible.

Make polygonal node interactor

The IltMakePolyGroupInteractor class creates a node with a polygonal shape ( IltPolyGroup). A point is added each time the user clicks. Double-clicking marks the last point to be added.

Make polyline node interactor

The IltMakeLinearGroupInteractor class creates a node with a polyline shape ( IltLinearGroup). A point is added each time the user clicks. Double-clicking marks the last point to be added.

Make link interactor

The IltMakeLinkInteractor class creates links ( IltLink) between nodes. This interactor works in the following way: the user clicks one node and then goes on dragging the mouse over another node so that the two nodes are selected. When the user releases the mouse, a link is drawn between the two nodes.

For a detailed description of interactors and gestures, refer to Interacting with the graphic components.

The topic Interacting with the network view describes how to set an interactor on the entire network view. You can also associate behavior with business objects (a whole class or individual objects), as well as with individual object instances.

To do so, you use object interactors, which offer you the same possibilities as the view interactor:

An object interactor handles any event occurring to the object with which it is associated, provided the view interactor has enabled the use of object interactors. You can check this with the isUsingObjectInteractor method or modify it with the setUsingObjectInteractor method.

Object interactors are enabled by default.

No default interactor is associated with any object. To associate actions with mouse or keyboard events, or to define a pop-up menu factory, you first have to create an instance of IlpObjectInteractor. You can use the IlpDefaultObjectInteractor class, extend it, or create your own implementation.

How to associate an object interactor with a network component object

You can associate an object interactor with a representation object by using either CSS or the API.

The following extract shows how to proceed in CSS:

The same configuration can be achieved through the API, as follows:

Actions related to mouse and keyboard events can be customized in the same way as for the view interactor. You can also define a pop-up menu factory in the same way as for the view interactor. Refer to Interacting with the network view.

An object interactor can also be associated with a specific decoration that is part of the business object graphic representation in the network view. Each decoration represents a business attribute in the model. Therefore the customization of the interactor for a specific decoration takes into account the business object and a business attribute as illustrated below:

How to associate an object interactor with the label decoration in a network component object

You can associate an object interactor with one of the graphic decorations of the object by setting the interactor to the business attribute that is represented. You can do it using CSS or the API.

The following extract shows how to proceed in CSS:

The same configuration can be achieved through the API, as follows:

Actions related to mouse and keyboard events can be customized in the same way as for the view interactor. You can also define a pop-up menu factory in the same way as for the view interactor. Refer to Interacting with the network view.

For a detailed description of interactors and gestures, refer to Interacting with the graphic components.

This facility is for defining where a given object is displayed on the screen.

Each representation object has the option of carrying a position. The position data can originate from the back end (mapped automatically from an attribute of the corresponding business object, or manually from a separate source), from computation by a default layout algorithm in the network view, or from explicit end-user gestures to move or reshape nodes in the view. It is possible to retrieve the origin of the position data through the IlpPositionSource enumeration. There are three possible origins for the position of representation objects:

To retrieve the position origin, you need to access the method getPositionSource in the network view.

The position implements the IlpPosition interface.The following supplied types implement IlpPosition :

The position can be attached to a representation object through the method setPosition and retrieved through the method getPosition of the network view ( IlpNetworkView).

A position converter is used to convert positions in the network model to positions in the network view or vice versa. The position converter implements the IlpPositionConverter interface.

JViews TGO provides a default position converter ( IlpDefaultPositionConverter) for the predefined business objects position data. The following predefined position types are supported:

Since the network view already supports these position types, the IlpDefaultPositionConverter does nothing else than verify that the given position is one of the predefined types.

Positioning using geographic coordinates

A more complex converter is provided for geographic coordinates ( IlpGeographicPositionConverter). It extends the default position converter to support the following types of positions:

When you use a background map, you can give the positions of objects directly in geographic coordinates (latitude/longitude). The conversion to screen coordinates is performed by using an instance of IlpGeographicPositionConverter. You can parameterize this converter through classes that are part of the Rogue Wave® JViews Maps product: an IlvProjection or an IlvMathTransform, optionally followed by an IlvTransformer. Refer to The two coordinate systems.

How to parameterize the geographic position converter

You can also parameterize the geographic position converter through CSS by using the following steps:

You can define your own application-specific implementation of the IlpPosition interface, for example, you could implement polar coordinates. When you define your own implementation of IlpPosition, you must also attach the corresponding implementation of the IlpPositionConverter to the view. In this particular case, you would attach a converter from polar positions to the predefined view position types.

When an object has no attached position, the view assigns a position to the corresponding graphic object. The position is assigned through the layout mechanism (node layout for positioning nodes, and link layout for shaping links).

If the position of an object changes due to user interaction, the controller requests the handler to confirm the change.

JViews TGO makes use of the Rogue Wave® JViews graph layout algorithms. Each IlpNetworkView can be connected to several node algorithms and one link algorithm.

The detailed description of all the graph layout algorithms can be found in the Rogue Wave JViewsDiagrammer Using Graph Layout Algorithms documentation.

In case of multiple layouts, one layout can be set to be applied automatically whenever the contents of the view changes, while the others can be applied on demand. If the view contains subnetworks, you can specify different node layouts and a different link layout for the subnetworks.

To configure the layouts, it is recommended to use CSS (see Configuring a network component through a CSS file). Using CSS, you can also configure per-object layout parameters.

If a layout takes too much time to execute, or if you want to add toolbar buttons to execute a layout, you can configure the layout for the view and subnetworks, then execute it on demand by using the API method performAttachedLayout. The advantage of this method over the method performLayoutOnce is that the layout remains attached to the view, therefore storing any previously-defined configuration.

The class IlpNetworkView provides the following methods to handle the layout operation:

How to use hierarchical node layout in the network component

In CSS, use the following rules:

Note that the full class path is required for the properties globalLinkStyle and connectorStyle for the type converter to locate and convert the constants.

For an example of a CSS link layout, refer to The LinkLayout rule.

In the API, use the following code:

Even when you decide to use a certain node or link layout, you may want some links or nodes to be pinned; that is, you may want to keep a certain element in a specified position that is not affected when the layout is executed on a network.

You can achieve this effect by using the following methods defined in IlvGraphLayout :

How to set a link to fixed shape and a node to fixed position in the network view

The following code illustrates how you can set a given link to have a fixed shape and a given node to have a fixed position in the network.

In CSS, use the following rules:

In the API, use the following code:

When the position or shape of an object is not handled by the layout, you must set it by calling the method setPosition (or IlpNetworkView.setPosition ).

JViews TGO provides a default layout which uses IlvShortLinkLayout to shape and position links. This default layout sets all objects without an attached position to (0,0).

How to use multiple node layouts in a network view

In this scenario, two node layouts are configured for the network view. The first one is configured to be executed automatically.

In CSS, use the following rules:

The same layout that is applied to the network view will be applied to the whole subnetwork hierarchy.

In the API, use the following code:

To execute the tree layout in the view, use the method performAttachedLayout, where the index is the one defined in the CSS configuration, as illustrated below:

How to use different layouts for the view and subnetworks

It is also possible to configure some subnetworks with layout algorithms that are different from the network view.

In this scenario, the object ' SubNetwork1 ' positions its nodes using a tree layout algorithm, while the nodes in the main view are positioned using a grid layout.

In CSS, use the following rules:

In the API, use the following code:

How to configure per-object layout properties in the network component

Some layout algorithms require a specific configuration in order to be properly executed. For example, the bus layout needs to have a bus object specified; or the tree layout, for which you may want to specify the root node prior to the layout execution. Starting from JViews TGO 7.5, you can configure these properties using CSS, as illustrated below:

or, using the API:

How to disable the per-object layout properties configuration in the network view

By default, per-object layout parameters can be configured using CSS. However, if you are not interested in this feature, you can disable it by setting the property usePerObjectParamenters in the graph layout renderer and link layout renderer. Disabling the per-object layout properties configuration speeds up significantly the rendering process.

JViews TGO allows you to place labels in a network automatically to make them easier to read. This placement overrides the default placement of labels in JViews TGO, namely:

Label layout allows you to reduce overlap between labels and other objects in the current view. Therefore, it is particularly useful for positioning labels on links. Network Links without Label Layout shows labels positioned by default. Network Links with Label Layout shows the same links with customized positioning of the labels through label layout.

Label layout in JViews TGO uses the label layout of Rogue Wave® JViews. See the Rogue Wave JViewsDiagrammer Using Graph Layout Algorithmsdocumentation for more details on label layout.

Using label layout

JViews TGO provides the IltAnnealingLabelLayout class (a subclass of IlvAnnealingLabelLayout) that moves the labels of the nodes and the links so that they do not overlap. If it is impossible to prevent some overlap, this class will minimize the overlap between different labels.

The class IlpNetworkView provides the following method for handling label layout:

This method sets the given layout for the specified view. This method is also available from the class IlpNetwork, for convenience.

Unlike node layout and link layout, label layout is not performed automatically when the content of the network changes. You need to call labelLayout.performLayout() explicitly. There is a toolbar button for triggering label layout computation. See the class IlpNetworkLabelLayoutButton.

Here is a typical example of how to use label layout.

How to use label layout

In this example you:

Defining the labels you want to position

Label layout positions only the labels of links by default. You can choose to apply the layout to other types of object through the following methods:

or through the following convenience methods:

How to apply label layout to network elements only

The method setObjects indicates whether a certain type of object will have its label placed by the label layout. In this example, only Network Elements will have their labels placed by the label layout.

How to apply label layout to network elements only using CSS

The property objects indicates whether a certain type of object will have its label placed by the label layout. In this example, only network elements will have their labels placed by the label layout.

Defining obstacles

The label layout positions the labels of the objects by taking into account the obstacles that are in the network view. By default, all objects are considered as obstacles, but you can configure this behavior in CSS or through the API:

How to specify obstacles in the label layout using CSS

How to specify obstacles in the label layout using the API

Constraints

The following constraints exist for label layout:

You can configure the label layout in a CSS file through the labelLayout property. For more information, see The LabelLayout rule.

The grapher in JViews TGO has a set of predefined rules for assigning layers to objects that are inserted in the grapher. The choice of layer for a given object can be customized using the abstract class IltLayerPolicy. The IlpNetworkView class provides the following default layering policy in setLayerPolicy, for which no coding is required:

JViews TGO adopts the following conventions for displaying network objects and their associated decorations:

The layer in which a representation object is displayed (along with all its associated decorations) is determined by the IltLayerPolicy.

JViews TGO provides support for layers in the form of a layer policy and a layer visibility.

Layer policy

Each graphic representation of an object is an instance of the class IlpGraphic. It has a set of decorations that are instances of the class IlvGraphic. (Note that the IlpGraphic class itself is a subclass of IlvGraphic.) The graphic representations ( IlpGraphic ) are layered according to a given order, and so are the decorations. The mechanism that defines the stacking order for decorations and graphic representations is called layer policy, and is implemented by the abstract class IltLayerPolicy. This mechanism defines how two graphic representations overlap and ensures that their decorations do not intertwine. See the stacking order defined at the beginning of Layers.

Each IlpNetworkView has a layer policy that defines in which order the objects will be displayed in the grapher. This layer policy is created during initialization, but you can also modify it through the IltCompositeGrapher class:

You get the IltCompositeGrapher that belongs to an IlpNetworkView by calling network.getView().getCompositeGrapher().

The layer policy is responsible for allocating specific layers in the Rogue Wave® JViews grapher. The grapher is used to define the stacking order of the decorations. JViews TGO provides a specific class for handling layers called IltcLayer. This interface is the extension of IlvManagerLayer for IlpGraphic objects. Even though JViews TGO uses IltcLayer instances, it is also possible to use IlvManagerLayer instances directly to place graphic objects like map backgrounds or annotations.

To create your own layer policy, you will have to implement the IltLayerPolicy interface that defines the following methods:

The layers returned by the methods above can be created in layer policy initialization. The class IltCompositeGrapher provides methods through its superclass for dynamically allocating the layers in the grapher to execute this operation.

The following code extract shows you how to create layers.

How to create layers

Layer visibility

The layering mechanism is frequently used to hide and show collections of objects. Since JViews TGO manages the allocation of layers and the distribution of IlvGraphic instances on them, the following methods are available for controlling the visibility of collections of objects.

There are three possible mechanisms for modifying the visibility of layers:

To control the visibility of an individual IlpObject, use the methods addObject or removeObject on IlpMutableDataSource. You can also use filters, or assign accepted or excluded classes to the component adapter (see Filtering for details).

To control the visibility of an individual IlpRepresentationObject use the methods addRootObject or removeRootObject on IlpMutableNetworkModel. For objects belonging to a container, use addChild or removeChild.

JViews TGO supports three different zooming modes, as described below:

To summarize, physical zoom provides a fast miniaturized view of a network, whereas logical zoom keeps the graphical quality of the displayed objects.

Zoom support is implemented by the IlpZoomPolicy instances. By default, an IlpNetworkView instance has the physical zoom support set. However, the user can modify this configuration through the following method:

The two coordinate systems

This section assumes that you are familiar with the Rogue Wave JViews class IlvTransformer and with the difference between manager coordinates and view coordinates (see the method getTransformer in the class IlvManagerView).

Because of the possibility of a logical zoom (where the coordinates of the objects are changed according to the zoom level), there are two coordinate systems in use in JViews TGO:

Depending on the method you use, it may be necessary to convert from one coordinate system to another.

To convert from stationary coordinates to view coordinates, apply network.getManagerView().getTransformer(). This rule holds good only for objects in the top-level network. It cannot be applied to subnetworks.

To convert back, apply the inverse transformer. (See the methods inverse and computeInverse in the class IlvTransformer.)

Physical zoom

Graphic representations of telecom objects make intensive use of labels and icons. Therefore, some graphic objects cannot be resized without deteriorating their aspect when the physical zoom mechanism is used. This effect is even more visible when unzooming. While some JViews TGO objects, like groups, can be resized, other objects, such as network elements, have been intentionally designed to have an optimal size depending on the quantity of information they hold. Resizing these objects impairs the readability and compactness of their graphic representation.

For these reasons, the physical zoom mode was implemented to hide the decorations of telecom objects according to a certain configurable zoom factor. This factor is called the visibility threshold and represents the absolute value of the determinant of the view transformer. When the value of this determinant is lower than the decoration visibility threshold, decorations of the affected type are no longer displayed.

The visibility threshold for each decoration type can be configured locally to a network component through the methods:

or through the CSS properties:

How to set the visibility threshold for decorations in a specific network component

The following example describes a network component configuration that sets a physical zoom policy to the component, and defines visibility thresholds for the decorations Name, AlarmBalloon, AlarmCount and Plinth. Refer to Configuring a network component through a CSS file for more information.

Visibility thresholds can also be configured globally for all network components through the methods:

How to set the visibility threshold of decorations for all network components

The following example shows how you can customize the visibility threshold of specific decorations globally, so that all network components created in the application have the same configuration:

Logical zoom

The logical zoom effectively transforms the proportional zoom mechanism of Rogue Wave® JViews in such a way that the coordinates of JViews TGO objects in the manager are modified when the zoom factor changes. The effect of this operation is that network elements are not resized and the layout of the links is recalculated to correspond to the new coordinates of the nodes in the manager.

Only the main view of an IlpNetwork can hold the logical zoom support.

Combining physical and logical zoom (mixed zoom)

JViews TGO provides a mechanism that combines the physical and logical zoom policies. This mechanism is implemented by the class IltMixedZoomPolicy and uses physical zoom for zoom factors less than one and logical zoom for zoom factors greater than one, in the same view.

You can configure the zoom policy in the CSS file through the zooming property. For more information, see The Zooming rule.

Rogue Wave® JViews TGO allows you to develop telecommunication user interfaces that display telecommunication elements on a geographic or non-geographic background.

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:

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:

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 onlyJViews 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 support classes illustrates the background support classes.

Configuring the background

Backgrounds can be configured at two different levels:

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:

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:

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.

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:

 

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

Advanced support

JViews TGO provides advanced support of the following:

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.

For more details on this topic, see:

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.

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:

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:

How to add a background map in MIF format

How to add a background to the network component

How to specify a tiled image background using the XML format

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):

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.

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:

The network component allows you to filter the nodes that are displayed. To do so, attach an instance of IlpFilter to the network component by using the method setFilter. The accept() method of the filter object will be invoked whenever the network is prompted to display an IlpObject. If the method returns false, the object will not be shown in the network. In the same way, an object will not be shown if its parent is not displayed.

For example, write the following code to show only objects of the class IltNetworkElement.

How to filter objects to be shown in the network component

All the objects are refiltered whenever a new filter is set. If the filter is null (which is the default), all the objects under the root nodes will be displayed.

To retrieve the active filter, use the method getFilter.

To see how to configure filtering through CSS, refer to The Adapter rule.

You can specify the business objects that will be represented or not in the network component depending on their business classes. To do so, you need to specify the business classes to be accepted or excluded using methods setAcceptedClasses or setExcludedClasses in the network component adapter. To retrieve the adapter, use the getAdapter method. The adapter must be an instance of a subclass of IlpAbstractNodeAdapter. By default, business objects of the class IltAlarm are excluded from the network component, so that alarm objects in the data source are only used to compute the alarms present in a given managed entity instead of being graphically represented in the view.

How to specify excluded classes in the network component

You can specify that business objects from specific business classes are not represented in the network component. You can do that using the API, setExcludedClasses method, or using CSS.

The following example shows you how to prevent objects from business classes IltAlarm and IltLed to be represented:

How to specify an accepted class in the network component

By default, all business classes, except IltAlarm, are accepted by the network component. If you want to specify exactly which business classes to represent, you should combine the list of excluded and accepted classes, so that you exclude all business classes except those that are marked in the accepted class list.

In the following example, the network component is configured in a way that it graphically represents only business objects from the class IltNetworkElement.

To see how to configure excluded and accepted classes through CSS, refer to The Adapter rule.

By default, all the objects in the data source that do not have a parent are treated as root nodes by the network component. However, you can explicitly select the root nodes to be displayed through the adapter that forms a bridge between the data source and the network component. To retrieve the adapter, use the getAdapter method. The adapter must be an instance of a subclass of IlpAbstractNodeAdapter.

The root nodes can be changed by modifying the list of origins for the adapter. These origins are set and retrieved as IlpObject identifiers. The network adapter has two options: either the origins are represented as root nodes, or they are hidden and their child objects are represented as root nodes.

The method getOrigins allows you to get the list of current origins. The method isShowingOrigin indicates whether the origins themselves or their child objects are represented as root nodes. By default, the list of origins is empty and the origins are not shown, which means that all objects without a parent are shown as root nodes. Thus, the entire contents of the data source are displayed in the network.

To change the list of origins, use the setOrigins method. This method takes a list of business object identifiers as its first parameter. Its second parameter is a Boolean flag that indicates whether or not the origins themselves should be shown as root nodes.

Calling this method with an empty list and the second parameter set to true empties the network:

Calling the method with an empty list and the second parameter set to false restores the default; that is, all the objects in the data source are shown:

How to show an object as the root node of a network

To show only a given IlpObject as the root node of a network, use the following code:

See the IlpAbstractHierarchyAdapter class for additional methods to help you manage origins.

To see how to configure origins through CSS, refer to The Adapter rule.

The network adapter converts business objects retrieved from the associated data source into instances of IlpNetworkNode. The new representation objects are created by a representation object factory. The network adapter uses by default the IlpDefaultNetworkNodeFactory that creates representation objects of type IlpDefaultNetworkNode.

To know how to configure a network node factory through CSS, refer to The Adapter rule.

As the network node factory transforms business objects into representation objects, the link factory transforms business objects that are links into representation objects that are instances of IlpNetworkLink. The network adapter uses by default the IlpDefaultNetworkLinkFactory that creates representation objects of type IlpDefaultNetworkLink.

To see how to configure a network link factory through CSS, refer to The Adapter rule.

The network adapter uses an expansion strategy to identify whether objects should be loaded or not in the network model. The expansion strategy defines how an object is going to behave when it is expanded, for example, when the user opens a network node by double-clicking or by using the network expansion handles. The expansion strategy indicates whether load on demand is implemented and provides methods to load and release child nodes.

The network adapter uses an expansion strategy factory to decide the expansion strategy to apply to a network node when it is created by the adapter. The default expansion strategy factory implementation, IlpDefaultNodeExpansionStrategyFactory, checks the property "expansion" of each business object in the cascading style sheet loaded in the component to identify the expansion strategy to use.

The default network expansion strategy factory supports three types of expansion strategies:

See Customizing the expansion of business objects in the Styling documentation for information on how to customize the business object expansion type, which is defined by the property expansion.

The expansion strategy factory can be customized for the adapter either through CSS or through the API.