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 1478234 2013-05-01 23:43:35Z sebb $ 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 // 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 public static <T> T deserialize(final InputStream inputStream) { 201 if (inputStream == null) { 202 throw new IllegalArgumentException("The InputStream must not be null"); 203 } 204 ObjectInputStream in = null; 205 try { 206 // stream closed in the finally 207 in = new ObjectInputStream(inputStream); 208 @SuppressWarnings("unchecked") // may fail with CCE if serialised form is incorrect 209 final T obj = (T) in.readObject(); 210 return obj; 211 212 } catch (final ClassCastException ex) { 213 throw new SerializationException(ex); 214 } catch (final ClassNotFoundException ex) { 215 throw new SerializationException(ex); 216 } catch (final IOException ex) { 217 throw new SerializationException(ex); 218 } finally { 219 try { 220 if (in != null) { 221 in.close(); 222 } 223 } catch (final IOException ex) { // NOPMD 224 // ignore close exception 225 } 226 } 227 } 228 229 /** 230 * <p> 231 * Deserializes a single {@code Object} from an array of bytes. 232 * </p> 233 * 234 * <p> 235 * If the call site incorrectly types the return value, a {@link ClassCastException} is thrown from the call site. 236 * Without Generics in this declaration, the call site must type cast and can cause the same ClassCastException. 237 * Note that in both cases, the ClassCastException is in the call site, not in this method. 238 * </p> 239 * 240 * @param <T> the object type to be deserialized 241 * @param objectData 242 * the serialized object, must not be null 243 * @return the deserialized object 244 * @throws IllegalArgumentException 245 * if {@code objectData} is {@code null} 246 * @throws SerializationException 247 * (runtime) if the serialization fails 248 */ 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 SerializationUtils.<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}