[516734] Adapts the EditingDomainServices and StandardServices

* We return a List instead of a collection. As we don't know which kind
of Collection it will be returned in
IStructuredItemContentProvider.getElements or in
ITreeItemContentProvider.getChildren, we instantiate a new ArrayList
with the Collection.
* Updates the specifier documentation.

Bug: 516734
Change-Id: I82b8d19a132b52514eb80d6ecd077cbbff7fda41
Signed-off-by: Florian Barbin <florian.barbin@obeo.fr>

7 files changed, 85 insertions, 84 deletions

diff --git a/plugins/org.eclipse.sirius.common/src/org/eclipse/sirius/common/tools/api/interpreter/StandardServices.java b/plugins/org.eclipse.sirius.common/src/org/eclipse/sirius/common/tools/api/interpreter/StandardServices.java
index 32319209ab..5c4e021df1 100644
--- a/plugins/org.eclipse.sirius.common/src/org/eclipse/sirius/common/tools/api/interpreter/StandardServices.java
+++ b/plugins/org.eclipse.sirius.common/src/org/eclipse/sirius/common/tools/api/interpreter/StandardServices.java
@@ -1,5 +1,5 @@
 /*******************************************************************************
- * Copyright (c) 2015 Obeo.
+ * Copyright (c) 2015, 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
@@ -10,14 +10,14 @@
  *******************************************************************************/
 package org.eclipse.sirius.common.tools.api.interpreter;
 
-import java.util.Collection;
 import java.util.Collections;
+import java.util.List;
 
 import org.eclipse.emf.ecore.EObject;
 
 /**
- * Class owning methods used for service: interpreter. The service methods
- * should be prefixed by std to avoid conflict with other services.
+ * Class owning methods used for service: interpreter. The service methods should be prefixed by std to avoid conflict
+ * with other services.
  * 
  * @author <a href="mailto:laurent.fasani@obeo.fr">Laurent Fasani</a>
  */
@@ -30,13 +30,13 @@ public class StandardServices {
     }
 
     /**
-     * Return an empty collection.
+     * Return an empty list.
      * 
      * @param context
      *            not used but necessary for the service conventions
-     * @return an empty collection
+     * @return an empty list
      */
-    public Collection<EObject> stdEmptyCollection(EObject context) {
-        return Collections.emptySet();
+    public List<EObject> stdEmptyCollection(EObject context) {
+        return Collections.emptyList();
     }
 }
diff --git a/plugins/org.eclipse.sirius.doc/doc/Release_Notes.html b/plugins/org.eclipse.sirius.doc/doc/Release_Notes.html
index 14a2f39de2..b0033f279f 100644
--- a/plugins/org.eclipse.sirius.doc/doc/Release_Notes.html
+++ b/plugins/org.eclipse.sirius.doc/doc/Release_Notes.html
@@ -294,6 +294,18 @@
 				<code>getFilesFromWorkspace(Collection&lt;IContainer&gt;, String)</code> to be more generic.
 			</li>
 		</ul>
+		<h4 id="Changesinorg.eclipse.sirius.ext.emf.edit">Changes in 
+			<code>org.eclipse.sirius.ext.emf.edit</code>
+		</h4>
+		<ul>
+			<li><span class="label label-info">Modified</span> 
+				<code>org.eclipse.sirius.ext.emf.edit.EditingDomainServices</code> does not use 
+				<code>Collection</code> anymore as return type or parameter type in its services. 
+				<code>java.util.Collection</code> has been replaced by 
+				<code>java.util.List</code>. As mentioned in the 
+				<a href="./specifier/general/Writing_Queries.html#service_methods">specifier documentation</a>, it is recommended to use List or Set instead of Collection in java services signature.
+			</li>
+		</ul>
 		<h4 id="Changesinorg.eclipse.sirius.ui">Changes in 
 			<code>org.eclipse.sirius.ui</code>
 		</h4>
