001/* 002 * Licensed to the Apache Software Foundation (ASF) under one or more 003 * contributor license agreements. See the NOTICE file distributed with 004 * this work for additional information regarding copyright ownership. 005 * The ASF licenses this file to You under the Apache License, Version 2.0 006 * (the "License"); you may not use this file except in compliance with 007 * the License. You may obtain a copy of the License at 008 * 009 * http://www.apache.org/licenses/LICENSE-2.0 010 * 011 * Unless required by applicable law or agreed to in writing, software 012 * distributed under the License is distributed on an "AS IS" BASIS, 013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 014 * See the License for the specific language governing permissions and 015 * limitations under the License. 016 */ 017package org.apache.commons.collections4.bag; 018 019import java.io.IOException; 020import java.io.ObjectInputStream; 021import java.io.ObjectOutputStream; 022import java.util.Collection; 023import java.util.Iterator; 024 025import org.apache.commons.collections4.Bag; 026 027/** 028 * Decorates another {@link Bag} to comply with the Collection contract. 029 * <p> 030 * By decorating an existing {@link Bag} instance with a {@link CollectionBag}, 031 * it can be safely passed on to methods that require Collection types that 032 * are fully compliant with the Collection contract. 033 * </p> 034 * <p> 035 * The method Javadoc highlights the differences compared to the original Bag interface. 036 * </p> 037 * 038 * @see Bag 039 * @param <E> the type of elements in this bag 040 * @since 4.0 041 */ 042public final class CollectionBag<E> extends AbstractBagDecorator<E> { 043 044 /** Serialization version */ 045 private static final long serialVersionUID = -2560033712679053143L; 046 047 /** 048 * Factory method to create a bag that complies to the Collection contract. 049 * 050 * @param <E> the type of the elements in the bag 051 * @param bag the bag to decorate, must not be null 052 * @return a Bag that complies to the Collection contract 053 * @throws NullPointerException if bag is null 054 */ 055 public static <E> Bag<E> collectionBag(final Bag<E> bag) { 056 return new CollectionBag<>(bag); 057 } 058 059 /** 060 * Constructor that wraps (not copies). 061 * 062 * @param bag the bag to decorate, must not be null 063 * @throws NullPointerException if bag is null 064 */ 065 public CollectionBag(final Bag<E> bag) { 066 super(bag); 067 } 068 069 /** 070 * <i>(Change)</i> 071 * Adds one copy of the specified object to the Bag. 072 * <p> 073 * Since this method always increases the size of the bag, it 074 * will always return {@code true}. 075 * 076 * @param object the object to add 077 * @return {@code true}, always 078 */ 079 @Override 080 public boolean add(final E object) { 081 return add(object, 1); 082 } 083 084 /** 085 * <i>(Change)</i> 086 * Adds {@code count} copies of the specified object to the Bag. 087 * <p> 088 * Since this method always increases the size of the bag, it 089 * will always return {@code true}. 090 * 091 * @param object the object to add 092 * @param count the number of copies to add 093 * @return {@code true}, always 094 */ 095 @Override 096 public boolean add(final E object, final int count) { 097 decorated().add(object, count); 098 return true; 099 } 100 101 // Collection interface 102 103 @Override 104 public boolean addAll(final Collection<? extends E> coll) { 105 boolean changed = false; 106 for (final E current : coll) { 107 final boolean added = add(current, 1); 108 changed = changed || added; 109 } 110 return changed; 111 } 112 113 /** 114 * <i>(Change)</i> 115 * Returns {@code true} if the bag contains all elements in 116 * the given collection, <b>not</b> respecting cardinality. That is, 117 * if the given collection {@code coll} contains at least one of 118 * every object contained in this object. 119 * 120 * @param coll the collection to check against 121 * @return {@code true} if the Bag contains at least one of every object in the collection 122 */ 123 @Override 124 public boolean containsAll(final Collection<?> coll) { 125 return coll.stream().allMatch(this::contains); 126 } 127 128 /** 129 * Read the collection in using a custom routine. 130 * 131 * @param in the input stream 132 * @throws IOException if an error occurs while reading from the stream 133 * @throws ClassNotFoundException if an object read from the stream can not be loaded 134 * @throws ClassCastException if deserialized object has wrong type 135 */ 136 @SuppressWarnings("unchecked") // will throw CCE, see Javadoc 137 private void readObject(final ObjectInputStream in) throws IOException, ClassNotFoundException { 138 in.defaultReadObject(); 139 setCollection((Collection<E>) in.readObject()); 140 } 141 142 /** 143 * <i>(Change)</i> 144 * Removes the first occurrence of the given object from the bag. 145 * <p> 146 * This will also remove the object from the {@link #uniqueSet()} if the 147 * bag contains no occurrence anymore of the object after this operation. 148 * 149 * @param object the object to remove 150 * @return {@code true} if this call changed the collection 151 */ 152 @Override 153 public boolean remove(final Object object) { 154 return remove(object, 1); 155 } 156 157 /** 158 * <i>(Change)</i> 159 * Remove all elements represented in the given collection, 160 * <b>not</b> respecting cardinality. That is, remove <i>all</i> 161 * occurrences of every object contained in the given collection. 162 * 163 * @param coll the collection to remove 164 * @return {@code true} if this call changed the collection 165 */ 166 @Override 167 public boolean removeAll(final Collection<?> coll) { 168 if (coll != null) { 169 boolean result = false; 170 for (final Object obj : coll) { 171 final boolean changed = remove(obj, getCount(obj)); 172 result = result || changed; 173 } 174 return result; 175 } 176 // let the decorated bag handle the case of null argument 177 return decorated().removeAll(null); 178 } 179 180 /** 181 * <i>(Change)</i> 182 * Remove any members of the bag that are not in the given collection, 183 * <i>not</i> respecting cardinality. That is, any object in the given 184 * collection {@code coll} will be retained in the bag with the same 185 * number of copies prior to this operation. All other objects will be 186 * completely removed from this bag. 187 * <p> 188 * This implementation iterates over the elements of this bag, checking 189 * each element in turn to see if it's contained in {@code coll}. 190 * If it's not contained, it's removed from this bag. As a consequence, 191 * it is advised to use a collection type for {@code coll} that provides 192 * a fast (e.g. O(1)) implementation of {@link Collection#contains(Object)}. 193 * 194 * @param coll the collection to retain 195 * @return {@code true} if this call changed the collection 196 */ 197 @Override 198 public boolean retainAll(final Collection<?> coll) { 199 if (coll != null) { 200 boolean modified = false; 201 final Iterator<E> e = iterator(); 202 while (e.hasNext()) { 203 if (!coll.contains(e.next())) { 204 e.remove(); 205 modified = true; 206 } 207 } 208 return modified; 209 } 210 // let the decorated bag handle the case of null argument 211 return decorated().retainAll(null); 212 } 213 214 // Bag interface 215 216 /** 217 * Write the collection out using a custom routine. 218 * 219 * @param out the output stream 220 * @throws IOException if an error occurs while writing to the stream 221 */ 222 private void writeObject(final ObjectOutputStream out) throws IOException { 223 out.defaultWriteObject(); 224 out.writeObject(decorated()); 225 } 226 227}