bundles/org.simantics.objmap2/src/org/simantics/objmap/graph/IMapping.java

   1 /*******************************************************************************\r
   2  * Copyright (c) 2007, 2013 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.objmap.graph;\r
  13 \r
  14 import java.util.Collection;\r
  15 import java.util.Set;\r
  16 \r
  17 import org.simantics.db.Disposable;\r
  18 import org.simantics.db.ReadGraph;\r
  19 import org.simantics.db.WriteGraph;\r
  20 import org.simantics.objmap.bidirectional.IBidirectionalMapping;\r
  21 import org.simantics.objmap.exceptions.MappingException;\r
  22 \r
  23 /**\r
  24  * A mapping consists of domain (a set of resources), range (a set of Java objects) and\r
  25  * a set of links relating them. The mapping is used to propagate modifications of\r
  26  * domain elements to range and vice versa. \r
  27  * \r
  28  * @see <a href="http://www.simantics.org/wiki/index.php/org.simantics.objmap_Manual#Concepts">Manual</a>\r
  29  * \r
  30  * @author Hannu Niemistö\r
  31  */\r
  32 public interface IMapping<Domain,Range> extends Disposable, IBidirectionalMapping<Domain, Range> {\r
  33 \r
  34     /**\r
  35      * Returns the domain of the mapping. All set operations are supported.\r
  36      * Adding a new domain element does not automatically create a link to it.\r
  37      * Removal of a domain element removes also a link and the target element,\r
  38      * but does not remove the element from the database.\r
  39      */\r
  40     Set<Domain> getDomain();\r
  41 \r
  42     /**\r
  43      * Returns the range of the mapping. All set operations are supported.\r
  44      * Adding a new range element does not automatically create a link to it.\r
  45      * Removal of a range element removes also a link and the domain element,\r
  46      * but does not remove the domain element from the database.\r
  47      */\r
  48     Set<Range> getRange();\r
  49 \r
  50     /**\r
  51      * Updates all domain elements whose counterpart is modified and creates new\r
  52      * domain elements for previously added range elements. Returns the\r
  53      * collection of domain elements that were modified or created in the update\r
  54      * process.\r
  55      */\r
  56     Collection<Domain> updateDomain(WriteGraph g) throws MappingException;\r
  57 \r
  58     /**\r
  59      * Updates all range elements whose counterpart is modified and creates new\r
  60      * range elements for previously added domain elements. Returns the\r
  61      * collection of range elements that were modified or created in the update\r
  62      * process.\r
  63      */\r
  64     Collection<Range> updateRange(ReadGraph g) throws MappingException;\r
  65 \r
  66     /**\r
  67      * Returns the counterpart of a domain element or null if the element does\r
  68      * not belong to the domain or does not have a link.\r
  69      */\r
  70     Range get(Domain domainElement);\r
  71 \r
  72     /**\r
  73      * Returns the counterpart of a range element or null if the element does\r
  74      * not belong to the range or does not have a link.\r
  75      */\r
  76     Domain inverseGet(Range rangeElement);\r
  77 \r
  78     /**\r
  79      * A convenience method that adds a domain element to the mapping and\r
  80      * immediately updates the mapping and returns the corresponding range\r
  81      * element.\r
  82      */\r
  83     Range map(ReadGraph g, Domain domainElement) throws MappingException;\r
  84 \r
  85     /**\r
  86      * A convenience method that adds a range element to the mapping and\r
  87      * immediately updates the mapping and returns the corresponding domain\r
  88      * element.\r
  89      */\r
  90     Domain inverseMap(WriteGraph g, Range rangeElement)\r
  91             throws MappingException;\r
  92 \r
  93     /**\r
  94      * Tells the mapping that the domain element has been modified.\r
  95      */\r
  96     void domainModified(Domain domainElement);\r
  97 \r
  98     /**\r
  99      * Tells the mapping that the range element has been modified.\r
 100      */\r
 101     void rangeModified(Range rangeElement);\r
 102 \r
 103     /**\r
 104      * Tells if some domain elements have been modified or added.\r
 105      */\r
 106     boolean isDomainModified();\r
 107 \r
 108     /**\r
 109      * Tells if some range elements have been modified or added.\r
 110      */\r
 111     boolean isRangeModified();\r
 112     \r
 113     Collection<Domain> getDomainModified();\r
 114     Collection<Range> getRangeModified();\r
 115 \r
 116     /**\r
 117      * Returns a collection of domain elements which have been modified and also\r
 118      * their counterparts in the mapping are modified. These elements are in\r
 119      * conflict in the sense that the updating domain and range in different\r
 120      * orders may produce different results.\r
 121      */\r
 122     Collection<Domain> getConflictingDomainElements();\r
 123 \r
 124     /**\r
 125      * Returns a collection of range elements which have been modified and also\r
 126      * their counterparts in the mapping are modified. These elements are in\r
 127      * conflict in the sense that the updating domain and range in different\r
 128      * orders may produce different results.\r
 129      */\r
 130     Collection<Range> getConflictingRangeElements();\r
 131 \r
 132     /**\r
 133      * Adds a listener for domain and range modifications.\r
 134      */\r
 135     void addMappingListener(IMappingListener listener);\r
 136 \r
 137     /**\r
 138      * Removes a previously added listener.\r
 139      */\r
 140     void removeMappingListener(IMappingListener listener);\r
 141 \r
 142 }\r