Merge branch 'develop' of https://source.jalview.org/git/jabaws into develop

[jabaws.git] / datamodel / compbio / metadata / Limit.java

diff --git a/datamodel/compbio/metadata/Limit.java b/datamodel/compbio/metadata/Limit.java
index cbbb3a7..8132832 100644 (file)
--- a/datamodel/compbio/metadata/Limit.java
+++ b/datamodel/compbio/metadata/Limit.java
@@ -29,9 +29,9 @@ import compbio.util.SysPrefs;
 \r
 /**\r
  * A value object containing a maximum number of sequences and a maximum average\r
- * sequence length for a preset.\r
+ * sequence length for a preset. Also contains static method for determining the\r
+ * number of sequence and their average length in the List<FastaSequence>\r
  * \r
- * @see LimitsManager\r
  * \r
  * @author pvtroshin\r
  * \r
@@ -40,12 +40,16 @@ import compbio.util.SysPrefs;
  * @param <T>\r
  *            the type of an executable for which this limit is defined.\r
  * \r
+ * @see LimitsManager\r
  */\r
 @XmlAccessorType(XmlAccessType.FIELD)\r
 public class Limit<T> {\r
 \r
+       // Allowed to be null\r
        private String preset;\r
+       // Cannot be 0 or below\r
        private int seqNumber;\r
+       // Can be 0 - i.e. undefined\r
        private int seqLength;\r
 \r
        @XmlAttribute\r
@@ -55,13 +59,26 @@ public class Limit<T> {
                // JAXB default constructor\r
        }\r
 \r
+       /**\r
+        * Instantiate the limit\r
+        * \r
+        * @param seqNumber\r
+        *            the maximum number of sequences allowed for calculation.\r
+        *            Required\r
+        * @param seqLength\r
+        *            the average length of the sequence, optional\r
+        * @param preset\r
+        *            the name of preset if any, optional\r
+        * @throws IllegalArgumentException\r
+        *             if the seqNumber is not supplied or the seqLength is negative\r
+        */\r
        public Limit(int seqNumber, int seqLength, String preset) {\r
                if (seqNumber <= 0) {\r
                        throw new IllegalArgumentException(\r
                                        "seqNumber - a maximum number of sequences to align must be greater than 0. Value given:"\r
                                                        + seqNumber);\r
                }\r
-               if (seqLength <= 0) {\r
+               if (seqLength < 0) {\r
                        throw new IllegalArgumentException(\r
                                        "seqLength - an average sequence length must be greater than 0. Value given:"\r
                                                        + seqLength);\r
@@ -81,14 +98,26 @@ public class Limit<T> {
                return preset;\r
        }\r
 \r
+       /**\r
+        * \r
+        * @return the allowed average sequence length\r
+        */\r
        public int getAvgSeqLength() {\r
                return seqLength;\r
        }\r
 \r
+       /**\r
+        * \r
+        * @return the maximum number of sequences allowed\r
+        */\r
        public int getSeqNumber() {\r
                return seqNumber;\r
        }\r
 \r
+       /**\r
+        * \r
+        * @return true is this is a default limit to be used, false otherwise\r
+        */\r
        public boolean isDefault() {\r
                return isDefault;\r
        }\r
@@ -128,27 +157,38 @@ public class Limit<T> {
        public String toString() {\r
                String value = "";\r
                if (isDefault) {\r
-                       value = "Default Limit" + SysPrefs.newlinechar;\r
+                       value = "Default Limits:" + SysPrefs.newlinechar;\r
                } else {\r
-                       value = "Limit for Preset '" + preset + "'" + SysPrefs.newlinechar;\r
+                       value = "Limits for Preset '" + preset + "'" + SysPrefs.newlinechar;\r
                }\r
                value += "Maximum sequence number=" + seqNumber + SysPrefs.newlinechar;\r
                value += "Average sequence length=" + seqLength + SysPrefs.newlinechar;\r
-               value += SysPrefs.newlinechar;\r
                return value;\r
        }\r
 \r
+       /*\r
+        * Calculates total number of letters allowed\r
+        */\r
        long numberOfLetters() {\r
                return this.seqNumber * this.seqLength;\r
        }\r
 \r
        /**\r
         * Checks if the number of sequences or their average length in the dataset\r
-        * exceeds limits the values defined by this Limit\r
+        * exceeds this limit.\r
         * \r
         * @param data\r
+        *            the dataset to measure\r
         * @return true if a limit is exceeded (what is the dataset is larger then\r
-        *         the limit), false otherwise.\r
+        *         the limit), false otherwise. First check the number of sequences\r
+        *         in the dataset and if it exceeds the limit return true\r
+        *         irrespective of the average length. If the number of sequences in\r
+        *         the dataset is less than the limit and average length is defined,\r
+        *         then check whether the total number of letters (number of\r
+        *         sequence multiplied by the average sequence length) is greater\r
+        *         then the total number of letters in the dataset. Returns true if\r
+        *         the total number of letters in the dataset is greater than the\r
+        *         limit, false otherwise.\r
         */\r
        public boolean isExceeded(List<FastaSequence> data) {\r
                if (data == null) {\r
@@ -158,8 +198,8 @@ public class Limit<T> {
                if (data.size() > this.seqNumber) {\r
                        return true;\r
                }\r
-               if (this.seqLength != 0) {\r
-                       if ((long) getAvgSeqLength() * data.size() > numberOfLetters()) {\r
+               if (this.seqLength != 0 && data.size() > 0) {\r
+                       if ((long) getAvgSequenceLength(data) * data.size() > numberOfLetters()) {\r
                                return true;\r
                        }\r
                }\r