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:
      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:
      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:
      {}