ilog.views.sdm
Interface IlvSDMModel

All Known Implementing Classes:

IlvAbstractSDMModel, IlvBasicSDMModel, IlvDefaultSDMModel, IlvFilterSDMModel, IlvJavaBeanSDMModel, IlvJDBCSDMModel, IlvMultipleSDMModel, IlvRDFSDMModel, IlvSDMUndoManager.UndoSDMModel, IlvTableSDMModel

public interface IlvSDMModel

The IlvSDMModel interface describes a set of objects that constitute a graph of nodes connected by links.

The SDM model is designed to be used as the source of data for an IlvSDMEngine that will display the data objects in an ILOG JViews grapher. The SDM model is independent of any graphic representation, and can be displayed under different forms, for example in a table or in a chart.

An SDM model describes a set of objects of two types: links and nodes. It is mandatory for a link to connect two nodes, but it is not mandatory for a node to be connected to other nodes. In other words, the SDM model distinguishes only between links and "non-links". For simplicity, we call these "non-link" objects "nodes", even when they are not connected to other nodes.

The model can be hierarchical: each top-level node or link can have children. This set of children is called a "sub-model". The nodes of a sub-model can be connected together, and they can also be connected to nodes that are outside of the sub-model. In other words, it is legal for a link to connect two nodes that belong to different levels in the data hierarchy.

The SDM model makes no assumptions about the Java class of the application objects: all node and link entities are returned as instances of Object. It is possible, for example, that some nodes will belong to a class and some other nodes will belong to another class. It is up to the SDM engine's graphic renderer (or any other object that displays the model) to create an appropriate graphic representation of the application objects returned by the model.

For most applications, you do not need to implement the IlvSDMModel interface from the start. You can either use the IlvDefaultSDMModel class that implements the interface using built-in node and link types, or you can subclass IlvBasicSDMModel and override only the methods that you need.

Since:

JViews 4.0

See Also:

IlvSDMEngine, IlvDefaultSDMModel, IlvBasicSDMModel

Method Summary

void	addObject(Object object, Object parent, Object before) Adds an object to the model.
void	addSDMModelListener(SDMModelListener listener) Adds a listener to this SDM model.
void	addSDMPropertyChangeListener(SDMPropertyChangeListener listener) Adds a property change listener to this SDM model.
void	clear() Removes all the objects from the model.
Object	createLink(String tag) Creates a new link.
Object	createNode(String tag) Creates a new node.
Enumeration	getChildren(Object parent) Returns the objects of a submodel.
Object	getFrom(Object link) Returns the application object that is the source of the specified link.
String	getID(Object obj) Returns the identifier of the object.
Object	getObject(String id) Returns the object of the model whose identifier is id.
Object	getObjectProperty(Object obj, String property) Returns a property of an object of the data.
String[]	getObjectPropertyNames(Object obj) Returns the names of the properties that can be retrieved for an object.
Enumeration	getObjects() Returns the application objects that represent the SDM nodes and links.
Object	getParent(Object obj) Returns the parent of an object, if that object belongs to a submodel.
String	getTag(Object obj) Returns the symbolic type (the "tag") of an object.
Object	getTo(Object link) Returns the application object that is the destination of the specified link.
boolean	isAdjusting() Returns the last value passed to setAdjusting(boolean).
boolean	isEditable() Specifies whether this model supports editing or not.
boolean	isLink(Object obj) Returns true if the specified data object is a link between two nodes.
void	removeObject(Object object) Removes an object from the model.
void	removeSDMModelListener(SDMModelListener listener) Removes a listener from this SDM model.
void	removeSDMPropertyChangeListener(SDMPropertyChangeListener listener) Removes a property change listener from this SDM model.
void	setAdjusting(boolean adjusting) Call this method to tell the SDM model that subsequent calls to the editing methods should be treated as a single modification.
void	setFrom(Object link, Object node) Sets the node that is the source of the specified link.
void	setID(Object obj, String id) Sets the identifier of an object.
void	setObjectProperty(Object object, String property, Object value) Sets the value of a property of an object of this model.
void	setTo(Object link, Object node) Sets the node that is the destination of the specified link.

Method Detail

getObjects

Enumeration getObjects()

Returns the application objects that represent the SDM nodes and links.

The nodes and the links are returned in a single enumeration, which makes it possible for an SDM model implementation to supply the data objects in a mixed order (for example, two nodes, then a link between them, then two other nodes, and so on).

