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.Iterator;
024    import java.util.Map;
025    
026    import org.apache.commons.collections.Predicate;
027    
028    /**
029     * Decorates another <code>Map</code> to validate that additions
030     * match a specified predicate.
031     * <p>
032     * This map exists to provide validation for the decorated map.
033     * It is normally created to decorate an empty map.
034     * If an object cannot be added to the map, an IllegalArgumentException is thrown.
035     * <p>
036     * One usage would be to ensure that no null keys are added to the map.
037     * <pre>Map map = PredicatedSet.decorate(new HashMap(), NotNullPredicate.INSTANCE, null);</pre>
038     * <p>
039     * <strong>Note that PredicatedMap is not synchronized and is not thread-safe.</strong>
040     * If you wish to use this map from multiple threads concurrently, you must use
041     * appropriate synchronization. The simplest approach is to wrap this map
042     * using {@link java.util.Collections#synchronizedMap(Map)}. This class may throw 
043     * exceptions when accessed by concurrent threads without synchronization.
044     * <p>
045     * This class is Serializable from Commons Collections 3.1.
046     *
047     * @since Commons Collections 3.0
048     * @version $Revision: 646777 $ $Date: 2008-04-10 13:33:15 +0100 (Thu, 10 Apr 2008) $
049     * 
050     * @author Stephen Colebourne
051     * @author Paul Jack
052     */
053    public class PredicatedMap
054            extends AbstractInputCheckedMapDecorator
055            implements Serializable {
056    
057        /** Serialization version */
058        private static final long serialVersionUID = 7412622456128415156L;
059    
060        /** The key predicate to use */
061        protected final Predicate keyPredicate;
062        /** The value predicate to use */
063        protected final Predicate valuePredicate;
064    
065        /**
066         * Factory method to create a predicated (validating) map.
067         * <p>
068         * If there are any elements already in the list being decorated, they
069         * are validated.
070         * 
071         * @param map  the map to decorate, must not be null
072         * @param keyPredicate  the predicate to validate the keys, null means no check
073         * @param valuePredicate  the predicate to validate to values, null means no check
074         * @throws IllegalArgumentException if the map is null
075         */
076        public static Map decorate(Map map, Predicate keyPredicate, Predicate valuePredicate) {
077            return new PredicatedMap(map, keyPredicate, valuePredicate);
078        }
079    
080        //-----------------------------------------------------------------------
081        /**
082         * Constructor that wraps (not copies).
083         * 
084         * @param map  the map to decorate, must not be null
085         * @param keyPredicate  the predicate to validate the keys, null means no check
086         * @param valuePredicate  the predicate to validate to values, null means no check
087         * @throws IllegalArgumentException if the map is null
088         */
089        protected PredicatedMap(Map map, Predicate keyPredicate, Predicate valuePredicate) {
090            super(map);
091            this.keyPredicate = keyPredicate;
092            this.valuePredicate = valuePredicate;
093            
094            Iterator it = map.entrySet().iterator();
095            while (it.hasNext()) {
096                Map.Entry entry = (Map.Entry) it.next();
097                Object key = entry.getKey();
098                Object value = entry.getValue();
099                validate(key, value);
100            }
101        }
102    
103        //-----------------------------------------------------------------------
104        /**
105         * Write the map out using a custom routine.
106         * 
107         * @param out  the output stream
108         * @throws IOException
109         * @since Commons Collections 3.1
110         */
111        private void writeObject(ObjectOutputStream out) throws IOException {
112            out.defaultWriteObject();
113            out.writeObject(map);
114        }
115    
116        /**
117         * Read the map in using a custom routine.
118         * 
119         * @param in  the input stream
120         * @throws IOException
121         * @throws ClassNotFoundException
122         * @since Commons Collections 3.1
123         */
124        private void readObject(ObjectInputStream in) throws IOException, ClassNotFoundException {
125            in.defaultReadObject();
126            map = (Map) in.readObject();
127        }
128    
129        //-----------------------------------------------------------------------
130        /**
131         * Validates a key value pair.
132         * 
133         * @param key  the key to validate
134         * @param value  the value to validate
135         * @throws IllegalArgumentException if invalid
136         */
137        protected void validate(Object key, Object value) {
138            if (keyPredicate != null && keyPredicate.evaluate(key) == false) {
139                throw new IllegalArgumentException("Cannot add key - Predicate rejected it");
140            }
141            if (valuePredicate != null && valuePredicate.evaluate(value) == false) {
142                throw new IllegalArgumentException("Cannot add value - Predicate rejected it");
143            }
144        }
145    
146        /**
147         * Override to validate an object set into the map via <code>setValue</code>.
148         * 
149         * @param value  the value to validate
150         * @throws IllegalArgumentException if invalid
151         * @since Commons Collections 3.1
152         */
153        protected Object checkSetValue(Object value) {
154            if (valuePredicate.evaluate(value) == false) {
155                throw new IllegalArgumentException("Cannot set value - Predicate rejected it");
156            }
157            return value;
158        }
159    
160        /**
161         * Override to only return true when there is a value transformer.
162         * 
163         * @return true if a value predicate is in use
164         * @since Commons Collections 3.1
165         */
166        protected boolean isSetValueChecking() {
167            return (valuePredicate != null);
168        }
169    
170        //-----------------------------------------------------------------------
171        public Object put(Object key, Object value) {
172            validate(key, value);
173            return map.put(key, value);
174        }
175    
176        public void putAll(Map mapToCopy) {
177            Iterator it = mapToCopy.entrySet().iterator();
178            while (it.hasNext()) {
179                Map.Entry entry = (Map.Entry) it.next();
180                Object key = entry.getKey();
181                Object value = entry.getValue();
182                validate(key, value);
183            }
184            map.putAll(mapToCopy);
185        }
186    
187    }