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; 018 019import java.util.Collection; 020import java.util.Iterator; 021import java.util.Set; 022 023/** 024 * Defines a collection that counts the number of times an object appears in 025 * the collection. 026 * <p> 027 * Suppose you have a Bag that contains {@code {a, a, b, c}}. 028 * Calling {@link #getCount(Object)} on {@code a} would return 2, while 029 * calling {@link #uniqueSet()} would return {@code {a, b, c}}. 030 * </p> 031 * <p> 032 * <i>NOTE: This interface violates the {@link Collection} contract.</i> 033 * The behavior specified in many of these methods is <i>not</i> the same 034 * as the behavior specified by {@code Collection}. 035 * The non-compliant methods are clearly marked with "(Violation)". 036 * Exercise caution when using a bag as a {@code Collection}. 037 * </p> 038 * <p> 039 * This violation resulted from the original specification of this interface. 040 * In an ideal world, the interface would be changed to fix the problems, however 041 * it has been decided to maintain backwards compatibility instead. 042 * </p> 043 * 044 * @param <E> the type of elements in this bag 045 * @since 2.0 046 */ 047public interface Bag<E> extends Collection<E> { 048 049 /** 050 * <i>(Violation)</i> 051 * Adds one copy of the specified object to the Bag. 052 * <p> 053 * If the object is already in the {@link #uniqueSet()} then increment its 054 * count as reported by {@link #getCount(Object)}. Otherwise add it to the 055 * {@link #uniqueSet()} and report its count as 1. 056 * </p> 057 * <p> 058 * Since this method always increases the size of the bag, 059 * according to the {@link Collection#add(Object)} contract, it 060 * should always return {@code true}. Since it sometimes returns 061 * {@code false}, this method violates the contract. 062 * </p> 063 * 064 * @param object the object to add 065 * @return {@code true} if the object was not already in the {@code uniqueSet} 066 */ 067 @Override 068 boolean add(E object); 069 070 /** 071 * Adds {@code nCopies} copies of the specified object to the Bag. 072 * <p> 073 * If the object is already in the {@link #uniqueSet()} then increment its 074 * count as reported by {@link #getCount(Object)}. Otherwise add it to the 075 * {@link #uniqueSet()} and report its count as {@code nCopies}. 076 * </p> 077 * 078 * @param object the object to add 079 * @param nCopies the number of copies to add 080 * @return {@code true} if the object was not already in the {@code uniqueSet} 081 */ 082 boolean add(E object, int nCopies); 083 084 /** 085 * <i>(Violation)</i> 086 * Returns {@code true} if the bag contains all elements in 087 * the given collection, respecting cardinality. That is, if the 088 * given collection {@code coll} contains {@code n} copies 089 * of a given object, calling {@link #getCount(Object)} on that object must 090 * be {@code >= n} for all {@code n} in {@code coll}. 091 * 092 * <p> 093 * The {@link Collection#containsAll(Collection)} method specifies 094 * that cardinality should <i>not</i> be respected; this method should 095 * return true if the bag contains at least one of every object contained 096 * in the given collection. 097 * </p> 098 * 099 * @param coll the collection to check against 100 * @return {@code true} if the Bag contains all the collection 101 */ 102 @Override 103 boolean containsAll(Collection<?> coll); 104 105 /** 106 * Returns the number of occurrences (cardinality) of the given 107 * object currently in the bag. If the object does not exist in the 108 * bag, return 0. 109 * 110 * @param object the object to search for 111 * @return the number of occurrences of the object, zero if not found 112 */ 113 int getCount(Object object); 114 115 /** 116 * Returns an {@link Iterator} over the entire set of members, 117 * including copies due to cardinality. This iterator is fail-fast 118 * and will not tolerate concurrent modifications. 119 * 120 * @return iterator over all elements in the Bag 121 */ 122 @Override 123 Iterator<E> iterator(); 124 125 /** 126 * <i>(Violation)</i> 127 * Removes all occurrences of the given object from the bag. 128 * <p> 129 * This will also remove the object from the {@link #uniqueSet()}. 130 * </p> 131 * <p> 132 * According to the {@link Collection#remove(Object)} method, 133 * this method should only remove the <i>first</i> occurrence of the 134 * given object, not <i>all</i> occurrences. 135 * </p> 136 * 137 * @param object the object to remove 138 * @return {@code true} if this call changed the collection 139 */ 140 @Override 141 boolean remove(Object object); 142 143 /** 144 * Removes {@code nCopies} copies of the specified object from the Bag. 145 * <p> 146 * If the number of copies to remove is greater than the actual number of 147 * copies in the Bag, no error is thrown. 148 * </p> 149 * 150 * @param object the object to remove 151 * @param nCopies the number of copies to remove 152 * @return {@code true} if this call changed the collection 153 */ 154 boolean remove(Object object, int nCopies); 155 156 /** 157 * <i>(Violation)</i> 158 * Remove all elements represented in the given collection, 159 * respecting cardinality. That is, if the given collection 160 * {@code coll} contains {@code n} copies of a given object, 161 * the bag will have {@code n} fewer copies, assuming the bag 162 * had at least {@code n} copies to begin with. 163 * 164 * <p> 165 * The {@link Collection#removeAll(Collection)} method specifies 166 * that cardinality should <i>not</i> be respected; this method should 167 * remove <i>all</i> occurrences of every object contained in the 168 * given collection. 169 * </p> 170 * 171 * @param coll the collection to remove 172 * @return {@code true} if this call changed the collection 173 */ 174 @Override 175 boolean removeAll(Collection<?> coll); 176 177 /** 178 * <i>(Violation)</i> 179 * Remove any members of the bag that are not in the given 180 * collection, respecting cardinality. That is, if the given 181 * collection {@code coll} contains {@code n} copies of a 182 * given object and the bag has {@code m > n} copies, then 183 * delete {@code m - n} copies from the bag. In addition, if 184 * {@code e} is an object in the bag but 185 * {@code !coll.contains(e)}, then remove {@code e} and any 186 * of its copies. 187 * 188 * <p> 189 * The {@link Collection#retainAll(Collection)} method specifies 190 * that cardinality should <i>not</i> be respected; this method should 191 * keep <i>all</i> occurrences of every object contained in the 192 * given collection. 193 * </p> 194 * 195 * @param coll the collection to retain 196 * @return {@code true} if this call changed the collection 197 */ 198 @Override 199 boolean retainAll(Collection<?> coll); 200 201 /** 202 * Returns the total number of items in the bag across all types. 203 * 204 * @return the total size of the Bag 205 */ 206 @Override 207 int size(); 208 209 /** 210 * Returns a {@link Set} of unique elements in the Bag. 211 * <p> 212 * Uniqueness constraints are the same as those in {@link java.util.Set}. 213 * </p> 214 * 215 * @return the Set of unique Bag elements 216 */ 217 Set<E> uniqueSet(); 218 219 // The following is not part of the formal Bag interface, however where possible 220 // Bag implementations should follow these comments. 221// /** 222// * Compares this Bag to another. 223// * This Bag equals another Bag if it contains the same number of occurrences of 224// * the same elements. 225// * This equals definition is compatible with the Set interface. 226// * 227// * @param obj the Bag to compare to 228// * @return true if equal 229// */ 230// boolean equals(Object obj); 231// 232// /** 233// * Gets a hash code for the Bag compatible with the definition of equals. 234// * The hash code is defined as the sum total of a hash code for each element. 235// * The per element hash code is defined as 236// * {@code (e==null ? 0 : e.hashCode()) ^ noOccurrences)}. 237// * This hash code definition is compatible with the Set interface. 238// * 239// * @return the hash code of the Bag 240// */ 241// int hashCode(); 242 243}