[516669] Add new inverseCrossReferencing functionality

* The new API SiriusReferenceFinder allows
- getting the DRepresentations or DRepresentationElements that reference
the provided semantic object
- getting the DRepresentationDescriptor which associated DRepresentation
is or contains elements that reference the provided semantic object
* EObjectQuery.getSiriusReferenceFinder(EObject) allow to
retrieve the SiriusReferenceFinder
* DASI owned his implementation. DASI sub-classes may provide their own
implementation.
* Add release notes

Bug: 516669
Change-Id: Ief74174b56bfe38a57fe007863ae1474e4c570ab
Signed-off-by: Laurent Fasani <laurent.fasani@obeo.fr>

6 files changed, 233 insertions, 2 deletions

diff --git a/plugins/org.eclipse.sirius.doc/doc/Release_Notes.html b/plugins/org.eclipse.sirius.doc/doc/Release_Notes.html
index 14d0d9b869..37784f1c30 100644
--- a/plugins/org.eclipse.sirius.doc/doc/Release_Notes.html
+++ b/plugins/org.eclipse.sirius.doc/doc/Release_Notes.html
@@ -170,6 +170,16 @@
 			<li><span class="label label-info">Modified</span> The filtering expression variables available in the properties view definition in the &#8216;Extends&#8217; tab were renamed to match the following pattern: featureName+&#8216;Description&#8217;.</li>
 		</ul>
 		<h3 id="DeveloperVisibleChanges">Developer-Visible Changes</h3>
+		<h4 id="Changesinorg.eclipse.sirius.business.api">Changes in 
+			<code>org.eclipse.sirius.business.api</code>
+		</h4>
+		<ul>
+			<li><span class="label label-success">Added</span> (experimental) The new API 
+				<code>org.eclipse.sirius.business.api.query.SiriusReferenceFinder</code> and 
+				<code>org.eclipse.sirius.business.api.query.EObjectQuery.getSiriusReferenceFinder()</code> method to get it have been added. This API allows getting the DRepresentations or DRepresentationElements that reference the provided semantic object. It also allows getting the DRepresentationDescriptor which associated DRepresentation is or contains elements that reference the provided semantic object. This API will be useful for 
+				<a href="#replazyloading">representation lazy loading</a> as it may, in the future, not need to load all not yet loaded representations. For now, the use of this API will load all not loaded representations.
+			</li>
+		</ul>
 		<h4 id="Changesinorg.eclipse.sirius.ui.editor.api.pages">Changes in 
 			<code>org.eclipse.sirius.ui.editor.api.pages</code>
 		</h4>
@@ -212,7 +222,7 @@
 				<em>12.1.0.201708031200</em>.
 			</li>
 		</ul>
-		<h4 id="Representationslazyloadingexperimental.">Representations lazy loading (experimental).</h4>
+		<h4 id="replazyloading">Representations lazy loading (experimental).</h4>
 		<p>A new mode (currently experimental) is available to load representations on demand and not during session opening. This feature implies to serialize Sirius representations in separate resources. This mode can be activated by setting the system property 
 			<code>createLocalRepresentationInSeparateResource</code> at true. For more detail, see the developer documentation: 
 			<a href="./developer/representations_lazy_loading.html">Representations lazy loading (experimental)</a>.
diff --git a/plugins/org.eclipse.sirius.doc/doc/Release_Notes.textile b/plugins/org.eclipse.sirius.doc/doc/Release_Notes.textile
index 195ecc9cd9..0f0ff0eca2 100644
--- a/plugins/org.eclipse.sirius.doc/doc/Release_Notes.textile
+++ b/plugins/org.eclipse.sirius.doc/doc/Release_Notes.textile
@@ -34,6 +34,10 @@ h3. Specifier-Visible Changes
 
 h3. Developer-Visible Changes
 
