WebObjects 5.4.2

com.webobjects.foundation
Class NSCoder

java.lang.Object
  extended by com.webobjects.foundation.NSCoder

public abstract class NSCoder
extends Object

NSCoder is an abstract class that declares the API used by concrete subclasses to transfer objects and other data items between memory and some other format. This capability provides the basis for archiving (where objects and data items are stored on disk) and distribution (where objects and data items are copied between different processes or threads).

You should never need to subclass NSCoder. Rather, WebObjects provides private concrete subclasses that it uses by default. However, you might interact with a coder object if you create a class that implements the NSCoding interface.

NSCoder operates on scalars (booleans, bytes, and integers, for example), and any other types of object. A coder object stores object type information along with an object's data, so an object decoded from a stream of bytes is normally of the same class as the object that was originally encoded into the stream.

Encoding and Decoding Objects and Scalar Values

To encode or decode an object or a scalar value, you must first create a coder object, then send it a message defined by NSCoder or by a concrete subclass to actually encode or decode the item. NSCoder itself defines no particular method for creating a coder; this typically varies with the subclass.

To encode an object or data item, use any of the encode... methods. To decode an object or data item, simply use the decode... method corresponding to the original encode... method. Matching these is important, as the method originally used determines the format of the encoded data.

NSCoder's interface is quite general. Concrete subclasses aren't required to properly implement all of NSCoder's methods, and may explicitly restrict themselves to certain types of operations.

Managing Object Graphs

Objects frequently contain references to other objects, which may in turn contain references to other objects. When analyzed, a group of objects may contain circular references or one object may be referred to by several other objects. In these cases, the objects form an object graph and require special handling to preserve the graph structure. NSCoder's encodeObject method preserves the graph structure.

See Also:
NSCoding, NSCoder.encodeObject(Object object)

Constructor Summary
NSCoder()
           
 
Method Summary
abstract  boolean decodeBoolean()
          Decodes a boolean value that was previously encoded with encodeBoolean.
abstract  byte decodeByte()
          Decodes a byte value that was previously encoded with encodeByte.
abstract  byte[] decodeBytes()
          Decodes an array of byte values that were previously encoded with encodeBytes.
abstract  char decodeChar()
          Decodes a character value that was previously encoded with encodeChar.
abstract  Class decodeClass()
          Decodes a class that was previously encoded with encodeClass.
abstract  double decodeDouble()
          Decodes a double value that was previously encoded with encodeDouble.
abstract  float decodeFloat()
          Decodes a float value that was previously encoded with encodeFloat.
abstract  int decodeInt()
          Decodes an integer value that was previously encoded with encodeInt.
abstract  long decodeLong()
          Decodes a long value that was previously encoded with encodeLong.
abstract  Object decodeObject()
          Decodes an object that was previously encoded with encodeObject.
abstract  Object[] decodeObjects()
          Decodes an array of objects that were previously encoded with encodeObjects.
abstract  short decodeShort()
          Decodes a short value that was previously encoded with encodeShort.
abstract  void encodeBoolean(boolean aBoolean)
          Encodes a boolean value.
abstract  void encodeByte(byte aByte)
          Encodes a byte value.
abstract  void encodeBytes(byte[] bytes)
          Encodes an array of bytes.
abstract  void encodeChar(char aChar)
          Encodes a character value.
abstract  void encodeClass(Class aClass)
          Encodes a class.
abstract  void encodeDouble(double aDouble)
          Encodes a double value.
abstract  void encodeFloat(float aFloat)
          Encodes a float value.
abstract  void encodeInt(int anInt)
          Encodes an integer value.
abstract  void encodeLong(long aLong)
          Encodes a long value.
abstract  void encodeObject(Object object)
          Encodes an object.
abstract  void encodeObjects(Object[] objects)
          Encodes an array of objects.
abstract  void encodeShort(short aShort)
          Encodes a short value.
 void finishCoding()
          Cleans up the receiver's state after the receiver has finished encoding data.
 void prepareForReading(InputStream stream)
          Prepares the receiver for reading data from stream.
 void prepareForWriting(OutputStream stream)
          Prepares the receiver for writing to stream.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

NSCoder

public NSCoder()
Method Detail

encodeBoolean

public abstract void encodeBoolean(boolean aBoolean)
Encodes a boolean value. To decode a value encoded with this method, use decodeBoolean.

Parameters:
aBoolean - the boolean value to be encoded
See Also:
NSCoder.decodeBoolean()

encodeByte

public abstract void encodeByte(byte aByte)
Encodes a byte value. To decode a value encoded with this method, use decodeByte.

Parameters:
aByte - the byte value to be encoded
See Also:
NSCoder.decodeByte()

encodeBytes

public abstract void encodeBytes(byte[] bytes)
Encodes an array of bytes. To decode a value encoded with this method, use decodeBytes.

Parameters:
bytes - the byte array to be encoded
See Also:
NSCoder.decodeBytes()

encodeChar

