Package com.emc.documentum.rest.binding

# Annotation Interface SerializableType

@Target(TYPE) @Retention(RUNTIME) @Inherited public @interface SerializableType
Annotation that can be used to mark a class as a serializable REST representation. The format of REST message complies with Open Text Documentum REST representation guidelines. This annotation can be used for both marshalling and unmarshalling. Documentum REST Services has default message converters to marshall an object with this annotation into XML and/or JSON messages; and vice versa for unmarshalling.
The serializable fields of a type are defined in two ways:
(1) Explicitly mark annotation `SerializableField` on fields
(2) Set field visibility in property `fieldVisibility()` to include other fields of the type
Constraints:
(a) this annotation can be applied to interface, abstract class or other non-concrete types
so that their fields can be marshalled or unmarshalled along with their concrete sub-classes.
But notice that these non-concrete types with this annotation can still not be marshaled or unmarshalled themselves.

- ## Nested Class Summary

  Nested Classes
  Modifier and Type
  Class
  Description
  `static enum`
  `SerializableType.FieldVisibility`
  Visibility of the field in marshalling.

- ## Optional Element Summary

  Optional Elements
  Modifier and Type
  Optional Element
  Description
  `String[]`
  `fieldOrder`
  Specify the order of fields names in array so that the fields will be marshalled by order.
  `SerializableType.FieldVisibility`
  `fieldVisibility`
  Specify the field visibility of the type for marshalling.
  `boolean`
  `ignoreNullFields`
  Specify whether to ignore fields with null value.
  `boolean`
  `inheritValue`
  Specify whether to reuse the serializable name of its super type.
  `String`
  `inlineField`
  Specify the referencing field to be inline.
  `boolean`
  `inlineOnly`
  When specified inline field, when whether serialize the other fields of the wrapper class.
  `String`
  `jsonRootField`
  For JSON marshalling, specifies the property name for which `value()` will be written when `jsonWriteRootAsField()` field is true.
  Choose "json-root" as it is unique in most cases.
  `boolean`
  `jsonWriteRootAsField`
  For JSON marshalling, specify whether to write the `value()` into a field specified by `jsonRootField()` under the root representation.
  E.G.
  `Class<? extends AnnotatedFieldDeserializer>[]`
  `unknownFieldDeserializers`
  Specify the deserializers for the unknown fields in the xml/json representation.
  `String`
  `value`
  Specify the serialized name for the type.
  Constraints:
  (a) 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.
  `String`
  `xmlNS`
  Specifies the namespace URI for the type.
  `String`
  `xmlNSPrefix`
  Specify the prefix name for the XML namespace.
  `String`
  `xmlValueField`
  Specifies the field from which the value will be taken as the XML element value of this class.

- ## Element Details

  - ### value

    String value
    Specify the serialized name for the type.
    Constraints:
    (a) 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.
    (b) this setting must not be empty when `inheritValue()` is FALSE. (c) the name is case sensitive.
    Returns:
      the serialized name
    Default:
      ""

  - ### inheritValue

    boolean inheritValue
    Specify whether to reuse the serializable name of its super type. Set this attribute to TRUE only for the types which supports marshalling only. Do not use it on a type which will be unmarshalled.
    If `inheritValue()` is FALSE, the serializable name of this type is `value()` on the class definition.
    If `inheritValue()` is TRUE, the serializable name of this type is the serializable name from its ancestor (its parent, or its parent's parent, ...). `value()` is ignored.
    Returns:
      `true` if inheriting serializable name
    Default:
      false

  - ### fieldVisibility

    SerializableType.FieldVisibility fieldVisibility
    Specify the field visibility of the type for marshalling.
    Returns:
      field visibility
    See Also:
      - `SerializableType.FieldVisibility`
    Default:
      ALL

  - ### fieldOrder

    String[] fieldOrder
    Specify the order of fields names in array so that the fields will be marshalled by order. This property just identifies the order of fields to be marshalled. It does not define the scope of fields to be serialized.
    For fields appearing in this list but not marked as serializable, they are just ignored.
    For fields not appearing in this list but marked as serializable, they are serialized at the tail of the ordered fields. The list could contain fields from base types.
    Returns:
      a string array for the fieldOrder field names
    Default:
      {}

  - ### ignoreNullFields

    boolean ignoreNullFields
    Specify whether to ignore fields with null value. If to ignore, the null fields are not marshalled.
    Returns:
      `true` if to ignore null field; false for otherwise
    Default:
      true

  - ### inlineField

    String inlineField
    Specify the referencing field to be inline. Inline means the specified field is promoted upper lever to represent this type.

    Constraints:
    (a) the data type of the inline field must be annotated with `SerializableType`.
    (b) at most one field in the class could be inline.

    Returns:
      the filed name to be inline.
    Default:
      ""

  - ### inlineOnly

    boolean inlineOnly
    When specified inline field, when whether serialize the other fields of the wrapper class. If false, then besides the inline field, other fields are written as well. Otherwise, only inline field is written.
    Returns:
      whether write inline field only
    Default:
      true

  - ### jsonWriteRootAsField

    boolean jsonWriteRootAsField
    For JSON marshalling, specify whether to write the `value()` into a field specified by `jsonRootField()` under the root representation.
    E.G. a class is annotated `value()`="foo", `jsonWriteRootAsField()`=true and `jsonRootField()`="root-field", the marshaled JSON representation is

         "root-field" = foo
             ...
             ...

    It's recommended to enable this attribute in such case. If the annotated type has super class which is annotated as well, the JSON root will be marshaled so that the type info exists in JSON representation which is useful during unmarshalling.
    For example, A is sub-class of B, and class Foobar has field of type List<B>, which contains instances of A. Keep serializable name of A in its `jsonRootField()` will help decide the real type of object to unmarshal.
    Returns:
      `true` if to write the root
    Default:
      false

  - ### jsonRootField

    String jsonRootField
    For JSON marshalling, specifies the property name for which `value()` will be written when `jsonWriteRootAsField()` field is true.
    Choose "json-root" as it is unique in most cases. jsonRoot like "name" would make trouble if customers define field named "name"
    Returns:
      the JSON root name
    Default:
      "json-root"

  - ### xmlValueField

    String xmlValueField
    Specifies the field from which the value will be taken as the XML element value of this class.

    Constraints:
    (a) the data type on the specified field must be simple data type.
    (b) when a XML value field is specified, no fields will be serialized as this type's child elements; annotations or visibility on the other fields are ignored unless their `SerializableField.xmlAsAttribute()` is true.

    But XML attributes still work.

    Returns:
      the field name from which the value is taken as the XML element value of this type
    Default:
      ""

  - ### xmlNS

    String xmlNS
    Specifies the namespace URI for the type.
    Returns:
      the XML namespace URI for the type
    Default:
      ""

  - ### xmlNSPrefix

    String xmlNSPrefix
    Specify the prefix name for the XML namespace.
    Returns:
      the prefix name for the XML namespace
    Default:
      ""

  - ### unknownFieldDeserializers

    Class<? extends AnnotatedFieldDeserializer>[] unknownFieldDeserializers
    Specify the deserializers for the unknown fields in the xml/json representation. By default, if there are unknown elements/nodes defined in the xml/json, the deserializers will throw an exception. If the unknown field need be processed by other implementation, or it's unwrapped, or generic, abstract, etc..., then this unknownFieldDeserializers can be defined as empty, unknownFieldDeserializers={}, so no exception will be thrown when encounter unknown field.
    Returns:
      the deserializers for unknown fields
    Default:
      {com.emc.documentum.rest.wire.common.AnnotatedExceptionalUnknownFieldDeserializer.class}