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.io.Serializable; 023import java.util.Collection; 024import java.util.Comparator; 025import java.util.Objects; 026import java.util.SortedMap; 027import java.util.TreeMap; 028 029import org.apache.commons.collections4.SortedBag; 030 031/** 032 * Implements {@link SortedBag}, using a {@link TreeMap} to provide the data storage. 033 * This is the standard implementation of a sorted bag. 034 * <p> 035 * Order will be maintained among the bag members and can be viewed through the iterator. 036 * </p> 037 * <p> 038 * A {@link org.apache.commons.collections4.Bag Bag} stores each object in the collection 039 * together with a count of occurrences. Extra methods on the interface allow multiple 040 * copies of an object to be added or removed at once. It is important to read the interface 041 * Javadoc carefully as several methods violate the {@link Collection} interface specification. 042 * </p> 043 * 044 * @param <E> the type of elements in this bag 045 * @since 3.0 (previously in main package v2.0) 046 */ 047public class TreeBag<E> extends AbstractMapBag<E> implements SortedBag<E>, Serializable { 048 049 /** Serial version lock */ 050 private static final long serialVersionUID = -7740146511091606676L; 051 052 /** 053 * Constructs an empty {@link TreeBag}. 054 */ 055 public TreeBag() { 056 super(new TreeMap<>()); 057 } 058 059 /** 060 * Constructs a {@link TreeBag} containing all the members of the 061 * specified collection. 062 * 063 * @param coll the collection to copy into the bag 064 */ 065 public TreeBag(final Collection<? extends E> coll) { 066 this(); 067 addAll(coll); 068 } 069 070 /** 071 * Constructs an empty bag that maintains order on its unique representative 072 * members according to the given {@link Comparator}. 073 * 074 * @param comparator the comparator to use 075 */ 076 public TreeBag(final Comparator<? super E> comparator) { 077 super(new TreeMap<>(comparator)); 078 } 079 080 /** 081 * {@inheritDoc} 082 * 083 * @throws IllegalArgumentException if the object to be added does not implement 084 * {@link Comparable} and the {@link TreeBag} is using natural ordering 085 * @throws NullPointerException if the specified key is null and this bag uses 086 * natural ordering, or its comparator does not permit null keys 087 */ 088 @Override 089 public boolean add(final E object) { 090 if (comparator() == null && !(object instanceof Comparable)) { 091 Objects.requireNonNull(object, "object"); 092 throw new IllegalArgumentException("Objects of type " + object.getClass() + " cannot be added to " + 093 "a naturally ordered TreeBag as it does not implement Comparable"); 094 } 095 return super.add(object); 096 } 097 098 @Override 099 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}