Home » openjdk-7 » java » io » [javadoc | source]
static class: ObjectInputStream.HandleTable [javadoc | source]
Unsynchronized table which tracks wire handle to object mappings, as well as ClassNotFoundExceptions associated with deserialized objects. This class implements an exception-propagation algorithm for determining which objects should have ClassNotFoundExceptions associated with them, taking into account cycles and discontinuities (e.g., skipped fields) in the object graph.

General use of the table is as follows: during deserialization, a given object is first assigned a handle by calling the assign method. This method leaves the assigned handle in an "open" state, wherein dependencies on the exception status of other handles can be registered by calling the markDependency method, or an exception can be directly associated with the handle by calling markException. When a handle is tagged with an exception, the HandleTable assumes responsibility for propagating the exception to any other objects which depend (transitively) on the exception-tagged object.

Once all exception information/dependencies for the handle have been registered, the handle should be "closed" by calling the finish method on it. The act of finishing a handle allows the exception propagation algorithm to aggressively prune dependency links, lessening the performance/memory impact of exception tracking.

Note that the exception propagation algorithm used depends on handles being assigned/finished in LIFO order; however, for simplicity as well as memory conservation, it does not enforce this constraint.
Field Summary
 byte[] status    array mapping handle -> object status 
 Object[] entries    array mapping handle -> object/exception (depending on status) 
 HandleList[] deps    array mapping handle -> list of dependent handles (if any) 
 int lowDep    lowest unresolved dependency 
 int size    number of handles in table 
 HandleTable(int initialCapacity) 
Method from java.io.ObjectInputStream$HandleTable Summary:
assign,   clear,   finish,   lookupException,   lookupObject,   markDependency,   markException,   setObject,   size
Methods from java.lang.Object:
clone,   equals,   finalize,   getClass,   hashCode,   notify,   notifyAll,   toString,   wait,   wait,   wait
Method from java.io.ObjectInputStream$HandleTable Detail:
 int assign(Object obj) 
    Assigns next available handle to given object, and returns assigned handle. Once object has been completely deserialized (and all dependencies on other objects identified), the handle should be "closed" by passing it to finish().
  void clear() 
    Resets table to its initial state.
  void finish(int handle) 
    Marks given handle as finished, meaning that no new dependencies will be marked for handle. Calls to the assign and finish methods must occur in LIFO order.
 ClassNotFoundException lookupException(int handle) 
    Looks up and returns ClassNotFoundException associated with the given handle. Returns null if the given handle is NULL_HANDLE, or if there is no ClassNotFoundException associated with the handle.
 Object lookupObject(int handle) 
    Looks up and returns object associated with the given handle. Returns null if the given handle is NULL_HANDLE, or if it has an associated ClassNotFoundException.
  void markDependency(int dependent,
    int target) 
    Registers a dependency (in exception status) of one handle on another. The dependent handle must be "open" (i.e., assigned, but not finished yet). No action is taken if either dependent or target handle is NULL_HANDLE.
  void markException(int handle,
    ClassNotFoundException ex) 
    Associates a ClassNotFoundException (if one not already associated) with the currently active handle and propagates it to other referencing objects as appropriate. The specified handle must be "open" (i.e., assigned, but not finished yet).
  void setObject(int handle,
    Object obj) 
    Assigns a new object to the given handle. The object previously associated with the handle is forgotten. This method has no effect if the given handle already has an exception associated with it. This method may be called at any time after the handle is assigned.
 int size() 
    Returns number of handles registered in table.