Improve on PR #26 for issues #24 and #25 (#29)

* Add methods to ImageWrapper: isOrphaned and getFilesetImages
* Add method to count links from annotations
* Add method to replace attachments
* Add argument to determine if images should be deleted when replaced
* Add methods to delete multiple objects at once
* Add method to get images from a project using the datasets names and the images names
* Add method GenericObjectWrapper#distinct to filter collections and keep distinct objects
* Replace lists of unknown capacity by lists of lists and flatmap
* Add tests
* Refactor code to create/remove files in tests
* Improve Javadoc
* Replace color concatenation in tests logs by String#format()
* Minor code improvements

src/main/java/fr/igred/omero/Client.java

@@ -62,6 +62,7 @@
 import java.util.concurrent.ExecutionException;
 import java.util.stream.Collectors;
 
+import static fr.igred.omero.GenericObjectWrapper.distinct;
 import static fr.igred.omero.GenericObjectWrapper.wrap;
 import static fr.igred.omero.exception.ExceptionHandler.handleServiceOrAccess;
 import static fr.igred.omero.exception.ExceptionHandler.handleServiceOrServer;
@@ -339,7 +340,7 @@ public List<ImageWrapper> getImages() throws ServiceException, AccessException,
 
 
     /**
-     * Gets all images with a certain from OMERO.
+     * Gets all images with a certain name from OMERO.
      *
      * @param name Name searched.
      *
@@ -376,15 +377,19 @@ public List<ImageWrapper> getImages(String name) throws ServiceException, Access
      */
     public List<ImageWrapper> getImages(String projectName, String datasetName, String imageName)
     throws ServiceException, AccessException, ExecutionException {
-        List<ImageWrapper>   images   = new ArrayList<>();
         List<ProjectWrapper> projects = getProjects(projectName);
+
+        Collection<List<ImageWrapper>> lists = new ArrayList<>(projects.size());
         for (ProjectWrapper project : projects) {
-            List<DatasetWrapper> datasets = project.getDatasets(datasetName);
-            for (DatasetWrapper dataset : datasets) {
-                images.addAll(dataset.getImages(this, imageName));
-            }
+            lists.add(project.getImages(this, datasetName, imageName));
         }
-        return images;
+
+        List<ImageWrapper> images = lists.stream()
+                                         .flatMap(Collection::stream)
+                                         .sorted(Comparator.comparing(GenericObjectWrapper::getId))
+                                         .collect(Collectors.toList());
+
+        return distinct(images);
     }
 
 