+h4. Changes in @org.eclipse.sirius.business.api@
+
+* <span class="label label-success">Added</span> (experimental) The new API @org.eclipse.sirius.business.api.query.SiriusReferenceFinder@ and @org.eclipse.sirius.business.api.query.EObjectQuery.getSiriusReferenceFinder()@ method to get it have been added. This API allows getting the DRepresentations or DRepresentationElements that reference the provided semantic object. It also allows getting the DRepresentationDescriptor which associated DRepresentation is or contains elements that reference the provided semantic object. This API will be useful for "representation lazy loading":#replazyloading as it may, in the future, not need to load all not yet loaded representations. For now, the use of this API will load all not loaded representations.
+
 h4. Changes in @org.eclipse.sirius.ui.editor.api.pages@
 
 * <span class="label label-success">Added</span> New classes have been added in package @org.eclipse.sirius.ui.editor.api.pages@. They are the following: @AbstractSessionEditorPage@, @PageProvider@, @PageUpdateCOmmand@, @PositioningKind@, @PageUpdateCommandFactory@. These classes allow to provide custom pages to session editor instances.
@@ -48,7 +52,7 @@ h4. Migrations
 * <span class="label label-success">Added</span> A migration has been added to add an @uid@ to all instances of type DRepresentation.This @uid@ is used to reference the DRepresentation from the DRepresentationDescriptor. @DRepresentationDescriptor.repPath@ has been changed to have @uid@ as fragment.
 * <span class="label label-success">Added</span> A migration has been added to fix diagram with edge bend-points corrupted (see "bugzilla #519044":https://bugs.eclipse.org/bugs/show_bug.cgi?id=519044 for more details). The corresponding version, stored in attribute version of viewpoint:DAnalysis of the aird file, is _12.1.0.201708031200_.
 
-h4. Representations lazy loading (experimental).
+h4(#replazyloading). Representations lazy loading (experimental).
 
 A new mode (currently experimental) is available to load representations on demand and not during session opening. This feature implies to serialize Sirius representations in separate resources. This mode can be activated by setting the system property @createLocalRepresentationInSeparateResource@ at true. For more detail, see the developer documentation: "Representations lazy loading (experimental)":./developer/representations_lazy_loading.html.
 
diff --git a/plugins/org.eclipse.sirius/src/org/eclipse/sirius/business/api/query/EObjectQuery.java b/plugins/org.eclipse.sirius/src/org/eclipse/sirius/business/api/query/EObjectQuery.java
index 11a78a7154..f70706e9a5 100644
--- a/plugins/org.eclipse.sirius/src/org/eclipse/sirius/business/api/query/EObjectQuery.java
+++ b/plugins/org.eclipse.sirius/src/org/eclipse/sirius/business/api/query/EObjectQuery.java
@@ -36,6 +36,7 @@ import org.eclipse.emf.ecore.util.EcoreUtil;
 import org.eclipse.sirius.business.api.session.Session;
 import org.eclipse.sirius.business.api.session.SessionManager;
 import org.eclipse.sirius.business.api.session.danalysis.DAnalysisSession;
+import org.eclipse.sirius.business.internal.session.danalysis.DAnalysisSessionImpl;
 import org.eclipse.sirius.ext.base.Option;
 import org.eclipse.sirius.ext.base.Options;
 import org.eclipse.sirius.ext.emf.EClassQuery;
@@ -473,4 +474,16 @@ public class EObjectQuery {
         }
         return dAnalysis;
     }
+
+    /**
+     * Provides a mean to get SiriusReferenceFinder to some Sirius Elements (such as DRepresentationElement, DRepresentation or DRepresentationDescriptor) from some semantic objects
+     * within the scope of the Sirius {@link Session} the semanticObject belongs to.
+     * 
+     * @return the API
+     */
+    public SiriusReferenceFinder getSiriusReferenceFinder() {
+        SiriusReferenceFinder inverseCrossRef = Optional.ofNullable(getSession()).filter(DAnalysisSessionImpl.class::isInstance).map(DAnalysisSessionImpl.class::cast)
+                .map(DAnalysisSessionImpl::getSiriusRepElementInverseCrossReferencer).orElse(null);
+        return inverseCrossRef;
+    }
 }
