y.view
Class ModelViewManager

java.lang.Object
  y.view.ModelViewManager

public class ModelViewManager
extends Object

Utility class that performs automatic synchronization of graph element insertion and removal between a distinguished graph (the model) and one or more satellite graphs (the views).

Additionally, ModelViewManager supports filtered views of its model by associating an appropriate implementation of ModelViewManager.Filter to a view. Filtering provides a convenient way to create views whose element sets are disjoint from the element set of the manager's model (where element set means the nodes and edges in a graph).

Note: Synchronization is triggered by special GraphListener implementations; using the various hide/unhide methods provided by Graph to manipulate either model or views will therefore prevent the manager from working properly.

Nested Class Summary

static interface

ModelViewManager.Filter Specifies the contract of graph element filters for views handled by ModelViewManager instances.

Method Summary

void	addViewGraph(Graph view, ModelViewManager.Filter filter, boolean updateModelOnStructuralChange) Adds the specified Graph to the list of views handled by this manager.
void	bindModelToView(Edge model, Edge view) Binds the specified model edge to the specified view edge.
void	bindModelToView(Node model, Node view) Binds the specified model node to the specified view node.
Edge	createModelEdge(Node src, Node tgt, boolean updateViewGraphs) Creates a new edge in this manager's model graph connecting the specified nodes.
Node	createModelNode(boolean updateViewGraphs) Creates a new node in this manager's model graph.
Edge	createViewEdge(Node src, Node tgt, boolean updateModel) Creates a new edge connecting the specified nodes.
Graph	createViewGraph(GraphCopier.CopyFactory factory, ModelViewManager.Filter filter, boolean updateModelOnStructuralChange) Creates a new view for the model of this manager.
Node	createViewNode(Graph view, boolean updateModel) Creates a new node in the specified Graph.
void	dispose() Disposes this ModelViewManager.
GraphCopier.CopyFactory	getDefaultCopyFactory() Returns the default CopyFactory used by this manager.
ModelViewManager.Filter	getFilter(Graph viewGraph) Returns the Filter that is currently associated to the specified graph, or null if no filtering is applied to the contents of the specified graph.
static ModelViewManager	getInstance(Graph graph) Returns a ModelViewManager instance for the specified graph.
Graph	getModel() Returns the model graph used by this manager.
Edge	getModelEdge(Edge viewEdge) Returns the edge in the model managed by this ModelViewManager that corresponds to viewEdge or null if no such edge exists.
Node	getModelNode(Node viewNode) Returns the node in the model managed by this ModelViewManager that corresponds to viewNode or null if there is no such node.
Edge	getViewEdge(Edge model, Graph viewGraph) Returns the edge in viewGraph corresponding to edge model or null if no such edge exists in viewGraph (due to filtering).
Node	getViewNode(Node model, Graph viewGraph) Returns the node in viewGraph corresponding to node model or null if there is no such node in viewGraph (due to filtering).
boolean	isUpdateModelOnStructuralChangeEnabled(Graph viewGraph) Returns true, iff structural changes in the specified graph are automatically propagated to the model graph; false otherwise.
void	removeModelEdge(Edge edge, boolean updateViewGraphs) Removes the specified edge from this manager's model graph.
void	removeModelNode(Node node, boolean updateViewGraphs) Removes the specified node from this manager's model graph.
void	removeViewEdge(Edge edge, boolean updateModel) Removes the specified edge from its associated graph.
void	removeViewGraph(Graph view) Removes the specified Graph from the list of views handled by this manager.
void	removeViewNode(Node node, boolean updateModel) Removes the specified node from its associated graph.
void	setDefaultCopyFactory(GraphCopier.CopyFactory factory) Specifies the default CopyFactory used by this manager.
void	setFilter(Graph viewGraph, ModelViewManager.Filter filter) Specifies the Filter that should be applied when elements in viewGraph are created by this manager.
void	setUpdateModelOnStructuralChangeEnabled(Graph viewGraph, boolean enabled) Specifies whether structural changes in viewGraph should be automatically propagated to the model graph (and from there to all other view graphs, as usual).
void	synchronizeModelToViewGraph(Graph viewGraph) Updates the specified graph to include all model elements accepted by the filter associated to it exclusively.
void	synchronizeModelToViewGraphs() Updates all view graphs handled by this manager to include all model elements accepted by their associated filters exclusively.
void	synchronizeViewGraphToModel(Graph viewGraph) Updates the model graph of this manager to include all elements currently contained in the specified graph exclusively.
Iterator	viewEdges(Edge model) Returns a read-only Iterator for all the view edges corresponding to edge model.
Iterator	viewGraphs() Returns a read-only Iterator for the views handled by this manager.
Iterator	viewNodes(Node model) Returns a read-only Iterator for all the view nodes corresponding to node model.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