Note that a link does not need to be enumerated after its end nodes, because the SDM engine handles forward references. Note, though, that loading the model will be faster if links are enumerated after their end nodes.

This method returns only the first level of the SDM, not the subobjects that can be attached to an object. If an object has a submodel, the elements of the submodel are returned by the getChildren method.

The SDM engine will call the isLink method to find out whether each object is a link or a node.

Returns:

An enumeration of objects that will be converted to IlvGraphics by the IlvSDMViewRenderer associated with the IlvSDMView. The returned enumeration can be null if the model has no objects.

getChildren

Enumeration getChildren(Object parent)

Returns the objects of a submodel. A submodel is a set of nodes and links that are logically attached to a parent object (usually a node, but this is not mandatory).

SDM renderers can decide to display subobjects in a special way, for instance with a "drill-down" node that displays the submodel only above a given zoom level.

The objects of the submodel can themselves have children.

Parameters:

parent - An object returned by getObjects or by a previous call to getChildren.

Returns:

An enumeration of objects in the submodel, or null if the parent has no children.

getParent

Object getParent(Object obj)

Returns the parent of an object, if that object belongs to a submodel. If the object is a top-level object, this method must return null.

Parameters:

obj - The object whose parent is queried.

isLink

boolean isLink(Object obj)

Returns true if the specified data object is a link between two nodes. When this method returns true, the model must be prepared to return non-null values from the getFrom and getTo methods.

Parameters:

obj - The object whose type is queried.

Returns:

true if and only if the specified data object is a link.

getFrom

Object getFrom(Object link)

Returns the application object that is the source of the specified link.

This method will be called only for links, that is, SDM objects for which the isLink method returned true.

The node returned by this method must be placed before the link in the enumeration returned by getObjects.

Parameters:

link - The link whose source node is queried.

getTo

Object getTo(Object link)

Returns the application object that is the destination of the specified link.

This method will be called only for links, that is, SDM objects for which the isLink method returned true.

The node returned by this method must be placed before the link in the enumeration returned by getObjects.

Parameters:

link - The link whose destination node is queried.

getID

String getID(Object obj)

Returns the identifier of the object. The identifier must allow you to find the object in a unique way using the method getObject(java.lang.String).

The implementations of the methods getID(java.lang.Object) and getObject(java.lang.String) must guarantee that getObject(getID(obj)) == obj for every object obj in a given model.

Parameters:

obj - The object whose identifier is requested.

Returns:

A string that identifies the object in a unique way.

setID

void setID(Object obj,
           String id)

Sets the identifier of an object. This method should generally be called only while the model is being built (for example, while reading an XML file). Changing the identifier of an object after getID(java.lang.Object) has been called may result in the object not being found any more by getObject(java.lang.String).

This method may do nothing if isEditable() returns false.

Parameters:

obj - The object whose identifier is to be changed.

id - The new identifier.

getObject

Object getObject(String id)

Returns the object of the model whose identifier is id.

The implementations of the methods getID(java.lang.Object) and getObject(java.lang.String) must guarantee that getObject(getID(obj)) == obj for every object obj in a given model.

Parameters:

id - The identifier of the requested object.

Returns:

The object whose identifier is id.

getTag

String getTag(Object obj)

Returns the symbolic type (the "tag") of an object.

The tag can be seen as a primary style: it allows the SDM to represent objects with different tags in different ways. When the model is saved or loaded from an XML file, the tag will be the tag name of the XML element.

The tag of an object cannot be changed. In general, all the objects with the same tag should have the same properties.

Parameters:

obj - The object whose tag is requested.

Returns:

A string that identifies the symbolic type of the object.

getObjectProperty

Object getObjectProperty(Object obj,
                         String property)

Returns a property of an object of the data.

The properties of data objects are queried by the SDM renderer, and used to set the graphic properties of the IlvGraphic object that represents the data object obj.

Parameters:

obj - The object whose property is queried.

property - The name of the property.

Returns:

An Object representing the value of the specified property, or null if the object does not have or support the specified property.

getObjectPropertyNames

String[] getObjectPropertyNames(Object obj)

Returns the names of the properties that can be retrieved for an object.

Parameters:

obj - The object whose property names are queried.

addSDMModelListener

void addSDMModelListener(SDMModelListener listener)

Adds a listener to this SDM model. Listeners are called to notify other objects (typically SDM engines using this SDM model) that nodes or links must be added to or removed from the SDM view, or that node or link properties have changed and must be rendered in the view.

Parameters:

listener - The listener to add.

removeSDMModelListener

void removeSDMModelListener(SDMModelListener listener)