@@ -457,7 +462,7 @@ public List<ImageWrapper> getImagesTagged(Long tagId)
     public List<ImageWrapper> getImagesKey(String key)
     throws ServiceException, AccessException, ExecutionException {
         List<ImageWrapper> images   = getImages();
-        List<ImageWrapper> selected = new ArrayList<>();
+        List<ImageWrapper> selected = new ArrayList<>(images.size());
         for (ImageWrapper image : images) {
             Map<String, String> pairsKeyValue = image.getKeyValuePairs(this);
             if (pairsKeyValue.get(key) != null) {
@@ -484,7 +489,7 @@ public List<ImageWrapper> getImagesKey(String key)
     public List<ImageWrapper> getImagesPairKeyValue(String key, String value)
     throws ServiceException, AccessException, ExecutionException {
         List<ImageWrapper> images   = getImages();
-        List<ImageWrapper> selected = new ArrayList<>();
+        List<ImageWrapper> selected = new ArrayList<>(images.size());
         for (ImageWrapper image : images) {
             Map<String, String> pairsKeyValue = image.getKeyValuePairs(this);
             if (pairsKeyValue.get(key) != null && pairsKeyValue.get(key).equals(value)) {
@@ -756,6 +761,30 @@ public TagAnnotationWrapper getTag(Long id) throws OMEROServerError, ServiceExce
     }
 
 
+    /**
+     * Deletes multiple objects from OMERO.
+     *
+     * @param objects The OMERO object.
+     *
+     * @throws ServiceException     Cannot connect to OMERO.
+     * @throws AccessException      Cannot access data.
+     * @throws ExecutionException   A Facility can't be retrieved or instantiated.
+     * @throws OMEROServerError     If the thread was interrupted.
+     * @throws InterruptedException If block(long) does not return.
+     */
+    public void delete(Collection<? extends GenericObjectWrapper<?>> objects)
+    throws ServiceException, AccessException, ExecutionException, OMEROServerError, InterruptedException {
+        for (GenericObjectWrapper<?> object : objects) {
+            if (object instanceof FolderWrapper) {
+                ((FolderWrapper) object).unlinkAllROI(this);
+            }
+        }
+        if (!objects.isEmpty()) {
+            delete(objects.stream().map(GenericObjectWrapper::asIObject).collect(Collectors.toList()));
+        }
+    }
+
+
     /**
      * Deletes an object from OMERO.
      *

src/main/java/fr/igred/omero/GatewayWrapper.java

@@ -424,6 +424,28 @@ void delete(IObject object)
     }
 
 
+    /**
+     * Deletes multiple objects from OMERO.
+     *
+     * @param objects The OMERO objects.
+     *
+     * @throws ServiceException     Cannot connect to OMERO.
+     * @throws AccessException      Cannot access data.
+     * @throws ExecutionException   A Facility can't be retrieved or instantiated.
+     * @throws OMEROServerError     If the thread was interrupted.
+     * @throws InterruptedException If block(long) does not return.
+     */
+    void delete(List<IObject> objects)
+    throws ServiceException, AccessException, ExecutionException, OMEROServerError, InterruptedException {
+        final int ms = 500;
+        try {
+            getDm().delete(ctx, objects).loop(10, ms);
+        } catch (DSOutOfServiceException | DSAccessException | LockTimeout e) {
+            handleException(e, "Cannot delete objects");
+        }
+    }
+
+
     /**
      * Deletes a file from OMERO
      *

src/main/java/fr/igred/omero/GenericObjectWrapper.java

@@ -28,6 +28,7 @@
 import omero.model.IObject;
 
 import java.sql.Timestamp;
+import java.util.ArrayList;
 import java.util.Collection;
 import java.util.Comparator;
 import java.util.List;
@@ -113,6 +114,29 @@ protected static void delete(Client client, IObject object)
     }
 
 
+    /**
+     * Only keeps objects with different IDs in a collection.
+     *
+     * @param objects A collection of objects.
+     * @param <T>     The objects type.
+     *
+     * @return Distinct objects list, sorted by ID.
+     */
+    public static <T extends GenericObjectWrapper<?>> List<T> distinct(Collection<? extends T> objects) {
+        Collection<Long> ids = new ArrayList<>(objects.size());
+
+        List<T> purged = new ArrayList<>(objects.size());
+        for (T image : objects) {
+            if (!ids.contains(image.getId())) {
+                ids.add(image.getId());
+                purged.add(image);
+            }
+        }
+        purged.sort(Comparator.comparing(T::getId));
+        return purged;
+    }
+
+
     /**
      * Returns the contained DataObject as IObject.
      *

src/main/java/fr/igred/omero/annotations/FileAnnotationWrapper.java

@@ -23,6 +23,7 @@
 import omero.ServerError;
 import omero.api.RawFileStorePrx;
 import omero.gateway.exception.DSOutOfServiceException;
+import omero.gateway.model.AnnotationData;
 import omero.gateway.model.FileAnnotationData;
 
 import java.io.File;
@@ -44,51 +45,108 @@ public FileAnnotationWrapper(FileAnnotationData annotation) {
     }
 
 
+    /**
+     * Returns the format of the original file.
+     *
+     * @return See above.
+     */
     public String getOriginalMimetype() {
         return data.getOriginalMimetype();
     }
 
 
+    /**
+     * Returns the file format as defined by the specification, corresponding to the file extension.
+     *
+     * @return See above.
+     */
     public String getServerFileMimetype() {
         return data.getServerFileMimetype();
     }
 
 
+    /**
+     * Returns the format of the uploaded file.
+     *
+     * @return See above.
+     */
     public String getFileFormat() {
         return data.getFileFormat();
     }
 
 
+    /**
+     * Returns a user readable description of the file.
+     *
+     * @return See above.
+     */
     public String getFileKind() {
         return data.getFileKind();
     }
 
 
+    /**
+     * Returns the file to upload to the server.
+     *
+     * @return See above.
+     */
     public File getAttachedFile() {
         return data.getAttachedFile();
     }
 
 
+    /**
+     * Returns the name of the file.
+     *
+     * @return See above.
+     */
     public String getFileName() {
         return data.getFileName();
     }
 
 
+    /**
+     * Returns the absolute path to the file.
+     *
+     * @return See above.
+     */
     public String getFilePath() {
         return data.getFilePath();
     }
 
 
+    /**
+     * Returns the size of the file.
+     *
+     * @return See above.
+     */
     public long getFileSize() {
         return data.getFileSize();
     }
 
 
+    /**
+     * Returns the id of the file.
+     *
+     * @return See above.
+     */
     public long getFileID() {
         return data.getFileID();
     }
 
 
+    /**
+     * Returns the original file.
+     *
+     * @param client The client handling the connection.
+     * @param path   The path where the file will be saved.
+     *
+     * @return See above.
+     *
+     * @throws ServiceException Cannot connect to OMERO.
+     * @throws IOException      Cannot write to the file.
+     * @throws OMEROServerError Server error.
+     */
     public File getFile(Client client, String path) throws IOException, ServiceException, OMEROServerError {
         final int inc = 262144;
 
@@ -121,11 +179,23 @@ public File getFile(Client client, String path) throws IOException, ServiceExcep
     }
 
 
+    /**
+     * Returns the absolute path to the file
+     *
+     * @return See above.
+     *
+     * @see AnnotationData#getContentAsString()
+     */
     public String getContentAsString() {
         return data.getContentAsString();
     }
 
 
+    /**
+     * Returns {@code true} if it is a movie file. {@code false} otherwise.
+     *
+     * @return See above.
+     */
     public boolean isMovieFile() {
         return data.isMovieFile();
     }

src/main/java/fr/igred/omero/annotations/GenericAnnotationWrapper.java

@@ -107,6 +107,22 @@ public void setDescription(String description) {
     }
 
 
+    /**
+     * Returns the number of annotations links for this object.
+     *
+     * @param client The client handling the connection.
+     *
+     * @return See above.
+     *
+     * @throws ServiceException Cannot connect to OMERO.
+     * @throws OMEROServerError Server error.
+     */
+    public int countAnnotationLinks(Client client) throws ServiceException, OMEROServerError {
+        return client.findByQuery("select link.parent from ome.model.IAnnotationLink link " +
+                                  "where link.child.id=" + getId()).size();
+    }
+
+
     /**
      * Gets all projects with this tag from OMERO.
      *

src/main/java/fr/igred/omero/annotations/TableWrapper.java

@@ -222,13 +222,13 @@ private static boolean isColumnNumeric(Variable[] resultsColumn) {
 
 
     /**
-     * Rename {@value IMAGE} column if it already exists to:
+     * Rename the {@value IMAGE} column if it already exists to:
      * <ul>
      *     <li>"{@value LABEL} if the column does not exist</li>
      *     <li>{@code "Image_column_" + columnNumber} otherwise</li>
      * </ul>
      *
-     * @param results The results table to process.
+     * @param results The ResultsTable to process.
      */
     private static void renameImageColumn(ResultsTable results) {
         if (results.columnExists(IMAGE)) {