public abstract void encodeChar(char aChar)
Encodes a character value. To decode a value encoded with this method, use decodeChar.

Parameters:
aChar - the character value to be encoded
See Also:
NSCoder.decodeChar()

encodeShort

public abstract void encodeShort(short aShort)
Encodes a short value. To decode a value encoded with this method, use decodeShort.

Parameters:
aShort - the short value to be encoded
See Also:
NSCoder.decodeShort()

encodeInt

public abstract void encodeInt(int anInt)
Encodes an integer value. To decode a value encoded with this method, use decodeInt.

Parameters:
anInt - the integer value to be encoded
See Also:
NSCoder.decodeInt()

encodeLong

public abstract void encodeLong(long aLong)
Encodes a long value. To decode a value encoded with this method, use decodeLong.

Parameters:
aLong - the long value to be encoded
See Also:
NSCoder.decodeLong()

encodeFloat

public abstract void encodeFloat(float aFloat)
Encodes a float value. To decode a value encoded with this method, use decodeFloat.

Parameters:
aFloat - the float value to be encoded
See Also:
NSCoder.decodeFloat()

encodeDouble

public abstract void encodeDouble(double aDouble)
Encodes a double value. To decode a value encoded with this method, use decodeDouble.

Parameters:
aDouble - the double value to be encoded
See Also:
NSCoder.decodeDouble()

encodeObject

public abstract void encodeObject(Object object)
Encodes an object. To decode a value encoded with this method, use decodeObject.

Parameters:
object - the object to be encoded
See Also:
NSCoder.decodeObject()

encodeClass

public abstract void encodeClass(Class aClass)
Encodes a class. To decode a value encoded with this method, use decodeClass.

Parameters:
aClass - the class to be encoded
See Also:
NSCoder.decodeClass()

encodeObjects

public abstract void encodeObjects(Object[] objects)
Encodes an array of objects. To decode a value encoded with this method, use decodeObjects.

Parameters:
objects - the object array to be encoded
See Also:
NSCoder.decodeObjects()

decodeBoolean

public abstract boolean decodeBoolean()
Decodes a boolean value that was previously encoded with encodeBoolean.

Returns:
the decoded boolean value
See Also:
NSCoder.encodeBoolean(boolean aBoolean)

decodeByte

public abstract byte decodeByte()
Decodes a byte value that was previously encoded with encodeByte.

Returns:
the decoded byte value
See Also:
NSCoder.encodeByte(byte aByte)

decodeBytes

public abstract byte[] decodeBytes()
Decodes an array of byte values that were previously encoded with encodeBytes.

Returns:
the decoded byte array
See Also:
NSCoder.encodeBytes(byte[])

decodeChar

public abstract char decodeChar()
Decodes a character value that was previously encoded with encodeChar.

Returns:
the decoded character value
See Also:
NSCoder.encodeChar(char aChar)

decodeShort

public abstract short decodeShort()
Decodes a short value that was previously encoded with encodeShort.

Returns:
the decoded short value
See Also:
NSCoder.encodeShort(short aShort)

decodeInt

public abstract int decodeInt()
Decodes an integer value that was previously encoded with encodeInt.

Returns:
the decoded integer value
See Also:
NSCoder.encodeInt(int anInt)

decodeLong

public abstract long decodeLong()
Decodes a long value that was previously encoded with encodeLong.

Returns:
the decoded long value
See Also:
NSCoder.encodeLong(long aLong)

decodeFloat

public abstract float decodeFloat()
Decodes a float value that was previously encoded with encodeFloat.

Returns:
the decoded float value
See Also:
NSCoder.encodeFloat(float aFloat)

decodeDouble

public abstract double decodeDouble()
Decodes a double value that was previously encoded with encodeDouble.

Returns:
the decoded double value
See Also:
NSCoder.encodeDouble(double aDouble)

decodeObject

public abstract Object decodeObject()
Decodes an object that was previously encoded with encodeObject.

Returns:
the decoded object
See Also:
NSCoder.encodeObject(Object object)

decodeClass

public abstract Class decodeClass()
Decodes a class that was previously encoded with encodeClass.

Returns:
the decoded class
See Also:
NSCoder.encodeClass(Class aClass)

decodeObjects

public abstract Object[] decodeObjects()
Decodes an array of objects that were previously encoded with encodeObjects.

Returns:
the decoded array of objects
See Also:
NSCoder.encodeObjects(Object[] objects)

prepareForWriting

public void prepareForWriting(OutputStream stream)
Prepares the receiver for writing to stream. NSCoder's default implementation does nothing.

Parameters:
stream - the OutputStream to write to

prepareForReading

public void prepareForReading(InputStream stream)
Prepares the receiver for reading data from stream. NSCoder's default implementation does nothing.

Parameters:
stream - the InputStream to read from

finishCoding

public void finishCoding()
Cleans up the receiver's state after the receiver has finished encoding data. NSCoder's default implementation does nothing.


Last updated June 2008

Copyright © 2000-2008 Apple Inc.