diff --git a/plugins/org.eclipse.sirius.doc/doc/Release_Notes.textile b/plugins/org.eclipse.sirius.doc/doc/Release_Notes.textile
index 756d35531b..da768d1e94 100644
--- a/plugins/org.eclipse.sirius.doc/doc/Release_Notes.textile
+++ b/plugins/org.eclipse.sirius.doc/doc/Release_Notes.textile
@@ -74,6 +74,10 @@ h4. Changes in @org.eclipse.sirius.common@
 * <span class="label label-success">Added</span> @org.eclipse.sirius.common.tools.api.util.LazyCrossReferencer.setEObjectToBeIgnored(Predicate<EObject>)@ has  been added to filter inverse references to prevent some references resolution.
 * <span class="label label-info">Modified</span> @org.eclipse.sirius.common.tools.api.util.WorkspaceUtil.getFilesFromWorkspace(Collection<IProject>, String)@ signature has been modified in @getFilesFromWorkspace(Collection<IContainer>, String)@ to be more generic.
 
+h4. Changes in @org.eclipse.sirius.ext.emf.edit@
+
+* <span class="label label-info">Modified</span> @org.eclipse.sirius.ext.emf.edit.EditingDomainServices@ does not use @Collection@ anymore as return type or parameter type in its services. @java.util.Collection@ has been replaced by @java.util.List@. As mentioned in the "specifier documentation":./specifier/general/Writing_Queries.html#service_methods, it is recommended to use List or Set instead of Collection in java services signature.
+
 h4. Changes in @org.eclipse.sirius.ui@
 
 * <span class="label label-success">Added</span> @org.eclipse.sirius.ui.tools.api.wizards.CreateEMFModelWizard@ is a new wizard that can be invoked to create instances of any metamodel. It will ask the end-user for a metamodel (@EPackage@), a concrete type to instanciate as root element, and finally the local path of the file to create. See the class Javadoc for sample usage. Note that the first two pages of the wizard (EPackage and root type selection) can be customized through the @org.eclipse.sirius.common.package_meta_data@ extension point to provide user-oriented name and documentation for an EPackage, and to suggest specific EClasses as good root candidates.
diff --git a/plugins/org.eclipse.sirius.doc/doc/specifier/general/Writing_Queries.html b/plugins/org.eclipse.sirius.doc/doc/specifier/general/Writing_Queries.html
index 9e50f0eb66..d2fd0d3b0d 100644
--- a/plugins/org.eclipse.sirius.doc/doc/specifier/general/Writing_Queries.html
+++ b/plugins/org.eclipse.sirius.doc/doc/specifier/general/Writing_Queries.html
@@ -321,6 +321,9 @@
 			</li>
 			<li>A service method may return a value, which can have the same kinds of types as parameters.</li>
 		</ul>
