uk.ac.sheffield.jast

Class Marshaller

java.lang.Object

uk.ac.sheffield.jast.Marshaller

public class Marshaller
extends java.lang.Object

Marshaller helps to convert a Java object-graph into an XML data stream. Marshalling is the act of converting a Java object structure into a serial XML data stream. Marshaller analyses each Java class to determine which fields should be serialized as XML attributes, or as dependent elements. It reflectively discovers which methods to use to extract the value of each field, and caches these methods to speed up subsequent access. It ensures that each distinct AST node is only written out once, and that duplicate encounters are written as references.

When a Marshaller first encounters a new AST node, it assigns it a unique "id", so that meeting the same object again in the object-graph will not result in it being serialized again; instead an XML element reference will be created with a "ref" attribute referring to the value of the "id". On first encounter of each AST class, Marshaller extracts its persistent fields in order of declaration, ignoring any transient and static fields. It determines whether the field stores an attribute, or a dependent node, by examining what kind of method was used to set the field. Methods used to access attributes, dependent nodes, or simple content, are reflectively discovered and cached, for use by ASTWriter.

Version:

2.5

Author:

Anthony J H Simons

Field Summary

Fields

Modifier and Type	Field and Description
private java.util.Map<java.lang.Class<?>,java.lang.Boolean>	contentMap The map from types to a boolean flag.
private java.util.Map<java.lang.Class<?>,java.util.List<java.lang.String>>	dependentMap The map from types to dependent property names.
private java.util.Map<java.lang.Class<?>,java.util.Map<java.lang.String,java.lang.reflect.Method>>	methodMap The map from types to property-indexed access methods.
private java.util.Map<java.lang.Object,java.lang.Integer>	objectMap The map of object IDs, indexed by unique object references.
private java.util.Map<java.lang.Class<?>,java.util.List<java.lang.String>>	propertyMap The map from types to attribute property names.

Constructor Summary

Constructors

Constructor and Description
Marshaller() Creates a Marshaller for mapping AST objects to XML output.

Method Summary

Modifier and Type	Method and Description
java.lang.Object	getContent(java.lang.Object object) Returns the content of the AST object, if it has any.
private java.lang.reflect.Method	getContentMethod(java.lang.Class<?> type)
java.util.List<java.lang.String>	getDependentNames(java.lang.Object object) Returns the names of all the Fields of an AST object that are dependent objects.
java.util.Collection<?>	getDependents(java.lang.Object object, java.lang.String property) Returns a collection of dependents of an AST object named by the given property.
private java.util.List<java.lang.reflect.Field>	getFields(java.lang.Class<?> type) Extracts all the persistent instance Fields of an AST class, in the order that they were originally declared.
private java.lang.Class<?>	getGenericType(java.lang.reflect.Field field, int index) Returns the component element type of a generic Field, found at the given index.
private java.lang.reflect.Method	getGetMethod(java.lang.Class<?> type, java.lang.String property) Searches the given AST class type for a public get-method to fetch the given property.
private java.lang.reflect.Method	getMethodMap(java.lang.Class<?> type, java.lang.String property) Fetches a get-method for a property of an AST class.
int	getObjectIndex(java.lang.Object object) Reports whether this Marshaller has seen an AST object before.
java.lang.Object	getProperty(java.lang.Object object, java.lang.String property) Returns the value of the named property in an AST object.
java.util.List<java.lang.String>	getPropertyNames(java.lang.Object object) Returns the names of all the Fields of an AST object that are attribute properties.
private void	putMethodMap(java.lang.Class<?> type, java.lang.String property, java.lang.reflect.Method method) Stores a get-method for a property of an AST class.
private void	registerFields(java.lang.Class<?> type) Registers which Fields of a type are properties and which are dependents.
private void	semanticError(java.lang.String message) Reports model-building error, when the model constraints are violated.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

objectMap

private java.util.Map<java.lang.Object,java.lang.Integer> objectMap

The map of object IDs, indexed by unique object references. Used to detect when a duplicate reference to an object is found, so that the same object ID is stored in a proxy. This MUST be initialised with an IdentityHashMap, so that we always compare objects by identity.

propertyMap

private java.util.Map<java.lang.Class<?>,java.util.List<java.lang.String>> propertyMap

The map from types to attribute property names. Used to determine which persistent fields to serialise as XML attributes.

dependentMap

private java.util.Map<java.lang.Class<?>,java.util.List<java.lang.String>> dependentMap

The map from types to dependent property names. Used to determine which persistent fields to serialise as dependent XML elements.

contentMap

private java.util.Map<java.lang.Class<?>,java.lang.Boolean> contentMap

The map from types to a boolean flag. Used to indicate whether the type has some content to convert to XML text.

methodMap

private java.util.Map<java.lang.Class<?>,java.util.Map<java.lang.String,java.lang.reflect.Method>> methodMap

