Architecture of the Equipment Component

INDEX PREVIOUS NEXT

A graphic component encapsulates a model, a view, and a controller. The equipment component, like all the other graphic components, is based on the MVC architecture, which means that it has a model, a view and a controller associated with it. For a general introduction to the MVC architecture, see section Architecture of Graphic Components.

• Class Overview
• The Model
• The View
• The Controller
• The Adapter

• The class IlpEquipment contains a model, a view, and a controller.
• The model interfaces are IlpEquipmentModel and IlpMutableEquipmentModel. IlpMutableEquipmentModel provides API facilities for adding and removing objects. The two equipment model interfaces are implemented through the class IlpDefaultEquipmentModel. Instances of IlpEquipment use the class IlpDefaultEquipmentModel.
The representation objects to be displayed in the equipment component must be added to the model. The equipment model recognizes the following objects: nodes, and links that connect nodes. The representation objects to be added to the model must implement the IlpEquipmentNode or IlpEquipmentLink interface. Concrete implementations of these interfaces are provided as IlpDefaultEquipmentNode and IlpDefaultEquipmentLink. You can create subclasses of these representation object classes.
• The class IlpEquipmentView defines the equipment view that is automatically instantiated when an equipment object (an instance of IlpEquipment) is created.
• The class IlpEquipmentController creates a controller that manages interactions between the user and an IlpEquipmentView.

• IlpEquipmentModel: Provides methods to access the model.
• IlpMutableEquipmentModel: Provides methods to set and update the model.

The default implementation of both interfaces is the class IlpDefaultEquipmentModel, which is automatically instantiated when the equipment component is created.

When a representation object is added, removed, or updated in the model, events of the EquipmentModelEvent class are sent to all registered listeners. The view itself is a listener to equipment model events, so that it is always synchronized with the contents of the model. To receive model events, you must implement the EquipmentModelListener interface and register your implementation with the model through the addEquipmentModelListener method.

The whole model API can be accessed through the IlpEquipment.getModel() method, but IlpEquipment also provides shortcut methods to access some model services.

To retrieve the root objects that are currently set in the equipment model, use the IlpEquipmentModel API, as follows:

IlpEquipment equipmentComponent = ...; // the equipment component
IlpMutableEquipmentModel model = equipmentComponent.getModel();
Collection roots = model.getRootObjects();

When a change occurs in the structure of the model (representation objects), a notification is fired to all listeners registered within the equipment model. In the case of multiple changes, it is more effective to store the changes in a buffer, thus postponing the internal processing of notifications. The method IlpAbstractDataSource.startBatch allows you to execute a series of operations at once in the equipment component. Then, when IlpAbstractDataSource.endBatch is called, all the notifications generated by these operations will be sent to the model and its listeners.

// starts notification bufferization
IlpDefaultDataSource datasource = (IlpDefaultDataSource) equipment.getDataSource();
datasource.startBatch();
datasource.addObject(newRoot1);
datasource.addObject(newRoot2);
datasource.addObject(newRoot3);
// ends notification bufferization

To add a listener to the model, you must implement the interface EquipmentModelListener and register it with the model by using the method IlpEquipmentModel.addEquipmentModelListener. Conversely, to remove a listener from the model, use the method IlpEquipmentModel.removeEquipmentModelListener.

The listener is based on the EquipmentModelEvent class, which defines the equipment model events. It is divided into four different types of events: ROOT_OBJECT_ADDED, ROOT_OBJECT_REMOVED, CHILDREN_ADDED and CHILDREN_REMOVED. Each type of event corresponds to a specific update. There are two special types of events, SERIES_BEGIN and SERIES_END, used to delimit a series of notifications sent after the model has completed buffered changes. Right after the method IlpAbstractDataSource.endBatch has been issued, an event of type SERIES_BEGIN is sent to the listeners indicating the beginning of buffered changes, followed by all the buffered events. Then, an event of type SERIES_END is sent, which indicates the end of buffered notifications.

• Displays a subset of the objects of the model
• Allows navigation using scrollbars and provides a zoom facility
• Assigns a default position to nodes that have no value for position in the model
• Assigns a shape to links that have none
• Modifies link shapes when end nodes are moved
• Provides a toolbar for choosing a view interactor
• Optionally displays an overview window

The IlpEquipment class automatically creates the concrete class IlpEquipmentView that is provided for developing the equipment view. This class provides methods that allow you to configure the view in the following ways:

• Turn the scrollbars on or off: setHorizontalScrollBarVisible, setVerticalScrollBarVisible
• Set the zoom level: getManagerView().addTransformer
• Set the toolbar on or off (here set to off): setToolBarVisible (false)
• Set the overview window to be displayed or not (here set to be displayed): setOverviewVisible (true)

For convenience, these methods are also accessible from the class IlpEquipment. They delegate to IlpEquipmentView.

See Configuring an Equipment Component through CSS for how to configure the equipment view in CSS.

