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     */
017    package org.apache.commons.collections.map;
018    
019    import java.io.IOException;
020    import java.io.ObjectInputStream;
021    import java.io.ObjectOutputStream;
022    import java.io.Serializable;
023    import java.util.Collection;
024    import java.util.Iterator;
025    import java.util.Map;
026    import java.util.Set;
027    import java.util.SortedMap;
028    
029    import org.apache.commons.collections.BoundedMap;
030    import org.apache.commons.collections.collection.UnmodifiableCollection;
031    import org.apache.commons.collections.set.UnmodifiableSet;
032    
033    /**
034     * Decorates another <code>SortedMap</code> to fix the size blocking add/remove.
035     * <p>
036     * Any action that would change the size of the map is disallowed.
037     * The put method is allowed to change the value associated with an existing
038     * key however.
039     * <p>
040     * If trying to remove or clear the map, an UnsupportedOperationException is
041     * thrown. If trying to put a new mapping into the map, an 
042     * IllegalArgumentException is thrown. This is because the put method can 
043     * succeed if the mapping's key already exists in the map, so the put method
044     * is not always unsupported.
045     * <p>
046     * <strong>Note that FixedSizeSortedMap is not synchronized and is not thread-safe.</strong>
047     * If you wish to use this map from multiple threads concurrently, you must use
048     * appropriate synchronization. The simplest approach is to wrap this map
049     * using {@link java.util.Collections#synchronizedSortedMap}. This class may throw 
050     * exceptions when accessed by concurrent threads without synchronization.
051     * <p>
052     * This class is Serializable from Commons Collections 3.1.
053     *
054     * @since Commons Collections 3.0
055     * @version $Revision: 646777 $ $Date: 2008-04-10 13:33:15 +0100 (Thu, 10 Apr 2008) $
056     * 
057     * @author Stephen Colebourne
058     * @author Paul Jack
059     */
060    public class FixedSizeSortedMap
061            extends AbstractSortedMapDecorator
062            implements SortedMap, BoundedMap, Serializable {
063    
064        /** Serialization version */
065        private static final long serialVersionUID = 3126019624511683653L;
066    
067        /**
068         * Factory method to create a fixed size sorted map.
069         * 
070         * @param map  the map to decorate, must not be null
071         * @throws IllegalArgumentException if map is null
072         */
073        public static SortedMap decorate(SortedMap map) {
074            return new FixedSizeSortedMap(map);
075        }
076    
077        //-----------------------------------------------------------------------
078        /**
079         * Constructor that wraps (not copies).
080         * 
081         * @param map  the map to decorate, must not be null
082         * @throws IllegalArgumentException if map is null
083         */
084        protected FixedSizeSortedMap(SortedMap map) {
085            super(map);
086        }
087    
088        /**
089         * Gets the map being decorated.
090         * 
091         * @return the decorated map
092         */
093        protected SortedMap getSortedMap() {
094            return (SortedMap) map;
095        }
096    
097        //-----------------------------------------------------------------------
098        /**
099         * Write the map out using a custom routine.
100         */
101        private void writeObject(ObjectOutputStream out) throws IOException {
102            out.defaultWriteObject();
103            out.writeObject(map);
104        }
105    
106        /**
107         * Read the map in using a custom routine.
108         */
109        private void readObject(ObjectInputStream in) throws IOException, ClassNotFoundException {
110            in.defaultReadObject();
111            map = (Map) in.readObject();
112        }
113    
114        //-----------------------------------------------------------------------
115        public Object put(Object key, Object value) {
116            if (map.containsKey(key) == false) {
117                throw new IllegalArgumentException("Cannot put new key/value pair - Map is fixed size");
118            }
119            return map.put(key, value);
120        }
121    
122        public void putAll(Map mapToCopy) {
123            for (Iterator it = mapToCopy.keySet().iterator(); it.hasNext(); ) {
124                if (mapToCopy.containsKey(it.next()) == false) {
125                    throw new IllegalArgumentException("Cannot put new key/value pair - Map is fixed size");
126                }
127            }
128            map.putAll(mapToCopy);
129        }
130    
131        public void clear() {
132            throw new UnsupportedOperationException("Map is fixed size");
133        }
134    
135        public Object remove(Object key) {
136            throw new UnsupportedOperationException("Map is fixed size");
137        }
138    
139        public Set entrySet() {
140            Set set = map.entrySet();
141            return UnmodifiableSet.decorate(set);
142        }
143    
144        public Set keySet() {
145            Set set = map.keySet();
146            return UnmodifiableSet.decorate(set);
147        }
148    
149        public Collection values() {
150            Collection coll = map.values();
151            return UnmodifiableCollection.decorate(coll);
152        }
153    
154        //-----------------------------------------------------------------------
155        public SortedMap subMap(Object fromKey, Object toKey) {
156            SortedMap map = getSortedMap().subMap(fromKey, toKey);
157            return new FixedSizeSortedMap(map);
158        }
159    
160        public SortedMap headMap(Object toKey) {
161            SortedMap map = getSortedMap().headMap(toKey);
162            return new FixedSizeSortedMap(map);
163        }
164    
165        public SortedMap tailMap(Object fromKey) {
166            SortedMap map = getSortedMap().tailMap(fromKey);
167            return new FixedSizeSortedMap(map);
168        }
169    
170        public boolean isFull() {
171            return true;
172        }
173    
174        public int maxSize() {
175            return size();
176        }
177    
178    }