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 * http://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.io.Serializable; 23 import java.util.Collection; 24 import java.util.Comparator; 25 import java.util.Objects; 26 import java.util.SortedMap; 27 import java.util.TreeMap; 28 29 import org.apache.commons.collections4.SortedBag; 30 31 /** 32 * Implements {@link SortedBag}, using a {@link TreeMap} to provide the data storage. 33 * This is the standard implementation of a sorted bag. 34 * <p> 35 * Order will be maintained among the bag members and can be viewed through the iterator. 36 * </p> 37 * <p> 38 * A {@link org.apache.commons.collections4.Bag Bag} stores each object in the collection 39 * together with a count of occurrences. Extra methods on the interface allow multiple 40 * copies of an object to be added or removed at once. It is important to read the interface 41 * Javadoc carefully as several methods violate the {@link Collection} interface specification. 42 * </p> 43 * 44 * @param <E> the type of elements in this bag 45 * @since 3.0 (previously in main package v2.0) 46 */ 47 public class TreeBag<E> extends AbstractMapBag<E> implements SortedBag<E>, Serializable { 48 49 /** Serial version lock */ 50 private static final long serialVersionUID = -7740146511091606676L; 51 52 /** 53 * Constructs an empty {@link TreeBag}. 54 */ 55 public TreeBag() { 56 super(new TreeMap<>()); 57 } 58 59 /** 60 * Constructs a {@link TreeBag} containing all the members of the 61 * specified collection. 62 * 63 * @param coll the collection to copy into the bag 64 */ 65 public TreeBag(final Collection<? extends E> coll) { 66 this(); 67 addAll(coll); 68 } 69 70 /** 71 * Constructs an empty bag that maintains order on its unique representative 72 * members according to the given {@link Comparator}. 73 * 74 * @param comparator the comparator to use 75 */ 76 public TreeBag(final Comparator<? super E> comparator) { 77 super(new TreeMap<>(comparator)); 78 } 79 80 /** 81 * {@inheritDoc} 82 * 83 * @throws IllegalArgumentException if the object to be added does not implement 84 * {@link Comparable} and the {@link TreeBag} is using natural ordering 85 * @throws NullPointerException if the specified key is null and this bag uses 86 * natural ordering, or its comparator does not permit null keys 87 */ 88 @Override 89 public boolean add(final E object) { 90 if (comparator() == null && !(object instanceof Comparable)) { 91 Objects.requireNonNull(object, "object"); 92 throw new IllegalArgumentException("Objects of type " + object.getClass() + " cannot be added to " + 93 "a naturally ordered TreeBag as it does not implement Comparable"); 94 } 95 return super.add(object); 96 } 97 98 @Override 99 public Comparator<? super E> comparator() { 100 return getMap().comparator(); 101 } 102 103 @Override 104 public E first() { 105 return getMap().firstKey(); 106 } 107 108 @Override 109 protected SortedMap<E, AbstractMapBag.MutableInteger> getMap() { 110 return (SortedMap<E, AbstractMapBag.MutableInteger>) super.getMap(); 111 } 112 113 @Override 114 public E last() { 115 return getMap().lastKey(); 116 } 117 118 /** 119 * Read the bag in using a custom routine. 120 * 121 * @param in the input stream 122 * @throws IOException if an error occurs while reading from the stream 123 * @throws ClassNotFoundException if an object read from the stream can not be loaded 124 */ 125 private void readObject(final ObjectInputStream in) throws IOException, ClassNotFoundException { 126 in.defaultReadObject(); 127 @SuppressWarnings("unchecked") // This will fail at runtime if the stream is incorrect 128 final Comparator<? super E> comp = (Comparator<? super E>) in.readObject(); 129 super.doReadObject(new TreeMap<>(comp), in); 130 } 131 132 /** 133 * Write the bag out using a custom routine. 134 * 135 * @param out the output stream 136 * @throws IOException if an error occurs while writing to the stream 137 */ 138 private void writeObject(final ObjectOutputStream out) throws IOException { 139 out.defaultWriteObject(); 140 out.writeObject(comparator()); 141 super.doWriteObject(out); 142 } 143 144 }