Package com.emc.documentum.rest.binding

# Annotation Interface SerializableField

@Target(FIELD) @Retention(RUNTIME) public @interface SerializableField
The annotation defined on a Java class field for marshalling and unmarshalling. Class field with this annotation is marked as serializable. This annotation is used only on fields of a class that is annotated with `SerializableType`.

- ## Nested Class Summary

  Nested Classes
  Modifier and Type
  Class
  Description
  `static final class`
  `SerializableField.DEFAULT`
  It is only for default value of `defaultImpl()`

- ## Optional Element Summary

  Optional Elements
  Modifier and Type
  Optional Element
  Description
  `Class`
  `defaultImpl`
  Specifies the default implementation class of the field.
  `Class<? extends AnnotatedFieldDeserializer>[]`
  `deserializers`
  Specified the customized deserializer for serializable field.
  `boolean`
  `override`
  Specifies whether to override the representation of parent's field with same serializable name.
  For example, PersistentObject has a field with serializable name "properties", which is a list of type Attribute.
  `boolean`
  `required`
  Specifies whether the field is required to be non-null for marshalling; if the field is required but its value is null, an exception should be thrown during marshalling.
  `Class<? extends AnnotatedFieldSerializer>[]`
  `serializers`
  Specifies the customized serializer for serializable field.
  `String`
  `value`
  Specifies the serializable name for the field.
  If `value()` is not specified, fieldLocalName(the name of this Java class field ) will be used as value.
  If `xmlWriteTypeRoot()` is enabled for a complex type, it will use `SerializableType.value()` of the complex type instead of `value()`.
  The characters of the name must comply with the name rules of specific formats; since one annotation could be used by multiple format marshalling, its recommended to use the simplest range of characters to define the name.
  `boolean`
  `xmlAsAttribute`
  Specifies whether the field is to be marshalled/unmarshalled as/from an XML attribute or XML element.
  `String`
  `xmlListItemName`
  Deprecated.
  Use `SerializableField4XmlList.itemName()`.
  `boolean`
  `xmlListUnwrap`
  Deprecated.
  Use `SerializableField4XmlList.unwrap()`.
  `String`
  `xmlNS`
  Specifies the prefix name for the XML namespace URI.
  `String`
  `xmlNSPrefix`
  Specifies the prefix name for the XML namespace.
  `boolean`
  `xmlPreserveSpace`
  Specifies whether the annotated XML element should be marked with XML attribute "xml:space=preserved".
  `boolean`
  `xmlWriteTypeRoot`
  Specifies whether to write `SerializableType.value()` of the field data type instead of `value()` of the field as the XML element name for this field.

