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.lang3;
18
19 import java.io.ByteArrayInputStream;
20 import java.io.ByteArrayOutputStream;
21 import java.io.IOException;
22 import java.io.InputStream;
23 import java.io.ObjectInputStream;
24 import java.io.ObjectOutputStream;
25 import java.io.ObjectStreamClass;
26 import java.io.OutputStream;
27 import java.io.Serializable;
28 import java.util.HashMap;
29 import java.util.Map;
30
31 /**
32 * <p>Assists with the serialization process and performs additional functionality based
33 * on serialization.</p>
34 * <p>
35 * <ul>
36 * <li>Deep clone using serialization
37 * <li>Serialize managing finally and IOException
38 * <li>Deserialize managing finally and IOException
39 * </ul>
40 *
41 * <p>This class throws exceptions for invalid {@code null} inputs.
42 * Each method documents its behaviour in more detail.</p>
43 *
44 * <p>#ThreadSafe#</p>
45 * @since 1.0
46 * @version $Id: SerializationUtils.java 1448293 2013-02-20 16:57:52Z tn $
47 */
48 public class SerializationUtils {
49
50 /**
51 * <p>SerializationUtils instances should NOT be constructed in standard programming.
52 * Instead, the class should be used as {@code SerializationUtils.clone(object)}.</p>
53 *
54 * <p>This constructor is public to permit tools that require a JavaBean instance
55 * to operate.</p>
56 * @since 2.0
57 */
58 public SerializationUtils() {
59 super();
60 }
61
62 // Clone
63 //-----------------------------------------------------------------------
64 /**
65 * <p>Deep clone an {@code Object} using serialization.</p>
66 *
67 * <p>This is many times slower than writing clone methods by hand
68 * on all objects in your object graph. However, for complex object
69 * graphs, or for those that don't support deep cloning this can
70 * be a simple alternative implementation. Of course all the objects
71 * must be {@code Serializable}.</p>
72 *
73 * @param <T> the type of the object involved
74 * @param object the {@code Serializable} object to clone
75 * @return the cloned object
76 * @throws SerializationException (runtime) if the serialization fails
77 */
78 public static <T extends Serializable> T clone(final T object) {
79 if (object == null) {
80 return null;
81 }
82 final byte[] objectData = serialize(object);
83 final ByteArrayInputStream bais = new ByteArrayInputStream(objectData);
84
85 ClassLoaderAwareObjectInputStream in = null;
86 try {
87 // stream closed in the finally
88 in = new ClassLoaderAwareObjectInputStream(bais, object.getClass().getClassLoader());
89 /*
90 * when we serialize and deserialize an object,
91 * it is reasonable to assume the deserialized object
92 * is of the same type as the original serialized object
93 */
94 @SuppressWarnings("unchecked") // see above
95 final
96 T readObject = (T) in.readObject();
97 return readObject;
98
99 } catch (final ClassNotFoundException ex) {
100 throw new SerializationException("ClassNotFoundException while reading cloned object data", ex);
101 } catch (final IOException ex) {
102 throw new SerializationException("IOException while reading cloned object data", ex);
103 } finally {
104 try {
105 if (in != null) {
106 in.close();
107 }
108 } catch (final IOException ex) {
109 throw new SerializationException("IOException on closing cloned object data InputStream.", ex);
110 }
111 }
112 }
113
114 // Serialize
115 //-----------------------------------------------------------------------
116 /**
117 * <p>Serializes an {@code Object} to the specified stream.</p>
118 *
119 * <p>The stream will be closed once the object is written.
120 * This avoids the need for a finally clause, and maybe also exception
121 * handling, in the application code.</p>
122 *
123 * <p>The stream passed in is not buffered internally within this method.
124 * This is the responsibility of your application if desired.</p>
125 *
126 * @param obj the object to serialize to bytes, may be null
127 * @param outputStream the stream to write to, must not be null
128 * @throws IllegalArgumentException if {@code outputStream} is {@code null}
129 * @throws SerializationException (runtime) if the serialization fails
130 */
131 public static void serialize(final Serializable obj, final OutputStream outputStream) {
132 if (outputStream == null) {
133 throw new IllegalArgumentException("The OutputStream must not be null");
134 }
135 ObjectOutputStream out = null;
136 try {
137 // stream closed in the finally
138 out = new ObjectOutputStream(outputStream);
139 out.writeObject(obj);
140
141 } catch (final IOException ex) {
142 throw new SerializationException(ex);
143 } finally {
144 try {
145 if (out != null) {
146 out.close();
147 }
148 } catch (final IOException ex) { // NOPMD
149 // ignore close exception
150 }
151 }
152 }
153
154 /**
155 * <p>Serializes an {@code Object} to a byte array for
156 * storage/serialization.</p>
157 *
158 * @param obj the object to serialize to bytes
159 * @return a byte[] with the converted Serializable
160 * @throws SerializationException (runtime) if the serialization fails
161 */
162 public static byte[] serialize(final Serializable obj) {
163 final ByteArrayOutputStream baos = new ByteArrayOutputStream(512);
164 serialize(obj, baos);
165 return baos.toByteArray();
166 }
167
168 // Deserialize
169 //-----------------------------------------------------------------------
170 /**
171 * <p>
172 * Deserializes an {@code Object} from the specified stream.
173 * </p>
174 *
175 * <p>
176 * The stream will be closed once the object is written. This avoids the need for a finally clause, and maybe also
177 * exception handling, in the application code.
178 * </p>
179 *
180 * <p>
181 * The stream passed in is not buffered internally within this method. This is the responsibility of your
182 * application if desired.
183 * </p>
184 *
185 * <p>
186 * If the call site incorrectly types the return value, a {@link ClassCastException} is thrown from the call site.
187 * Without Generics in this declaration, the call site must type cast and can cause the same ClassCastException.
188 * Note that in both cases, the ClassCastException is in the call site, not in this method.
189 * </p>
190 *
191 * @param <T> the object type to be deserialized
192 * @param inputStream
193 * the serialized object input stream, must not be null
194 * @return the deserialized object
195 * @throws IllegalArgumentException
196 * if {@code inputStream} is {@code null}
197 * @throws SerializationException
198 * (runtime) if the serialization fails
199 */
200 @SuppressWarnings("unchecked")
201 // Don't warn about "(T) deserialize" because we want the avoid type casting call sites.
202 public static <T> T deserialize(final InputStream inputStream) {
203 if (inputStream == null) {
204 throw new IllegalArgumentException("The InputStream must not be null");
205 }
206 ObjectInputStream in = null;
207 try {
208 // stream closed in the finally
209 in = new ObjectInputStream(inputStream);
210 return (T) in.readObject();
211
212 } catch (final ClassNotFoundException ex) {
213 throw new SerializationException(ex);
214 } catch (final IOException ex) {
215 throw new SerializationException(ex);
216 } finally {
217 try {
218 if (in != null) {
219 in.close();
220 }
221 } catch (final IOException ex) { // NOPMD
222 // ignore close exception
223 }
224 }
225 }
226
227 /**
228 * <p>
229 * Deserializes a single {@code Object} from an array of bytes.
230 * </p>
231 *
232 * <p>
233 * If the call site incorrectly types the return value, a {@link ClassCastException} is thrown from the call site.
234 * Without Generics in this declaration, the call site must type cast and can cause the same ClassCastException.
235 * Note that in both cases, the ClassCastException is in the call site, not in this method.
236 * </p>
237 *
238 * @param <T> the object type to be deserialized
239 * @param objectData
240 * the serialized object, must not be null
241 * @return the deserialized object
242 * @throws IllegalArgumentException
243 * if {@code objectData} is {@code null}
244 * @throws SerializationException
245 * (runtime) if the serialization fails
246 */
247 @SuppressWarnings("unchecked")
248 // Don't warn about "(T) deserialize" because we want the avoid type casting call sites.
249 public static <T> T deserialize(final byte[] objectData) {
250 if (objectData == null) {
251 throw new IllegalArgumentException("The byte[] must not be null");
252 }
253 return (T) deserialize(new ByteArrayInputStream(objectData));
254 }
255
256 /**
257 * <p>Custom specialization of the standard JDK {@link java.io.ObjectInputStream}
258 * that uses a custom <code>ClassLoader</code> to resolve a class.
259 * If the specified <code>ClassLoader</code> is not able to resolve the class,
260 * the context classloader of the current thread will be used.
261 * This way, the standard deserialization work also in web-application
262 * containers and application servers, no matter in which of the
263 * <code>ClassLoader</code> the particular class that encapsulates
264 * serialization/deserialization lives. </p>
265 *
266 * <p>For more in-depth information about the problem for which this
267 * class here is a workaround, see the JIRA issue LANG-626. </p>
268 */
269 static class ClassLoaderAwareObjectInputStream extends ObjectInputStream {
270 private static final Map<String, Class<?>> primitiveTypes =
271 new HashMap<String, Class<?>>();
272 private final ClassLoader classLoader;
273
274 /**
275 * Constructor.
276 * @param in The <code>InputStream</code>.
277 * @param classLoader classloader to use
278 * @throws IOException if an I/O error occurs while reading stream header.
279 * @see java.io.ObjectInputStream
280 */
281 public ClassLoaderAwareObjectInputStream(final InputStream in, final ClassLoader classLoader) throws IOException {
282 super(in);
283 this.classLoader = classLoader;
284
285 primitiveTypes.put("byte", byte.class);
286 primitiveTypes.put("short", short.class);
287 primitiveTypes.put("int", int.class);
288 primitiveTypes.put("long", long.class);
289 primitiveTypes.put("float", float.class);
290 primitiveTypes.put("double", double.class);
291 primitiveTypes.put("boolean", boolean.class);
292 primitiveTypes.put("char", char.class);
293 primitiveTypes.put("void", void.class);
294 }
295
296 /**
297 * Overriden version that uses the parametrized <code>ClassLoader</code> or the <code>ClassLoader</code>
298 * of the current <code>Thread</code> to resolve the class.
299 * @param desc An instance of class <code>ObjectStreamClass</code>.
300 * @return A <code>Class</code> object corresponding to <code>desc</code>.
301 * @throws IOException Any of the usual Input/Output exceptions.
302 * @throws ClassNotFoundException If class of a serialized object cannot be found.
303 */
304 @Override
305 protected Class<?> resolveClass(final ObjectStreamClass desc) throws IOException, ClassNotFoundException {
306 final String name = desc.getName();
307 try {
308 return Class.forName(name, false, classLoader);
309 } catch (final ClassNotFoundException ex) {
310 try {
311 return Class.forName(name, false, Thread.currentThread().getContextClassLoader());
312 } catch (final ClassNotFoundException cnfe) {
313 final Class<?> cls = primitiveTypes.get(name);
314 if (cls != null) {
315 return cls;
316 } else {
317 throw cnfe;
318 }
319 }
320 }
321 }
322
323 }
324
325 }