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 
    Visibility of the field in marshalling.
  • Optional Element Summary

    Optional Elements
    Modifier and Type
    Optional Element
    Description
    Specify the order of fields names in array so that the fields will be marshalled by order.
    Specify the field visibility of the type for marshalling.
    boolean
    Specify whether to ignore fields with null value.
    boolean
    Specify whether to reuse the serializable name of its super type.
    Specify the referencing field to be inline.
    boolean
    When specified inline field, when whether serialize the other fields of the wrapper class.
    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
    For JSON marshalling, specify whether to write the value() into a field specified by jsonRootField() under the root representation.
    E.G.
    Specify the deserializers for the unknown fields in the xml/json representation.
    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.
    Specifies the namespace URI for the type.
    Specify the prefix name for the XML namespace.
    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

      Specify the field visibility of the type for marshalling.
      Returns:
      field visibility
      See Also:
      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}