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.io.InputStream;
f@0: import java.util.concurrent.locks.ReentrantLock;
f@0: 
f@0: 
f@0: /**
f@0:  * A Diagram Element is either a node or an edge of the diagram. It's an abstract 
f@0:  * class which is extended by DiagramEdge and DiagramNode.    
f@0:  *
f@0:  */
f@0: @SuppressWarnings("serial")
f@0: public abstract class DiagramElement extends DiagramTreeNode implements Cloneable{
f@0: 	
f@0: 	protected DiagramElement(){
f@0: 		name = "";
f@0: 		id = NO_ID;
f@0: 		notifier = DUMMY_NOTIFIER; // initially set to no effect notifier
f@0: 	}
f@0: 	
f@0: 	/**
f@0: 	 * Returns the type of this diagram element. The type is like the category this element belongs to. 
f@0: 	 * For instance in a public transport diagram one might have three types of diagram element: tube, train
f@0: 	 * and busses.   
f@0: 	 *  
f@0: 	 * @return the type of this element 
f@0: 	 */
f@0: 	public String getType(){
f@0: 		return type;
f@0: 	}
f@0: 	
f@0: 	/**
f@0: 	 * Set the type of this diagram element. This method should be called as soon as the object is created
f@0: 	 * and should not be called anymore on this object.
f@0: 	 * 
f@0: 	 * @param type the type of this element
f@0: 	 */
f@0: 	protected void setType(String type){
f@0: 		 this.type = type;
f@0: 	}
f@0: 	
f@0: 	/**
f@0: 	 * Notifies the model of a changed that has happened on this element. If this element is not 
f@0: 	 * held by any model than this method will have no effect. 
f@0: 	 * @param evt an event representing the fact that the element is changed
f@0: 	 */
f@0: 	protected void notifyChange(ElementChangedEvent evt){
f@0: 		notifier.notifyChange(evt);
f@0: 	}
f@0: 	
f@0: 	/**
f@0: 	 * returns the tree node name "as it is", without any decoration such as notes, bookmarks or cardinality.
f@0: 	 * Unlike the String returned by toString
f@0: 	 * @return the tree node name
f@0: 	 */
f@0: 	public String getName(){
f@0: 		if(name.isEmpty() && id != NO_ID)
f@0: 			return "new " + getType() + " " + id;
f@0: 		return name;
f@0: 	}
f@0: 	   
f@0: 	/**
f@0: 	 * Sets the name of this element instance.
f@0: 	 * 
f@0: 	 * @param s the string to set as the name 
f@0: 	 * @param source the source of this action
f@0: 	 */
f@0: 	public void setName(String s, Object source){
f@0: 		String name = s;
f@0: 		/* if the user enters an empty string we go back to the default name */
f@0: 		if(s.isEmpty() && id != NO_ID){
f@0: 			name = "new " + getType() + " " + id;
f@0: 		}		
f@0: 		setUserObject(name);
f@0: 		this.name = name;
f@0: 		notifyChange(new ElementChangedEvent(this,this,"name",source));
f@0: 	}
f@0: 	
f@0: 	/**
f@0: 	 * Returns an InputStream to a sound file with the sound of this element 
f@0: 	 * @return an InputStream 
f@0: 	 */
f@0: 	public abstract InputStream getSound();
f@0: 	
f@0: 	/**
f@0: 	 * Sets the if for this element. The id is a number which uniquely identifies this instance
f@0: 	 * within a DiagramModel. 
f@0: 	 * Unlike the name, which can be the same for two different instances.  
f@0: 	 * @param id a long number which must be greater than 0
f@0: 	 * @throws IllegalArgumentException id the id passe as argument is lower or equal to 0.
f@0: 	 */
f@0: 	public void setId(long id){
f@0: 		if (id < NO_ID)
f@0: 			throw new IllegalArgumentException();
f@0: 		else 
f@0: 			this.id = id;
f@0: 		if(name.isEmpty() && id != NO_ID){
f@0: 			String s = "new " + getType() + " " + id; 
f@0: 			this.name = s;
f@0: 			setUserObject(s);
f@0: 		}
f@0: 	}
f@0: 	
f@0: 	/**
f@0: 	 * Returns the id of this instance of DiagramElement.
f@0: 	 * @return a long representing the id of this instance of the element 
f@0: 	 * or NO_ID if it hasn't got one. 
f@0: 	 */
f@0: 	public long getId(){
f@0: 		return id;
f@0: 	}
f@0: 	
f@0: 	public ReentrantLock getMonitor(){
f@0: 		if(notifier == null)
f@0: 			return null;
f@0: 		return (ReentrantLock)notifier;
f@0: 	}
f@0: 		
f@0: 	/** 
f@0: 	 *  Sets the notifier to be used for notification 
f@0: 	 *  following an internal change of the node
f@0: 	 * @param notifier the notifier call the notify method(s) on 
f@0: 	 */
f@0: 	<N extends DiagramNode,E extends DiagramEdge> void setNotifier(DiagramModel<N,E>.ReentrantLockNotifier notifier){
f@0: 		this.notifier = notifier;
f@0: 	}
f@0: 	
f@0: 	@Override
f@0: 	public Object clone(){
f@0: 		DiagramElement clone = (DiagramElement)super.clone();
f@0: 		clone.name = "";
f@0: 		clone.id = NO_ID;
f@0: 		return clone;
f@0: 	}
f@0: 	
f@0: 	/**
f@0: 	 * Returns a description of the DiagramElement passed as argument, suitable 
f@0: 	 * for logging purposes. 
f@0: 	 * 
f@0: 	 * @param de the diagram element to log stuff about 
f@0: 	 * @return a log entry describing the element passed as agument
f@0: 	 */
f@0: 	public static String toLogString(DiagramElement de){
f@0: 		StringBuilder builder = new StringBuilder(de.getName());
f@0: 		builder.append('(');
f@0: 		if(de.getId() == DiagramElement.NO_ID)
f@0: 			builder.append("no id");
f@0: 		else
f@0: 			builder.append(de.getId());
f@0: 		builder.append(')');	
f@0: 		return builder.toString();
f@0: 	}
f@0: 	
f@0: 	private long id = NO_ID;
f@0: 	private ElementNotifier notifier;
f@0: 	private String type;
f@0: 	private String name;
f@0: 	private static final ElementNotifier DUMMY_NOTIFIER = new ElementNotifier(){
f@0: 		@Override
f@0: 		public void notifyChange(ElementChangedEvent evt) {}
f@0: 	};
f@0: 	/**
f@0: 	 * The value returned by getId() if the element instance has not been assigned any id 
f@0: 	 */
f@0: 	public static final long NO_ID = 0;
f@0: }