1 /*
2 * Licensed to the Apache Software Foundation (ASF) under one or more
3 * contributor license agreements. See the NOTICE file distributed with
4 * this work for additional information regarding copyright ownership.
5 * The ASF licenses this file to You under the Apache License, Version 2.0
6 * (the "License"); you may not use this file except in compliance with
7 * the License. You may obtain a copy of the License at
8 *
9 * https://www.apache.org/licenses/LICENSE-2.0
10 *
11 * Unless required by applicable law or agreed to in writing, software
12 * distributed under the License is distributed on an "AS IS" BASIS,
13 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14 * See the License for the specific language governing permissions and
15 * limitations under the License.
16 */
17 package org.apache.commons.collections4.bag;
18
19 import java.io.IOException;
20 import java.io.ObjectInputStream;
21 import java.io.ObjectOutputStream;
22 import java.util.Collection;
23 import java.util.Iterator;
24
25 import org.apache.commons.collections4.Bag;
26 import org.apache.commons.collections4.MultiSet;
27
28 /**
29 * Decorates another {@link Bag} to comply with the Collection contract.
30 * <p>
31 * By decorating an existing {@link Bag} instance with a {@link CollectionBag},
32 * it can be safely passed on to methods that require Collection types that
33 * are fully compliant with the Collection contract.
34 * </p>
35 * <p>
36 * The method Javadoc highlights the differences compared to the original Bag interface.
37 * </p>
38 *
39 * @see Bag
40 * @param <E> The type of elements in this bag
41 * @since 4.0
42 * @deprecated Since 4.6.0, no longer needed; a {@link MultiSet} already complies with the {@link Collection} contract.
43 */
44 @Deprecated
45 public final class CollectionBag<E> extends AbstractBagDecorator<E> {
46
47 /** Serialization version */
48 private static final long serialVersionUID = -2560033712679053143L;
49
50 /**
51 * Factory method to create a bag that complies to the Collection contract.
52 *
53 * @param <E> The type of the elements in the bag
54 * @param bag The bag to decorate, must not be null
55 * @return A Bag that complies to the Collection contract
56 * @throws NullPointerException if bag is null
57 */
58 public static <E> Bag<E> collectionBag(final Bag<E> bag) {
59 return new CollectionBag<>(bag);
60 }
61
62 /**
63 * Constructor that wraps (not copies).
64 *
65 * @param bag The bag to decorate, must not be null
66 * @throws NullPointerException if bag is null
67 */
68 public CollectionBag(final Bag<E> bag) {
69 super(bag);
70 }
71
72 /**
73 * <em>(Change)</em> Adds one copy of the specified object to the Bag.
74 * <p>
75 * Since this method always increases the size of the bag, it will always return {@code true}.
76 * </p>
77 *
78 * @param object The object to add
79 * @return {@code true}, always
80 * @throws ClassCastException if the class of the specified element prevents it from being added to this collection
81 */
82 @Override
83 public boolean add(final E object) {
84 return add(object, 1);
85 }
86
87 /**
88 * <em>(Change)</em>
89 * Adds {@code count} copies of the specified object to the Bag.
90 * <p>
91 * Since this method always increases the size of the bag, it
92 * will always return {@code true}.
93 *
94 * @param object The object to add
95 * @param count The number of copies to add
96 * @return {@code true}, always
97 * @throws ClassCastException if the class of the specified element prevents it from being added to this collection
98 */
99 @Override
100 public boolean add(final E object, final int count) {
101 decorated().add(object, count);
102 return true;
103 }
104
105 @Override
106 public boolean addAll(final Collection<? extends E> coll) {
107 boolean changed = false;
108 for (final E current : coll) {
109 final boolean added = add(current, 1);
110 changed = changed || added;
111 }
112 return changed;
113 }
114
115 /**
116 * <em>(Change)</em>
117 * Returns {@code true} if the bag contains all elements in
118 * the given collection, <strong>not</strong> respecting cardinality. That is,
119 * if the given collection {@code coll} contains at least one of
120 * every object contained in this object.
121 *
122 * @param coll The collection to check against
123 * @return {@code true} if the Bag contains at least one of every object in the collection
124 */
125 @Override
126 public boolean containsAll(final Collection<?> coll) {
127 return coll.stream().allMatch(this::contains);
128 }
129
130 /**
131 * Reads the collection in using a custom routine.
132 *
133 * @param in The input stream
134 * @throws IOException Thrown if an error occurs while reading from the stream
135 * @throws ClassNotFoundException if an object read from the stream cannot be loaded
136 * @throws ClassCastException if deserialized object has wrong type
137 */
138 @SuppressWarnings("unchecked") // will throw CCE, see Javadoc
139 private void readObject(final ObjectInputStream in) throws IOException, ClassNotFoundException {
140 in.defaultReadObject();
141 setCollection((Collection<E>) in.readObject());
142 }
143
144 /**
145 * <em>(Change)</em>
146 * Removes the first occurrence of the given object from the bag.
147 * <p>
148 * This will also remove the object from the {@link #uniqueSet()} if the
149 * bag contains no occurrence anymore of the object after this operation.
150 * </p>
151 *
152 * @param object The object to remove
153 * @return {@code true} if this call changed the collection
154 */
155 @Override
156 public boolean remove(final Object object) {
157 return remove(object, 1);
158 }
159
160 /**
161 * <em>(Change)</em>
162 * Remove all elements represented in the given collection,
163 * <strong>not</strong> respecting cardinality. That is, remove <em>all</em>
164 * occurrences of every object contained in the given collection.
165 *
166 * @param coll The collection to remove
167 * @return {@code true} if this call changed the collection
168 */
169 @Override
170 public boolean removeAll(final Collection<?> coll) {
171 if (coll != null) {
172 boolean result = false;
173 for (final Object obj : coll) {
174 final boolean changed = remove(obj, getCount(obj));
175 result = result || changed;
176 }
177 return result;
178 }
179 // let the decorated bag handle the case of null argument
180 return decorated().removeAll(null);
181 }
182
183 /**
184 * <em>(Change)</em>
185 * Remove any members of the bag that are not in the given collection,
186 * <em>not</em> respecting cardinality. That is, any object in the given
187 * collection {@code coll} will be retained in the bag with the same
188 * number of copies prior to this operation. All other objects will be
189 * completely removed from this bag.
190 * <p>
191 * This implementation iterates over the elements of this bag, checking
192 * each element in turn to see if it's contained in {@code coll}.
193 * If it's not contained, it's removed from this bag. As a consequence,
194 * it is advised to use a collection type for {@code coll} that provides
195 * a fast (for example O(1)) implementation of {@link Collection#contains(Object)}.
196 * </p>
197 *
198 * @param coll The collection to retain
199 * @return {@code true} if this call changed the collection
200 */
201 @Override
202 public boolean retainAll(final Collection<?> coll) {
203 if (coll != null) {
204 boolean modified = false;
205 final Iterator<E> e = iterator();
206 while (e.hasNext()) {
207 if (!coll.contains(e.next())) {
208 e.remove();
209 modified = true;
210 }
211 }
212 return modified;
213 }
214 // let the decorated bag handle the case of null argument
215 return decorated().retainAll(null);
216 }
217
218 /**
219 * Writes the collection out using a custom routine.
220 *
221 * @param out The output stream
222 * @throws IOException Thrown if an error occurs while writing to the stream
223 */
224 private void writeObject(final ObjectOutputStream out) throws IOException {
225 out.defaultWriteObject();
226 out.writeObject(decorated());
227 }
228
229 }