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

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