getModel

public Graph getModel()

Returns the model graph used by this manager.

Returns:

the model graph used by this manager

createViewGraph

public Graph createViewGraph(GraphCopier.CopyFactory factory,
                             ModelViewManager.Filter filter,
                             boolean updateModelOnStructuralChange)

Creates a new view for the model of this manager. The contents of the view will be a filtered copy of the model's current elements.

Parameters:

factory - a GraphCopier.CopyFactory that is used to create the new view and any graph elements in it. If null, the default copy factory is used.

filter - a Filter that determines which model elements are to be included in the created view. If null, all model elements are included.

updateModelOnStructuralChange - determines whether structural changes in the created view are to be automatically synchronized to the model.

addViewGraph

public void addViewGraph(Graph view,
                         ModelViewManager.Filter filter,
                         boolean updateModelOnStructuralChange)

Adds the specified Graph to the list of views handled by this manager.

The CopyFactory currently set on the specified Graph is used for all subsequent view element creation operations.

The view is added as is, i.e. existing view elements are not removed, neither are existing model elements added. Use methods bindModelToView(y.base.Node, y.base.Node) and bindModelToView(y.base.Edge, y.base.Edge) to bind existing model elements to existing view elements. Use method synchronizeModelToViewGraph(y.base.Graph) to clear and recreate the view complete with appropriate model-to-view bindings.

Throws:

IllegalArgumentException - if view is null or if view has already been registered as a view in the context of a ModelViewManager.

Parameters:

view - a Graph graph to be registered as a view for this manager's model.

filter - a Filter that determines which model elements are to be included in the created view. If null, all model elements are included.

updateModelOnStructuralChange - determines whether structural changes in the added view are to be automatically synchronized to the model.

removeViewGraph

public void removeViewGraph(Graph view)

Removes the specified Graph from the list of views handled by this manager. All model-to-view binding information concerning the specified Graph is deleted, too.

viewGraphs

public Iterator viewGraphs()

Returns a read-only Iterator for the views handled by this manager.

Returns:

a read-only Iterator for the views handled by this manager.

viewEdges

public Iterator viewEdges(Edge model)

Returns a read-only Iterator for all the view edges corresponding to edge model.

Note, the iterators created with this method are not fail-fast as one is used to from the Java™ Collections Framework, because there is no reliable way to check for comodifications of the view graphs that actually hold the view edges.

Parameters:

model - an Edge in the model of this ModelViewManager.

Returns:

a read-only Iterator for all the view edges corresponding to edge model.

viewNodes

public Iterator viewNodes(Node model)

Returns a read-only Iterator for all the view nodes corresponding to node model.

Note, the iterators created with this method are not fail-fast as one is used to from the Java™ Collections Framework, because there is no reliable way to check for comodifications of the view graphs that actually hold the view nodes.

Parameters:

model - a Node in the model of this ModelViewManager.

Returns:

a read-only Iterator for all the view nodes corresponding to edge model.

getDefaultCopyFactory

public GraphCopier.CopyFactory getDefaultCopyFactory()

Returns the default CopyFactory used by this manager.

Returns:

the default CopyFactory used by this manager.

setDefaultCopyFactory

public void setDefaultCopyFactory(GraphCopier.CopyFactory factory)

Specifies the default CopyFactory used by this manager.

Parameters:

factory - the default CopyFactory used by this manager.

getViewEdge

public Edge getViewEdge(Edge model,
                        Graph viewGraph)

Returns the edge in viewGraph corresponding to edge model or null if no such edge exists in viewGraph (due to filtering).

Throws:

IllegalArgumentException - if viewGraph is not one of the views handled by this ModelViewManager.

Parameters:

model - an Edge in the model of this ModelViewManager.

viewGraph - a Graph from the list of views handled by this ModelViewManager.

Returns:

the edge in viewGraph corresponding to edge viewGraph (due to filtering). model or null if no such edge exists in

getModelEdge

public Edge getModelEdge(Edge viewEdge)

Returns the edge in the model managed by this ModelViewManager that corresponds to viewEdge or null if no such edge exists.

Throws:

IllegalArgumentException - if viewEdge does not belong to a graph at all or if said graph is not one of the views handled by this ModelViewManager.

Parameters:

viewEdge - an Edge in a view that is handled by this ModelViewManager

Returns:

