From: pvtroshin <pvtroshin@e3abac25-378b-4346-85de-24260fe3988d>
Date: Wed, 24 Nov 2010 12:48:49 +0000 (+0000)
Subject: Adding changes from JWS2 branch. Fixes for Limit in particular
X-Git-Url: http://source.jalview.org/gitweb/?a=commitdiff_plain;h=0cf25749808de13ed56cd16a281da7adf48b6530;p=jabaws.git

Adding changes from JWS2 branch. Fixes for Limit in particular

git-svn-id: link to svn.lifesci.dundee.ac.uk/svn/barton/ptroshin/JABA2@3377 e3abac25-378b-4346-85de-24260fe3988d
---

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