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

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