the edge in the model managed by this ModelViewManager that corresponds to viewEdge or null if there is no such edge.

getViewNode

public Node getViewNode(Node model,
                        Graph viewGraph)

Returns the node in viewGraph corresponding to node model or null if there is no such node in viewGraph (due to filtering).

Throws:

IllegalArgumentException - if viewGraph is not one of the views handled by this ModelViewManager.

Parameters:

model - a Node in the model of this ModelViewManager

viewGraph - a Graph from the list of views handled by this ModelViewManager.

Returns:

the node in viewGraph corresponding to node model or null if there is no such node in viewGraph (due to filtering).

getModelNode

public Node getModelNode(Node viewNode)

Returns the node in the model managed by this ModelViewManager that corresponds to viewNode or null if there is no such node.

Throws:

IllegalArgumentException - if viewNode does not belong to a graph at all or if said graph is not one of the views handled by this ModelViewManager.

Parameters:

viewNode - a Node in a view that is handled by this ModelViewManager

Returns:

the node in the model managed by this ModelViewManager that corresponds to viewNode or null if there is no such node.

createModelNode

public Node createModelNode(boolean updateViewGraphs)

Creates a new node in this manager's model graph.

Parameters:

updateViewGraphs - determines whether or not the creation of the new node should be propagated to the views associated to the model graph.

Returns:

the newly created node.

createModelEdge

public Edge createModelEdge(Node src,
                            Node tgt,
                            boolean updateViewGraphs)

Creates a new edge in this manager's model graph connecting the specified nodes.

Throws:

IllegalArgumentException - if either src or tgt is null.

Parameters:

src - the source node of the new edge.

tgt - the target node of the new edge.

updateViewGraphs - determines whether or not the creation of the new edge should be propagated to the views associated to the model graph.

Returns:

the newly created edge.

createViewNode

public Node createViewNode(Graph view,
                           boolean updateModel)

Creates a new node in the specified Graph.

Throws:

IllegalArgumentException - is view is null or if view is not one of the views handled by this ModelViewManager.

Parameters:

view - a Graph from the list of views handled by this ModelViewManager in which the new node is to be created.

updateModel - determines whether or not the creation of the new node should be propagated to the model graph.

Returns:

the newly created node.

createViewEdge

public Edge createViewEdge(Node src,
                           Node tgt,
                           boolean updateModel)

Creates a new edge connecting the specified nodes.

Throws:

IllegalArgumentException - if either src or tgt is null or src does not belong to one of the views handled by this ModelViewManager.

Parameters:

src - the source node of the new edge.

tgt - the target node of the new edge.

updateModel - determines whether or not the creation of the new edge should be propagated to the model graph.

Returns:

the newly created edge.

removeModelEdge

public void removeModelEdge(Edge edge,
                            boolean updateViewGraphs)

Removes the specified edge from this manager's model graph.

Parameters:

edge - the Edge to be removed.

updateViewGraphs - determines whether or not the removal of the edge should be propagated to the views associated to the model graph.

removeModelNode

public void removeModelNode(Node node,
                            boolean updateViewGraphs)

Removes the specified node from this manager's model graph.

Parameters:

node - the Node to be removed.

updateViewGraphs - determines whether or not the removal of the node should be propagated to the views associated to the model graph.

removeViewEdge

public void removeViewEdge(Edge edge,
                           boolean updateModel)

Removes the specified edge from its associated graph.

Throws:

IllegalArgumentException - if edge does not belong to one of the views handled by this ModelViewManager.

Parameters:

edge - the Edge to be removed.

updateModel - determines whether or not the removal of the edge should be propagated to the model graph.

removeViewNode

public void removeViewNode(Node node,
                           boolean updateModel)

Removes the specified node from its associated graph.

Throws:

IllegalArgumentException - if node does not belong to one of the views handled by this ModelViewManager.

Parameters:

node - the Node to be removed.

updateModel - determines whether or not the removal of the node should be propagated to the model graph.

bindModelToView

public void bindModelToView(Node model,
                            Node view)

Binds the specified model node to the specified view node. I.e. after model has been bound to view a call to getModelNode(view) will return model and a call to getViewNode(model, view.getGraph()) will return view

Throws:

IllegalArgumentException - if model does not belong to this ModelViewManager's model graph or if view does not belong to one of the views handled by this ModelViewManager.

Parameters:

model - the model node.

view - the view node.

bindModelToView

public void bindModelToView(Edge model,
                            Edge view)

Binds the specified model edge to the specified view edge. I.e. after model has been bound to view a call to getModelEdge(view) will return model and a call to getViewEdge(model, view.getGraph()) will return view

