org.openide.util.io
Class NbObjectInputStream

java.lang.Object
  extended by java.io.InputStream
      extended by java.io.ObjectInputStream
          extended by org.openide.util.io.NbObjectInputStream
All Implemented Interfaces:
java.io.Closeable, java.io.DataInput, java.io.ObjectInput, java.io.ObjectStreamConstants

public class NbObjectInputStream
extends java.io.ObjectInputStream

Controlled deserialization stream using the system class loader. Employs the classloader available from lookup (currently that used for modules). Also contains static methods to safely read objects that might have problems during deserialization that should not corrupt the stream. The stream also provides support for changing name of stored classes.

See Also:
readClassDescriptor()

Nested Class Summary
 
Nested classes/interfaces inherited from class java.io.ObjectInputStream
java.io.ObjectInputStream.GetField
 
Field Summary
 
Fields inherited from interface java.io.ObjectStreamConstants
baseWireHandle, PROTOCOL_VERSION_1, PROTOCOL_VERSION_2, SC_BLOCK_DATA, SC_ENUM, SC_EXTERNALIZABLE, SC_SERIALIZABLE, SC_WRITE_METHOD, STREAM_MAGIC, STREAM_VERSION, SUBCLASS_IMPLEMENTATION_PERMISSION, SUBSTITUTION_PERMISSION, TC_ARRAY, TC_BASE, TC_BLOCKDATA, TC_BLOCKDATALONG, TC_CLASS, TC_CLASSDESC, TC_ENDBLOCKDATA, TC_ENUM, TC_EXCEPTION, TC_LONGSTRING, TC_MAX, TC_NULL, TC_OBJECT, TC_PROXYCLASSDESC, TC_REFERENCE, TC_RESET, TC_STRING
 
Constructor Summary
NbObjectInputStream(java.io.InputStream is)
          Create a new object input.
 
Method Summary
protected  java.io.ObjectStreamClass readClassDescriptor()
          Provides a special handling for renaming of serialized classes.
static java.lang.Object readSafely(java.io.ObjectInput oi)
          Reads an object from the given object input.
protected  java.lang.Class resolveClass(java.io.ObjectStreamClass v)
           
static void skipSafely(java.io.ObjectInput oi)
          Skips an object from the given object input without loading it.
 
Methods inherited from class java.io.ObjectInputStream
available, close, defaultReadObject, enableResolveObject, read, read, readBoolean, readByte, readChar, readDouble, readFields, readFloat, readFully, readFully, readInt, readLine, readLong, readObject, readObjectOverride, readShort, readStreamHeader, readUnshared, readUnsignedByte, readUnsignedShort, readUTF, registerValidation, resolveObject, resolveProxyClass, skipBytes
 
Methods inherited from class java.io.InputStream
mark, markSupported, read, reset, skip
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 
Methods inherited from interface java.io.ObjectInput
read, skip
 

Constructor Detail

NbObjectInputStream

public NbObjectInputStream(java.io.InputStream is)
                    throws java.io.IOException
Create a new object input.

Parameters:
is - underlying input stream
Throws:
java.io.IOException - for the usual reasons
Method Detail

resolveClass

protected java.lang.Class resolveClass(java.io.ObjectStreamClass v)
                                throws java.io.IOException,
                                       java.lang.ClassNotFoundException
Overrides:
resolveClass in class java.io.ObjectInputStream
Throws:
java.io.IOException
java.lang.ClassNotFoundException

readClassDescriptor

protected java.io.ObjectStreamClass readClassDescriptor()
                                                 throws java.io.IOException,
                                                        java.lang.ClassNotFoundException
Provides a special handling for renaming of serialized classes.

Often, as the time goes the serialized classes evolve. They can be moved to new packages, renamed or changed (by a mistake) to not reflect the version of class stored in previous sessions.

This method deals with some of this incompatibilites and provides the module owners a way how to fix some of them.

When a class is read, the Utilities.translate is consulted to find out what whether the name of the class is listed there and what new value is assigned to it. This allows complete rename of the serialized class. For example: org.netbeans.core.NbMainExplorer can be renamed to org.netbeans.core.ui.NbExp - of course supposing that the new class is able to read the serialized fields of the old one.

Another useful feature of this method is the ability to supress wrong serialVersionUID. This was causing us a lot of problems, because people were forgetting to specify the serialVersionUID field in their sources and then it was hard to recover from it. Right now we have a solution: Just use Utilities.translate framework to assing your class org.yourpackage.YourClass the same name as it had e.g. org.yourpackage.YourClass. This will be interpreted by this method as a hit to suppress serialVersionUID and the NbObjectInputStream will ignore its value.

Please see Utilities.translate to learn how your module can provide list of classes that changed name or want to suppress serialVersionUID.

Overrides:
readClassDescriptor in class java.io.ObjectInputStream
Throws:
java.io.IOException
java.lang.ClassNotFoundException

readSafely

public static java.lang.Object readSafely(java.io.ObjectInput oi)
                                   throws java.io.IOException
Reads an object from the given object input. The object had to be saved by the NbObjectOutputStream.writeSafely(java.io.ObjectOutput, java.lang.Object) method.

Parameters:
oi - object input
Returns:
the read object
Throws:
java.io.IOException - if IO error occured
SafeException - if the operation failed but the stream is ok for further reading

skipSafely

public static void skipSafely(java.io.ObjectInput oi)
                       throws java.io.IOException
Skips an object from the given object input without loading it. The object had to be saved by the NbObjectOutputStream.writeSafely(java.io.ObjectOutput, java.lang.Object) method.

Parameters:
oi - object input
Throws:
java.io.IOException - if an I/O error occurred