public class XSerializer extends com.streamscape.omf.serializer.AbstractSerializer implements TextSerializer
Title: Object Mediation Framework
Description: A serialization mechanism for persisting Java objects as XML.
This object serialization mechanism is currently based on the XStream project from thoughtworks.
The serializer uses its own wrapper, modified reflection converters and element aliasing system. It does not
support backwards compatibility with earlier versions of XStream or any JDK below 1.5 version. The serializer
provides additional extensions for null
handling, mapping and working with global alias maps. The
serializer elements are derived from the fabric's semantic types and it's class loaders are maintained by the Object
Mediation Framework's package and loader registries. It is currently compatible with XStream ver 1.3.1 only
and may change further in the future.
The XSerializer
implementation has a number of deviations from the original source. Most notably,
the serializer is part of a larger framework that supports multiple serialized data formats and pre-packaged data
structures. The serializer may only be created by the associate serializer factory. It has been extended to
handle namespaces, configurable null
behavior and Context Driven Class Loader Management to
ensure maximum compatibility with application servers and micro-containers such as Spring or an Enterprise
Service Bus.
The serializer is seamlessly integrated with StreamScape's Structured Data Objects
library. This library provides
a set of pre-packaged, configurable Event Objects and Data Objects that may be used to transmit serialized
data over a variety of messaging transports, including IBM MQSeries, TIBCO Rendezvous, StreamScape's Service
Event Fabric messaging protocol (TLP) or any JMS compliant message broker. Event Objects support serialization
into several popular formats: XML, Binary and JSON (JavaScript Object Notation) which allows the objects to be used
across languages and seamlessly embedded in a variety of technologies. Event Objects support extended system and user-defined
header elements similar to JMS Messages. They also support Content Annotation which allows any object content to
be dynamically extracted from the message and placed into the event's header at message composition time. Any elements
in the event's header may be used for routing and filtering using SQL-like event selector syntax. Combining the serializer's
capabilities with Event Objects allows developers to configure complex Content Based Routing Rules on virtually
any Java Class, XML document or JSON object content using simple, SQL-like syntax.
Event Objects are created and defined by using their appropriate DatagramFactory
. Users can create an
arbitrary Java class and set it as the content of a DataEvent
, then use the serializer to create a transportable
data object. Events may be created as part of a Runtime Context
environment an used in complement with
the Service Event Fabric's
messaging transport: the Structured Data Exchange. In this case the
fabric will use it's internal binary serialization format and the user may use this serializer to build XML content for
the event's data elements. For more information on binary serialization format see JSerializerFactory
.
Alternatively it is possible to make use of the serializers and supporting framework from a Client Context
.
Users may create any object including Event Objects and general Structured Data Objects and serialize
them for transport. Both contexts provide a similar API for dealing with objects and datagram factories. The tutorial
below illustrates how to make use of the XML Serializer.
Example: Creating Event Datagrams
The following example illustrates how to work with serializers and datagram factories in the context of a fabric client application. Users can access the event datagram factory and define an event prototype that has an arbitrary Java Object as it's payload. They can then populate the object with values and create a full event datagram object in XML format. Such an object may be used with a variety of transports and injected into the fabric as a standard event.
Any object may be wrapped as an event. In this example we are using the serializer to persist the datagram as XML rather then generate XML to a specific schema. However, is should be noted that the object's data content may it self be a fully formed XML document or it may be extracted as an XML fragment and use with any standard XML parsing technologies.
import com.streamscape.cli.ClientContext; import com.streamscape.sdo.event.EventDatagramFactory; import com.streamscape.sdo.mf.admin.DatagramPrototypeFactory; import unit.test.serial.JDEJournalBatch; import unit.test.serial.JDEBatchElement; .. .. // Initialize client context ClientContext ctx = ClientContext.getInstance(); // Obtain the datagram factory EventDatagramFactory evFactory = ctx.getEventDatagramFactory(); // set aliases for types ctx.getSemanticAliasManager().alias("JDEBatchElement", JDEBatchElement.class); ctx.getSemanticAliasManager().alias("JDEJournalBatch", JDEJournalBatch.class); ..Using Alias Manager: All serializers require that objects be prepared for marshaling by providing an
Alias
name for each class element that is part of the object. The context
environment adds all primitive types, popular collections and internal objects to the alias map by
default. However any user defined objects must be made known to the serializer by aliasing it.
XSerializer uses the alias names to generate XML tags for elements and attributes, whereas other
serializers may use aliases to generate similar meta-data information (ie. JSON element blocks).
In the code snippet above two objects are aliased, an element and a batch object which is a
sequence (collection) of elements. In our example the batch is a Java ArrayList collection.
The serializer automatically recognizes such collections and also allows users to mark them
as implicit, removing the default enclosing tag which would normally enclose such
collections.
Registering Data Event Prototypes: In this example the user is crating an event datagram
that may be used to wrap the data object to prepare it for transport. Unlike conventional messaging
systems which provide a user with a finite set of message types, the event fabric allows users to create
their own message types (models) or extend existing ones. User-defined events (prototypes) are created
by calling appropriate methods in the Datagram Prototype Factory
. Alternatively developers
may also make use of the lower level datagram factory for a specific model, but the suggested method
is to use the Datagram Prototype Factory
. It encapsulates many functions from the
datagram factory and offers a simple and effective interface.
Adding a prototype requires that a user specify it's instance name, the eventId that the event will
be associated with and in case of the DataEvent
the semantic type of the data element.
The type should have been previously registered (as shown above using the alia() method).
.. // Obtain the prototype factory and create the event prototype DatagramPrototypeFactory dtFactory = ctx.getDatagramPrototypeFactory(); dtFactory.addDataEventPrototype("event.JDE.Journal.Batch", "JDEJournalBatch"); // Create new event DataEvent event = (DataEvent) evFactory.createEvent("event.JDE.Journal.Batch"); // Initialize the data object JDEJournalBatch batch = (JDEJournalBatch)event.getData(); .. initBatch(batch); .. // Set some correlation values event.setCorrelationId(batch.getBatchId()); event.setReplyTo("event.JDE.Journal.Batch.Reply"); // Serialize the EventGram // by using the default serializer byte[] xbuffer = ctx.getXSerializer().serialize(event); System.out.println("\n---Event Datagram---\n"); System.out.println(new String(xbuffer)); System.out.println("\n-------end----------\n");Understanding Semantic Types: All serializers require that objects be prepared for marshaling by providing an
Alias
name for each class element that is part of the object. The context
environment adds all primitive types, popular collections and internal objects to the alias map by
default. However any user defined objects must be made known to the serializer by aliasing it.
XSerializer uses the alias names to generate XML tags for elements or attributes, whereas other
serializers may use aliases to generate other meta-data information (ie. JSON element blocks).
In the code snippet above two objects are aliased, an element and a batch object which is a
sequence (collection) of elements. A SemanticType
is a configuration class that contains
additional meta-data about the aliased object such as ancestor names and serial version id.
Semantic types are used extensively by the framework and users may define their own types and use
them as aliases or allow the framework to auto-generate them.
Example: Creating XML Documents and XML Fragments
Assuming we want to create an XML document (or fragment, an XML snipped without a header) lets consider the following data objects:
public class TMS_Feed { public String SeqID="1"; public String Type="Fund Distribution"; public VectorSimilar to the earlier example, we can obtain a context, a serializer and then simply use thedistributions = new Vector (); .. } public class Distribution { public String FundFamily ="BCP IV"; public String LegalEntity ="Capital Partners IV NQ L.L.P. (CPN)"; public String IsGP_Fund ="1"; .. .. }
serialize()
method to generate an XML representation of an arbitrary object. The
object does not need to implement the Serializable
interface or otherwise be
prepared for serialization in any way. Aliasing is required by the framework to identify
serializable elements but it does not alter or impact the serializable object in any way.
.. // Initialize client context ClientContext ctx = ClientContext.getInstance(); // set aliases for types ctx.getSemanticAliasManager().alias("TMS_Feed", TMS_Feed.class); ctx.getSemanticAliasManager().alias("Distribution", Distribution.class); .. // Create the TMS Feed object.. TMS_Feed feed = new TMS_Feed(); .. // Obtain a default serializer and serialize byte[] xbuffer = ctx.getXSerializer().serialize(feed); ..Altering the object definition does not break serialization as long as there are no new elements introduced into the object's serialized form. This is known as the exclusion principle. As long as existing elements are excluded from the serial form the object-to-XML mapping contract remains valid. When new elements are introduced into the serial form and an attempt is made to deserialize a new elements using an older version of the object an exception is thrown.
Developers will notice the design and implementation of the Object Mediation Framework enforces a certain type of collaborative, object-centric development. Whenever an object's signature changes and entails the inclusion of new elements, serialized versions of the object must be re-generated and copies of the new object (class) must be distributed to all system participants. The framework is purposefully designed to enforce this dependency between object producers and consumers. Although it is possible to mediate between old and new versions of objects it is recommended that the general approach be followed to ensure a strong (non-brittle) contract between applications exchanging structured data.
Example: Tweaking the XML Document
XSerializer is able to serialize most objects without the need for custom mapping. The object graph supports object references, circular references and when used exclusively or serialization it produces XML that is clean and compliant with most XML mapping tools. Keep in mind that the primary function of the serializer is to persist objects. References reduce the overhead of re-printing the same data values in the graph by substituting the value for a references. For example:
.. Cd bj = new Cd("basement_jaxx_singles"); List order = new ArrayList(); // adds the same cd twice (two references to the same object) order.add(bj); order.add(bj); // adds itself (cycle) order.add(order); ..The example above adds duplicate references and a circular reference to it self. This results in the following XML:
<list> <cd> <id>maria rita</id> </cd> <cd> <id>basement_jaxx_singles</id> </cd> <cd reference="../cd[2]"/> <list reference=".."/> </list>When the serializer is used for the purpose of persisting object graphs it may make sense to retain references for both optimization and to protect against excessive duplication of data. However when the serializer is used to generate presentable XML structures it is possible to disable references.
ctx.getXSerializer().setMode(XSerializer.NO_REFERENCES);Sometimes it's desirable to tweak the output in order to conform to a particular schema or format. Most of the structure elements output by the serializer can be configured. It is possible to set aliases for class types and field names that are mapped to XML tag or attribute names. Objects that can be represented as simple string value can be written as attributes. It is possible to omit fields or to flatten the structure for collections.
Aliases offer a simple way to use different tag or attribute names in the XML. The simplest and most
common tweak is to alias a fully qualified class to a shorter name in order to avoid bleeding class names
and object references in the XML. Other cases include using a different field name for a class member,
mapping class fields to attributes or specifying default values for null
elements. Aliases can
be set for following elements:
<cat> <age>4</age> <name>Garfield</name> <owner type="StandardPerson"> <name>Jon Arbuckle</name> </owner> </cat>Additional control may applied to XML processing:
transient
will omit it automatically from processingreadResolve()
method can be used inliu of a default constructorExample: Handling NULL values in XML output
By default XML rules for handling NULL
elements are based on the exclusion principle.
If an element or attribute does not exist it is considered NULL
. Because it is
possible to define a document's structure by a variety of supplemental mechanisms such as DTD, XSL
schema or even XSLT an XML document does not typically specify explicit missing values. This
presents a problem for data serialization mechanisms or technologies that do not use XML schema.
In general, when XSerializer is used to persist data the exclusion principle works well because
NULL
data fields are not included in the generated XML and this makes the document
footprint smaller. However, when XML is used as a data mediation layer, mapping between XML
elements and files or database queries presents a problem because data management systems often
require explicit NULL
indicators to be present.
The serializer solves this problem by providing configurable behavior for NULL
and
general default handling. Each serializer instance has a defaults provider that may be
configured to provide specific defaults at the field or class level. In case of missing values
the serializer can be instructed to recognize XML compliant xsi:nil="true"
, or
the value NULL
or a customized value. For example:
.. DefaultsProvider defaults = ctx.getXSerializer().getDefaultsProvider(); .. // Tells the serializer to use the xsi:nil namespace indicator for allWhen the serializer is configured to useInteger
objects defaults.setClassDefault(Integer.class, XConstants.XSI_NIL); // Tells the serializer to usenull-name
for fieldname
in objectTestObeject.class
defaults.setFieldDefault("name", Name.class, TestObject.class, new Name("null-name")); // Tells the serializer to useNULL
indicator foraddress
field defaults.setFieldDefault("address", Address.class, TestObject.class, XConstants.NULL); ..
xsi:nil
the namespace attribute is automatically added to the
XML header of every document mapped by the serializer. The namespace xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
must also exist in the source XML document during deserialization in order to support proper handling of missing values.
The header (prolog) name space references xsi:nil
in order to comply with standard namespace processing.
Note that enabling namespace support has the effect of enabling general namespace support across the serializer instance.
If XSerializer is used for mapping XML documents and namespaces are not required, developers should use a different
serializer instance configured to not use namespaces.
Handling special characters in field names and XML tags
XML as a meta-language presents a number of problems for programmers because often a particular
language may generate field names and data content that cannot be interpreted by XML parsers as
valid. As we have seen previously, such a problem already exists when handling NULL
elements. It may also exist when control characters reserved by XML appear in field names. The
serializer provides a configurable way to specify what type of substitution to perform for such
characters during marshaling and unmarshalling of XML. The XmlFriendlyNameCoder
allows
users to specify how a particular character is handled. In the example below the underscore (_) and
dash (-) characters are escaped by a standard underscore(_) character, allowing the XML to retain
the basic syntax of the class. However, such element names may not be handled properly by certain
XML mapping or processing mechanism such as XQuery.
.. XmlFriendlyNameCoder uEncoder = new XmlFriendlyNameCoder("_-", "_"); xf = (XSerializer) xFactory.createSerializer("InvestranToWSS", uEncoder); ..Note that in this example we are creating a new serializer instance instead of using the system one. Serializers are thread safe and users may create and use multiple copies of XSerializer to map between specific XML formats, default handlers and name spaces. In this way the serializer may also be used as a common data model mapper or a general XML transformation tool. While this approach requires some coding it is typically much more efficient then an XML mapping technology such as XQuery or XSLT and yields much higher performance.
Mapping attributes in XML output
In general, working with XML serialization follows two paths of development and is guided by the motivation of the developer. Reverse Engineering implies that the developer is attempting to generate a Java object from an existing XML document. This is currently done manually by creating a set of classes that map to the general structure of the XML and giving the serializer hints on how to properly format the XML. Forward Engineering is the act of taking an existing set of objects and generating an XML, JSON or similar object from the class.
The serializer allows users to map object class fields to XML Attributes by identifying the fields and specifying the relationship. Using our prior example of serializing an object:
.. // Create a new serializer instance xf = (XSerializer) xFactory.createSerializer("InvestranToWSS", uEncoder); // Alias the object xFactory.alias("TMS_Feed", TMS_Feed.class, false); xFactory.alias("Distribution", Distribution.class, false); // Specify use of Attributes for field names xf.useAttributeFor(TMS_Feed.class, "SeqID"); xf.useAttributeFor(TMS_Feed.class, "Type"); // Specify distributions as an implicit collection to remove collection tags xf.addImplicitCollection(TMS_Feed.class, "distributions"); .. xf.useAttributeFor(Distribution.class, "FundFamily"); xf.useAttributeFor(Distribution.class, "LegalEntity"); .. ..
Example: Deserializing Objects from XML
Deserializing objects is a very straight-forward operation. It's success relies on having a setup of your serializer symmetric to the one that created the serialized object. XSerializer may be configured in different (asymmetric) ways to deserialize object in some cases. However this is not recommended and usually unnecessary. It is fairly easy to create targeted serializers that handle specific objects and use such serializers when required.
The example below assumes that we are deserializing our Data Event
from the prior step.
The steps taken to initialize the client context and alias the semantic types have already been taken.
.. // Create a new data event instance by deserializing // Note that we need to specify the Semantic Type of our target object DataEvent e2 = (DataEvent) ctx.getXSerializer().deserialize("DataEvent", xbuffer); // Create a new batch object from serialized data JDEJournalBatch newBatch = (JDEJournalBatch) e2.getData(); // Iterate thru element instances Iterator<JDEBatchElement> elements = batch.getBatchElements(); int itemNo = 0; while(elements.hasNext()) { itemNo++; JDEBatchElement element = elements.next(); System.out.println("\tBatch Element " + itemNo + "=" + element.getABALP1()); } System.out.println("\n----------end---------\n") ;General object unmarshalling is handled exactly the same way. The
deserialize()
method is
overload to allow stream-based unmarshalling as well as arbitrary, non-typed deserialization. The example
below shows deserialization using the custom serializer xserial
that was created in a prior step.
.. // Deserialize an object instance from a bytes buffer INVTmsFeed feedIn = (INVTmsFeed) xserial.deserialize("TMS_Feed", xbuffer);However in situations where the type being deserialized is unknown the developer may employ anonymous deserialization and inspect the object after it has been created.
..
Object obj = xserial.deserialize(xbuffer);
For additional samples and general information on the original project, please visit the XStream Project site.
Copyright: Copyright (c) 2009
Company: StreamScape Technologies
SerializerSupport
,
Serializer
,
SerializerFactory
,
JSerializer
,
JSerializerFactory
,
JSONSerializerFactory
,
JSONSerializer
,
Serialized FormModifier and Type | Field and Description |
---|---|
static int |
ID_REFERENCES |
static int |
NO_REFERENCES |
static int |
PRIORITY_LOW |
static int |
PRIORITY_NORMAL |
static int |
PRIORITY_VERY_HIGH |
static int |
PRIORITY_VERY_LOW |
static int |
SINGLE_NODE_XPATH_ABSOLUTE_REFERENCES |
static int |
SINGLE_NODE_XPATH_RELATIVE_REFERENCES |
static java.lang.String |
XML_HEADER |
static int |
XPATH_ABSOLUTE_REFERENCES |
static int |
XPATH_RELATIVE_REFERENCES |
DEFAULT_SERIAL_VERSION_ID
Modifier and Type | Method and Description |
---|---|
void |
addClassElementConverter(java.lang.Class definedIn,
java.lang.String fieldName,
com.streamscape.omf.xml.xstream.converters.Converter converter)
Register a local
Converter for a field in a given class. |
void |
addClassElementConverter(java.lang.Class definedIn,
java.lang.String fieldName,
com.streamscape.omf.xml.xstream.converters.SingleValueConverter converter)
Register a local
SingleValueConverter for a field. |
void |
addDefaultImplementation(java.lang.Class defaultImplementation,
java.lang.Class ofType)
Associate a default implementation of a class with an object.
|
void |
addDefaultImplementationDeserializationOnly(java.lang.Class defaultImplementation,
java.lang.Class ofType) |
void |
addFieldAliases(java.lang.String typeName)
Processes alias annotations for an object
NOTE: 'processAnnotations' can process nested objects types.
|
void |
addImplicitCollection(java.lang.Class ownerType,
java.lang.String fieldName)
Adds a default implicit collection which is used for any unmapped XML tag.
|
void |
addImplicitCollection(java.lang.Class ownerType,
java.lang.String fieldName,
java.lang.Class itemType)
Adds implicit collection which is used for all items of the given itemType.
|
void |
addImplicitCollection(java.lang.Class ownerType,
java.lang.String fieldName,
java.lang.String itemFieldName,
java.lang.Class itemType)
Adds implicit collection which is used for all items of the given element name defined by
itemFieldName.
|
void |
alias(java.lang.String name,
java.lang.Class type)
Alias a Class to a shorter name to be used in XML elements.
|
com.streamscape.omf.xml.xstream.io.HierarchicalStreamReader |
createReader(java.io.Reader xml) |
java.lang.Object |
deserialize(byte[] buffer)
Deserializes instance of a Java object from byte array.
|
java.lang.Object |
deserialize(java.lang.Class objectClass,
java.lang.String buffer)
Deserializes instance of Java object from a
buffer . |
java.lang.Object |
deserialize(java.io.DataInputStream buffer)
Deserializes an object from the provided Data Input Stream.
|
java.lang.Object |
deserialize(java.io.Reader reader)
Deserializes an object from the provided Data Input Stream.
|
java.lang.Object |
deserialize(java.lang.String buffer)
Deserializes instance of a Java object from string.
|
java.lang.Object |
deserialize(java.lang.String semanticType,
byte[] buffer)
Deserializes instance of a Java object or
StructuredDataObject from byte array based on the
semantic name. |
java.lang.Object |
deserialize(java.lang.String semanticType,
byte[] buffer,
boolean useAliases) |
java.lang.Object |
deserialize(java.lang.String semanticType,
java.io.DataInputStream buffer)
Deserializes an object from the provided Data Input Stream and performs Semantic
Type verification.
|
java.lang.Object |
deserialize(java.lang.String semanticType,
java.io.Reader reader)
Deserializes an object from the provided Reader and performs Semantic
Type verification.
|
java.lang.Object |
deserialize(java.lang.String semanticType,
java.lang.String buffer)
Deserializes instance of a Java object or
StructuredDataObject from string based on the
semantic name. |
java.lang.Object |
deserialize(java.lang.String semanticType,
java.lang.String buffer,
boolean useAliases) |
com.streamscape.omf.xml.xstream.converters.ConverterLookup |
getConverterLookup() |
com.streamscape.omf.xml.xstream.converters.reflection.FabricDefaultsProvider |
getDefaultsProvider() |
com.streamscape.omf.xml.xstream.mapper.Mapper |
getMapper()
Retrieve the
Mapper . |
java.lang.String |
getName()
Returns the name of the serializer.
|
com.streamscape.omf.xml.xstream.converters.reflection.ReflectionProvider |
getReflectionProvider()
Retrieve the
ReflectionProvider in use. |
boolean |
isAnnotated(java.lang.Class type) |
boolean |
isEnforcedXSerializer()
Returns serializable and externalizable objects processing state.
|
boolean |
isXFragment()
Returns
true if XFragment processing is enabled. |
void |
mapAttribute(java.lang.Class definedIn,
java.lang.String attributeName,
java.lang.String alias)
Create an alias for an attribute.
|
void |
mapAttribute(java.lang.String alias,
java.lang.String attributeName)
Create an alias for an attribute
|
void |
mapFieldToElement(java.lang.String alias,
java.lang.Class definedIn,
java.lang.String fieldName)
Maps a class field's name to a specific XML element name, thereby allowing a
user defined element tag to be substituted for the actual field name in the XML.
|
void |
marshal(java.lang.Object obj,
com.streamscape.omf.xml.xstream.io.HierarchicalStreamWriter writer)
Serialize and object to a hierarchical data structure (such as XML).
|
void |
omitField(java.lang.Class definedIn,
java.lang.String fieldName)
Prevents a field from being serialized.
|
void |
registerConverter(com.streamscape.omf.xml.xstream.converters.Converter converter) |
void |
registerConverter(com.streamscape.omf.xml.xstream.converters.Converter converter,
int priority) |
void |
registerConverter(com.streamscape.omf.xml.xstream.converters.SingleValueConverter converter) |
void |
registerConverter(com.streamscape.omf.xml.xstream.converters.SingleValueConverter converter,
int priority) |
java.lang.String |
serialize(java.lang.Object obj)
Serializes an instance of an arbitrary
Java Object into text. |
void |
serialize(java.lang.Object obj,
java.io.DataOutputStream buffer)
Serializes instance of a Java object into
DataOutputStream . |
void |
serialize(java.lang.Object obj,
java.io.Writer writer)
Serializes instance of a Java object into
Writer . |
java.lang.String |
serialize(java.lang.String semanticType,
java.lang.Object obj)
Serializes an instance of an arbitrary
Java Object into string. |
void |
serialize(java.lang.String semanticType,
java.lang.Object obj,
java.io.DataOutputStream buffer)
Serializes provided object into Data Output Stream.
|
void |
serialize(java.lang.String semanticType,
java.lang.Object obj,
java.io.Writer writer)
Serializes instance of a Java object into
Writer . |
java.lang.String |
serializeAtRoot(java.lang.Object obj,
java.lang.String xmlRoot)
Returns an XML fragment (not a full xDoc) from an object starting at a specific root element.
|
void |
setEnforceXSerializer(boolean enforce)
Set whether default serializable and externalizable converters should be overridden and a fabric-specific
reflection provider with a NULL-values handler should be used.
|
void |
setEscapeStrategy(EscapeStrategy strategy) |
void |
setMarshallingStrategy(com.streamscape.omf.xml.xstream.MarshallingStrategy marshallingStrategy) |
void |
setMode(int mode)
Change mode for dealing with duplicate references.
|
void |
setXFragment(boolean fragment)
Enables XFragment processing.
|
java.lang.Object |
unmarshal(com.streamscape.omf.xml.xstream.io.HierarchicalStreamReader reader)
Deserialize an object from a hierarchical data structure (such as XML).
|
void |
useAttributeFor(java.lang.Class type)
Use an attribute for an arbitrary type.
|
void |
useAttributeFor(java.lang.Class definedIn,
java.lang.String fieldName)
Use an attribute for a field declared in a specific type.
|
void |
useAttributeFor(java.lang.String fieldName,
java.lang.Class type)
Use an attribute for a field or a specific type.
|
destroy, getClassLoader, setClassLoader
clone, getSerialVersionUID
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
destroy, getClassLoader, setClassLoader
public static final java.lang.String XML_HEADER
public static final int NO_REFERENCES
public static final int ID_REFERENCES
public static final int XPATH_RELATIVE_REFERENCES
public static final int XPATH_ABSOLUTE_REFERENCES
public static final int SINGLE_NODE_XPATH_RELATIVE_REFERENCES
public static final int SINGLE_NODE_XPATH_ABSOLUTE_REFERENCES
public static final int PRIORITY_VERY_HIGH
public static final int PRIORITY_NORMAL
public static final int PRIORITY_LOW
public static final int PRIORITY_VERY_LOW
public boolean isEnforcedXSerializer()
true
if fabric-specific
provider with NULL-values handler is used for serializable (with readObject
or writeObject
methods overridden) and externalizable objects. Otherwise returns false
if XSerializer default serializable
and externalizable converters are used for such objects.public void setEnforceXSerializer(boolean enforce)
true
to use fabric-specific
provider for serializable (with readObject
or writeObject
methods overridden) and
externalizable objects.enforce
- new valuepublic void setXFragment(boolean fragment)
fragment
- booleanpublic boolean isXFragment()
true
if XFragment processing is enabled.public com.streamscape.omf.xml.xstream.converters.reflection.FabricDefaultsProvider getDefaultsProvider()
public java.lang.String getName()
getName
in interface Serializer
public java.lang.Object deserialize(java.io.DataInputStream buffer) throws SerializerException
deserialize
in interface Serializer
buffer
- input stream with the serialized objectSerializerException
- if an object type or class are not defined in the Alias Map
or
if other errors occur.public java.lang.Object deserialize(java.lang.String semanticType, java.io.DataInputStream buffer) throws SerializerException
deserialize
in interface Serializer
semanticType
- expected type of the serialized objectbuffer
- input stream with the serialized objectSerializerException
- if an object type or class are not defined in the Alias Map
or
if other errors occur.public java.lang.Object deserialize(byte[] buffer) throws SerializerException
Serializer
Alias Map
.
The actual instance creation is implementation specific. Framework serializers may not require the presence of a
null constructor.deserialize
in interface Serializer
buffer
- the buffer containing serialized object.SerializerException
- if an object type or class are not defined in the Alias Map
or
if other errors occur.public void addFieldAliases(java.lang.String typeName)
typeName
- public java.lang.Object deserialize(java.lang.String semanticType, byte[] buffer, boolean useAliases) throws SerializerException
semanticType
- the semantic type name of the object being deserialized.buffer
- array to deserialize from.useAliases
- use aliases from SDOXSerializerException
- if an object type or class are not defined in the Alias Map
or if other errors occur.SerializerException
public java.lang.Object deserialize(java.lang.String semanticType, byte[] buffer) throws SerializerException
StructuredDataObject
from byte array based on the
semantic name. The semantic name may point to an interface allowing for casting of types.deserialize
in interface Serializer
semanticType
- the semantic type name of the object being deserialized.buffer
- array to deserialize from.XSerializerException
- if an object type or class are not defined in the Alias Map
or if other errors occur.SerializerException
- if an object type or class are not defined in the Alias Map
or
if other errors occur.public java.lang.Object deserialize(java.io.Reader reader) throws SerializerException
deserialize
in interface TextSerializer
buffer
- reader with the serialized objectSerializerException
- if an object type or class are not defined in the Alias Map
or
if other errors occur.public java.lang.Object deserialize(java.lang.Class objectClass, java.lang.String buffer) throws SerializerException
TextSerializer
buffer
. Buffer contains a text representation of an
object in its serialized form. Meaning that the actual format of the object may be XML or JSON or whatever
format dictated by the serializer. The actual format is implementation specific.
The method allows users to specify a particular semantic type, thereby engaging in forced casting of the deserialized object.
deserialize
in interface TextSerializer
objectClass
- the class of the specified object.buffer
- the buffer containing serialized object.SerializerException
- if some errors occur.public java.lang.Object deserialize(java.lang.String semanticType, java.io.Reader reader) throws SerializerException
deserialize
in interface TextSerializer
semanticType
- expected type of the serialized objectbuffer
- reader with the serialized objectSerializerException
- if an object type or class are not defined in the Alias Map
or
if other errors occur.public java.lang.Object deserialize(java.lang.String buffer) throws SerializerException
TextSerializer
Alias Map
.
The actual instance creation is implementation specific. Framework serializers may not require the presence of a
null constructor.deserialize
in interface TextSerializer
buffer
- the string containing serialized object.SerializerException
- if an object type or class are not defined in the Alias Map
or
if other errors occur.public java.lang.Object deserialize(java.lang.String semanticType, java.lang.String buffer, boolean useAliases) throws SerializerException
semanticType
- the semantic type name of the object being deserialized.buffer
- string to deserialize from.useAliases
- use aliases from SDOXSerializerException
- if an object type or class are not defined in the Alias Map
or if other errors occur.SerializerException
public java.lang.Object deserialize(java.lang.String semanticType, java.lang.String buffer) throws SerializerException
StructuredDataObject
from string based on the
semantic name. The semantic name may point to an interface allowing for casting of types.deserialize
in interface TextSerializer
semanticType
- the semantic type name of the object being deserialized.buffer
- string to deserialize from.XSerializerException
- if an object type or class are not defined in the Alias Map
or if other errors occur.SerializerException
- if an object type or class are not defined in the Alias Map
or
if other errors occur.public java.lang.String serialize(java.lang.String semanticType, java.lang.Object obj) throws SerializerException
TextSerializer
Java Object
into string. The object may be
a plain Java object or an instance of a StructuredDataObject
.
The object must be defined as a known Semantic Type and all of its elements must be registered
in the Alias Map
.
This method allows for a specific semantic type to be specified, which results in a form of protected casting for
the object based on the Alias Map
. It is therefore possible to serialize varied objects that implement
the same interface.
serialize
in interface TextSerializer
semanticType
- the semantic type of the specified object.obj
- the object to be serializedSerializerException
- if an object type or class are not defined in the Alias Map
or
if other errors occur.public java.lang.String serialize(java.lang.Object obj) throws SerializerException
Java Object
into text. This
method is constrained in the sense that it mandates the object's semantic type is registered
with the alias mapper.serialize
in interface TextSerializer
obj
- Object The object to be serialized.XSerializerException
- Thrown if an object type or class are not defined in the Alias Map
or if other errors occur.SerializerException
- if an object type or class are not defined in the Alias Map
or
if other errors occur.public void serialize(java.lang.String semanticType, java.lang.Object obj, java.io.Writer writer) throws SerializerException
TextSerializer
Writer
. The object may be an
instance of StructuredDataObject
or a standard Java object. The actual output format is
implementation specific. The object must be defined as a known Semantic Type and all of its elements
must be registered in the Alias Map
.
This method allows for a specific semantic type to be specified, which results in a form of protected casting for
the object based on the Alias Map
. It is therefore possible to serialize varied objects that implement
the same interface.
serialize
in interface TextSerializer
semanticType
- the semantic type of the specified object.obj
- the object to be serialized.writer
- the writer that holds the serialized object.SerializerException
- if an object type or class are not defined in the Alias Map
or
if other errors occur.public void serialize(java.lang.Object obj, java.io.Writer writer) throws SerializerException
TextSerializer
Writer
. The object may be an
instance of StructuredDataObject
or a standard Java object. The actual output format is
implementation specific. The object must be defined as a known Semantic Type and all of its elements
must be registered in the Alias Map
.serialize
in interface TextSerializer
obj
- the object to be serialized.writer
- the writer that holds the serialized object.SerializerException
- if an object type or class are not defined in the Alias Map
or
if other errors occur.public void serialize(java.lang.Object obj, java.io.DataOutputStream buffer) throws SerializerException
DataOutputStream
.serialize
in interface Serializer
obj
- Objectbuffer
- DataOutputStreamXSerializerException
- Thrown if an object type or class are not defined in the Alias Map
or if other errors occur.SerializerException
- if an object type or class are not defined in the Alias Map
or
if other errors occur.public void serialize(java.lang.String semanticType, java.lang.Object obj, java.io.DataOutputStream buffer) throws SerializerException
serialize
in interface Serializer
semanticType
- the semantic type of the specified object.obj
- the object to be serialized.SerializerException
- if an object type or class are not defined in the Alias Map
or
if other errors occur.public java.lang.String serializeAtRoot(java.lang.Object obj, java.lang.String xmlRoot) throws XSerializerException
obj
- Object Objects instance to serialize into an XML fragment.xmlRoot
- String The root element of the object.XSerializerException
public void setMarshallingStrategy(com.streamscape.omf.xml.xstream.MarshallingStrategy marshallingStrategy)
public void marshal(java.lang.Object obj, com.streamscape.omf.xml.xstream.io.HierarchicalStreamWriter writer)
XStreamException
- if the object cannot be serializedpublic com.streamscape.omf.xml.xstream.io.HierarchicalStreamReader createReader(java.io.Reader xml)
public java.lang.Object unmarshal(com.streamscape.omf.xml.xstream.io.HierarchicalStreamReader reader)
XStreamException
- if the object cannot be deserializedpublic void alias(java.lang.String name, java.lang.Class type)
name
- Short nametype
- Type to be aliasedcom.streamscape.omf.xml.xstream.InitializationException
- if no ClassAliasingMapper
is availablepublic void mapFieldToElement(java.lang.String alias, java.lang.Class definedIn, java.lang.String fieldName)
Scope: serializer instance.
alias
- the alias itselfdefinedIn
- the type that declares the fieldfieldName
- the name of the fieldcom.streamscape.omf.xml.xstream.InitializationException
- if no FieldAliasingMapper
is availablepublic void mapAttribute(java.lang.String alias, java.lang.String attributeName)
alias
- the alias itselfattributeName
- the name of the attributecom.streamscape.omf.xml.xstream.InitializationException
- if no AttributeAliasingMapper
is availablepublic void mapAttribute(java.lang.Class definedIn, java.lang.String attributeName, java.lang.String alias)
definedIn
- the type where the attribute is definedattributeName
- the name of the attributealias
- the alias itselfcom.streamscape.omf.xml.xstream.InitializationException
- if no AttributeAliasingMapper
is availablepublic void useAttributeFor(java.lang.String fieldName, java.lang.Class type)
fieldName
- the name of the fieldtype
- the Class of the type to be rendered as XML attributecom.streamscape.omf.xml.xstream.InitializationException
- if no AttributeMapper
is availablepublic void useAttributeFor(java.lang.Class definedIn, java.lang.String fieldName)
fieldName
- the name of the fielddefinedIn
- the Class containing such fieldcom.streamscape.omf.xml.xstream.InitializationException
- if no AttributeMapper
is availablepublic void useAttributeFor(java.lang.Class type)
type
- the Class of the type to be rendered as XML attributecom.streamscape.omf.xml.xstream.InitializationException
- if no AttributeMapper
is availablepublic void addDefaultImplementation(java.lang.Class defaultImplementation, java.lang.Class ofType)
defaultImplementation
- ofType
- com.streamscape.omf.xml.xstream.InitializationException
- if no DefaultImplementationsMapper
is availablepublic void addDefaultImplementationDeserializationOnly(java.lang.Class defaultImplementation, java.lang.Class ofType)
public void registerConverter(com.streamscape.omf.xml.xstream.converters.Converter converter)
public void registerConverter(com.streamscape.omf.xml.xstream.converters.Converter converter, int priority)
public void registerConverter(com.streamscape.omf.xml.xstream.converters.SingleValueConverter converter)
public void registerConverter(com.streamscape.omf.xml.xstream.converters.SingleValueConverter converter, int priority)
public void addClassElementConverter(java.lang.Class definedIn, java.lang.String fieldName, com.streamscape.omf.xml.xstream.converters.Converter converter)
Converter
for a field in a given class.definedIn
- the class type the field is defined infieldName
- the field nameconverter
- the converter to usepublic void addClassElementConverter(java.lang.Class definedIn, java.lang.String fieldName, com.streamscape.omf.xml.xstream.converters.SingleValueConverter converter)
SingleValueConverter
for a field.definedIn
- the class type the field is defined infieldName
- the field nameconverter
- the converter to usepublic com.streamscape.omf.xml.xstream.mapper.Mapper getMapper()
Mapper
. This is by default a chain of MapperWrappers
.public com.streamscape.omf.xml.xstream.converters.reflection.ReflectionProvider getReflectionProvider()
ReflectionProvider
in use.public com.streamscape.omf.xml.xstream.converters.ConverterLookup getConverterLookup()
public void setMode(int mode)
XPATH_ABSOLUTE_REFERENCES
, XPATH_RELATIVE_REFERENCES
,
XStream.ID_REFERENCES
and XStream.NO_REFERENCES
.java.lang.IllegalArgumentException
- if the mode is not one of the declared typesXPATH_ABSOLUTE_REFERENCES
,
XPATH_RELATIVE_REFERENCES
,
ID_REFERENCES
,
NO_REFERENCES
public void setEscapeStrategy(EscapeStrategy strategy)
public void addImplicitCollection(java.lang.Class ownerType, java.lang.String fieldName)
ownerType
- class owning the implicit collectionfieldName
- name of the field in the ownerType. This field must be a concrete
collection type or matching the default implementation type of the collection
type.public void addImplicitCollection(java.lang.Class ownerType, java.lang.String fieldName, java.lang.Class itemType)
ownerType
- class owning the implicit collectionfieldName
- name of the field in the ownerType. This field must be a concrete
collection type or matching the default implementation type of the collection
type.itemType
- type of the items to be part of this collection.com.streamscape.omf.xml.xstream.InitializationException
- if no ImplicitCollectionMapper
is availablepublic void addImplicitCollection(java.lang.Class ownerType, java.lang.String fieldName, java.lang.String itemFieldName, java.lang.Class itemType)
ownerType
- class owning the implicit collectionfieldName
- name of the field in the ownerType. This field must be a concrete
collection type or matching the default implementation type of the collection
type.itemFieldName
- element name of the implicit collectionitemType
- item type to be aliases be the itemFieldNamecom.streamscape.omf.xml.xstream.InitializationException
- if no ImplicitCollectionMapper
is availablepublic void omitField(java.lang.Class definedIn, java.lang.String fieldName)
com.streamscape.omf.xml.xstream.InitializationException
- if no FieldAliasingMapper
is availablepublic boolean isAnnotated(java.lang.Class type)
Copyright © 2015-2024 StreamScape Technologies. All rights reserved.