オブジェクト出力クラス

トピック:

• ObjectOutputStreamクラス
• ObjectOutputStream.PutFieldクラス
• writeObjectメソッド
• writeExternalメソッド
• writeReplaceメソッド
• useProtocolVersionメソッド

2.1 ObjectOutputStreamクラス

package java.io;

public class ObjectOutputStream
    extends OutputStream
    implements ObjectOutput, ObjectStreamConstants
{
    public ObjectOutputStream(OutputStream out)
        throws IOException;

    public final void writeObject(Object obj)
        throws IOException;

    public void writeUnshared(Object obj)
        throws IOException;

    public void defaultWriteObject()
        throws IOException, NotActiveException;

    public PutField putFields()
        throws IOException;

    public writeFields()
        throws IOException;

    public void reset() throws IOException;

    protected void annotateClass(Class cl) throws IOException;

    protected void writeClassDescriptor(ObjectStreamClass desc)
        throws IOException;

    protected Object replaceObject(Object obj) throws IOException;

    protected boolean enableReplaceObject(boolean enable)
        throws SecurityException;

    protected void writeStreamHeader() throws IOException;

    public void write(int data) throws IOException;

    public void write(byte b[]) throws IOException;

    public void write(byte b[], int off, int len) throws IOException;

    public void flush() throws IOException;

    protected void drain() throws IOException;

    public void close() throws IOException;

    public void writeBoolean(boolean data) throws IOException;

    public void writeByte(int data) throws IOException;

    public void writeShort(int data) throws IOException;

    public void writeChar(int data) throws IOException;

    public void writeInt(int data) throws IOException;

    public void writeLong(long data) throws IOException;

    public void writeFloat(float data) throws IOException;

    public void writeDouble(double data) throws IOException;

    public void writeBytes(String data) throws IOException;

    public void writeChars(String data) throws IOException;

    public void writeUTF(String data) throws IOException;

    // Inner class to provide access to serializable fields.
    abstract static public class PutField
    {
        public void put(String name, boolean value)
            throws IOException, IllegalArgumentException;

        public void put(String name, char data)
            throws IOException, IllegalArgumentException;

        public void put(String name, byte data)
            throws IOException, IllegalArgumentException;

        public void put(String name, short data)
            throws IOException, IllegalArgumentException;

        public void put(String name, int data)
            throws IOException, IllegalArgumentException;

        public void put(String name, long data)
            throws IOException, IllegalArgumentException;

        public void put(String name, float data)
            throws IOException, IllegalArgumentException;

        public void put(String name, double data)
            throws IOException, IllegalArgumentException;

        public void put(String name, Object data)
            throws IOException, IllegalArgumentException;
    }

    public void useProtocolVersion(int version) throws IOException;

    protected ObjectOutputStream()
        throws IOException;

     protected writeObjectOverride()
        throws NotActiveException, IOException;
}

writeObjectメソッドは、オブジェクトをストリームに直列化するために使用します。オブジェクトは、次のように直列化されます。

例外は、トラバーサル中に発生する場合も、基になるストリーム内で発生する場合もあります。IOExceptionのサブクラスの場合、例外プロトコルを使って例外がストリームに書き込まれ、ストリーム状態が破棄されます。最初の例外をストリームに書き込んでいる間に2番目のIOExceptionがスローされた場合、ストリームは不明状態のままになり、writeObjectからStreamCorruptedExceptionがスローされます。その他の例外の場合、ストリームは中止され、不明で使用不能な状態のままになります。

• writeUnsharedを使用して書き込まれたオブジェクトは、そのオブジェクトが以前に書き込まれているかどうかにかかわらず、常に新しく出現するオブジェクト(ストリームにまだ書き込まれたことがないオブジェクト)として同じ方法で直列化されます。
• writeUnsharedによって以前に書き込まれたオブジェクトを書き込む際にwriteObjectを使用すると、以前のwriteUnshared操作は、別のオブジェクトの書き込みとして扱われます。つまり、ObjectOutputStreamは、writeUnshared呼出しによって書き込まれたオブジェクト・データへの逆参照を生成しません。

defaultWriteObjectメソッドは、現在のクラスに対するデフォルト直列化メカニズムを実装します。このメソッドの呼出しは、クラスのwriteObjectメソッドからのみ可能です。このメソッドは、現在のクラスのすべての直列化可能フィールドをストリームに書き込みます。writeObjectメソッドの外部からこのメソッドが呼び出されると、NotActiveExceptionがスローされます。

putFieldsメソッドは、ストリーム内の直列化可能フィールドの値を設定する際に呼出し側が使用するPutFieldオブジェクトを返します。フィールドは、任意の順序で設定できます。すべてのフィールドの設定が完了したら、writeFieldsを呼び出して、フィールド値を正規の順序でストリームに書き込む必要があります。フィールドが設定されていない場合、その型に適したデフォルト値がストリームに書き込まれます。このメソッドは、直列化可能クラスのwriteObjectメソッド内からしか呼び出すことができません。また、このメソッドは、1回しか呼び出すことができず、defaultWriteObjectがすでに呼び出されている場合は呼び出せません。writeFieldsを呼び出したあとでないと、ほかのデータをストリームに書き込むことはできません。

resetメソッドは、ストリーム状態をリセットして、構築時の状態に戻します。Resetは、すでにストリームに書き込まれたオブジェクトの状態を破棄します。ストリーム内の現在位置にリセットのマークが付けられるので、対応するObjectInputStreamも同じ位置でリセットされます。以前にストリームに書き込まれたオブジェクトが、ストリームに書込み済みのオブジェクトとして記憶されることはありません。これらのオブジェクトは、ストリームに再度書き込まれます。これは、オブジェクトの内容やオブジェクトを再送信しなければいけない場合に有用です。Resetは、オブジェクトの直列化中は呼び出されない場合もあります。不正に呼び出されると、IOExceptionがスローされます。

Java 2 SDK, Standard Edition, v1.3から、ObjectStreamClassの直列化が必要になると、writeClassDescriptorメソッドが呼び出されるようになりました。writeClassDescriptorは、ObjectStreamClass表現の直列化ストリームへの書込みを担当します。サブクラスでこのメソッドをオーバーライドすることにより、クラス記述子の直列化ストリームへの書込み方法をカスタマイズできます。このメソッドをオーバーライドする場合は、ObjectInputStream内の対応するreadClassDescriptorメソッドもオーバーライドして、カスタム・ストリーム表現からクラス記述子を再構成することをお薦めします。デフォルトでは、writeClassDescriptorは、6.4項「ストリーム形式の文法」で指定された形式に従ってクラス記述子を書き込みます。このメソッドは、ObjectOutputStreamが古い直列化ストリーム形式を使用していない場合にのみ、呼出し可能です(6.3項「ストリーム・プロトコル・バージョン」を参照)。この直列化ストリームが古い形式(ObjectStreamConstants.PROTOCOL_VERSION_1)を使用している場合、クラス記述子はオーバーライドまたはカスタマイズが不可能な方法で内部的に書き込まれます。

Classの直列化中、かつクラス記述子のストリームへの書込み後に、annotateClassメソッドが呼び出されます。サブクラスがこのメソッドを継承して、クラスに関するほかの情報をストリームに書き込むことも可能です。この情報の読取りは、対応するObjectInputStreamサブクラスのresolveClassメソッドを使って実行する必要があります。

ObjectOutputStreamサブクラスは、replaceObjectメソッドを実装することにより、直列化中にオブジェクトの監視および置換を実行できます。最初の置換対象オブジェクトに対してwriteObjectを呼び出す前に、enableReplaceObjectを呼び出して、置換を明示的に有効にする必要があります。オブジェクトの置換が有効にされたあと、オブジェクトをはじめて直列化する直前に、各オブジェクトに対してreplaceObjectが呼び出されます。replaceObjectメソッドは、特別に処理されるクラスであるClassおよびObjectStreamClassのオブジェクトに対しては呼び出されません。サブクラスの実装が、元のオブジェクトではなく直列化される代替オブジェクトを返す場合があります。代替オブジェクトは、直列化可能でなければいけません。ストリームにおける元のオブジェクトへのすべての参照は、置換オブジェクトによって置き換えられます。

サブクラスはオブジェクトが置換されているときに、置換されるオブジェクトが参照を保存するすべてのフィールドと互換性が持つこと、つまり直列化復元時に補完的な置換が行われることを保証する必要があります。型がフィールドまたは配列要素の型のサブクラスでないオブジェクトは、あとでClassCastExceptionをスローして直列化復元を中止することになり、参照は保存されません。

enableReplaceObjectメソッドは、直列化の際にあるオブジェクトを別のオブジェクトで置換するために、ObjectOutputStreamの信頼できるサブクラスで呼び出すことができます。オブジェクトの置換は、enableReplaceObjectがtrue値で呼び出されるまでは、無効になっています。それ以降は、falseに設定することで無効にできます。前の設定が返されます。enableReplaceObjectメソッドは、置換を要求するストリームを信頼できるかどうかを調べます。オブジェクトのprivate状態が意図せずに公開されないことを保証するために、信頼できるストリーム・サブクラスだけがreplaceObjectを使用できます。信頼されるクラスとは、Serializable置換を有効にする権限を保持する、セキュリティ保護ドメインに属するクラスのことです。

ObjectOutputStreamのサブクラスがシステム・ドメインの一部とはみなされない場合、SerializablePermission "enableSubstitution"をセキュリティ・ポリシー・ファイルに追加する必要があります。ObjectInputStreamのサブクラスの保護ドメインに、enableReplaceObject呼出しによる"enableSubstitution"の権限がない場合は、AccessControlExceptionがスローされます。セキュリティ・モデルの詳細は、Javaセキュリティ・アーキテクチャ(JDK1.2)のドキュメントを参照してください。

