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.collection;
18
19 import java.util.ArrayList;
20 import java.util.Collection;
21 import java.util.List;
22 import java.util.Objects;
23
24 import org.apache.commons.collections4.Transformer;
25
26 /**
27 * Decorates another {@link Collection} to transform objects that are added.
28 * <p>
29 * The add methods are affected by this class.
30 * Thus objects must be removed or searched for using their transformed form.
31 * For example, if the transformation converts Strings to Integers, you must
32 * use the Integer form to remove objects.
33 * </p>
34 * <p>
35 * This class is Serializable from Commons Collections 3.1.
36 * </p>
37 *
38 * @param <E> the type of the elements in the collection
39 * @since 3.0
40 */
41 public class TransformedCollection<E> extends AbstractCollectionDecorator<E> {
42
43 /** Serialization version */
44 private static final long serialVersionUID = 8692300188161871514L;
45
46 /**
47 * Factory method to create a transforming collection that will transform
48 * existing contents of the specified collection.
49 * <p>
50 * If there are any elements already in the collection being decorated, they
51 * will be transformed by this method.
52 * Contrast this with {@link #transformingCollection(Collection, Transformer)}.
53 *
54 * @param <E> the type of the elements in the collection
55 * @param collection the collection to decorate, must not be null
56 * @param transformer the transformer to use for conversion, must not be null
57 * @return a new transformed Collection
58 * @throws NullPointerException if collection or transformer is null
59 * @since 4.0
60 */
61 public static <E> TransformedCollection<E> transformedCollection(final Collection<E> collection,
62 final Transformer<? super E, ? extends E> transformer) {
63
64 final TransformedCollection<E> decorated = new TransformedCollection<>(collection, transformer);
65 // null collection & transformer are disallowed by the constructor call above
66 if (!collection.isEmpty()) {
67 @SuppressWarnings("unchecked") // collection is of type E
68 final E[] values = (E[]) collection.toArray(); // NOPMD - false positive for generics
69 collection.clear();
70 for (final E value : values) {
71 decorated.decorated().add(transformer.apply(value));
72 }
73 }
74 return decorated;
75 }
76
77 /**
78 * Factory method to create a transforming collection.
79 * <p>
80 * If there are any elements already in the collection being decorated, they
81 * are NOT transformed.
82 * Contrast this with {@link #transformedCollection(Collection, Transformer)}.
83 *
84 * @param <E> the type of the elements in the collection
85 * @param coll the collection to decorate, must not be null
86 * @param transformer the transformer to use for conversion, must not be null
87 * @return a new transformed collection
88 * @throws NullPointerException if collection or transformer is null
89 * @since 4.0
90 */
91 public static <E> TransformedCollection<E> transformingCollection(final Collection<E> coll,
92 final Transformer<? super E, ? extends E> transformer) {
93 return new TransformedCollection<>(coll, transformer);
94 }
95
96 /** The transformer to use */
97 protected final Transformer<? super E, ? extends E> transformer;
98
99 /**
100 * Constructor that wraps (not copies).
101 * <p>
102 * If there are any elements already in the collection being decorated, they
103 * are NOT transformed.
104 *
105 * @param collection the collection to decorate, must not be null
106 * @param transformer the transformer to use for conversion, must not be null
107 * @throws NullPointerException if collection or transformer is null
108 */
109 protected TransformedCollection(final Collection<E> collection, final Transformer<? super E, ? extends E> transformer) {
110 super(collection);
111 this.transformer = Objects.requireNonNull(transformer, "transformer");
112 }
113
114 @Override
115 public boolean add(final E object) {
116 return decorated().add(transform(object));
117 }
118
119 @Override
120 public boolean addAll(final Collection<? extends E> coll) {
121 return decorated().addAll(transform(coll));
122 }
123
124 /**
125 * Transforms a collection.
126 * <p>
127 * The transformer itself may throw an exception if necessary.
128 *
129 * @param coll the collection to transform
130 * @return a transformed object
131 */
132 protected Collection<E> transform(final Collection<? extends E> coll) {
133 final List<E> list = new ArrayList<>(coll.size());
134 for (final E item : coll) {
135 list.add(transform(item));
136 }
137 return list;
138 }
139
140 /**
141 * Transforms an object.
142 * <p>
143 * The transformer itself may throw an exception if necessary.
144 *
145 * @param object the object to transform
146 * @return a transformed object
147 */
148 protected E transform(final E object) {
149 return transformer.apply(object);
150 }
151
152 }