View Javadoc

1   /*
2    * Copyright (c) 2005 Regents of the University of California (Regents). Created
3    * by TELS, Graduate School of Education, University of California at Berkeley.
4    *
5    * This software is distributed under the GNU Lesser General Public License, v2.
6    *
7    * Permission is hereby granted, without written agreement and without license
8    * or royalty fees, to use, copy, modify, and distribute this software and its
9    * documentation for any purpose, provided that the above copyright notice and
10   * the following two paragraphs appear in all copies of this software.
11   *
12   * REGENTS SPECIFICALLY DISCLAIMS ANY WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
13   * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
14   * PURPOSE. THE SOFTWAREAND ACCOMPANYING DOCUMENTATION, IF ANY, PROVIDED
15   * HEREUNDER IS PROVIDED "AS IS". REGENTS HAS NO OBLIGATION TO PROVIDE
16   * MAINTENANCE, SUPPORT, UPDATES, ENHANCEMENTS, OR MODIFICATIONS.
17   *
18   * IN NO EVENT SHALL REGENTS BE LIABLE TO ANY PARTY FOR DIRECT, INDIRECT,
19   * SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES, INCLUDING LOST PROFITS,
20   * ARISING OUT OF THE USE OF THIS SOFTWARE AND ITS DOCUMENTATION, EVEN IF
21   * REGENTS HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
22   */
23  package net.sf.sail.core.entity;
24  
25  import java.util.EmptyStackException;
26  import java.util.Iterator;
27  
28  /***
29   * Subset of java.util.Collection plus a peek() from java.util.Stack
30   * 
31   * @author turadg
32   */
33  public interface ISock extends Iterable {
34  
35  	/***
36  	 * Returns the number of elements in this collection. If this collection
37  	 * contains more than <tt>Integer.MAX_VALUE</tt> elements, returns
38  	 * <tt>Integer.MAX_VALUE</tt>.
39  	 * 
40  	 * @return the number of elements in this collection
41  	 */
42  	int size();
43  
44  	/***
45  	 * Returns <tt>true</tt> if this collection contains no elements.
46  	 * 
47  	 * @return <tt>true</tt> if this collection contains no elements
48  	 */
49  	boolean isEmpty();
50  
51  	/***
52  	 * Returns an iterator over the elements in this collection. There are no
53  	 * guarantees concerning the order in which the elements are returned
54  	 * (unless this collection is an instance of some class that provides a
55  	 * guarantee).
56  	 * 
57  	 * @return an <tt>Iterator</tt> over the elements in this collection
58  	 */
59  	Iterator iterator();
60  
61  	/***
62  	 * Ensures that this collection contains the specified element (optional
63  	 * operation). Returns <tt>true</tt> if this collection changed as a
64  	 * result of the call. (Returns <tt>false</tt> if this collection does not
65  	 * permit duplicates and already contains the specified element.)
66  	 * <p>
67  	 * Collections that support this operation may place limitations on what
68  	 * elements may be added to this collection. In particular, some collections
69  	 * will refuse to add <tt>null</tt> elements, and others will impose
70  	 * restrictions on the type of elements that may be added. Collection
71  	 * classes should clearly specify in their documentation any restrictions on
72  	 * what elements may be added.
73  	 * <p>
74  	 * If a collection refuses to add a particular element for any reason other
75  	 * than that it already contains the element, it <i>must</i> throw an
76  	 * exception (rather than returning <tt>false</tt>). This preserves the
77  	 * invariant that a collection always contains the specified element after
78  	 * this call returns.
79  	 * 
80  	 * @param o
81  	 *            element whose presence in this collection is to be ensured.
82  	 * @return <tt>true</tt> if this collection changed as a result of the
83  	 *         call
84  	 * @throws UnsupportedOperationException
85  	 *             <tt>add</tt> is not supported by this collection.
86  	 * @throws ClassCastException
87  	 *             class of the specified element prevents it from being added
88  	 *             to this collection.
89  	 * @throws NullPointerException
90  	 *             if the specified element is null and this collection does not
91  	 *             support null elements.
92  	 * @throws IllegalArgumentException
93  	 *             some aspect of this element prevents it from being added to
94  	 *             this collection.
95  	 */
96  	boolean add(Object o);
97  
98  	/***
99  	 * Looks at the most recent object in this sock.
100 	 * 
101 	 * @return the object most recently added to this sock
102 	 * @exception EmptyStackException
103 	 *                if this sock is empty.
104 	 */
105 	public Object peek();
106 
107 }