writeStreamHeaderメソッドは、マジック番号とバージョンをストリームに書き込みます。この情報は、ObjectInputStreamのreadStreamHeaderメソッドを使って読み取る必要があります。ストリームの一意形式を識別するために、サブクラスがこのメソッドを実装することが必要な場合があります。

flushメソッドは、ストリームが保持するバッファを空にして基になるストリームにフラッシュを転送するために、使用されます。基になるストリームのフラッシュを強制せずにObjectOutputStreamのバッファだけを空にするために、サブクラスからdrainメソッドを使用できます。

プリミティブ型用のすべてのwriteメソッドは、DataOutputStreamを使って値をエンコードして、標準ストリーム形式にします。バイトがブロック・データ・レコードにバッファリングされることにより、オブジェクトのエンコーディングとの区別が可能になります。このバッファリングにより、クラスのバージョン管理が必要な場合、プリミティブ・データのスキップも可能になります。また、クラス固有のメソッドを呼び出すことなく、ストリームの構文解析を行うことも可能になります。

直列化の実装をオーバーライドするときは、ObjectOutputStreamのサブクラスは引数なしのprotected ObjectOutputStreamコンストラクタを呼び出すことをお勧めします。SerializablePermission "enableSubclassImplementation"用の引数なしコンストラクタ内では、信頼できるクラスだけがデフォルト実装のオーバーライドを許可されるようにセキュリティ・チェックがあります。このコンストラクタは、ObjectOutputStreamにprivateなデータを割り当てず、final writeObjectメソッドがwriteObjectOverrideメソッドを呼び出してから復帰するべきことを示すフラグを設定します。ほかのすべてのObjectOutputStreamメソッドは、finalではないので、サブクラスによって直接オーバーライドできます。

2.2 ObjectOutputStream.PutFieldクラス

クラスPutFieldは、あるクラスがデフォルト直列化を使わない場合に、そのクラスの直列化可能フィールドの値を設定するためのAPIを提供します。各メソッドは、指定された名前付き値をストリームに置きます。nameが、フィールドが書き込まれているクラスの直列化可能フィールドの名前と一致しない場合、または指定されたフィールドの型が、呼び出された特定のputメソッドの2番目のパラメータの型と一致しない場合、IllegalArgumentExceptionがスローされます。

2.3 writeObjectメソッド

    private void writeObject(ObjectOutputStream stream)
        throws IOException;

クラスのwriteObjectメソッドには、実装されている場合、クラスの状態を保存する責任があります。ObjectOutputStreamのdefaultWriteObjectメソッドまたはwriteFieldsメソッドを一度(一度のみ)呼び出してからでないと、対応するreadObjectメソッドがオブジェクトの状態を復元するために必要なオプション・データを書き込むことはできません。オプション・データを書き込まない場合でも、defaultWriteObjectまたはwriteFieldsを一度呼び出す必要があります。オプション・データ(ある場合)の書込みの前にdefaultWriteObjectかwriteFieldsが呼び出されなければ、ObjectInputStreamがそのwriteObjectメソッドを定義したクラスを解決できない場合に、インスタンス直列化復元の動作は未定義になります。

オプション・データの形式、構造体、バージョン管理の責任は、完全にクラスにあります。

2.4 writeExternalメソッド

    public void writeExternal(ObjectOutput stream)
        throws IOException;

JDK 1.2で、Externalizableデータを書き込むための新しいデフォルト形式が導入されました。新しい形式は、プリミティブ・データがwriteExternalメソッドによってブロック・データ・モードで書き込まれるように指定します。さらに、writeExternalメソッドから戻ったあとに、外部オブジェクトの末尾を示すタグがストリームに付加されます。この形式変更の利点については、セクション3.6「readExternalメソッド」を参照してください。この変更により生じる互換性の問題の詳細は、セクション2.6「useProtocolVersionメソッド」を参照してください。

2.5 writeReplaceメソッド

このメソッドは、次のように定義されます。

   ANY-ACCESS-MODIFIER Object writeReplace() {
                 throws ObjectStreamException;

ObjectOutputStreamがストリームにオブジェクトを書き込む準備をしているとき、writeReplaceメソッドが呼び出されます。ObjectOutputStreamは、クラスがwriteReplaceメソッドを定義しているかどうかをチェックします。このメソッドが定義されている場合は、オブジェクトがストリーム内で置換を指定することを許可するためにwriteReplaceメソッドが呼び出されます。返されるオブジェクトは、渡されるオブジェクトと同じ型であるか、または読み込まれて解釈されたオブジェクトが、オブジェクトへのすべての参照と互換性を持つ型のオブジェクトであるべきです。そうでない場合、型の不一致が検出されたときに、ClassCastExceptionが発生します。

2.6 useProtocolVersionメソッド

ストリーム・プロトコル・バージョンについては、セクション6.3「ストリーム・プロトコル・バージョン」を参照してください。