See Configuring an Equipment Component through the API for how to configure the equipment view through the API.

• Nodes--Nodes are the basic graphic objects and they are represented as equipment elements according to the conventions of the governing standards, such as ITU-T or ANSI, and the appropriate protocols.
• Links--Links are the connections between nodes.

For more information on object interactors, see Object Interactors.

The graphic representation of each object displayed in the equipment component is implemented through the IlpGraphic interface. JViews TGO provides predefined equipment graphic objects that are produced by the default equipment component renderer. You can customize the rendering of the objects through CSS.

For custom business objects, JViews TGO provides a default representation with a set of properties that can be customized to better represent your objects. If you prefer, you can also specify a new graphic representation by defining an IlvGraphic class in the CSS. For more information, refer to section Customizing User-Defined Business Objects in the Styling documentation. You can also refer to samples.network.compositeGraphic to see how to create a new object representation by using the ILOG JViews composite graphics feature.

Predefined business objects already have a specific graphic representation that can only be changed through CSS customization by setting the object properties. Refer to the Styling documentation for complete lists of business object properties. You can customize the graphic representation by adding new decorations. Refer to the Styling documentation for more information and to samples.network.decoration for how to add new decorations to the objects using CSS.

Such subcomponents are combined into composite graphic objects, like the link with secondary states and a label shown in Figure 3.6 by using attachments.

A composite graphic object constructed in this way looks like one object. The different instances of IlpGraphic used to build the graphic object cannot be distinguished as separate objects in the equipment. JViews TGO manages only the composite object. You cannot move the label separately from the link.

The controller manages the actions triggered by the end user, which have an immediate effect on the view, such as changing the zoom level. It is an instance of the class IlpEquipmentController.

Each time an equipment component is created (instance of IlpEquipment), a default controller of class IlpEquipmentController is automatically created.

By default, a handler of class IlpEquipmentHandlerWithoutDataSource is instantiated. This handler is designed to forward end-user interactions directly to the equipment model. When a data source is attached to an equipment component, a different handler is instantiated, namely IlpEquipmentHandlerWithDataSource; this handler forwards end-user interactions to the data source instead of the model.

Some of the most common methods of the class IlpEquipmentController can also be found in the class IlpEquipment.

Access to the controller API is through the method IlpEquipment.getController.

By default, no data source is associated with the equipment component, which means that the default handler is an instance of the class IlpEquipmentHandlerWithoutDataSource. When a mutable data source is associated with the equipment component through the method IlpEquipment.setDataSource, a new handler of class IlpEquipmentHandlerWithDataSource is instantiated, unless a custom handler has been set. The method IlpEquipment.setHandler allows you to set new handlers to the controller.

The controller manages the view and object interactors. By default, an instance of the class IlpEquipmentDefaultViewInteractor is set as the view interactor for the controller, but it is possible to define specific interactors for the view through the IlpEquipment API.

• Actions triggered by interactors for
• Creating objects in the data source
• Removing objects from the data source
• Changing attributes of objects in the data source
• Changing the parent object of an object in the data source
• Expanding and collapsing container objects
• Propagating position changes of objects
The position changes are usually due to layout, zoom change, or interactors.

• IlpPositionHandler to handle object position changes.
• IlpNodeHandler to handle object additions, removals and updates, as well as relationship changes.
• IlpLoadHandler to handle reloading of model objects from an XML file.
• IlpExpansionHandler to handle the expansion and collapsing of objects.

The IlpEquipmentHandler interface indirectly extends all four types of handler.

The handler has a reference to the data source in the form of an IlpMutableDataSource, and to the equipment adapter.

You can customize the behavior of the handler by subclassing the class IlpEquipmentHandlerWithDataSource. A particular method can be overridden for each of the possible actions.

You can customize the way position changes are propagated by overriding the method propagatePositionToDataSource. In a typical situation where the client is active, position changes are propagated to the data source. Therefore, this method returns true by default. In a situation where the client has read-only access, you may want to allow only user-requested position changes or no position changes at all to be forwarded to the data source. You can achieve this result by allowing the method propagatePositionToDataSource to return false in the appropriate cases.

The handler is most often subclassed to allow you to customize the creation of new objects in the data source. The object interactors may need to be customized in the same way. A customized object creation interactor typically calls the controller method IlpEquipmentController.createObject with specific properties. The controller then forwards these properties to the handler. Finally, the method handleCreateObject of the handler parses the additional properties and creates the new objects.

0. The ID of the new object is created with the method createObjectID.
1. The IlpObject corresponding to this ID is created with the method createObject.

• IlpEquipmentHandlerWithoutDataSource is attached by default to the controller and performs user interactions directly in the equipment model.
• IlpEquipmentHandlerWithDataSource is automatically attached to the controller when a data source is connected with the equipment component. User interactions are executed inside the data source that will notify the adapter, and the adapter in turn will notify the equipment model. In this particular use case, changes will be reflected on all equipment components, if any, connected to the data source.