| 目次 | 前の項目 | 次の項目 | Java オブジェクト直列化仕様 |
クラスの直列化状態を文書化して Serializable クラスのほかの実装と相互運用可能にすること、およびクラスの展開を文書化することは重要です。直列化可能フィールドが文書化されていれば、そのフィールドが直列化可能かどうかを最終的に確認することができます。ソースコード内の Serializable クラスの直列化形式を文書化する 1 つの方法は、javadoc の直列化タグ@serial、@serialField、および@serialDataを使うことです。
- デフォルトの直列化可能フィールドに対しては、
@serialタグを javadoc コメント内に配置する必要があります。構文は、@serialfield-description となります。オプションの field-description には、フィールドの意味および設定可能な値を記述します。field-description が複数の列に渡ることも可能です。初期のリリース後にフィールドを追加した場合は、追加したフィールドのバージョンを@sinceタグを使って示します。@serialの field-description では直列化仕様の文書が提供され、直列化形式の文書内でフィールドの javadoc コメントに追加されます。serialPersistentFields配列のObjectStreamFieldコンポーネントを文書化するには、@serialFieldタグを使います。各ObjectStreamFieldコンポーネントで、これらのタグのうちの 1 つを使う必要があります。構文は、@serialFieldfield-name field-type field-description となります。@serialDataタグを使って、書き込みまたは読み込みが行われるデータの順序および型を記述します。このタグで、writeObjectによって書き込まれた任意指定のデータ、またはExternalizable.writeExternalメソッドによって書き込まれたすべてのデータの順序と型を記述します。構文は、@serialDatadata-description となります。
javadoc アプリケーションは、javadoc の直列化タグを認識し、各 Serializable クラスおよび Externalizable クラスの仕様を生成します。これらのタグを使った例については、「C.1 java.io.File 代替実装の例」を参照してください。クラスを Serializable として宣言した場合、オブジェクトの直列化可能状態は、直列化可能フィールド (名前と型による) に加え、任意指定のデータによって定義されます。任意指定のデータは、
SerializableクラスのwriteObjectメソッドによってのみ書き込まれます。任意指定のデータは、SerializableクラスのreadObjectによって読み込まれるか、または直列化では読み込まれずにスキップされます。クラスを Externalizable として宣言した場合、クラス自体によってストリームに書き込まれたデータが直列化状態を定義します。クラスは、ストリームに書き込まれる各データの順番、型、および意味を指定する必要があります。クラスは、以前のバージョンで書き込まれたデータを引き続き読み込めるようにし、以前のバージョンで読み込まれたデータを書き込めるようにするために、自らの展開を処理する必要があります。クラスは、データの保存および復元時には、スーパークラスと協調動作しなければなりません。ストリーム内のスーパークラスのデータ位置を指定する必要があります。
直列化可能クラスの設計者は、そのクラスに保存される情報が持続性に適し、直列化特有の展開および相互運用性の規則に従っていることを保証する必要があります。クラスの展開の詳細については、第 5 章「直列化可能オブジェクトのバージョン管理」を参照してください。