diff --git a/plugins/org.eclipse.sirius/src/org/eclipse/sirius/business/api/query/SiriusReferenceFinder.java b/plugins/org.eclipse.sirius/src/org/eclipse/sirius/business/api/query/SiriusReferenceFinder.java
new file mode 100644
index 0000000000..771042d03b
--- /dev/null
+++ b/plugins/org.eclipse.sirius/src/org/eclipse/sirius/business/api/query/SiriusReferenceFinder.java
@@ -0,0 +1,89 @@
+/*******************************************************************************
+ * Copyright (c) 2017 Obeo.
+ * All rights reserved. This program and the accompanying materials
+ * are made available under the terms of the Eclipse Public License v1.0
+ * which accompanies this distribution, and is available at
+ * http://www.eclipse.org/legal/epl-v10.html
+ *
+ * Contributors:
+ *    Obeo - initial API and implementation
+ *******************************************************************************/
+package org.eclipse.sirius.business.api.query;
+
+import java.util.Collection;
+import java.util.Map;
+
+import org.eclipse.emf.ecore.EObject;
+import org.eclipse.emf.ecore.EReference;
+import org.eclipse.sirius.business.api.session.Session;
+import org.eclipse.sirius.viewpoint.DRepresentation;
+import org.eclipse.sirius.viewpoint.DRepresentationDescriptor;
+import org.eclipse.sirius.viewpoint.DRepresentationElement;
+
+/**
+ * Allow to retrieve SiriusElement that are directly associated to semantic elements within the scope of a Sirius
+ * {@link Session}.</br>
+ * * {@link DRepresentation}s or {@link DRepresentationElement}s referencing the provided semantic objects through
+ * {@link ViewpointPackage.DSEMANTIC_DECORATOR__TARGET} or
+ * {@link ViewpointPackage.DREPRESENTATION_ELEMENT__SEMANTIC_ELEMENTS} {@link EReference}</br>
+ * * {@link DRepresentationDescriptor}s which associated DRepresentation is or contains elements that reference the
+ * provided semantic object
+ * 
+ * @author <a href="mailto:laurent.fasani@obeo.fr">Laurent Fasani</a>
+ *
+ */
+public interface SiriusReferenceFinder {
+
+    /**
+     * The scope of the research.
+     * 
+     * @author lfasani
+     */
+    enum SearchScope {
+        /**
+         * Only loaded representations in the session are considered in the research scope.
+         */
+        LOADED_REPRESENTATIONS_SCOPE,
+        /**
+         * All representations, including non loaded representations, are considered in the research scope.
+         */
+        ALL_REPRESENTATIONS_SCOPE
+    };
+
+    /**
+     * Return the {@link DRepresentation}s or {@link DRepresentationElement}s referencing the semanticObjects.</br>
+     * In ALL_REPRESENTATIONS_SCOPE case, the DRepresentation containing the found EObjects will be automatically
+     * loaded. The search may possibly need to load the DRepresentation resources. But, without guaranteeing it, the
+     * implementation will do its best to not load it.</br>
+     * Whatever the searchScope is, the DRepresentations containing the found EObject will be automatically loaded.
+     * 
+     * @param semanticObjects
+     *            the semantic objects from which to retrieve the referencing EObjects.
+     * @param searchScope
+     *            if LOADED_REPRESENTATIONS_SCOPE, the scope of the search is limited to EObjects in loaded
+     *            DRepresentation in the Session</br>
+     *            if ALL_REPRESENTATIONS_SCOPE, the scope is loaded and not loaded DRepresentations of the Session. The
+     *            search may possibly need to load the DRepresentation.</br>
+     *            In any case, the DRepresentation containing the found EObject will be automatically loaded.
+     * @return the found EObjects that are of type DRepresentation or DRepresentationElement for each of the
+     *         semanticObjects.
+     */
+    Map<EObject, Collection<EObject>> getReferencingSiriusElements(Collection<EObject> semanticObjects, SearchScope searchScope);
+
+    /**
+     * Return the {@link DRepresentationDescriptor}s which associated {@link DRepresentation} is or contains a
+     * {@link DRepresentationElement} that is referencing the semanticObjects.</br>
+     * In ALL_REPRESENTATIONS_SCOPE case, the aim of this method is to avoid loading one of the non loaded
+     * representations. Without guaranteeing it, the implementation will do its best to achieve that.</br>
+     * 
+     * @param semanticObjects
+     *            the semantic objects from which to retrieve the referencing EObjects.
+     * @param searchScope
+     *            if LOADED_REPRESENTATIONS_SCOPE, the scope of the search is limited to EObjects in loaded
+     *            DRepresentation in the Session</br>
+     *            if ALL_REPRESENTATIONS_SCOPE, the scope is loaded and not loaded DRepresentations of the Session. The
+     *            search may possibly need to load the not yet loaded DRepresentation resources.</br>
+     * @return the found DRepresentationDescriptors for each of the semanticObjects.
+     */
+    Map<EObject, Collection<DRepresentationDescriptor>> getImpactedRepresentationDescriptors(Collection<EObject> semanticObjects, SearchScope searchScope);
+}
diff --git a/plugins/org.eclipse.sirius/src/org/eclipse/sirius/business/internal/session/danalysis/DAnalysisSessionImpl.java b/plugins/org.eclipse.sirius/src/org/eclipse/sirius/business/internal/session/danalysis/DAnalysisSessionImpl.java
index 7ef50143fa..4c4356f187 100644
--- a/plugins/org.eclipse.sirius/src/org/eclipse/sirius/business/internal/session/danalysis/DAnalysisSessionImpl.java
+++ b/plugins/org.eclipse.sirius/src/org/eclipse/sirius/business/internal/session/danalysis/DAnalysisSessionImpl.java
@@ -53,6 +53,7 @@ import org.eclipse.sirius.business.api.query.DAnalysisQuery;
 import org.eclipse.sirius.business.api.query.FileQuery;
 import org.eclipse.sirius.business.api.query.RepresentationDescriptionQuery;
 import org.eclipse.sirius.business.api.query.ResourceQuery;