- ## Element Details

  - ### value

    String value
    Specifies the serializable name for the field.
    If `value()` is not specified, fieldLocalName(the name of this Java class field ) will be used as value.
    If `xmlWriteTypeRoot()` is enabled for a complex type, it will use `SerializableType.value()` of the complex type instead of `value()`.
    The characters of the name must comply with the name rules of specific formats; since one annotation could be used by multiple format marshalling, its recommended to use the simplest range of characters to define the name. Please check the format specific specifications for the name rules.
    Returns:
      the serialized name
    Default:
      ""

  - ### required

    boolean required
    Specifies whether the field is required to be non-null for marshalling; if the field is required but its value is null, an exception should be thrown during marshalling.
    Returns:
      `true` if the field is required; false for otherwise
    Default:
      false

  - ### xmlAsAttribute

    boolean xmlAsAttribute
    Specifies whether the field is to be marshalled/unmarshalled as/from an XML attribute or XML element. The data type of the value field must be simple data type.

    Returns:
      `true` if the field is to be marshalled/unmarshalled as/from the XML attribute; false for otherwise
    Default:
      false

  - ### xmlListUnwrap

    @Deprecated boolean xmlListUnwrap
    Deprecated.
    Use `SerializableField4XmlList.unwrap()`.
    Specifies whether to unwrap the list/array items of this field as the direct members of the serializable type.
    Returns:
      `true` if the field is to be unwrapped; false for otherwise.
    See Also:
      - `SerializableField4XmlList.unwrap()`
    Default:
      false

  - ### xmlListItemName

    @Deprecated String xmlListItemName
    Deprecated.
    Use `SerializableField4XmlList.itemName()`.
    Specifies the child XML element name for each item within a `List` data type field.
    Returns:
      the defined list item name in XML
    See Also:
      - `SerializableField4XmlList.itemName()`
    Default:
      "item"

  - ### xmlNS

    String xmlNS
    Specifies the prefix name for the XML namespace URI. If not specified, inherit the prefix from the field's class definition.
    Returns:
      the prefix name for the XML namespace URI
    Default:
      ""

  - ### xmlNSPrefix

    String xmlNSPrefix
    Specifies the prefix name for the XML namespace. If not specified, inherit the prefix from its XML element.
    Returns:
      the prefix name for the XML namespace
    Default:
      ""

  - ### override

    boolean override
    Specifies whether to override the representation of parent's field with same serializable name.
    For example, PersistentObject has a field with serializable name "properties", which is a list of type Attribute. It's sub-type TypeObject has a field with the same serializable name, but it is of type AttributeInfo. TypeObject can override the representation of "properties" with SerializableField.override.

         @SerializableType
         public class PersistentObject extends Linkable {
              ...
              @SerializableField(value = "properties")
              protected List<Attribute<?>>; properties = new ArrayList<Attribute<?>>();
              ...
         }

         @SerializableType
         public class TypeObject extends PersistentObject {
              ...
              @SerializableField(value = "properties", override = true)
              private List<AttributeInfo> attributeInfoList = new ArrayList<AttributeInfo>();
              ...
         }

    Returns:
      `true` if it will override representation of parent's field with same serializable name
    Default:
      false

  - ### xmlWriteTypeRoot

    boolean xmlWriteTypeRoot
    Specifies whether to write `SerializableType.value()` of the field data type instead of `value()` of the field as the XML element name for this field. Complex type here means custom type annotated with `SerializableType`. This setting applies to a field of complex type. "Write type root" means the XML element entity of the complex type object "<complexType/>" will be the direct child of XML type which owns the field. If `xmlWriteTypeRoot()` is false, the field XML element `value()` is marshaled instead of complex type entity.

         <field><complexType/></field>

    Constraints:
    (a) it is only for complex type, not for collection of complex type.
    (b) it is not recommend to enable this attribute on more than one fields of same complex type, which is ambiguous and has trouble during unmarshalling.

    Returns:
      `true` if it writes `SerializableType.value()` instead of `value()` for complex type.
    Default:
      false

  - ### xmlPreserveSpace

    boolean xmlPreserveSpace
    Specifies whether the annotated XML element should be marked with XML attribute "xml:space=preserved". This setting is applicable to the simple data type of XML element only. For other cases, it is ignored. This attribute is for internal use.
    Returns:
      true if "xml:space=preserved" is marked on the element; false for otherwise.
    Default:
      false

  - ### defaultImpl

    Class defaultImpl
    Specifies the default implementation class of the field.

    Constraints:
    (a) it is MUST for field which is declared as interface and abstract class
    (b) it is prior to the type of field declaration during unmarshalling

    Returns:
      the class qualified name of the default implementation
    Default:
      com.emc.documentum.rest.binding.SerializableField.DEFAULT.class

  - ### serializers

    Class<? extends AnnotatedFieldSerializer>[] serializers
    Specifies the customized serializer for serializable field. Generally one serializer works for several specific media types. For example, one serializer is for application/json and application/vnd.emc.documentum+json; the other is for application/xml and application/vnd.emc.documentum+xml

    Constraints:
    (a) For XML, these cases are not supported: (1) serializable fields used as XML attributes; (2) serializable fields used as XML value
    (b) For both XML and JSON, it is recommended to write the serializable name of the field and only customize the value. Or it will fail to deserialize the field from the customized output.
    (c) It is not recommended to define nested customized serializer because it need sophisticated code to make the nested one invoked.

    Returns:
      the classes which customize the field serializing
    Default:
      {}

  - ### deserializers

    Class<? extends AnnotatedFieldDeserializer>[] deserializers
    Specified the customized deserializer for serializable field. Generally one deserializer works for several specific media types. For example, one deserializer is for application/json and application/vnd.emc.documentum+json; the other is for application/xml and application/vnd.emc.documentum+xml

    Constraints: (a) For XML, these cases are not supported: (1) serializable fields used as XML attributes (2) serializable fields used as XML value (3) serializable fields of unwrapped list
    (b) For both XML and JSON, it will fail to deserialize the field if the serializer writes the customized name instead of serializable name
    (c) It is not recommended to define nested customized deserializer because it need sophisticated code to make the nested one invoked.

    Returns:
      the classes which customize the field serializing
    Default:
      {}