JAL-3383 tidy method signature and Javadoc

[jalview.git] / src / jalview / datamodel / features / FeatureStore.java

diff --git a/src/jalview/datamodel/features/FeatureStore.java b/src/jalview/datamodel/features/FeatureStore.java
index c582e56..653d389 100644 (file)
--- a/src/jalview/datamodel/features/FeatureStore.java
+++ b/src/jalview/datamodel/features/FeatureStore.java
@@ -232,6 +232,13 @@ public class FeatureStore
     // only construct nonPositionalFeatures or contactFeatures if needed
   }
 
+  /**
+   * Returns a new instance of IntervalStoreI of implementation as selected by
+   * the type parameter
+   * 
+   * @param type
+   * @return
+   */
   private IntervalStoreI<SequenceFeature> getIntervalStore(
           IntervalStoreType type)
   {
@@ -355,6 +362,14 @@ public class FeatureStore
     return true;
   }
 
+  /**
+   * A helper method that adds to the result list any features from the
+   * collection provided whose feature group matches the specified group
+   * 
+   * @param group
+   * @param sfs
+   * @param result
+   */
   private void addFeaturesForGroup(String group,
           Collection<SequenceFeature> sfs, List<SequenceFeature> result)
   {
@@ -499,30 +514,62 @@ public class FeatureStore
     return removed;
   }
 
-  public List<SequenceFeature> findOverlappingFeatures(long start, long end)
+  public List<SequenceFeature> findFeatures(long start, long end)
   {
-    return findOverlappingFeatures(start, end, null);
+    return findFeatures(start, end, null);
   }
 
+  /**
+   * Returns a (possibly empty) list of features whose extent overlaps the given
+   * range. The returned list is not ordered. Contact features are included if
+   * either of the contact points lies within the range. If the {@code result}
+   * parameter is not null, new entries are added to this list and the (possibly
+   * extended) list returned.
+   * 
+   * @param start
+   *          start position of overlap range (inclusive)
+   * @param end
+   *          end position of overlap range (inclusive)
+   * @param result
+   * @return
+   */
+  public List<SequenceFeature> findFeatures(long start, long end,
+          List<SequenceFeature> result)
+  {
+    if (result == null)
+    {
+      result = new ArrayList<>();
+    }
+
+    findContactFeatures(start, end, result);
+    features.findOverlaps(start, end, result);
+
+    return result;
+  }
+
+  /**
+   * Returns a (possibly empty) list of stored contact features
+   * 
+   * @return
+   */
   public List<SequenceFeature> getContactFeatures()
   {
-    return getContactFeatures(new ArrayList<>());
+    List<SequenceFeature> result = new ArrayList<>();
+    getContactFeatures(result);
+    return result;
   }
 
   /**
-   * Answers a list of all contact features. If there are none, returns an
-   * immutable empty list.
+   * Adds any stored contact features to the result list
    * 
    * @return
    */
-  public List<SequenceFeature> getContactFeatures(
-          List<SequenceFeature> result)
+  public void getContactFeatures(List<SequenceFeature> result)
   {
     if (contactFeatureStarts != null)
     {
       result.addAll(contactFeatureStarts);
     }
-    return result;
   }
 
   /**
@@ -540,8 +587,19 @@ public class FeatureStore
               : nonPositionalFeatures.size();
     }
 
-    return (contactFeatureStarts == null ? 0 : contactFeatureStarts.size())
-            + features.size();
+    int size = 0;
+
+    if (contactFeatureStarts != null)
+    {
+      // note a contact feature (start/end) counts as one
+      size += contactFeatureStarts.size();
+    }
+
+    if (features != null)
+    {
+      size += features.size();
+    }
+    return size;
   }
 
   /**
@@ -627,41 +685,50 @@ public class FeatureStore
     return positional ? positionalMinScore : nonPositionalMinScore;
   }
 
+  /**
+   * Answers a (possibly empty) list of all non-positional features
+   * 
+   * @return
+   */
   public List<SequenceFeature> getNonPositionalFeatures()
   {
-    return getNonPositionalFeatures(new ArrayList<>());
+    List<SequenceFeature> result = new ArrayList<>();
+    getNonPositionalFeatures(result);
+    return result;
   }
 
   /**
-   * Answers a list of all non-positional features. If there are none, returns
-   * an immutable empty list.
+   * Adds any stored non-positional features to the result list
    * 
    * @return
    */
-  public List<SequenceFeature> getNonPositionalFeatures(
-          List<SequenceFeature> result)
+  public void getNonPositionalFeatures(List<SequenceFeature> result)
   {
     if (nonPositionalFeatures != null)
     {
       result.addAll(nonPositionalFeatures);
     }
-    return result;
   }
 
+  /**
+   * Returns a (possibly empty) list of all positional features stored
+   * 
+   * @return
+   */
   public List<SequenceFeature> getPositionalFeatures()
   {
-    return getPositionalFeatures(new ArrayList<>());
+    List<SequenceFeature> result = new ArrayList<>();
+    getPositionalFeatures(result);
+
+    return result;
   }
 
   /**
-   * Answers a list of all positional features stored, in no guaranteed order
-   * 
-   * @return
+   * Adds all positional features stored to the result list, in no guaranteed
+   * order, and with no check for duplicates
    */
-  public List<SequenceFeature> getPositionalFeatures(
-          List<SequenceFeature> result)
+  public void getPositionalFeatures(List<SequenceFeature> result)
   {
-
     /*
      * add any contact features - from the list by start position
      */
@@ -677,8 +744,6 @@ public class FeatureStore
     {
       result.addAll(features);
     }
-
-    return result;
   }
 
   /**
@@ -703,7 +768,7 @@ public class FeatureStore
             && !contactFeatureStarts.isEmpty())
             || (nonPositionalFeatures != null
                     && !nonPositionalFeatures.isEmpty())
-            || features.size() > 0;
+            || (features != null && features.size() > 0);
 
     return !hasFeatures;
   }
@@ -938,32 +1003,4 @@ public class FeatureStore
     }
   }
 
-  /**
-   * Returns a (possibly empty) list of features whose extent overlaps the given
-   * range. The returned list is not ordered. Contact features are included if
-   * either of the contact points lies within the range. If the {@code result}
-   * parameter is not null, new entries are added to this list and the (possibly
-   * extended) list returned.
-   * 
-   * @param start
-   *          start position of overlap range (inclusive)
-   * @param end
-   *          end position of overlap range (inclusive)
-   * @param result
-   * @return
-   */
-  public List<SequenceFeature> findOverlappingFeatures(long start, long end,
-          List<SequenceFeature> result)
-  {
-    if (result == null)
-    {
-      result = new ArrayList<>();
-    }
-
-    findContactFeatures(start, end, result);
-    features.findOverlaps(start, end, result);
-
-    return result;
-  }
-
 }