com.webobjects.foundation
Class NSCoder

java.lang.Object
  |
  +--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, 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

decodeBoolean

public abstract boolean decodeBoolean()

Decodes a boolean value that was previously encoded with encodeBoolean.

Returns:

the decoded boolean value

See Also:

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:

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:

encodeBytes(byte[])

decodeChar

public abstract char decodeChar()

Decodes a character value that was previously encoded with encodeChar.

Returns:

the decoded character value

See Also:

encodeChar(char aChar)

decodeClass

public abstract Class decodeClass()

Decodes a class that was previously encoded with encodeClass.

Returns:

the decoded class

See Also:

encodeClass(Class aClass)

decodeDouble

public abstract double decodeDouble()

Decodes a double value that was previously encoded with encodeDouble.

Returns:

the decoded double value

See Also:

encodeDouble(double aDouble)

decodeFloat

public abstract float decodeFloat()

Decodes a float value that was previously encoded with encodeFloat.

Returns:

the decoded float value

See Also:

encodeFloat(float aFloat)

decodeInt

public abstract int decodeInt()

Decodes an integer value that was previously encoded with encodeInt.

Returns:

the decoded integer value

See Also:

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:

encodeLong(long aLong)

decodeObject

public abstract Object decodeObject()

Decodes an object that was previously encoded with encodeObject.

Returns:

the decoded object

See Also:

encodeObject(Object object)

decodeObjects

public abstract Object[] decodeObjects()

Decodes an array of objects that were previously encoded with encodeObjects.

Returns:

the decoded array of objects

See Also:

encodeObjects(Object[] objects)

decodeShort

public abstract short decodeShort()

Decodes a short value that was previously encoded with encodeShort.

Returns:

the decoded short value

See Also:

encodeShort(short aShort)

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:

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:

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:

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:

decodeChar()

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:

decodeClass()

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:

decodeDouble()

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:

decodeFloat()

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:

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:

decodeLong()

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:

decodeObject()

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:

decodeObjects()

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:

decodeShort()

finishCoding

public void finishCoding()

Cleans up the receiver's state after the receiver has finished encoding data. NSCoder's default implementation does nothing.

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

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