Главная » Java » Тэги документирования сериализуемых данных в Java

0

 

  Как можно было убедиться на примере класса Rectangle, форма представления объекта класса в процессе сериализации не менее важна, нежели та, которую объект принимает во время выполнения программы, и первая, вообще говоря, может отличаться от второй либо ввиду эволюции класса, либо в соответствии с исходным проектным замыслом. При создании класса, поддерживающего механизм сериализации и подлежащего наследованию, необходимо добротно документировать обе формы объекта, чтобы программист, которому придется развивать ваше решение, смог верно реализовать как механизм сериализации полей класса, так и характеристики его поведения на этапе выполнения программы. С этой целью применяются специальные тэги документирования— @serial, @serialField и @serialData.

  Тэг @serial используется для документирования полей, сериализация которых выполняется в соответствии со схемой, принятой по умолчанию. Фрагмент текста класса Rectangle, снабженного комментариями документирования с участием тэгов ©serial, может выглядеть следующим образом:

/**  координата х одной вершины.

 *            @serial   */

private double xl;

/**  координата Y одной вершины.

 *            @serial   */

private double yl;

/’"""  координата х противоположной вершины.

 *            @serial   */

private double x2;

/** Координата Y противоположной вершины.

 *            @serial   */

private double y2;

Тэг @serial может включать описание назначения поля. Если такое описание не задано (как в примере), используется комментарий, относящийся к версии поля периода выполнения программы.

  Тэг @serial Field служит для документирования полей, обрабатываемых средствами объектов GetField и PutField. В начало тэга включается наименование поля, за которым следуют его тип и описание. В контексте нашего примера такие тэги могли бы выглядеть следующим образом:

 

/** ©serialField xl double Координата х одной вершины. */

 /** ©serialField yl double Координата Y одной вершины. */

/** ©serialField x2  double  Координата X противоположной  вершины.

/** ©serialField y2  double  Координата Y противоположной  вершины.

transient  private  double  x,   у;

 transient  private double width,   height;

 

   Тэг @serialData используется для документирования любых дополнитель ных данных, сохраняемых методом writeObject либо методом writeExternal объекта класса, реализующего интерфейс External i zable.

 

Источник: Арнолд, Кен, Гослинг, Джеймс, Холмс, Дэвид. Язык программирования Java. 3-е изд .. : Пер. с англ. – М. : Издательский дом «Вильяме», 2001. – 624 с. : ил. – Парал. тит. англ.

По теме:

  • Комментарии