Throws:

IllegalArgumentException - if model does not belong to this ModelViewManager's model graph or if view does not belong to one of the views handled by this ModelViewManager.

Parameters:

model - the model edge.

view - the view edge.

synchronizeModelToViewGraphs

public void synchronizeModelToViewGraphs()

Updates all view graphs handled by this manager to include all model elements accepted by their associated filters exclusively. I.e. if there are elements in this manager's model for which no model-to-view bindings exist for a given view, representatives of these elements are created in said view. Moreover, all elements in a given view for which no model representatives exist are removed from said view.

synchronizeModelToViewGraph

public void synchronizeModelToViewGraph(Graph viewGraph)

Updates the specified graph to include all model elements accepted by the filter associated to it exclusively. I.e. if there are elements in this manager's model for which no model-to-view bindings exist for viewGraph, representatives of these elements are created in viewGraph. Moreover, all elements in viewGraph for which no model representatives exist are removed from viewGraph.

Throws:

IllegalArgumentException - if viewGraph is not one of the views handled by this ModelViewManager.

Parameters:

viewGraph - a Graph from the list of views handled by this ModelViewManager that is to be updated.

synchronizeViewGraphToModel

public void synchronizeViewGraphToModel(Graph viewGraph)

Updates the model graph of this manager to include all elements currently contained in the specified graph exclusively. I.e. if there are elements in viewGraph for which no model-to-view bindings exist, representatives of these elements are created in the model. Moreover, all elements in the model for which no representatives exist in viewGraph are removed from the model.

Note: Structural changes in the model due to the synchronization process triggered by this method will be propagated to all other views as usual.

Throws:

IllegalArgumentException - if viewGraph is not one of the views handled by this ModelViewManager.

Parameters:

viewGraph - a Graph from the list of views handled by this ModelViewManager whose structure is to be replicated in the model graph.

isUpdateModelOnStructuralChangeEnabled

public boolean isUpdateModelOnStructuralChangeEnabled(Graph viewGraph)

Returns true, iff structural changes in the specified graph are automatically propagated to the model graph; false otherwise.

Throws:

IllegalArgumentException - if viewGraph is not one of the views handled by this ModelViewManager.

Parameters:

viewGraph - a Graph from the list of views handled by this ModelViewManager.

Returns:

true, iff structural changes in the specified graph are automatically propagated to the model graph; false otherwise.

setUpdateModelOnStructuralChangeEnabled

public void setUpdateModelOnStructuralChangeEnabled(Graph viewGraph,
                                                    boolean enabled)

Specifies whether structural changes in viewGraph should be automatically propagated to the model graph (and from there to all other view graphs, as usual).

Throws:

IllegalArgumentException - if viewGraph is not one of the views handled by this ModelViewManager.

Parameters:

viewGraph - a Graph from the list of views handled by this ModelViewManager.

enabled - if true, structural changes are automatically propagated from the specifed view graph to the model graph.

getFilter

public ModelViewManager.Filter getFilter(Graph viewGraph)

Returns the Filter that is currently associated to the specified graph, or null if no filtering is applied to the contents of the specified graph.

Throws:

IllegalArgumentException - if viewGraph is not one of the views handled by this ModelViewManager.

Parameters:

viewGraph - a Graph from the list of views handled by this ModelViewManager.

Returns:

the Filter that is currently associated to the specified graph, or null if no filtering is applied to the contents of the specified graph.

setFilter

public void setFilter(Graph viewGraph,
                      ModelViewManager.Filter filter)

Specifies the Filter that should be applied when elements in viewGraph are created by this manager.

Note: Setting a new filter has no effect on the current contents of the specified graph, but only on possible future element creations.

Throws:

IllegalArgumentException - if viewGraph is not one of the views handled by this ModelViewManager.

Parameters:

viewGraph - a Graph from the list of views handled by this ModelViewManager.

filter - the Filter that determines whether or not model elements should be included in the specified view. May be null, indicating that no filtering should occur for the specified graph (i.e. all model elements are included).

dispose

public void dispose()

Disposes this ModelViewManager. All model-to-view bindings stored by this manager are removed.

getInstance

public static ModelViewManager getInstance(Graph graph)

Returns a ModelViewManager instance for the specified graph. The specified graph will serve as the manager's model graph for all future purposes.

Throws:

IllegalArgumentException - if graph is null.

Parameters:

graph - the Graph that should serve as the returned ModelViewManager's model. May not be null.

Returns:

a ModelViewManager instance for the specified graph.