Package com.emc.documentum.rest.binding
Annotation 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
(2) Set field visibility in property
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.
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 typeConstraints:
(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 ClassesModifier and TypeClassDescriptionstatic enum
Visibility of the field in marshalling. -
Optional Element Summary
Optional ElementsModifier and TypeOptional ElementDescriptionString[]
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 whichvalue()
will be written whenjsonWriteRootAsField()
field is true.
Choose "json-root" as it is unique in most cases.boolean
For JSON marshalling, specify whether to write thevalue()
into a field specified byjsonRootField()
under the root representation.
E.G.Class<? extends AnnotatedFieldDeserializer>[]
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 valueSpecify 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 wheninheritValue()
is FALSE. (c) the name is case sensitive.- Returns:
- the serialized name
- Default:
- ""
-
inheritValue
boolean inheritValueSpecify 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.
IfinheritValue()
is FALSE, the serializable name of this type isvalue()
on the class definition.
IfinheritValue()
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 fieldVisibilitySpecify the field visibility of the type for marshalling.- Returns:
- field visibility
- See Also:
- Default:
- ALL
-
fieldOrder
String[] fieldOrderSpecify 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 ignoreNullFieldsSpecify 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 inlineFieldSpecify 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 withSerializableType
.
(b) at most one field in the class could be inline.- Returns:
- the filed name to be inline.
- Default:
- ""
-
inlineOnly
boolean inlineOnlyWhen 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 jsonWriteRootAsFieldFor JSON marshalling, specify whether to write thevalue()
into a field specified byjsonRootField()
under the root representation.
E.G. a class is annotatedvalue()
="foo",jsonWriteRootAsField()
=true andjsonRootField()
="root-field", the marshaled JSON representation is"root-field" = foo ... ...
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 itsjsonRootField()
will help decide the real type of object to unmarshal.- Returns:
true
if to write the root
- Default:
- false
-
jsonRootField
String jsonRootFieldFor JSON marshalling, specifies the property name for whichvalue()
will be written whenjsonWriteRootAsField()
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 xmlValueFieldSpecifies 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 theirSerializableField.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 xmlNSSpecifies the namespace URI for the type.- Returns:
- the XML namespace URI for the type
- Default:
- ""
-
xmlNSPrefix
String xmlNSPrefixSpecify the prefix name for the XML namespace.- Returns:
- the prefix name for the XML namespace
- Default:
- ""
-
unknownFieldDeserializers
Class<? extends AnnotatedFieldDeserializer>[] unknownFieldDeserializersSpecify 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}
-