The map from types to property-indexed access methods.

Constructor Detail

Marshaller

public Marshaller()

Creates a Marshaller for mapping AST objects to XML output.

Method Detail

getObjectIndex

public int getObjectIndex(java.lang.Object object)

Reports whether this Marshaller has seen an AST object before. If so, returns the previously-seen ID; and if not, returns zero. The object will always be inserted into the object map, such that a call which returned zero will subsequently return a non-zero value.

Parameters:

object - the AST object to be recorded.

Returns:

the unique ID for this object.

getPropertyNames

public java.util.List<java.lang.String> getPropertyNames(java.lang.Object object)

Returns the names of all the Fields of an AST object that are attribute properties. If the object has not been seen before, registers all the Fields of its Class as either properties, or dependents, or content. Finally, returns a list of attribute property names.

Parameters:

object - the AST object.

Returns:

a list of property names.

getDependentNames

public java.util.List<java.lang.String> getDependentNames(java.lang.Object object)

Returns the names of all the Fields of an AST object that are dependent objects. If the object has not been seen before, registers all the Fields of its Class as either properties, or dependents, or content. Finally, returns a list of dependent property names.

Parameters:

object - the AST object.

Returns:

a list of dependents.

getProperty

public java.lang.Object getProperty(java.lang.Object object,
                                    java.lang.String property)

Returns the value of the named property in an AST object.

Parameters:

object - the AST object.

property - the property name.

Returns:

the value of this property.

getDependents

public java.util.Collection<?> getDependents(java.lang.Object object,
                                             java.lang.String property)

Returns a collection of dependents of an AST object named by the given property. Fetches the result using a public get-method, e.g. for the name "property" uses the method "getProperty". If the result is some kind of Collection, returns this unchanged. If the result is a Map, returns the values only. If the result is a singleton, returns this in a singleton list. Otherwise, if the result is null, returns an empty list.

Parameters:

object - the AST object.

property - the property name.

Returns:

a collection of dependents.

getContent

public java.lang.Object getContent(java.lang.Object object)

Returns the content of the AST object, if it has any. If the AST object's class provides methods to set and get simple content, uses the "getContent" method to return the content. The result may be null, if the method returns no value, or if no content-field was defined for the AST class.

Parameters:

object - the AST object.

Returns:

the content, or null.

semanticError

private void semanticError(java.lang.String message)
                    throws SemanticError

Reports model-building error, when the model constraints are violated.

Parameters:

message - the error message.

Throws:

SemanticError - always.

getFields

private java.util.List<java.lang.reflect.Field> getFields(java.lang.Class<?> type)

Extracts all the persistent instance Fields of an AST class, in the order that they were originally declared. Persistent instance Fields are any Fields that were not prefixed with the 'static' or 'transient' modifiers. Fields are returned in the order that they were declared, starting from the root of the class hierarchy. This order is used to determine the order of XML attributes, and XML dependents.

Parameters:

type - the AST Class.

Returns:

a list of fields.

registerFields

private void registerFields(java.lang.Class<?> type)
                     throws SemanticError

Registers which Fields of a type are properties and which are dependents. The persistent Fields are filtered to determine whether they are assigned through an add-method or a set-method. The former are dependents; while the latter are properties. Fields may have simple or collection types. If the latter, the principal element type is chosen as the dependent.

Parameters:

type - the AST class.

Throws:

SemanticError

getGenericType

private java.lang.Class<?> getGenericType(java.lang.reflect.Field field,
                                          int index)

Returns the component element type of a generic Field, found at the given index. This is used to extract the element types of Fields having List or Set types, or the value-types of Fields having Map types.

Parameters:

field - the Field with a generic type.

index - the index of the element type.

Returns:

the element type at the index.

getGetMethod

private java.lang.reflect.Method getGetMethod(java.lang.Class<?> type,
                                              java.lang.String property)
                                       throws SemanticError

Searches the given AST class type for a public get-method to fetch the given property. The property is a field-name that has been registered as an attribute property. Converts the property name, e.g. "property" into a no-argument method named "getProperty", and then searches the AST class for a public method with this name.

Parameters:

type - the AST class.

property - the attribute property.

Returns:

the public get-Method to fetch the property.

Throws:

SemanticError - if no such Method exists.

getContentMethod

private java.lang.reflect.Method getContentMethod(java.lang.Class<?> type)

getMethodMap

private java.lang.reflect.Method getMethodMap(java.lang.Class<?> type,
                                              java.lang.String property)

Fetches a get-method for a property of an AST class.

Parameters:

type - the AST class.

property - the property name.

Returns:

the corresponding get-method, or null.

putMethodMap

private void putMethodMap(java.lang.Class<?> type,
                          java.lang.String property,
                          java.lang.reflect.Method method)

Stores a get-method for a property of an AST class.

Parameters:

type - the AST class.

property - the property name.

method - the get-method to use for this property.