/* $Id: UseCaseDiagramGraphModel.java 17866 2010-01-12 20:45:46Z linus $
*****************************************************************************
* Copyright (c) 2009 Contributors - see below
* All rights reserved. This program and the accompanying materials
* are made available under the terms of the Eclipse Public License v1.0
* which accompanies this distribution, and is available at
* http://www.eclipse.org/legal/epl-v10.html
*
* Contributors:
* tfmorris
*****************************************************************************
*
* Some portions of this file was previously release using the BSD License:
*/
// Copyright (c) 1996-2006 The Regents of the University of California. All
// Rights Reserved. Permission to use, copy, modify, and distribute this
// software and its documentation without fee, and without a written
// agreement is hereby granted, provided that the above copyright notice
// and this paragraph appear in all copies. This software program and
// documentation are copyrighted by The Regents of the University of
// California. The software program and documentation are supplied "AS
// IS", without any accompanying services from The Regents. The Regents
// does not warrant that the operation of the program will be
// uninterrupted or error-free. The end-user understands that the program
// was developed for research purposes and is advised not to rely
// exclusively on the program for any reason. IN NO EVENT SHALL THE
// UNIVERSITY OF CALIFORNIA BE LIABLE TO ANY PARTY FOR DIRECT, INDIRECT,
// SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES, INCLUDING LOST PROFITS,
// ARISING OUT OF THE USE OF THIS SOFTWARE AND ITS DOCUMENTATION, EVEN IF
// THE UNIVERSITY OF CALIFORNIA HAS BEEN ADVISED OF THE POSSIBILITY OF
// SUCH DAMAGE. THE UNIVERSITY OF CALIFORNIA SPECIFICALLY DISCLAIMS ANY
// WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
// MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE SOFTWARE
// PROVIDED HEREUNDER IS ON AN "AS IS" BASIS, AND THE UNIVERSITY OF
// CALIFORNIA HAS NO OBLIGATIONS TO PROVIDE MAINTENANCE, SUPPORT,
// UPDATES, ENHANCEMENTS, OR MODIFICATIONS.
package org.argouml.uml.diagram.use_case;
import java.beans.PropertyChangeEvent;
import java.beans.VetoableChangeListener;
import java.util.ArrayList;
import java.util.Collection;
import java.util.Collections;
import java.util.Iterator;
import java.util.List;
import org.apache.log4j.Logger;
import org.argouml.model.Model;
import org.argouml.uml.CommentEdge;
import org.argouml.uml.diagram.UMLMutableGraphSupport;
/**
* This class defines a bridge between the UML meta-model
* representation of the design and the GraphModel interface used by
* GEF.<p>
*
* This class handles only UML Use Case Diagrams.<p>
*/
public class UseCaseDiagramGraphModel
extends UMLMutableGraphSupport
implements VetoableChangeListener {
/**
* Logger.
*/
private static final Logger LOG =
Logger.getLogger(UseCaseDiagramGraphModel.class);
///////////////////////////////////////////////////////////////////////////
//
// Methods that implement the GraphModel itself
//
///////////////////////////////////////////////////////////////////////////
/**
* Return all ports on a node or edge supplied as argument.<p>
*
* The only objects on our diagram that have any ports are use
* cases and actors, and they each have one - themself.<p>
*
* @param nodeOrEdge A model element, for whom the list of ports is
* wanted.
*
* @return A List of the ports found.
*/
public List getPorts(Object nodeOrEdge) {
if (Model.getFacade().isAActor(nodeOrEdge)) {
List result = new ArrayList();
result.add(nodeOrEdge);
return result;
} else if (Model.getFacade().isAUseCase(nodeOrEdge)) {
List result = new ArrayList();
result.add(nodeOrEdge);
return result;
}
return Collections.EMPTY_LIST;
}
/**
* Return the node or edge that owns the given port.<p>
*
* In our implementation the only objects with ports, use
* themselves as the port, so are there own owner.<p>
*
* @param port The port, whose owner is wanted.
*
* @return The owner of the port.
*/
public Object getOwner(Object port) {
return port;
}
/**
* Return all edges going to given port.<p>
*
* The only objects with ports on the use case diagram are actors
* and use cases. In each case we find the attached association
* ends, and build a list of them as the incoming ports.<p>
*
* @param port The port for which we want to know the incoming edges.
*
* @return A list of objects which are the incoming edges.
*/
public List getInEdges(Object port) {
if (Model.getFacade().isAActor(port)
|| Model.getFacade().isAUseCase(port)) {
List result = new ArrayList();
Collection ends = Model.getFacade().getAssociationEnds(port);
if (ends == null) {
return Collections.EMPTY_LIST;
}
for (Object ae : ends) {
result.add(Model.getFacade().getAssociation(ae));
}
return result;
}
return Collections.EMPTY_LIST;
}
/**
* Return all edges going from the given port.<p>
*
* <em>Needs more work</em>. This would seem superficially to be
* identical to {@link #getInEdges}, but in our implementation we
* return an empty list.<p>
*
* @param port The port for which we want to know the outgoing edges.
*
* @return A list of objects which are the outgoing edges. Currently
* return the empty list.
*/
public List getOutEdges(Object port) {
return Collections.EMPTY_LIST;
}
///////////////////////////////////////////////////////////////////////////
//
// Methods that implement the MutableGraphModel interface
//
///////////////////////////////////////////////////////////////////////////
/**
* Determine if the given node can validly be placed on this
* graph.<p>
*
* This is simply a matter of determining if the node is an actor
* or use case.<p>
*
* <em>Note</em>. This is inconsistent with {@link #addNode},
* which will not allow a node to be added to the graph if it is
* already there.<p>
*
* @param node The node to be considered
*
* @return <code>true</code> if the given object is a valid node in
* this graph, <code>false</code> otherwise.
*/
@Override
public boolean canAddNode(Object node) {
if (Model.getFacade().isAAssociation(node)
&& !Model.getFacade().isANaryAssociation(node)) {
// A binary association is not a node so reject.
return false;
}
if (super.canAddNode(node)) {
return true;
}
if (containsNode(node)) {
return false;
}
return Model.getFacade().isAActor(node)
|| Model.getFacade().isAUseCase(node)
|| Model.getFacade().isAPackage(node);
}
/**
* Determine if the given edge can validly be placed on this graph.<p>
*
* We cannot do so if the edge is already on the graph (unlike
* nodes they may not appear more than once).<p>
*
* Otherwise, for all valid types of edge (binary association,
* generalization, extend, include, dependency) we get the two
* ends. If they are both nodes already on the graph we are OK,
* otherwise we cannot place the edge on the graph.<p>
*
* @param edge The edge to be considered
*
* @return <code>true</code> if the given object is a valid edge in
* this graph, <code>false</code> otherwise.
*/
@Override
public boolean canAddEdge(Object edge) {
if (edge == null) {
return false;
}
if (containsEdge(edge)) {
return false;
}
// Get the two ends of any valid edge
Object sourceModelElement = null;
Object destModelElement = null;
if (Model.getFacade().isAAssociation(edge)) {
// Only allow binary associations
Collection conns = Model.getFacade().getConnections(edge);
Iterator iter = conns.iterator();
if (conns.size() < 2) {
return false;
}
Object associationEnd0 = iter.next();
Object associationEnd1 = iter.next();
// Give up if the assocation ends don't have a type defined
if ((associationEnd0 == null) || (associationEnd1 == null)) {
return false;
}
sourceModelElement = Model.getFacade().getType(associationEnd0);
destModelElement = Model.getFacade().getType(associationEnd1);
} else if (Model.getFacade().isAGeneralization(edge)) {
sourceModelElement = Model.getFacade().getSpecific(edge);
destModelElement = Model.getFacade().getGeneral(edge);
} else if (Model.getFacade().isAExtend(edge)) {
sourceModelElement = Model.getFacade().getBase(edge);
destModelElement = Model.getFacade().getExtension(edge);
} else if (Model.getFacade().isAInclude(edge)) {
sourceModelElement = Model.getFacade().getBase(edge);
destModelElement = Model.getFacade().getAddition(edge);
} else if (Model.getFacade().isADependency(edge)) {
// A dependency potentially has many clients and suppliers. We only
// consider the first of each (not clear that we should really
// accept the case where there is more than one of either)
Collection clients = Model.getFacade().getClients(edge);
Collection suppliers = Model.getFacade().getSuppliers(edge);
if (clients == null || clients.isEmpty()
|| suppliers == null || suppliers.isEmpty()) {
return false;
}
sourceModelElement = clients.iterator().next();
destModelElement = suppliers.iterator().next();
} else if (edge instanceof CommentEdge) {
sourceModelElement = ((CommentEdge) edge).getSource();
destModelElement = ((CommentEdge) edge).getDestination();
} else {
return false;
}
// Both ends must be defined and nodes that are on the graph already.
if (sourceModelElement == null || destModelElement == null) {
LOG.error("Edge rejected. Its ends are not attached to anything");
return false;
}
if (!containsNode(sourceModelElement)
&& !containsEdge(sourceModelElement)) {
LOG.error("Edge rejected. Its source end is attached to "
+ sourceModelElement
+ " but this is not in the graph model");
return false;
}
if (!containsNode(destModelElement)
&& !containsEdge(destModelElement)) {
LOG.error("Edge rejected. Its destination end is attached to "
+ destModelElement
+ " but this is not in the graph model");
return false;
}
return true;
}
/**
* Add the given node to the graph, if valid.<p>
*
* We add the node if it is not already on the graph, and
* (assuming it to be an actor or use case) add it to the owned
* elements for the model.<p>
*
* <em>Needs more work</em>. In adding the node to the owned
* elements of the model namespace, we are implicitly making it
* public visibility (it could be private to this namespace).<p>
*
* <em>Note</em>. This method is inconsistent with
* {@link #canAddNode}, which will allow a node to be added to the
* graph if it is already there.<p>
*
* @param node The node to be added to the graph.
*/
@Override
public void addNode(Object node) {
LOG.debug("adding usecase node");
// Give up if we are already on the graph. This is a bit inconistent
// with canAddNode above.
if (!canAddNode(node)) {
return;
}
// Add the node, check that it is an actor or use case and add it to
// the model namespace.
getNodes().add(node);
if (Model.getFacade().isAUMLElement(node)
&& Model.getFacade().getNamespace(node) == null) {
Model.getCoreHelper().addOwnedElement(getHomeModel(), node);
}
// Tell GEF its changed
fireNodeAdded(node);
}
/**
* Add the given edge to the graph, if valid.<p>
*
* We add the edge if it is not already on the graph, and
* (assuming it to be an association, generalization, extend,
* include or dependency) add it to the owned elements for the
* model.<p>
*
* <em>Needs more work</em>. In adding the edge to the owned
* elements of the model namespace, we are implicitly making it
* public visibility (it could be private to this namespace).<p>
*
* @param edge The edge to be added to the graph.
*/
@Override
public void addEdge(Object edge) {
if (edge == null) {
throw new IllegalArgumentException("Cannot add a null edge");
}
if (getDestPort(edge) == null || getSourcePort(edge) == null) {
throw new IllegalArgumentException(
"The source and dest port should be provided on an edge");
}
if (LOG.isInfoEnabled()) {
LOG.info("Adding an edge of type "
+ edge.getClass().getName()
+ " to use case diagram.");
}
if (!canAddEdge(edge)) {
LOG.info("Attempt to add edge rejected");
return;
}
// Add the element and place it in the namespace of the model
getEdges().add(edge);
// TODO: assumes public
if (Model.getFacade().isAUMLElement(edge)
&& Model.getFacade().getNamespace(edge) == null) {
Model.getCoreHelper().addOwnedElement(getHomeModel(), edge);
}
// Tell GEF
fireEdgeAdded(edge);
}
/**
* Add the various types of edge that may be connected with the
* given node.<p>
*
* For use cases we may find extend and include relationships. For
* classifiers (effectively actors and use cases) we may find
* associations. For generalizable elements (effectively actors
* and use cases again) we may find generalizations and
* specializations. For ModelElements (effectively actors and use
* cases again) we may find dependencies.<p>
*
* @param node The node whose edges are to be added.
*/
@Override
public void addNodeRelatedEdges(Object node) {
super.addNodeRelatedEdges(node);
if (Model.getFacade().isAUseCase(node)) {
List relations = new ArrayList();
relations.addAll(Model.getFacade().getIncludes(node));
relations.addAll(Model.getFacade().getIncluders(node));
relations.addAll(Model.getFacade().getExtends(node));
relations.addAll(Model.getFacade().getExtenders(node));
for (Object relation : relations) {
if (canAddEdge(relation)) {
addEdge(relation);
}
}
}
if (Model.getFacade().isAClassifier(node)) {
Collection ends = Model.getFacade().getAssociationEnds(node);
for (Object ae : ends) {
if (canAddEdge(Model.getFacade().getAssociation(ae))) {
addEdge(Model.getFacade().getAssociation(ae));
}
}
}
if (Model.getFacade().isAGeneralizableElement(node)) {
Collection gn = Model.getFacade().getGeneralizations(node);
for (Object g : gn) {
if (canAddEdge(g)) {
addEdge(g);
}
}
Collection sp = Model.getFacade().getSpecializations(node);
for (Object s : sp) {
if (canAddEdge(s)) {
addEdge(s);
}
}
}
if (Model.getFacade().isAUMLElement(node)) {
Collection dependencies =
new ArrayList(Model.getFacade().getClientDependencies(node));
dependencies.addAll(Model.getFacade().getSupplierDependencies(node));
for (Object dependency : dependencies) {
if (canAddEdge(dependency)) {
addEdge(dependency);
}
}
}
}
/**
* Determine if the two given ports can be connected by a kind of
* edge to be determined by the ports.<p>
*
* <em>Note</em>. There appears to be a problem with the
* implementation, since it suggests actors cannot connect. In
* fact generalization is permitted, and this works, suggesting
* this method is not actually invoked in the current
* implementation of ArgoUML.<p>
*
* @param fromP The source port of the connection
*
* @param toP The destination port of the connection.
*
* @return <code>true</code> if the two given ports can be connected
* by a kind of edge to be determined by the
* ports. <code>false</code> otherwise.
*/
@Override
public boolean canConnect(Object fromP, Object toP) {
// Suggest that actors may not connect (see JavaDoc comment about
// this).
if (Model.getFacade().isAActor(fromP)
&& Model.getFacade().isAActor(toP)) {
return false;
}
// Everything else is OK
return true;
}
///////////////////////////////////////////////////////////////////////////
//
// Methods that implement the VetoableChangeListener interface
//
///////////////////////////////////////////////////////////////////////////
/**
* Called when a property of interest has been changed - in this
* case the owned elements of the model. Provided to implement the
* {@link VetoableChangeListener} interface.<p>
*
* We could throw a PropertyVetoException if we wished to allow
* the change to be rolled back, but we don't.<p>
*
* @param pce The event that triggered us, and from which we can extract
* the name of the property that triggered us.
*/
public void vetoableChange(PropertyChangeEvent pce) {
// Only interested in the "ownedElement" property. Either something has
// been added to the namespace for this model, or removed. In the
// latter case the "something" will be in the old value of the
// property, which is the collection of owned elements, and the new value
// will be the element import describing the model element and the
// model from which it was removed
if ("ownedElement".equals(pce.getPropertyName())) {
List oldOwned = (List) pce.getOldValue();
Object eo = /*(MElementImport)*/ pce.getNewValue();
Object me = Model.getFacade().getModelElement(eo);
// If the element import is in the old owned, it means it must have
// been removed. Make sure the associated model element is removed.
if (oldOwned.contains(eo)) {
LOG.debug("model removed " + me);
// Remove a node
if ((Model.getFacade().isAActor(me))
|| (Model.getFacade().isAUseCase(me))) {
removeNode(me);
} else if ((Model.getFacade().isAAssociation(me))
|| (Model.getFacade().isAGeneralization(me))
|| (Model.getFacade().isAExtend(me))
|| (Model.getFacade().isAInclude(me))
|| (Model.getFacade().isADependency(me))) {
// Remove an edge
removeEdge(me);
}
} else {
// Something was added - nothing for us to worry about
LOG.debug("model added " + me);
}
}
}
/**
* The UID.
*/
static final long serialVersionUID = -8516841965639203796L;
}