+import org.eclipse.sirius.business.api.query.SiriusReferenceFinder;
 import org.eclipse.sirius.business.api.resource.ResourceDescriptor;
 import org.eclipse.sirius.business.api.resource.strategy.ResourceStrategyRegistry;
 import org.eclipse.sirius.business.api.session.CustomDataConstants;
@@ -123,6 +124,11 @@ import com.google.common.collect.Sets;
  * @author cbrun
  */
 public class DAnalysisSessionImpl extends DAnalysisSessionEObjectImpl implements Session, DAnalysisSession, ResourceSyncClient {
+    /**
+     * The inverse cross referencer to retrieve DRep and DRepElement.
+     */
+    protected SiriusReferenceFinder repElementInverseCrossReferencer;
+
     /** The custom saving policy the session should use. */
     private SavingPolicy savingPolicy;
 
@@ -1482,4 +1488,16 @@ public class DAnalysisSessionImpl extends DAnalysisSessionEObjectImpl implements
         }
         return repFiles;
     }
+
+    /**
+     * Return the {@link SiriusReferenceFinder} of this Session.
+     * 
+     * @return the {@link SiriusReferenceFinder}
+     */
+    public SiriusReferenceFinder getSiriusRepElementInverseCrossReferencer() {
+        if (repElementInverseCrossReferencer == null) {
+            repElementInverseCrossReferencer = new SiriusReferenceFinderImpl(this);
+        }
+        return repElementInverseCrossReferencer;
+    }
 }
