Content on demand
Describes the content on demand feature.
Describes the purpose and use cases of the content on demand feature.
Describes the concepts involved in content on demand.
Describes the classes used by the content on demand feature.
Explains how to implement the content on demand feature.
Describes what makes the difference between tiling systems and content on demand feature.
About content on demand
The content on demand feature allows an SDM model to delay the loading of its objects content in order to save resources. Unlike a tiling system, content on demand requires that all the objects be present in the model. The objects can be hollow. Assuming that hollow model objects have low memory and time footprints, content on demand allows you to fill them on demand and empty them when they are no more needed. Content on demand sends a notification when the content of a set of objects needs to be loaded, and, optionally, when it can be unloaded.
Content on demand addresses two main use cases:
Models that are time-consuming in terms of loading, and applications that are slow at start up. The lazy loading of content speeds the start up of the Diagrammer application because the model and the graphic representation of the model objects are light and simple. Objects are filled on demand, and the customization and rendering time is used only for the requested objects.
Fat models that need to load content for a subset of objects only. Typically, only the objects that are visible in the main view should be fully loaded. When panning or zooming, the content of newly visible objects is loaded and the content of non visible objects can be unloaded, which keeps the model memory footprint to a minimum.
The classes of the content on demand feature are located in the package
ilog.views.sdm.modeltools. The entry point is the class
IlvContentController.
Concepts
The content on demand feature operates at the granularity of SDM model objects. Content on demand makes use of the following concepts.
Content controller
The content controller maintains a state for each model object. A model object can be in one of three states:
locked The object content is loaded and in use.
loaded The object content is loaded, but not locked. It is considered as cached and will be unloaded when the cache is full.
unloaded The object content is not loaded.
The state changes after events, such as a user request, a zoom or a pan change (in fact visible area changes), have taken place. The controller then sends a notification to explicitly load or unload a set of objects.
Usually, the lifecycle of an object content is: unloaded, then locked, then loaded, then potentially back to unloaded.
The cache is virtual. The object content is held in the SDM model. When the state changes to loaded, this simply means that the content remains in the model. As a matter of fact, the SDM model implements the cache for the object content, and the controller manages this cache.
The controller contains the states of the objects as well as a handler that processes the load and unload commands.
Cache size tuning
Extreme values for the cache size have a radical impact on the content on demand behavior.
Null (0) cache size: The objects are either in use (locked) or unloaded. Use this value to minimize the memory footprint.
Infinite cache size: The objects are loaded when needed but never unloaded. This is a pure lazy load behavior.
For other cache size values, the objects are loaded when locked and remain in the cache until they are flushed (FIFO way) to keep the average memory size close to constant. Note that when objects are requested to be locked, they are loaded before the cache is purged to avoid unloading an object that is going to be locked again. This means that the cache can temporarily be larger that the expected size.
Locking requests
A locking request is an event sent to the controller to lock, load or unload objects. There are two types of event:
Area events The controller is requested to lock all objects that intersect a given area. A mode indicates whether previously locked objects should remain locked or should be unlocked, that is, loaded (default). Typically, the area may be computed from the visible part of the main view in order to load all visible objects.
Set events The user sends a request to the controller to lock, load, or unload a given set of objects. For example, a drill-down mechanism loads the content of the selected object.
Both types of event are non exclusive: An area event may be followed by a set event, and conversely.
Notifications
The controller does not know by itself how to load the content of SDM model objects. On request, it calls a handler,
IlvContentHandler, that performs the load and unload actions by upgrading the SDM model. Then, the usual SDM model notifications take over to customize and refresh the graphic representations.
A load event is sent when the object state changes from unloaded to locked or loaded.
An unload event is sent when the object state changes from locked or loaded to unloaded.
No notification is sent when the state changes between loaded and locked.
Multithreading
The handler is able to work asynchronously, that is, if the controller asks to load an object, the handler marks the object as locked while the object may be loaded in a separate thread. In any case, the handler must notify the SDM model when the action is complete. The locking requests are synchronized, so that the handler holds the controller synchronization lock until completion of the event.
SDM model changes
The controller is aware of SDM model structural changes when:
IlvSDMEngine.setModel() sets a new model: All the objects are unloaded without notification to the handler.
The SDM model deletes an object: The object is unloaded in the controller without notification to the handler.
To summarize, the controller forgets about the obsolete objects of the model.
Classes involved
The content on demand feature involves the following classes:
The IlvContentController class
The
IlvContentController class defines the following methods:
setSDMEngine(IlvSDMEngine engine) Sets the SDM engine to work on.
setContentHandler(IlvContentHandler handler) Sets the handler.
setCacheSize(int size) Sets the cache size.
Methods to send requests
lockArea(IlvRect area, int mode) Locks the objects that intersect with the given rectangle. The mode indicates the status of previously locked objects. The allowed values are:
IlvContentHandler.OVERRIDE Previously locked objects are unlocked.
IlvContentHandler.AUGMENT Previously locked objects remain locked.
The class ilog.views.sdm.modeltools.IlvVisibleAreaListener provides a view listener that locks automatically the visible area of an SDM view.
processObjects(Object[] objects, int action) Locks, loads, or unloads the given objects, according to the action value, which can be one of:
IlvContentHandler.LOCK Lock action.
IlvContentHandler.UNLOCK Unlock action (once unlocked, objects can be unloaded at any time).
IlvContentHandler.UNLOAD Unload action.
processObjects(Enumeration objects, int action) Similar to the previous method but objects are defined in an Enumeration.
processObjects(Iterator objects, int action) Similar to the previous method but objects are defined in an Iterator.
processAllObjects(int action) Similar to the previous method but operates on all objects.
All these methods are synchronized and return an integer which represents the number of objects that have switched to the requested state.
Methods to retrieve the current state of an object
The following method retrieves the current state (LOCK/UNLOCK/UNLOAD) of an object in the controller. Depending on the handler implementation (typically, if actions are performed in a different thread), the state may differ from reality, for example, a content is not yet available although the state is LOCK.
int getObjectStatus(Object obj) Returns the current state of the given object.
Other methods of the IlvContentController class:
IlvSDMEngine getSDMEngine() Returns the SDM engine.
IlvContentHandler getContentHandler() Returns the content handler.
void setNotificationEnabled(boolean on) If
on is
false, the handler is not notified.
boolean isNotificationEnabled() Returns whether notifications are enabled.
int getLockedCount() Returns the number of locked objects.
int getLoadedCount() Returns the number of objects in the cache.
The IlvContentHandler interface
The
IlvContentHandler interface defines the following methods:
loadContent(IlvContentControler source, Object[] objs) Loads the content of the given objects into the SDM model.
unloadContent(IlvContentControler source, Object[] objs) Unloads the content of the given objects into the SDM model.
The source argument indicates the controller that sends the request.
The IlvVisibleAreaListener class
The
IlvVisibleAreaListener class computes the visible area of a view as it changes and sends it as a request to the controller. The constructor takes the controller as parameter. To start listening to the visible area changes on a view, call the method:
installListener(IlvManagerView target) Installs a transformer listener.
Example of use:
IlvVisibleAreaListener l = new IlvVisibleAreaListener(contentControler);
l.installListener(contentControler.getSDMEngine().getReferenceView());
The method requestAreaToLock can be subclassed to control the area to lock, as follows:
int requestAreaToLock(IlvRect area) Called when the view transformer has changed. The default implementation simply calls the controller method
lockArea(area, OVERRIDE) and returns the number of objects that have been loaded.
Using content on demand
The content controller needs to be associated with an SDM engine and a handler.
Using the content on demand feature involves the following steps:
To use the content on demand feature:
1. Associate the content controller with the SDM engine and the handler.
_controller = new IlvContentController();
_controller.setSDMEngine(diagrammer.getEngine());
_controller.setContentHandler(new ContentHandler());
private class ContentHandler extends IlvContentHandler() {
// here we load/unload objects
private void loadObject(Object node, boolean load) {
if (load) {
model.setObjectProperty(node, CONTENT, ...);
} else {
// unload values
model.setObjectProperty(node, CONTENT, null);
}
}
// callback for loading content
public void loadContent(IlvContentController source, Object[] objects) {
// prevent too much notifications
diagrammer.setAdjusting(true);
// loop over objects to load
for (int i=0; i<objects.length; i++) {
loadObject(objects[i], true);
}
diagrammer.setAdjusting(false);
}
// callback for unloading content
public void unloadContent(IlvContentController source, Object[]
objects) {
diagrammer.setAdjusting(true);
for (int i=0; i<objects.length; i++) {
loadObject(objects[i], false);
}
diagrammer.setAdjusting(false);
}
}
}
2. Optionally, change the cache value using the setCacheSize(int size) method.
You can adjust the cache size according to the desired behavior. The default value is infinite, which means that all loaded content is never unloaded.
_controller.setCacheSize(1024);
3. Install a view listener that will send requests to the controller.
IlvVisibleAreaListener l = new IlvVisibleAreaListener(contentControler);
l.installListener(contentControler.getSDMEngine().getReferenceView());
4. Now navigate in the view to automatically load or unload objects.
Content on demand and tiling systems
The content on demand feature is similar to a tiling system, such as ilog.views.tiling, with the following major differences:
The granularity of content on demand is an SDM model object, not a tile. However, it is possible to implement a tiling behavior outside the controller. For example, when the handler is asked to load an object, all the objects of the same group can be loaded as well.
Content on demand does not create objects, it loads and unloads content. In other words, the controller knows only about the objects currently in the SDM model.
The user has the possibility to load or unload objects that are not in the visible area.
Copyright © 2018, Rogue Wave Software, Inc. All Rights Reserved.
