f@0: /*  
f@0:  CCmI Editor - A Collaborative Cross-Modal Diagram Editing Tool
f@0:   
f@0:  Copyright (C) 2011  Queen Mary University of London (http://ccmi.eecs.qmul.ac.uk/)
f@0: 
f@0:  This program is free software: you can redistribute it and/or modify
f@0:  it under the terms of the GNU General Public License as published by
f@0:  the Free Software Foundation, either version 3 of the License, or
f@0:  (at your option) any later version.
f@0: 
f@0:  This program is distributed in the hope that it will be useful,
f@0:  but WITHOUT ANY WARRANTY; without even the implied warranty of
f@0:  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
f@0:  GNU General Public License for more details.
f@0: 
f@0:  You should have received a copy of the GNU General Public License
f@0:  along with this program.  If not, see <http://www.gnu.org/licenses/>.
f@0: */
f@0: package uk.ac.qmul.eecs.ccmi.diagrammodel;
f@0: 
f@0: import java.util.Collection;
f@0: import java.util.concurrent.locks.ReentrantLock;
f@0: 
f@0: import javax.swing.event.ChangeListener;
f@0: 
f@0: /**
f@0:  * 
f@0:  * Represents the collection side of a DiagramModel instance. 
f@0:  *
f@0:  * @param <N> a type extending DiagramNode
f@0:  * @param <E> a type extending DiagramEdge
f@0:  */
f@0: public interface CollectionModel<N extends DiagramNode, E extends DiagramEdge> {
f@0: 	/**
f@0: 	 * Adds a collection listener to the model.  
f@0: 	 * @param listener the listener to be added
f@0: 	 */
f@0: 	void addCollectionListener(CollectionListener listener);
f@0: 	/**
f@0: 	 * Removed a collection listener to the model.  
f@0: 	 * @param listener the listener to be removed
f@0: 	 */
f@0: 	void removeCollectionListener (CollectionListener listener);
f@0: 	
f@0: 	/**
f@0: 	 * insert a DiagramNode into the diagram model
f@0: 	 * @param n the DiagramNode to be inserted in the collection
f@0: 	 * @param source the source of the action. This will be reported as the source of the event 
f@0: 	 * generated by this action to the registered listeners. If null the CollectionModel instance
f@0: 	 * itself will be used as source 
f@0: 	 * @return true if this collection changed as a result of the call
f@0: 	 */
f@0: 	boolean insert(N n, Object source) ;
f@0: 	
f@0: 	/**
f@0: 	 * insert a DiagramEdge into the diagram model
f@0: 	 * @param e the DiagramNode to be inserted in the collection
f@0: 	 * @param source the source of the action. This will be reported as the source of the event 
f@0: 	 * generated by this action to the registered listeners. If null the CollectionModel instance
f@0: 	 * itself will be used as source
f@0: 	 * @return true if this collection changed as a result of the call
f@0: 	 */
f@0: 	boolean insert(E e, Object source);
f@0: 	
f@0: 	/**
f@0: 	 * Removes a DiagramElement from the model
f@0: 	 * @param e the diagramElement to be removed
f@0: 	 * @param source the source of the action. This will be reported as the source of the event 
f@0: 	 * generated by this action to the registered listeners. If null the CollectionModel instance
f@0: 	 * itself will be used as source
f@0: 	 * @return true if this collection changed as a result of the call
f@0: 	 */
f@0: 	boolean takeOut(DiagramElement e, Object source);
f@0: 	
f@0: 	/**
f@0: 	 * Returns the diagram nodes contained by the model as a collection  
f@0: 	 * @return the collection of diagram nodes
f@0: 	 */
f@0: 	Collection<N> getNodes();
f@0: 	
f@0: 	/**
f@0: 	 * Returns the diagram edges contained by the model as a collection  
f@0: 	 * @return the collection of diagram edges
f@0: 	 */
f@0: 	Collection<E> getEdges();
f@0: 	
f@0: 	/**
f@0: 	 * return a list of nodes and edges in the model as a unique collection 
f@0: 	 * of diagram elements. 
f@0: 	 * @return the collection of diagram elements
f@0: 	 */
f@0: 	Collection<DiagramElement> getElements();
f@0: 	
f@0: 	/**
f@0: 	 * Add a change listener to the model. the listeners will be fired each time the model 
f@0: 	 * goes from the unmodified to modified state. The model is modified when a either a 
f@0: 	 * node or an edge are inserted or removed or changed when they are within the model.    
f@0: 	 * @param l a ChangeListener to add to the model  
f@0: 	 */
f@0: 	void addChangeListener(ChangeListener l);
f@0: 	
f@0: 	/**
f@0: 	 * Removes a change listener from the model. 
f@0: 	 * @param l a ChangeListener to remove from the model
f@0: 	 */
f@0: 	void removeChangeListener(ChangeListener l);
f@0: 	
f@0: 	/**
f@0: 	 * Returns true if the model has been modified
f@0: 	 * @return true if the model has been modified
f@0: 	 */
f@0: 	boolean isModified();
f@0: 	
f@0: 	/**
f@0: 	 * Sets the model as unmodified. This entails that {@link #isModified()} will return 
f@0: 	 * false unless the model doesn't get modified again. After this call a new modification
f@0: 	 * of the model would trigger the associated change listeners again. 
f@0: 	 */
f@0: 	void setUnmodified();
f@0: 	
f@0: 	/**
f@0: 	 * Sorts the nodes and edges is the model. The ordering method is given by a diagram 
f@0: 	 * element comparator.
f@0: 	 * @see DiagramElementComparator
f@0: 	 */
f@0: 	void sort();
f@0: 	
f@0: 	/**
f@0: 	 * Returns a reentrant lock that can be used to access the nodes and edges via {@code getNodes()}
f@0: 	 * and {@code getEdges()} and the change methods in a synchronized fashion.   
f@0: 	 * @return a lock object
f@0: 	 */
f@0: 	ReentrantLock getMonitor();
f@0: 
f@0: }