diff --git a/plugins/org.eclipse.sirius/src/org/eclipse/sirius/business/internal/session/danalysis/SiriusReferenceFinderImpl.java b/plugins/org.eclipse.sirius/src/org/eclipse/sirius/business/internal/session/danalysis/SiriusReferenceFinderImpl.java
new file mode 100644
index 0000000000..183b9c800f
--- /dev/null
+++ b/plugins/org.eclipse.sirius/src/org/eclipse/sirius/business/internal/session/danalysis/SiriusReferenceFinderImpl.java
@@ -0,0 +1,97 @@
+/*******************************************************************************
+ * Copyright (c) 2017 Obeo.
+ * All rights reserved. This program and the accompanying materials
+ * are made available under the terms of the Eclipse Public License v1.0
+ * which accompanies this distribution, and is available at
+ * http://www.eclipse.org/legal/epl-v10.html
+ *
+ * Contributors:
+ *    Obeo - initial API and implementation
+ *******************************************************************************/
+package org.eclipse.sirius.business.internal.session.danalysis;
+
+import java.util.Arrays;
+import java.util.Collection;
+import java.util.LinkedHashMap;
+import java.util.LinkedHashSet;
+import java.util.List;
+import java.util.Map;
+import java.util.Set;
+import java.util.stream.Collectors;
+
+import org.eclipse.emf.ecore.EObject;
+import org.eclipse.emf.ecore.EReference;
+import org.eclipse.emf.ecore.EStructuralFeature.Setting;
+import org.eclipse.sirius.business.api.dialect.DialectManager;
+import org.eclipse.sirius.business.api.query.DRepresentationQuery;
+import org.eclipse.sirius.business.api.query.EObjectQuery;
+import org.eclipse.sirius.business.api.query.SiriusReferenceFinder;
+import org.eclipse.sirius.ext.base.Option;
+import org.eclipse.sirius.viewpoint.DRepresentation;
+import org.eclipse.sirius.viewpoint.DRepresentationDescriptor;
+import org.eclipse.sirius.viewpoint.ViewpointPackage;
+
+public class SiriusReferenceFinderImpl implements SiriusReferenceFinder {
+
+    /**
+     * EReferences used to find inverse cross references.
+     */
+    protected final List<EReference> refs = Arrays.asList(ViewpointPackage.Literals.DSEMANTIC_DECORATOR__TARGET, ViewpointPackage.Literals.DREPRESENTATION_ELEMENT__SEMANTIC_ELEMENTS);
+
+    /**
+     * The session.
+     */
+    protected DAnalysisSessionImpl dAnalysisSessionImpl;
+
+    /**
+     * Default constructor.
+     * 
+     * @param dAnalysisSessionImpl
+     *            the session
+     */
+    public SiriusReferenceFinderImpl(DAnalysisSessionImpl dAnalysisSessionImpl) {
+        this.dAnalysisSessionImpl = dAnalysisSessionImpl;
+    }
+
+    @Override
+    public Map<EObject, Collection<EObject>> getReferencingSiriusElements(Collection<EObject> semanticObjects, SearchScope searchScope) {
+        if (SearchScope.ALL_REPRESENTATIONS_SCOPE.equals(searchScope)) {
+            loadAllRepresentations();
+        }
+        Map<EObject, Collection<EObject>> result = new LinkedHashMap<>();
+        for (EObject semanticObject : semanticObjects) {
+            Collection<EObject> siriusElements = dAnalysisSessionImpl.getSemanticCrossReferencer().getNonNavigableInverseReferences(semanticObject).stream() //
+                    .filter(setting -> refs.contains(setting.getEStructuralFeature())) // keep only refs features
+                    .map(Setting::getEObject).collect(Collectors.toSet());
+            result.put(semanticObject, siriusElements);
+        }
+
+        return result;
+    }
+
+    @Override
+    public Map<EObject, Collection<DRepresentationDescriptor>> getImpactedRepresentationDescriptors(Collection<EObject> semanticObjects, SearchScope searchScope) {
+        Map<EObject, Collection<DRepresentationDescriptor>> impactedRepDesc = new LinkedHashMap<>();
+        Map<EObject, Collection<EObject>> referencingSiriusElements = getReferencingSiriusElements(semanticObjects, searchScope);
+        for (EObject semanticObject : semanticObjects) {
+            Set<DRepresentationDescriptor> repDescs = new LinkedHashSet<>();
+            referencingSiriusElements.get(semanticObject).stream().forEach(obj -> {
+                Option<DRepresentation> representation = new EObjectQuery(obj).getRepresentation();
+                if (representation.some()) {
+                    DRepresentationDescriptor representationDescriptor = new DRepresentationQuery(representation.get()).getRepresentationDescriptor();
+                    if (representationDescriptor != null) {
+                        repDescs.add(representationDescriptor);
+                    }
+                }
+            });
+            if (repDescs.size() > 0) {
+                impactedRepDesc.put(semanticObject, repDescs);
+            }
+        }
+        return impactedRepDesc;
+    }
+
+    private void loadAllRepresentations() {
+        DialectManager.INSTANCE.getAllRepresentationDescriptors(dAnalysisSessionImpl).stream().forEach(repDesc -> repDesc.getRepresentation());
+    }
+}