Touched up the javadoc

Focus can be specified as an integer, the item id


git-svn-id: http://scm.dspace.org/svn/repo/trunk@74 9c30dcfa-912a-0410-8fc2-9e0234be79fd

dspace/src/org/dspace/browse/BrowseScope.java

@@ -51,14 +51,18 @@ import org.dspace.content.*;
  *    community or collection.
  *
  *  focus: The point at which a Browse begins. This can be a String,
- *      an Item, or null. If a String, Browses begin with values
+ *      an Item (given by either the Item object or its id), or null.
- *      lexicographically greater than or equal to the String.
+ *      If a String, Browses begin with values lexicographically greater
- *      If an Item, Browses begin with values
+ *      than or equal to the String.
- *      If null, Browses
+ *      If an Item, Browses begin with the value of the Item int the
+ *      corresponding browse index. If the item has multiple values
+ *      in the index, the behavior is undefined.
+ *      If null, Browses begin at the start of the index.
  *
  *  total: The total number of results returned from a Browse.
  *
- *  numberBefore: The number of results
+ *  numberBefore: The maximum number of results returned previous
+ *    to the focus.
  *
  * @author  Peter Breton
  * @version $Revision$
@@ -77,6 +81,7 @@ public class BrowseScope
     /** Total results to return. -1 indicates all results. */
     private int total;
 
+    /** Maximum number of results previous to the focus */
     private int numberBefore;
 
     /**
@@ -85,7 +90,7 @@ public class BrowseScope
      *   + Include results from all of DSpace
      *   + Start from the beginning of the given index
      *   + Return 0 total results
-     *   + Return 0 values before results
+     *   + Return 0 values previous to focus
      *
      * @param context - The DSpace context.
      */
@@ -151,6 +156,22 @@ public class BrowseScope
         focus = value;
     }
 
+    /**
+     * Browse starts at the item with the given id. Note that if the item
+     * has more than one value for the given browse index, the results are
+     * undefined.
+     * (FIXME -- do we want to specify this at some point??)
+     *
+     * This setting is ignored for itemsByAuthor, byAuthor, and
+     * lastSubmitted browses.
+     *
+     * @param item_id - The item to begin the browse at.
+     */
+    public void setFocus(int item_id)
+    {
+        focus = new Integer(item_id);
+    }
+
     /**
      * Browse starts at beginning (default)
      */
@@ -162,6 +183,8 @@ public class BrowseScope
     /**
      * Set the total returned to n.
      * If n is -1, all results are returned.
+     *
+     * @param n - The total number of results to return
      */
     public void setTotal(int n)
     {
@@ -177,7 +200,11 @@ public class BrowseScope
     }
 
     /**
-     * Set the point
+     * Set the maximum number of results to return previous to
+     * the focus.
+     *
+     * @param n - the maximum number of results to return previous to
+     * the focus.
      */
     public void setNumberBefore(int n)
     {
@@ -190,6 +217,8 @@ public class BrowseScope
 
     /**
      * Return the context for the browse.
+     *
+     * @return - The context for the browse.
      */
     Context getContext()
     {
@@ -198,6 +227,8 @@ public class BrowseScope
 
     /**
      * Return the browse scope.
+     *
+     * @return - The browse scope.
      */
     Object getScope()
     {
@@ -205,7 +236,10 @@ public class BrowseScope
     }
 
     /**
-     * Return the browse focus. This is either an Item or a String.
+     * Return the browse focus. This is either an Item, an
+     * Integer (the Item id) or a String.
+     *
+     * @return - The focus of the browse.
      */
     Object getFocus()
     {
@@ -213,7 +247,11 @@ public class BrowseScope
     }
 
     /**
-     * Return the total
+     * Return the maximum number of results to return.
+     * A total of -1 indicates that the entire index should
+     * be returned.
+     *
+     * @return - The maximum number of results.
      */
     int getTotal()
     {
@@ -221,7 +259,10 @@ public class BrowseScope
     }
 
     /**
-     * Return the number before
+     * Return the maximum number of results to return previous to
+     * the focus.
+     *
+     * @return - The maximum number of results previous to the focus.
      */
     int getNumberBefore()
     {