BrowseScope


1   /*
2    * BrowseScope.java
3    *
4    * Version: $Revision: 1.15 $
5    *
6    * Date: $Date: 2005/04/20 14:23:03 $
7    *
8    * Copyright (c) 2002-2005, Hewlett-Packard Company and Massachusetts
9    * Institute of Technology.  All rights reserved.
10   *
11   * Redistribution and use in source and binary forms, with or without
12   * modification, are permitted provided that the following conditions are
13   * met:
14   *
15   * - Redistributions of source code must retain the above copyright
16   * notice, this list of conditions and the following disclaimer.
17   *
18   * - Redistributions in binary form must reproduce the above copyright
19   * notice, this list of conditions and the following disclaimer in the
20   * documentation and/or other materials provided with the distribution.
21   *
22   * - Neither the name of the Hewlett-Packard Company nor the name of the
23   * Massachusetts Institute of Technology nor the names of their
24   * contributors may be used to endorse or promote products derived from
25   * this software without specific prior written permission.
26   *
27   * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
28   * ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
29   * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
30   * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
31   * HOLDERS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
32   * INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
33   * BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS
34   * OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
35   * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR
36   * TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE
37   * USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH
38   * DAMAGE.
39   */
40  package org.dspace.browse;
41  
42  import org.dspace.content.Collection;
43  import org.dspace.content.Community;
44  import org.dspace.content.Item;
45  import org.dspace.core.Context;
46  
47  /**
48   * Object which describes the desired parameters for a browse. A scope object
49   * contains the following:
50   * 
51   * <dl>
52   * <dt>scope</dt>
53   * <dd>A {@link org.dspace.content.Community}, a
54   * {@link org.dspace.content.Collection}, or null. If the scope is a community
55   * or collection, browses return only objects within the community or
56   * collection.</dd>
57   * 
58   * <dt>focus</dt>
59   * <dd>The point at which a Browse begins. This can be a String, an
60   * {@link org.dspace.content.Item}(given by either the Item object or its id),
61   * or null. <br>
62   * If a String, Browses begin with values lexicographically greater than or
63   * equal to the String. <br>
64   * If an Item, Browses begin with the value of the Item in the corresponding
65   * browse index. If the item has multiple values in the index, the behavior is
66   * undefined. <br>
67   * If null, Browses begin at the start of the index.</dd>
68   * 
69   * <dt>total</dt>
70   * <dd>The total number of results returned from a Browse. A total of -1 means
71   * to return all results.</dd>
72   * 
73   * <dt>numberBefore</dt>
74   * <dd>The maximum number of results returned previous to the focus.</dd>
75   * </dl>
76   * 
77   * @author Peter Breton
78   * @version $Revision: 1.15 $
79   */
80  public class BrowseScope implements Cloneable  
81  {
82      /** The DSpace context */
83      private Context context;
84  
85      /** The scope */
86      private Object   scope;
87  
88      /** The String or Item at which to start the browse. */
89      private Object   focus;
90  
91      /** Total results to return. -1 indicates all results. */
92      private int total;
93  
94      /** Maximum number of results previous to the focus */
95      private int numberBefore;
96  
97      // Internal variables used by Browse
98  
99      /** The type of browse */
100     private int browseType;
101 
102     /** Whether results should be ascending or descending */
103     private boolean ascending;
104 
105     /** Whether results should be sorted */
106     private Boolean   sort;
107 
108     /**
109      * Create a browse scope with the given context. The default scope settings
110      * are:
111      * <ul>
112      * <li>Include results from all of DSpace
113      * <li>Start from the beginning of the given index
114      * <li>Return 21 total results
115      * <li>Return 3 values previous to focus
116      * </ul>
117      * 
118      * @param context
119      *            The DSpace context.
120      */
121     public BrowseScope(Context context)
122     {
123         this.context = context;
124         scope = null;
125         focus = null;
126         total = 21;
127         numberBefore = 3;
128     }
129 
130     /**
131      * Clone this object
132      */
133     public Object   clone()
134     {
135         BrowseScope clone = new BrowseScope(context);
136 
137         clone.scope = scope;
138         clone.focus = focus;
139         clone.total = total;
140         clone.numberBefore = numberBefore;
141         clone.browseType = browseType;
142         clone.ascending = ascending;
143         clone.sort = sort;
144 
145         return clone;
146     }
147 
148     /**
149      * Set the browse scope to all of DSpace.
150      */
151     public void setScopeAll()
152     {
153         scope = null;
154     }
155 
156     /**
157      * Limit the browse to a community.
158      * 
159      * @param community
160      *            The community to browse.
161      */
162     public void setScope(Community community)
163     {
164         scope = community;
165     }
166 
167     /**
168      * Limit the browse to a collection.
169      * 
170      * @param collection
171      *            The collection to browse.
172      */
173     public void setScope(Collection collection)
174     {
175         scope = collection;
176     }
177 
178     /**
179      * Browse starts at item i. Note that if the item has more than one value
180      * for the given browse, the results are undefined.
181      * 
182      * This setting is ignored for itemsByAuthor, byAuthor, and lastSubmitted
183      * browses.
184      * 
185      * @param item
186      *            The item to begin the browse at.
187      */
188     public void setFocus(Item item)
189     {
190         focus = item;
191     }
192 
193     /**
194      * Browse starts at value. If value is null, Browses begin from the start of
195      * the index.
196      * 
197      * This setting is ignored for itemsByAuthor and lastSubmitted browses.
198      * 
199      * @param value
200      *            The value to begin the browse at.
201      */
202     public void setFocus(String   value)
203     {
204         focus = value.toLowerCase();
205     }
206 
207     /**
208      * Browse starts at the item with the given id. Note that if the item has
209      * more than one value for the given browse index, the results are
210      * undefined.
211      * 
212      * This setting is ignored for itemsByAuthor, byAuthor, and lastSubmitted
213      * browses.
214      * 
215      * @param item_id
216      *            The item to begin the browse at.
217      */
218     public void setFocus(int item_id)
219     {
220         focus = new Integer  (item_id);
221     }
222 
223     /**
224      * Browse starts at beginning (default).
225      */
226     public void noFocus()
227     {
228         focus = null;
229     }
230 
231     /**
232      * Set the total returned to n. If n is -1, all results are returned.
233      * 
234      * @param n
235      *            The total number of results to return
236      */
237     public void setTotal(int n)
238     {
239         total = n;
240     }
241 
242     /**
243      * Return all results from browse.
244      */
245     public void setTotalAll()
246     {
247         setTotal(-1);
248     }
249 
250     /**
251      * Set the maximum number of results to return previous to the focus.
252      * 
253      * @param n
254      *            The maximum number of results to return previous to the focus.
255      */
256     public void setNumberBefore(int n)
257     {
258         this.numberBefore = n;
259     }
260 
261     ////////////////////////////////////////
262     // Accessor methods
263     ////////////////////////////////////////
264 
265     /**
266      * Return the context for the browse.
267      * 
268      * @return The context for the browse.
269      */
270     public Context getContext()
271     {
272         return context;
273     }
274 
275     /**
276      * Return the browse scope.
277      * 
278      * @return The browse scope.
279      */
280     public Object   getScope()
281     {
282         return scope;
283     }
284 
285     /**
286      * Return the browse focus. This is either an
287      * {@link org.dspace.content.Item}, an Integer (the Item id) or a String.
288      * 
289      * @return The focus of the browse.
290      */
291     public Object   getFocus()
292     {
293         return focus;
294     }
295 
296     /**
297      * Return the maximum number of results to return. A total of -1 indicates
298      * that all matching results should be returned.
299      * 
300      * @return The maximum number of results.
301      */
302     public int getTotal()
303     {
304         return total;
305     }
306 
307     /**
308      * Return the maximum number of results to return previous to the focus.
309      * 
310      * @return The maximum number of results previous to the focus.
311      */
312     public int getNumberBefore()
313     {
314         return numberBefore;
315     }
316 
317     /**
318      * Return true if there is no limit on the number of matches returned, false
319      * otherwise.
320      */
321     public boolean hasNoLimit()
322     {
323         return total == -1;
324     }
325 
326     /**
327      * Return true if there is a focus for the browse, false otherwise.
328      */
329     public boolean hasFocus()
330     {
331         return focus != null;
332     }
333 
334     ////////////////////////////////////////
335     // Convenience methods at package scope
336     ////////////////////////////////////////
337 
338     /**
339      * Return true if the focus is an Item.
340      */
341     boolean focusIsItem()
342     {
343         return (focus instanceof Item) || (focus instanceof Integer  );
344     }
345 
346     /**
347      * Return true if the focus is a String.
348      */
349     boolean focusIsString()
350     {
351         return (focus instanceof String  );
352     }
353 
354     /**
355      * Return the focus item id.
356      */
357     int getFocusItemId()
358     {
359         if (!focusIsItem())
360         {
361             throw new IllegalArgumentException  ("Focus is not an Item");
362         }
363 
364         if (focus instanceof Integer  )
365         {
366             return ((Integer  ) focus).intValue();
367         }
368 
369         return ((Item) focus).getID();
370     }
371 
372     /**
373      * Return the focus string value.
374      */
375     String   getFocusValue()
376     {
377         return (String  ) focus;
378     }
379 
380     /**
381      * True if the scope is that of a collection.
382      */
383     boolean isCollectionScope()
384     {
385         if (scope == null)
386         {
387             return false;
388         }
389 
390         return scope instanceof Collection;
391     }
392 
393     /**
394      * True if the scope is that of a community.
395      */
396     boolean isCommunityScope()
397     {
398         if (scope == null)
399         {
400             return false;
401         }
402 
403         return scope instanceof Community;
404     }
405 
406     /**
407      * True if the scope is all of DSpace.
408      */
409     boolean isAllDSpaceScope()
410     {
411         return scope == null;
412     }
413 
414     ////////////////////////////////////////
415     // Internal browse fields
416     ////////////////////////////////////////
417 
418     /**
419      * Return the type of browse (one of the constants in Browse).
420      */
421     int getBrowseType()
422     {
423         return browseType;
424     }
425 
426     void setBrowseType(int type)
427     {
428         browseType = type;
429     }
430 
431     /**
432      * If true, sort the results by title. If false, sort the results by date.
433      * If null, do no sorting at all.
434      */
435     Boolean   getSortByTitle()
436     {
437         return sort;
438     }
439 
440     void setSortByTitle(Boolean   s)
441     {
442         this.sort = s;
443     }
444 
445     /**
446      * If true, results are in ascending order. Otherwise, results are in
447      * descending order.
448      */
449     boolean getAscending()
450     {
451         return ascending;
452     }
453 
454     void setAscending(boolean a)
455     {
456         this.ascending = a;
457     }
458 
459     /**
460      * Return true if this BrowseScope is equal to another object, false
461      * otherwise.
462      * 
463      * @param obj
464      *            The object to compare to
465      * @return True if this BrowseScope is equal to the other object, false
466      *         otherwise.
467      */
468     public boolean equals(Object   obj)
469     {
470         if (!(obj instanceof BrowseScope))
471         {
472             return false;
473         }
474 
475         BrowseScope other = (BrowseScope) obj;
476 
477         return _equals(scope, other.scope) && _equals(focus, other.focus)
478                 && _equals(sort, other.sort) && (total == other.total)
479                 && (browseType == other.browseType)
480                 && (ascending == other.ascending)
481                 && (numberBefore == other.numberBefore);
482     }
483 
484     private boolean _equals(Object   first, Object   second)
485     {
486         if ((first == null) && (second == null))
487         {
488             return true;
489         }
490 
491         if ((first != null) && (second == null))
492         {
493             return false;
494         }
495 
496         if ((first == null) && (second != null))
497         {
498             return false;
499         }
500 
501         return first.equals(second);
502     }
503 
504     /*
505      * Return a hashCode for this object.
506      */
507     public int hashCode()
508     {
509         return new StringBuffer  ().append(scope).append(focus).append(total)
510                 .append(numberBefore).append(browseType).append(ascending)
511                 .append(sort).toString().hashCode();
512     }
513 }
514
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags