オブジェクト出力クラス

トピック:

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

2.1 ObjectOutputStream クラス

クラス 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;
}

単一引数の ObjectOutputStream コンストラクタは、指定された OutputStream にオブジェクトを直列化する ObjectOutputStream を作成します。このコンストラクタは、writeStreamHeader を呼び出して、マジック番号とバージョンをストリームに書き込みます。そして、このストリームは、単一引数の ObjectInputStream コンストラクタの対応する readStreamHeader を呼び出すことによって読み込まれ、検査されます。セキュリティーマネージャーがインストールされている場合、このコンストラクタは、putFields メソッドまたは writeUnshared メソッド、あるいはその両方をオーバーライドするサブクラスのコンストラクタによって直接または間接的に呼び出されたときに、"enableSubclassImplementation" SerializablePermission のチェックを行います。

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

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

writeUnshared メソッドは、「非共有」オブジェクトを ObjectOutputStream に書き込みます。このメソッドは、指定されたオブジェクトを常に新しい一意のオブジェクトとしてストリームに書き込む (以前に直列化されたインスタンスへのバック参照とは対照的) 点を除いては、writeObject と同じです。具体的には、次のようになります。

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

writeUnshared を介してオブジェクトを書き込むこと自体は、オブジェクトが直列化復元されたときにそのオブジェクトへの一意参照を保証するものではありませんが、1 つのオブジェクトがストリーム内で複数回定義されることは可能になります。そのため、受け取り側が ObjectInputStream.readUnshared メソッド (「3.1 ObjectInputStream クラス」を参照) を複数回呼び出しても衝突が生じません。ここで説明した規則は、writeUnshared によって書き込まれた基本レベルのオブジェクトだけに適用され、直列化されるオブジェクトのグラフ内で一時的に参照されるサブオブジェクトには一切適用されません。

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

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

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

Java^TM 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^TM セキュリティーアーキテクチャー (JDK1.2) のドキュメントを参照してください。

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

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

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

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

2.2 ObjectOutputStream.PutField クラス

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

2.3 writeObject メソッド

Serializable オブジェクトの場合、writeObject メソッドによって、クラスがそれ自身のフィールドの直列化を制御することができます。そのシグニチャーを次に示します。

    private void writeObject(ObjectOutputStream stream)
        throws IOException;

Serializable オブジェクトの各サブクラスは、自らの writeObject メソッドを定義することができます。クラスにこのメソッドが実装されていなければ、defaultWriteObject によって与えられるデフォルトの直列化が使用されます。実装されている場合は、そのクラスは、そのスーパータイプやサブタイプのフィールドではなく、それ独自のフィールドだけを書き込む責任があります。

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

この任意指定データの形式、構造体、バージョン管理の責任のすべては、そのクラスにあります。

2.4 writeExternal メソッド

java.io.Externalizable を実装するオブジェクトは、writeExternal メソッドを実装して、そのオブジェクトの状態全体を保存する必要があります。このオブジェクトは、そのスーパークラスと協調して、それらの状態を保管しなければなりません。ObjectOutput のすべてのメソッドが、オブジェクトのプリミティブ型フィールドとオブジェクトフィールドを保管するために使用できます。

    public void writeExternal(ObjectOutput stream)
        throws IOException;

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

2.5 writeReplace メソッド

Serializable および Externalizable クラスの場合には、writeReplace メソッドは、オブジェクトが書き込まれる前に、オブジェクトのクラスがストリーム内で自らの置換を指定することを許可します。writeReplace メソッドを実装することにより、クラスは、直列化されている自らのインスタンスの型およびインスタンスを直接制御できます。

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

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

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

2.6 useProtocolVersion メソッド

下位互換性のないストリームプロトコルへの変更のため、現在の仮想マシンでは、以前のリリースが読み取り可能な直列化ストリームを書き込むことができる機構が追加されました。ただし、下位互換性のあるプロトコルを使う場合は、新しいストリーム形式では修正されている問題が発生する可能性があります。

ストリームプロトコルのバージョンについては、「6.3 ストリームプロトコルのバージョン」で説明します。