KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > jodd > util > collection > Bag


1 // Copyright (c) 2003-2007, Jodd Team (jodd.sf.net). All Rights Reserved.
2
3 package jodd.util.collection;
4
5
6 import java.util.Collection JavaDoc;
7 import java.util.Iterator JavaDoc;
8 import java.util.Set JavaDoc;
9
10 /**
11  * Bags are a specialization of unordered collections that explicitly allow duplicates.
12  */
13 public interface Bag extends Collection JavaDoc {
14
15     /**
16      * Returns the number of occurrences (cardinality) of the given
17      * object currently in the bag. If the object does not exist in the
18      * bag, return 0.
19      *
20      * @param object the object to search for
21      * @return the number of occurrences of the object, zero if not found
22      */
23     int getCount(Object JavaDoc object);
24
25     /**
26      * <i>(Violation)</i>
27      * Adds one copy the specified object to the Bag.
28      * <p>
29      * If the object is already in the {@link #uniqueSet()} then increment its
30      * count as reported by {@link #getCount(Object)}. Otherwise add it to the
31      * {@link #uniqueSet()} and report its count as 1.
32      * <p>
33      * Since this method always increases the size of the bag,
34      * according to the {@link Collection#add(Object)} contract, it
35      * should always return <code>true</code>. Since it sometimes returns
36      * <code>false</code>, this method violates the contract.
37      *
38      * @param object the object to add
39      * @return <code>true</code> if the object was not already in the <code>uniqueSet</code>
40      */
41     boolean add(Object JavaDoc object);
42
43     /**
44      * Adds <code>nCopies</code> copies of the specified object to the Bag.
45      * <p>
46      * If the object is already in the {@link #uniqueSet()} then increment its
47      * count as reported by {@link #getCount(Object)}. Otherwise add it to the
48      * {@link #uniqueSet()} and report its count as <code>nCopies</code>.
49      *
50      * @param object the object to add
51      * @param nCopies the number of copies to add
52      * @return <code>true</code> if the object was not already in the <code>uniqueSet</code>
53      */
54     boolean add(Object JavaDoc object, int nCopies);
55
56     /**
57      * <i>(Violation)</i>
58      * Removes all occurrences of the given object from the bag.
59      * <p>
60      * This will also remove the object from the {@link #uniqueSet()}.
61      * <p>
62      * According to the {@link Collection#remove(Object)} method,
63      * this method should only remove the <i>first</i> occurrence of the
64      * given object, not <i>all</i> occurrences.
65      *
66      * @return <code>true</code> if this call changed the collection
67      */
68     boolean remove(Object JavaDoc object);
69
70     /**
71      * Removes <code>nCopies</code> copies of the specified object from the Bag.
72      * <p>
73      * If the number of copies to remove is greater than the actual number of
74      * copies in the Bag, no error is thrown.
75      *
76      * @param object the object to remove
77      * @param nCopies the number of copies to remove
78      * @return <code>true</code> if this call changed the collection
79      */
80     boolean remove(Object JavaDoc object, int nCopies);
81
82     /**
83      * Returns a {@link Set} of unique elements in the Bag.
84      * <p>
85      * Uniqueness constraints are the same as those in {@link java.util.Set}.
86      *
87      * @return the Set of unique Bag elements
88      */
89     Set JavaDoc uniqueSet();
90
91     /**
92      * Returns the total number of items in the bag across all types.
93      *
94      * @return the total size of the Bag
95      */
96     int size();
97
98     /**
99      * <i>(Violation)</i>
100      * Returns <code>true</code> if the bag contains all elements in
101      * the given collection, respecting cardinality. That is, if the
102      * given collection <code>coll</code> contains <code>n</code> copies
103      * of a given object, calling {@link #getCount(Object)} on that object must
104      * be <code>&gt;= n</code> for all <code>n</code> in <code>coll</code>.
105      * <p>
106      * The {@link Collection#containsAll(Collection)} method specifies
107      * that cardinality should <i>not</i> be respected; this method should
108      * return true if the bag contains at least one of every object contained
109      * in the given collection.
110      *
111      * @param coll the collection to check against
112      * @return <code>true</code> if the Bag contains all the collection
113      */
114     boolean containsAll(Collection JavaDoc coll);
115
116     /**
117      * <i>(Violation)</i>
118      * Remove all elements represented in the given collection,
119      * respecting cardinality. That is, if the given collection
120      * <code>coll</code> contains <code>n</code> copies of a given object,
121      * the bag will have <code>n</code> fewer copies, assuming the bag
122      * had at least <code>n</code> copies to begin with.
123      *
124      * <P>The {@link Collection#removeAll(Collection)} method specifies
125      * that cardinality should <i>not</i> be respected; this method should
126      * remove <i>all</i> occurrences of every object contained in the
127      * given collection.
128      *
129      * @param coll the collection to remove
130      * @return <code>true</code> if this call changed the collection
131      */
132     boolean removeAll(Collection JavaDoc coll);
133
134     /**
135      * <i>(Violation)</i>
136      * Remove any members of the bag that are not in the given
137      * collection, respecting cardinality. That is, if the given
138      * collection <code>coll</code> contains <code>n</code> copies of a
139      * given object and the bag has <code>m &gt; n</code> copies, then
140      * delete <code>m - n</code> copies from the bag. In addition, if
141      * <code>e</code> is an object in the bag but
142      * <code>!coll.contains(e)</code>, then remove <code>e</code> and any
143      * of its copies.
144      *
145      * <P>The {@link Collection#retainAll(Collection)} method specifies
146      * that cardinality should <i>not</i> be respected; this method should
147      * keep <i>all</i> occurrences of every object contained in the
148      * given collection.
149      *
150      * @param coll the collection to retain
151      * @return <code>true</code> if this call changed the collection
152      */
153     boolean retainAll(Collection JavaDoc coll);
154
155     /**
156      * Returns an {@link Iterator} over the entire set of members,
157      * including copies due to cardinality. This iterator is fail-fast
158      * and will not tolerate concurrent modifications.
159      *
160      * @return iterator over all elements in the Bag
161      */
162     Iterator JavaDoc iterator();
163
164 }
Popular Tags