Migrated source code from Simantics SVN

[simantics/platform.git] / bundles / org.simantics.objmap2 / src / org / simantics / objmap / graph / IMapping.java

diff --git a/bundles/org.simantics.objmap2/src/org/simantics/objmap/graph/IMapping.java b/bundles/org.simantics.objmap2/src/org/simantics/objmap/graph/IMapping.java
new file mode 100644 (file)
index 0000000..655c716
--- /dev/null
+++ b/bundles/org.simantics.objmap2/src/org/simantics/objmap/graph/IMapping.java
@@ -0,0 +1,142 @@
+/*******************************************************************************\r
+ * Copyright (c) 2007, 2013 Association for Decentralized Information Management\r
+ * in Industry THTH ry.\r
+ * All rights reserved. This program and the accompanying materials\r
+ * are made available under the terms of the Eclipse Public License v1.0\r
+ * which accompanies this distribution, and is available at\r
+ * http://www.eclipse.org/legal/epl-v10.html\r
+ *\r
+ * Contributors:\r
+ *     VTT Technical Research Centre of Finland - initial API and implementation\r
+ *******************************************************************************/\r
+package org.simantics.objmap.graph;\r
+\r
+import java.util.Collection;\r
+import java.util.Set;\r
+\r
+import org.simantics.db.Disposable;\r
+import org.simantics.db.ReadGraph;\r
+import org.simantics.db.WriteGraph;\r
+import org.simantics.objmap.bidirectional.IBidirectionalMapping;\r
+import org.simantics.objmap.exceptions.MappingException;\r
+\r
+/**\r
+ * A mapping consists of domain (a set of resources), range (a set of Java objects) and\r
+ * a set of links relating them. The mapping is used to propagate modifications of\r
+ * domain elements to range and vice versa. \r
+ * \r
+ * @see <a href="http://www.simantics.org/wiki/index.php/org.simantics.objmap_Manual#Concepts">Manual</a>\r
+ * \r
+ * @author Hannu Niemistö\r
+ */\r
+public interface IMapping<Domain,Range> extends Disposable, IBidirectionalMapping<Domain, Range> {\r
+\r
+    /**\r
+     * Returns the domain of the mapping. All set operations are supported.\r
+     * Adding a new domain element does not automatically create a link to it.\r
+     * Removal of a domain element removes also a link and the target element,\r
+     * but does not remove the element from the database.\r
+     */\r
+    Set<Domain> getDomain();\r
+\r
+    /**\r
+     * Returns the range of the mapping. All set operations are supported.\r
+     * Adding a new range element does not automatically create a link to it.\r
+     * Removal of a range element removes also a link and the domain element,\r
+     * but does not remove the domain element from the database.\r
+     */\r
+    Set<Range> getRange();\r
+\r
+    /**\r
+     * Updates all domain elements whose counterpart is modified and creates new\r
+     * domain elements for previously added range elements. Returns the\r
+     * collection of domain elements that were modified or created in the update\r
+     * process.\r
+     */\r
+    Collection<Domain> updateDomain(WriteGraph g) throws MappingException;\r
+\r
+    /**\r
+     * Updates all range elements whose counterpart is modified and creates new\r
+     * range elements for previously added domain elements. Returns the\r
+     * collection of range elements that were modified or created in the update\r
+     * process.\r
+     */\r
+    Collection<Range> updateRange(ReadGraph g) throws MappingException;\r
+\r
+    /**\r
+     * Returns the counterpart of a domain element or null if the element does\r
+     * not belong to the domain or does not have a link.\r
+     */\r
+    Range get(Domain domainElement);\r
+\r
+    /**\r
+     * Returns the counterpart of a range element or null if the element does\r
+     * not belong to the range or does not have a link.\r
+     */\r
+    Domain inverseGet(Range rangeElement);\r
+\r
+    /**\r
+     * A convenience method that adds a domain element to the mapping and\r
+     * immediately updates the mapping and returns the corresponding range\r
+     * element.\r
+     */\r
+    Range map(ReadGraph g, Domain domainElement) throws MappingException;\r
+\r
+    /**\r
+     * A convenience method that adds a range element to the mapping and\r
+     * immediately updates the mapping and returns the corresponding domain\r
+     * element.\r
+     */\r
+    Domain inverseMap(WriteGraph g, Range rangeElement)\r
+            throws MappingException;\r
+\r
+    /**\r
+     * Tells the mapping that the domain element has been modified.\r
+     */\r
+    void domainModified(Domain domainElement);\r
+\r
+    /**\r
+     * Tells the mapping that the range element has been modified.\r
+     */\r
+    void rangeModified(Range rangeElement);\r
+\r
+    /**\r
+     * Tells if some domain elements have been modified or added.\r
+     */\r
+    boolean isDomainModified();\r
+\r
+    /**\r
+     * Tells if some range elements have been modified or added.\r
+     */\r
+    boolean isRangeModified();\r
+    \r
+    Collection<Domain> getDomainModified();\r
+    Collection<Range> getRangeModified();\r
+\r
+    /**\r
+     * Returns a collection of domain elements which have been modified and also\r
+     * their counterparts in the mapping are modified. These elements are in\r
+     * conflict in the sense that the updating domain and range in different\r
+     * orders may produce different results.\r
+     */\r
+    Collection<Domain> getConflictingDomainElements();\r
+\r
+    /**\r
+     * Returns a collection of range elements which have been modified and also\r
+     * their counterparts in the mapping are modified. These elements are in\r
+     * conflict in the sense that the updating domain and range in different\r
+     * orders may produce different results.\r
+     */\r
+    Collection<Range> getConflictingRangeElements();\r
+\r
+    /**\r
+     * Adds a listener for domain and range modifications.\r
+     */\r
+    void addMappingListener(IMappingListener listener);\r
+\r
+    /**\r
+     * Removes a previously added listener.\r
+     */\r
+    void removeMappingListener(IMappingListener listener);\r
+\r
+}\r