+		<p>
+			<strong>WARNING:</strong> AQL only supports Sequences and Set as collection types. As a result, to get the full benefit from the AQL validation, it is recommended to write services that return a List or a Set as collection type.
+		</p>
 		<p>Here is an example of a Java service:</p>
 		<pre><code id="ecore_services">public class EObjectServices {
     public List&lt;EClass&gt; getEClasses(EPackage ePackage) {
diff --git a/plugins/org.eclipse.sirius.doc/doc/specifier/general/Writing_Queries.textile b/plugins/org.eclipse.sirius.doc/doc/specifier/general/Writing_Queries.textile
index 1c6a13d1a1..d5e8a11a8d 100644
--- a/plugins/org.eclipse.sirius.doc/doc/specifier/general/Writing_Queries.textile
+++ b/plugins/org.eclipse.sirius.doc/doc/specifier/general/Writing_Queries.textile
@@ -132,6 +132,7 @@ A service is simply a public Java methods which follows some conventions:
 ** EMF types (i.e. @EObject@ or a sub-type)
 ** Java collections of EMF types (note that array types are *not* supported).
 * A service method may return a value, which can have the same kinds of types as parameters.
+*WARNING:* AQL only supports Sequences and Set as collection types. As a result, to get the full benefit from the AQL validation, it is recommended to write services that return a List or a Set as collection type.
 
 Here is an example of a Java service:
 
diff --git a/plugins/org.eclipse.sirius.ext.emf.edit/src/org/eclipse/sirius/ext/emf/edit/EditingDomainServices.java b/plugins/org.eclipse.sirius.ext.emf.edit/src/org/eclipse/sirius/ext/emf/edit/EditingDomainServices.java
index a631945575..4096027eb3 100644
--- a/plugins/org.eclipse.sirius.ext.emf.edit/src/org/eclipse/sirius/ext/emf/edit/EditingDomainServices.java
+++ b/plugins/org.eclipse.sirius.ext.emf.edit/src/org/eclipse/sirius/ext/emf/edit/EditingDomainServices.java
@@ -1,5 +1,5 @@
 /*******************************************************************************
- * Copyright (c) 2016 Obeo.
+ * Copyright (c) 2016, 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
@@ -11,7 +11,6 @@
 package org.eclipse.sirius.ext.emf.edit;
 
 import java.util.ArrayList;
-import java.util.Collection;
 import java.util.List;
 
 import org.eclipse.emf.common.command.Command;
@@ -46,9 +45,8 @@ import org.eclipse.emf.edit.provider.ReflectiveItemProviderAdapterFactory;
 import org.eclipse.emf.edit.provider.resource.ResourceItemProviderAdapterFactory;
 
 /**
- * Provides access to common {@link EditingDomain} and
- * {@link AdapterFactoryEditingDomain} methods in a way that is compatible with
- * "Java services" invocation from Sirius interpreted expressions.
+ * Provides access to common {@link EditingDomain} and {@link AdapterFactoryEditingDomain} methods in a way that is
+ * compatible with "Java services" invocation from Sirius interpreted expressions.
  * <p>
  * <h4>General EditingDomain-related Services</h4>
  * <p>
@@ -63,8 +61,8 @@ import org.eclipse.emf.edit.provider.resource.ResourceItemProviderAdapterFactory
  * <p>
  * <h4>Item Providers Services</h4>
  * <p>
- * Most public methods of the following interfaces are available as services on
- * any {@link EObject} (typically from a Sirius session):
+ * Most public methods of the following interfaces are available as services on any {@link EObject} (typically from a
+ * Sirius session):
  * <ul>
  * <li>{@link org.eclipse.emf.edit.provider.IItemLabelProvider}</li>
  * <li>{@link org.eclipse.emf.edit.provider.IItemColorProvider}</li>
@@ -76,37 +74,30 @@ import org.eclipse.emf.edit.provider.resource.ResourceItemProviderAdapterFactory
  * <li>{@link org.eclipse.emf.edit.provider.ITableItemFontProvider}</li>
  * </ul>
  * <p>
- * In all cases, a {@code getXXXProvider()} service method is also made
- * available (for example {@link #getLabelProvider(EObject)}, which returns the
- * item provider itself (or <code>null</code>). The item provider is located
- * using the {@code ItemProviderAdapter} returned by the {@link AdapterFactory}
- * associated to the element's editing domain. This assumes said domain is an
- * {@link AdapterFactoryEditingDomain} (which is true in practice in Sirius,
- * which uses a <code>TransactionalEditingDomain</code> that inherits from
- * this).
+ * In all cases, a {@code getXXXProvider()} service method is also made available (for example
+ * {@link #getLabelProvider(EObject)}, which returns the item provider itself (or <code>null</code>). The item provider
+ * is located using the {@code ItemProviderAdapter} returned by the {@link AdapterFactory} associated to the element's
+ * editing domain. This assumes said domain is an {@link AdapterFactoryEditingDomain} (which is true in practice in
+ * Sirius, which uses a <code>TransactionalEditingDomain</code> that inherits from this).
  * <p>
- * All service methods return an explicit <code>null</code> value (or
- * <code>false</code> for services that return a boolean) if the corresponding
- * item provider could not be found. Note that this is indistinguishable from an
- * item provider method which actually returns <code>null</code>/
- * <code>false</code>.
+ * All service methods return an explicit <code>null</code> value (or <code>false</code> for services that return a
+ * boolean) if the corresponding item provider could not be found. Note that this is indistinguishable from an item
+ * provider method which actually returns <code>null</code>/ <code>false</code>.
  * <h4>Item Property-Related Services</h4>
  * <p>
- * The {@link IItemPropertySource} associated with an element and its
- * {@link IItemPropertyDescriptor}s can be obtained using the following
- * services:
+ * The {@link IItemPropertySource} associated with an element and its {@link IItemPropertyDescriptor}s can be obtained
+ * using the following services:
  * <ul>
  * <li>{@link #getItemPropertySource(EObject)}</li>
- * <li>{@link #getPropertyDescriptors(EObject)} to obtain <em>all</em> the
- * {@link IItemPropertyDescriptor} of the element.</li>
- * <li>{@link #getPropertyDescriptorForFeature(EObject, String)} to obtain the
- * {@link IItemPropertyDescriptor} of an element's specific feature</li>
+ * <li>{@link #getPropertyDescriptors(EObject)} to obtain <em>all</em> the {@link IItemPropertyDescriptor} of the
+ * element.</li>
+ * <li>{@link #getPropertyDescriptorForFeature(EObject, String)} to obtain the {@link IItemPropertyDescriptor} of an
+ * element's specific feature</li>
  * </ul>
  * <p>
- * The following services, which all take a feature name as a second argument
- * (the first explicit one when invoked as a service) give access to the
- * corresponding methods in the {@link IItemPropertyDescriptor} associated to
- * the corresponding element's feature:
+ * The following services, which all take a feature name as a second argument (the first explicit one when invoked as a
+ * service) give access to the corresponding methods in the {@link IItemPropertyDescriptor} associated to the
+ * corresponding element's feature:
  * <ul>
  * <li>{@link #getPropertyDescriptorPropertyValue()}</li>
  * <li>{@link #isPropertyDescriptorPropertySet()}</li>
@@ -129,15 +120,12 @@ import org.eclipse.emf.edit.provider.resource.ResourceItemProviderAdapterFactory
  * <p>
  * <h4>Command-related Services</h4>
  * <p>
- * A series of service methods can be used to invoke the standard EMF Commands
- * available from {@code ItemProviderAdapter}'s various
- * {@code createXXXCommand()} methods. Note that contrary to the
- * {@code createXXXCommand()} methods which simply returns a {@link Command}
- * instance, the service methods exposed in this class will directly
- * <em>execute</em> the command on the editing domains {@link CommandStack}.
- * Their names follow the {@code perfomXXXCommand()} pattern to reflect this.
- * They all return the {@code self} element (the {@link EObject} on which the
- * service was invoked.
+ * A series of service methods can be used to invoke the standard EMF Commands available from
+ * {@code ItemProviderAdapter}'s various {@code createXXXCommand()} methods. Note that contrary to the
+ * {@code createXXXCommand()} methods which simply returns a {@link Command} instance, the service methods exposed in
+ * this class will directly <em>execute</em> the command on the editing domains {@link CommandStack}. Their names follow
+ * the {@code perfomXXXCommand()} pattern to reflect this. They all return the {@code self} element (the {@link EObject}
+ * on which the service was invoked.
  * <p>
  * The command-related services available are:
  * <ul>
@@ -149,11 +137,9 @@ import org.eclipse.emf.edit.provider.resource.ResourceItemProviderAdapterFactory
  * <li>{@link #performMoveCommand()}</li>
  * </ul>
  * <p>
- * The implementation of these services delegate to the
- * {@link EditingDomain#createCommand(Class, CommandParameter)} which delegates
- * to the IEditingDomainItemProvider#createCommand(Object, EditingDomain, Class,
- * CommandParameter) method, so any customization made in the
- * {@code IEditingDomainItemProvider}'s implementation will be taken into
+ * The implementation of these services delegate to the {@link EditingDomain#createCommand(Class, CommandParameter)}
+ * which delegates to the IEditingDomainItemProvider#createCommand(Object, EditingDomain, Class, CommandParameter)
+ * method, so any customization made in the {@code IEditingDomainItemProvider}'s implementation will be taken into
  * account.
  * 
  * @author pcdavid
@@ -277,10 +263,10 @@ public class EditingDomainServices {
         return getAdapter(self, IStructuredItemContentProvider.class);
     }
 
-    public Collection<?> getStructuredItemContentProviderElements(EObject self) {
+    public List<?> getStructuredItemContentProviderElements(EObject self) {
         IStructuredItemContentProvider scp = getStructuredItemContentProvider(self);
         if (scp != null) {
-            return scp.getElements(self);
+            return new ArrayList<>(scp.getElements(self));
         } else {
             return null;
         }
@@ -292,10 +278,10 @@ public class EditingDomainServices {
         return getAdapter(self, ITreeItemContentProvider.class);
     }
 
-    public Collection<?> getTreeContentProviderChildren(EObject self) {
+    public List<?> getTreeContentProviderChildren(EObject self) {
         ITreeItemContentProvider tp = getTreeContentProvider(self);
         if (tp != null) {
-            return tp.getChildren(self);
+            return new ArrayList<>(tp.getChildren(self));
         } else {
             return null;
         }
@@ -558,10 +544,10 @@ public class EditingDomainServices {
         }
     }
 
-    public Collection<?> getPropertyDescriptorChoiceOfValues(EObject self, String featureName) {
+    public List<?> getPropertyDescriptorChoiceOfValues(EObject self, String featureName) {
         IItemPropertyDescriptor desc = getPropertyDescriptorForFeature(self, featureName);
         if (desc != null) {
-            return desc.getChoiceOfValues(self);
+            return new ArrayList<>(desc.getChoiceOfValues(self));
         } else {
             return null;
         }
@@ -628,35 +614,35 @@ public class EditingDomainServices {
         return self;
     }
 
-    public EObject performAddCommand(EObject self, String featureName, Collection<?> collection, int index) {
+    public EObject performAddCommand(EObject self, String featureName, List<?> list, int index) {
         EStructuralFeature feature = self.eClass().getEStructuralFeature(featureName);
         if (feature != null) {
 
-            performCommand(self, AddCommand.class, new CommandParameter(self, feature, collection, index));
+            performCommand(self, AddCommand.class, new CommandParameter(self, feature, list, index));
         }
         return self;
     }
 
-    public EObject performAddCommand(EObject self, String featureName, Collection<?> collection) {
+    public EObject performAddCommand(EObject self, String featureName, List<?> list) {
         EStructuralFeature feature = self.eClass().getEStructuralFeature(featureName);
         if (feature != null) {
-            performCommand(self, AddCommand.class, new CommandParameter(self, feature, collection));
+            performCommand(self, AddCommand.class, new CommandParameter(self, feature, list));
         }
         return self;
     }
 
-    public EObject performRemoveCommand(EObject self, String featureName, Collection<?> collection) {
+    public EObject performRemoveCommand(EObject self, String featureName, List<?> list) {
         EStructuralFeature feature = self.eClass().getEStructuralFeature(featureName);
         if (feature != null) {
-            performCommand(self, RemoveCommand.class, new CommandParameter(self, feature, collection));
+            performCommand(self, RemoveCommand.class, new CommandParameter(self, feature, list));
         }
         return self;
     }
 
-    public EObject performReplaceCommand(EObject self, String featureName, Object value, Collection<?> collection) {
+    public EObject performReplaceCommand(EObject self, String featureName, Object value, List<?> list) {
         EStructuralFeature feature = self.eClass().getEStructuralFeature(featureName);
         if (feature != null) {
-            performCommand(self, ReplaceCommand.class, new CommandParameter(self, feature, value, collection));
+            performCommand(self, ReplaceCommand.class, new CommandParameter(self, feature, value, list));
         }
         return self;
     }
diff --git a/plugins/org.eclipse.sirius.sample.ecore.design/src/org/eclipse/sirius/ecore/design/service/EcoreService.java b/plugins/org.eclipse.sirius.sample.ecore.design/src/org/eclipse/sirius/ecore/design/service/EcoreService.java
index 71b435e66f..0e307eb704 100644
--- a/plugins/org.eclipse.sirius.sample.ecore.design/src/org/eclipse/sirius/ecore/design/service/EcoreService.java
+++ b/plugins/org.eclipse.sirius.sample.ecore.design/src/org/eclipse/sirius/ecore/design/service/EcoreService.java
@@ -1,5 +1,5 @@
 /*******************************************************************************
- * Copyright (c) 2008 THALES GLOBAL SERVICES.
+ * Copyright (c) 2008, 2017 THALES GLOBAL SERVICES.
  * 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
@@ -11,7 +11,6 @@
 package org.eclipse.sirius.ecore.design.service;
 
 import java.util.ArrayList;
-import java.util.Collection;
 import java.util.Collections;
 import java.util.List;
 
@@ -33,25 +32,23 @@ import org.eclipse.sirius.ext.emf.AllContents;
  */
 public class EcoreService {
     /**
-     * Returns all the root objects of all the resources in the same
-     * resource-set as the specified object.
+     * Returns all the root objects of all the resources in the same resource-set as the specified object.
      * 
      * @param any
      *            an EObject.
-     * @return all the root objects in the same resource-set as <code>any</code>
-     *         or an empty collection if <code>any</code> is not inside a
-     *         resource-set.
+     * @return all the root objects in the same resource-set as <code>any</code> or an empty collection if
+     *         <code>any</code> is not inside a resource-set.
      */
-    public Collection<EObject> allRoots(EObject any) {
+    public List<EObject> allRoots(EObject any) {
         Resource res = any.eResource();
         if (res != null && res.getResourceSet() != null) {
-            Collection<EObject> roots = new ArrayList<EObject>();
+            List<EObject> roots = new ArrayList<EObject>();
             for (Resource childRes : res.getResourceSet().getResources()) {
                 roots.addAll(childRes.getContents());
             }
             return roots;
         } else {
-            return Collections.emptySet();
+            return Collections.emptyList();
         }
     }
 
@@ -136,17 +133,15 @@ public class EcoreService {
     }
 
     /**
-     * Finds a type matching the specified name (case-insensitive) in the same
-     * resource-set as obj, or inside Ecore itself if none could be found.
+     * Finds a type matching the specified name (case-insensitive) in the same resource-set as obj, or inside Ecore
+     * itself if none could be found.
      * 
      * @param obj
      *            the object defining the context in which to look.
      * @param name
-     *            the name of the type to look for (case-insensitive). Only
-     *            basic type names are supported (no qualified names).
-     *            Whitespace before or after the name is ignored.
-     * @return the first type found in the resource set or Ecore itself which
-     *         matches the specified name.
+     *            the name of the type to look for (case-insensitive). Only basic type names are supported (no qualified
+     *            names). Whitespace before or after the name is ignored.
+     * @return the first type found in the resource set or Ecore itself which matches the specified name.
      */
     public EClassifier findTypeByName(EObject obj, String name) {
         EClassifier result = findTypeByName(allRoots(obj), name);