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 }