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 */
017package org.apache.commons.lang3;
018
019import java.io.ByteArrayInputStream;
020import java.io.ByteArrayOutputStream;
021import java.io.IOException;
022import java.io.InputStream;
023import java.io.ObjectInputStream;
024import java.io.ObjectOutputStream;
025import java.io.ObjectStreamClass;
026import java.io.OutputStream;
027import java.io.Serializable;
028import java.util.HashMap;
029import java.util.Map;
030
031/**
032 * <p>Assists with the serialization process and performs additional functionality based
033 * on serialization.</p>
034 * <p>
035 * <ul>
036 * <li>Deep clone using serialization
037 * <li>Serialize managing finally and IOException
038 * <li>Deserialize managing finally and IOException
039 * </ul>
040 *
041 * <p>This class throws exceptions for invalid {@code null} inputs.
042 * Each method documents its behaviour in more detail.</p>
043 *
044 * <p>#ThreadSafe#</p>
045 * @since 1.0
046 * @version $Id: SerializationUtils.java 1572877 2014-02-28 08:42:25Z britter $
047 */
048public class SerializationUtils {
049
050    /**
051     * <p>SerializationUtils instances should NOT be constructed in standard programming.
052     * Instead, the class should be used as {@code SerializationUtils.clone(object)}.</p>
053     *
054     * <p>This constructor is public to permit tools that require a JavaBean instance
055     * to operate.</p>
056     * @since 2.0
057     */
058    public SerializationUtils() {
059        super();
060    }
061
062    // Clone
063    //-----------------------------------------------------------------------
064    /**
065     * <p>Deep clone an {@code Object} using serialization.</p>
066     *
067     * <p>This is many times slower than writing clone methods by hand
068     * on all objects in your object graph. However, for complex object
069     * graphs, or for those that don't support deep cloning this can
070     * be a simple alternative implementation. Of course all the objects
071     * must be {@code Serializable}.</p>
072     *
073     * @param <T> the type of the object involved
074     * @param object  the {@code Serializable} object to clone
075     * @return the cloned object
076     * @throws SerializationException (runtime) if the serialization fails
077     */
078    public static <T extends Serializable> T clone(final T object) {
079        if (object == null) {
080            return null;
081        }
082        final byte[] objectData = serialize(object);
083        final ByteArrayInputStream bais = new ByteArrayInputStream(objectData);
084
085        ClassLoaderAwareObjectInputStream in = null;
086        try {
087            // stream closed in the finally
088            in = new ClassLoaderAwareObjectInputStream(bais, object.getClass().getClassLoader());
089            /*
090             * when we serialize and deserialize an object,
091             * it is reasonable to assume the deserialized object
092             * is of the same type as the original serialized object
093             */
094            @SuppressWarnings("unchecked") // see above
095            final
096            T readObject = (T) in.readObject();
097            return readObject;
098
099        } 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    /**
115     * Performs a serialization roundtrip. Serializes and deserializes the given object, great for testing objects that
116     * implement {@link Serializable}.
117     *
118     * @param <T>
119     *           the type of the object involved
120     * @param msg
121     *            the object to roundtrip
122     * @return the serialized and deseralized object
123     * @since 3.3
124     */
125    public static <T extends Serializable> T roundtrip(final T msg) {
126        return SerializationUtils.deserialize(SerializationUtils.serialize(msg));
127    }
128
129    // Serialize
130    //-----------------------------------------------------------------------
131    /**
132     * <p>Serializes an {@code Object} to the specified stream.</p>
133     *
134     * <p>The stream will be closed once the object is written.
135     * This avoids the need for a finally clause, and maybe also exception
136     * handling, in the application code.</p>
137     *
138     * <p>The stream passed in is not buffered internally within this method.
139     * This is the responsibility of your application if desired.</p>
140     *
141     * @param obj  the object to serialize to bytes, may be null
142     * @param outputStream  the stream to write to, must not be null
143     * @throws IllegalArgumentException if {@code outputStream} is {@code null}
144     * @throws SerializationException (runtime) if the serialization fails
145     */
146    public static void serialize(final Serializable obj, final OutputStream outputStream) {
147        if (outputStream == null) {
148            throw new IllegalArgumentException("The OutputStream must not be null");
149        }
150        ObjectOutputStream out = null;
151        try {
152            // stream closed in the finally
153            out = new ObjectOutputStream(outputStream);
154            out.writeObject(obj);
155
156        } catch (final IOException ex) {
157            throw new SerializationException(ex);
158        } finally {
159            try {
160                if (out != null) {
161                    out.close();
162                }
163            } catch (final IOException ex) { // NOPMD
164                // ignore close exception
165            }
166        }
167    }
168
169    /**
170     * <p>Serializes an {@code Object} to a byte array for
171     * storage/serialization.</p>
172     *
173     * @param obj  the object to serialize to bytes
174     * @return a byte[] with the converted Serializable
175     * @throws SerializationException (runtime) if the serialization fails
176     */
177    public static byte[] serialize(final Serializable obj) {
178        final ByteArrayOutputStream baos = new ByteArrayOutputStream(512);
179        serialize(obj, baos);
180        return baos.toByteArray();
181    }
182
183    // Deserialize
184    //-----------------------------------------------------------------------
185    /**
186     * <p>
187     * Deserializes an {@code Object} from the specified stream.
188     * </p>
189     * 
190     * <p>
191     * The stream will be closed once the object is written. This avoids the need for a finally clause, and maybe also
192     * exception handling, in the application code.
193     * </p>
194     * 
195     * <p>
196     * The stream passed in is not buffered internally within this method. This is the responsibility of your
197     * application if desired.
198     * </p>
199     * 
200     * <p>
201     * If the call site incorrectly types the return value, a {@link ClassCastException} is thrown from the call site.
202     * Without Generics in this declaration, the call site must type cast and can cause the same ClassCastException.
203     * Note that in both cases, the ClassCastException is in the call site, not in this method.
204     * </p>
205     *
206     * @param <T>  the object type to be deserialized
207     * @param inputStream
208     *            the serialized object input stream, must not be null
209     * @return the deserialized object
210     * @throws IllegalArgumentException
211     *             if {@code inputStream} is {@code null}
212     * @throws SerializationException
213     *             (runtime) if the serialization fails
214     */
215    public static <T> T deserialize(final InputStream inputStream) {
216        if (inputStream == null) {
217            throw new IllegalArgumentException("The InputStream must not be null");
218        }
219        ObjectInputStream in = null;
220        try {
221            // stream closed in the finally
222            in = new ObjectInputStream(inputStream);
223            @SuppressWarnings("unchecked") // may fail with CCE if serialised form is incorrect
224            final T obj = (T) in.readObject();
225            return obj;
226
227        } catch (final ClassCastException ex) {
228            throw new SerializationException(ex);
229        } catch (final ClassNotFoundException ex) {
230            throw new SerializationException(ex);
231        } catch (final IOException ex) {
232            throw new SerializationException(ex);
233        } finally {
234            try {
235                if (in != null) {
236                    in.close();
237                }
238            } catch (final IOException ex) { // NOPMD
239                // ignore close exception
240            }
241        }
242    }
243
244    /**
245     * <p>
246     * Deserializes a single {@code Object} from an array of bytes.
247     * </p>
248     * 
249     * <p>
250     * If the call site incorrectly types the return value, a {@link ClassCastException} is thrown from the call site.
251     * Without Generics in this declaration, the call site must type cast and can cause the same ClassCastException.
252     * Note that in both cases, the ClassCastException is in the call site, not in this method.
253     * </p>
254     * 
255     * @param <T>  the object type to be deserialized
256     * @param objectData
257     *            the serialized object, must not be null
258     * @return the deserialized object
259     * @throws IllegalArgumentException
260     *             if {@code objectData} is {@code null}
261     * @throws SerializationException
262     *             (runtime) if the serialization fails
263     */
264    public static <T> T deserialize(final byte[] objectData) {
265        if (objectData == null) {
266            throw new IllegalArgumentException("The byte[] must not be null");
267        }
268        return SerializationUtils.<T>deserialize(new ByteArrayInputStream(objectData));
269    }
270
271    /**
272     * <p>Custom specialization of the standard JDK {@link java.io.ObjectInputStream}
273     * that uses a custom  <code>ClassLoader</code> to resolve a class.
274     * If the specified <code>ClassLoader</code> is not able to resolve the class,
275     * the context classloader of the current thread will be used.
276     * This way, the standard deserialization work also in web-application
277     * containers and application servers, no matter in which of the
278     * <code>ClassLoader</code> the particular class that encapsulates
279     * serialization/deserialization lives. </p>
280     * 
281     * <p>For more in-depth information about the problem for which this
282     * class here is a workaround, see the JIRA issue LANG-626. </p>
283     */
284     static class ClassLoaderAwareObjectInputStream extends ObjectInputStream {
285        private static final Map<String, Class<?>> primitiveTypes = 
286                new HashMap<String, Class<?>>();
287        private final ClassLoader classLoader;
288        
289        /**
290         * Constructor.
291         * @param in The <code>InputStream</code>.
292         * @param classLoader classloader to use
293         * @throws IOException if an I/O error occurs while reading stream header.
294         * @see java.io.ObjectInputStream
295         */
296        public ClassLoaderAwareObjectInputStream(final InputStream in, final ClassLoader classLoader) throws IOException {
297            super(in);
298            this.classLoader = classLoader;
299
300            primitiveTypes.put("byte", byte.class);
301            primitiveTypes.put("short", short.class);
302            primitiveTypes.put("int", int.class);
303            primitiveTypes.put("long", long.class);
304            primitiveTypes.put("float", float.class);
305            primitiveTypes.put("double", double.class);
306            primitiveTypes.put("boolean", boolean.class);
307            primitiveTypes.put("char", char.class);
308            primitiveTypes.put("void", void.class);
309        }
310
311        /**
312         * Overriden version that uses the parametrized <code>ClassLoader</code> or the <code>ClassLoader</code>
313         * of the current <code>Thread</code> to resolve the class.
314         * @param desc An instance of class <code>ObjectStreamClass</code>.
315         * @return A <code>Class</code> object corresponding to <code>desc</code>.
316         * @throws IOException Any of the usual Input/Output exceptions.
317         * @throws ClassNotFoundException If class of a serialized object cannot be found.
318         */
319        @Override
320        protected Class<?> resolveClass(final ObjectStreamClass desc) throws IOException, ClassNotFoundException {
321            final String name = desc.getName();
322            try {
323                return Class.forName(name, false, classLoader);
324            } catch (final ClassNotFoundException ex) {
325                try {
326                    return Class.forName(name, false, Thread.currentThread().getContextClassLoader());
327                } catch (final ClassNotFoundException cnfe) {
328                    final Class<?> cls = primitiveTypes.get(name);
329                    if (cls != null) {
330                        return cls;
331                    } else {
332                        throw cnfe;
333                    }
334                }
335            }
336        }
337
338    }
339
340}