The model

The model in the equipment component contains and manages the representation objects, that is, the objects that are used to represent equipment business objects in JViews TGO (typically shelves and cards). The representation objects will in turn be converted to graphic objects displayed in the equipment view. Therefore, the equipment view needs to have access to the model to be able to render and graphically display the representation objects.

The model sends notifications for every single change in the representation node hierarchy, that is, for added or removed root and child nodes.

Classes of the equipment model

The model is made up of two interfaces:

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.

The model stores and maintains information about the representation objects, which may be added to the model either through the API or by an adapter. The adapter converts the business objects of the data source to representation objects. (An adapter is created automatically when a data source is connected to the equipment component.)

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.

When a data source is attached to the equipment component, the model listens to changes affecting the business objects; it updates the representation objects accordingly and fires model events to all is listeners.

Using the equipment model

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

How to retrieve the model root objects

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 startBatch allows you to execute a series of operations at once in the equipment component. Then, when endBatch is called, all the notifications generated by these operations will be sent to the model and its listeners.

Note

It is your responsibility to manage both startBatch and endBatch methods. In other words, when the method startBatch is issued, it has to be followed by the method endBatch .

The following example shows how to batch a series of changes in the equipment model

How to manage notification in batch mode

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

In this example, implicit notifications arising from additions or removals of child objects will also be buffered.

To add a listener to the model, you must implement the interface EquipmentModelListener and register it with the model by using the method addEquipmentModelListener. Conversely, to remove a listener from the model, use the method 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 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.

Current section

Architecture of the equipment component