Removes a listener from this SDM model. Listeners are called to notify other objects (typically SDM engines using this SDM model) that nodes or links must be added to or removed from the SDM view, or that node or link properties have changed and must be rendered in the view.

Parameters:

listener - The listener to remove.

addSDMPropertyChangeListener

void addSDMPropertyChangeListener(SDMPropertyChangeListener listener)

Adds a property change listener to this SDM model. Property change listeners are called to notify other objects (typically SDM engines using this SDM model) that a property of a node or a link has changed.

Parameters:

listener - The listener to add.

removeSDMPropertyChangeListener

void removeSDMPropertyChangeListener(SDMPropertyChangeListener listener)

Removes a property change listener from this SDM model. Property change listeners are called to notify other objects (typically SDM engines using this SDM model) that a property of a node or a link has changed.

Parameters:

listener - The listener to remove.

isEditable

boolean isEditable()

Specifies whether this model supports editing or not. If this method returns true, the methods addObject(java.lang.Object, java.lang.Object, java.lang.Object), removeObject(java.lang.Object), and setObjectProperty(java.lang.Object, java.lang.String, java.lang.Object) can be called to edit the model. Otherwise, the editing methods may be empty.

addObject

void addObject(Object object,
               Object parent,
               Object before)

Adds an object to the model.

This method should fire an SDMModelListener.objectAdded(ilog.views.sdm.event.SDMModelEvent) event to all SDMModelListeners registered with this model.

This method may do nothing if isEditable() returns false.

Parameters:

object - The new object to add to the model.

parent - The parent if the new object must be added to a submodel, or null if the new object is a top-level object.

before - An existing object of the model before which the new object must be inserted. You can pass null to append the new object at the end of the model.

removeObject

void removeObject(Object object)

Removes an object from the model.

This method should fire an SDMModelListener.objectRemoved(ilog.views.sdm.event.SDMModelEvent) event to all SDMModelListeners registered with this model.

Note that if object is a node, all the links connected to this node will point to a nonexistent object. If you also want the links coming from or going to that node to be removed from the object model, you must call removeObject on these links.

This method may do nothing if isEditable() returns false.

Parameters:

object - The object to remove.

setObjectProperty

void setObjectProperty(Object object,
                       String property,
                       Object value)

Sets the value of a property of an object of this model.

This method should fire a SDMPropertyChangeListener.propertyChanged(ilog.views.sdm.event.SDMPropertyChangeEvent) event to all SDMPropertyChangeListeners registered with this model.

This method may do nothing if isEditable() returns false.

Parameters:

object - The object whose property must be set.

property - The name of the property to set.

value - The new value of the property.

createNode

Object createNode(String tag)

Creates a new node.

This method may return null if isEditable() returns false.

Parameters:

tag - The tag of the new node.

createLink

Object createLink(String tag)

Creates a new link.

This method may return null if isEditable() returns false.

Parameters:

tag - The tag of the new link.

setFrom

void setFrom(Object link,
             Object node)

Sets the node that is the source of the specified link.

This method must be called only for links, that is, SDM objects for which the isLink method returned true.

This method may do nothing if isEditable() returns false.

Parameters:

link - The link whose source node must be set.

node - The new source node of the link.

setTo

void setTo(Object link,
           Object node)

Sets the node that is the destination of the specified link.

This method must be called only for links, that is, SDM objects for which the isLink method returned true.

This method may do nothing if isEditable() returns false.

Parameters:

link - The link whose destination node must be set.

node - The new destination node of the link.

setAdjusting

void setAdjusting(boolean adjusting)

Call this method to tell the SDM model that subsequent calls to the editing methods should be treated as a single modification. For example, an editor will typically issue the following calls to create a new object:

   boolean oldAdjusting = model.isAdjusting();
   model.setAdjusting(true);
   try {
     Object obj = model.createNode("node");
     obj.setObjectProperty("x", new Float(x));
     obj.setObjectProperty("y", new Float(y));
     obj.setObjectProperty("name", "Foo");
   } finally {
     model.setAdjusting(oldAdjusting);
   }
 

All SDMModelEvent events fired during an adjustment sequence should have their adjustment field set to this value.

If an IlvSDMEngine is using the model, ILOG suggests that you call IlvSDMEngine.setAdjusting(boolean) instead.

Parameters:

adjusting - The value of the flag.

isAdjusting

boolean isAdjusting()

Returns the last value passed to setAdjusting(boolean).

clear

void clear()

Removes all the objects from the model.