bundles/org.simantics.g2d/src/org/simantics/g2d/diagram/handler/RelationshipHandler.java

   1 /*******************************************************************************
   2  * Copyright (c) 2007, 2010 Association for Decentralized Information Management
   3  * in Industry THTH ry.
   4  * All rights reserved. This program and the accompanying materials
   5  * are made available under the terms of the Eclipse Public License v1.0
   6  * which accompanies this distribution, and is available at
   7  * http://www.eclipse.org/legal/epl-v10.html
   8  *
   9  * Contributors:
  10  *     VTT Technical Research Centre of Finland - initial API and implementation
  11  *******************************************************************************/
  12 package org.simantics.g2d.diagram.handler;
  13
  14 import java.util.Collection;
  15
  16 import org.simantics.g2d.diagram.IDiagram;
  17 import org.simantics.utils.ObjectUtils;
  18
  19 /**
  20  * A diagram handler for managing and querying arbitrary relationships between
  21  * diagram objects. The management is done by claiming and denying relationships
  22  * about the objects. A single relationship can only exist once or not at all
  23  * between two objects, i.e. no duplicate relationships can be added.
  24  *
  25  * <p>
  26  * There is no pre-defined meaning for a relationship - it is completely
  27  * customizable by implementing your own {@link Relationship} interface.
  28  * </p>
  29  *
  30  * @author Tuukka Lehtonen
  31  */
  32 public interface RelationshipHandler extends DiagramHandler {
  33
  34     /**
  35      * A simple holder class for a single relationship. Holds all the
  36      * ingredients: two elements and the role of the relationship. The
  37      * relationship is either uni- or bi-directional.
  38      */
  39     public final class Relation {
  40         private final Object       subject;
  41         private final Relationship relationship;
  42         private final Object       object;
  43
  44         public Relation(Object subject, Relationship relationship, Object object) {
  45             assert subject != null;
  46             assert relationship != null;
  47             assert object != null;
  48             this.subject = subject;
  49             this.relationship = relationship;
  50             this.object = object;
  51         }
  52
  53         public Object getSubject() {
  54             return subject;
  55         }
  56
  57         public Relationship getRelationship() {
  58             return relationship;
  59         }
  60
  61         public Object getObject() {
  62             return object;
  63         }
  64
  65         @Override
  66         public int hashCode() {
  67             return ((ObjectUtils.hashCode(subject) * 31)
  68                     + ObjectUtils.hashCode(object) * 31)
  69                     + ObjectUtils.hashCode(relationship);
  70         }
  71
  72         @Override
  73         public boolean equals(Object obj) {
  74             if (obj == this)
  75                 return true;
  76             if (!(obj instanceof Relation))
  77                 return false;
  78             Relation other = (Relation) obj;
  79             return subject.equals(other.subject) && object.equals(other.object) && relationship.equals(other.relationship);
  80         }
  81
  82         @Override
  83         public String toString() {
  84             return "(" + subject + ", " + relationship + ", " + object + ")";
  85         }
  86     }
  87
  88     /**
  89      * Claim a single relationship between the specified subject and object. An
  90      * inverse relation will also be claimed if one exists.
  91      *
  92      * Subject and object should be alive (not destroyed). However it should not
  93      * be enforced to be activated within the specified diagram, at the moment
  94      * of invocation. This is because the relationship may be denied while the
  95      * elements are still in the process of being added to or removed from a
  96      * diagram.
  97      *
  98      * @param diagram the diagram to operate on
  99      * @param subject the subject of the relationship
 100      * @param predicate the relationship itself
 101      * @param object the object of the relationship
 102      */
 103     void claim(IDiagram diagram, Object subject, Relationship predicate, Object object);
 104
 105     /**
 106      * Deny a relationship. This will also deny the inverse relationship if one
 107      * exists.
 108      *
 109      * Subject and object should be alive (not destroyed). However it should not
 110      * be enforced to be activated within the specified diagram, at the moment
 111      * of invocation. This is because the relationship may be denied while the
 112      * elements are still in the process of being added to or removed from a
 113      * diagram.
 114      */
 115     void deny(IDiagram diagram, Object subject, Relationship predicate, Object object);
 116     void deny(IDiagram diagram, Relation relation);
 117     void denyAll(IDiagram diagram, Object element);
 118
 119     /**
 120      * Get all the relationships that are recorded for the specified element.
 121      *
 122      * @param diagram the diagram to operate on
 123      * @param element the element to get all relations for
 124      * @param result a collection for gathering the result of the query or null
 125      *        to create a new collection for the result.
 126      * @return
 127      */
 128     Collection<Relation> getRelations(IDiagram diagram, Object element, Collection<Relation> result);
 129
 130 }