uk.ac.sheffield.jast

Class Unmarshaller

java.lang.Object

uk.ac.sheffield.jast.Unmarshaller

public class Unmarshaller
extends java.lang.Object

Unmarshaller helps to convert an XML data stream into a Java object-graph. Unmarshalling is the act of restoring a Java object structure in memory from a serial XML data stream. Unmarshaller reflectively discovers the appropriate Java AST classes and methods to use when building the AST object-graph, and caches these methods to speed up subsequent building. It expects the AST class to provide set-methods to store the values of attributes and simple content, and add-methods to attach dependent children nodes. It ensures that multiple references to the same element are mapped to the same AST node.

When an Unmarshaller encounters an XML element, it creates an instance of the corresponding AST class. It checks the "id" attribute (or assigns one) and associates this with the AST node. If an element is encountered with a "ref" attribute, it is treated as a reference and is mapped to the existing AST node whose "id" has the same value as the "ref". Other XML attributes are mapped to fields of the AST node and values are coerced to the type of the field. Dependent XML children are added as dependents of the AST node. Methods used to set attributes, or add dependent nodes, or set simple content, are reflectively discovered and cached, for use by an ASTReader or ASTBuilder.

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.util.Map<java.lang.String,java.lang.reflect.Method>>	methodMap The map from types to property-indexed set- and add-methods.
private java.util.Map<java.lang.Integer,java.lang.Object>	objectMap The map of created AST nodes, indexed by their unique ID.

Constructor Summary

Constructors

Constructor and Description
Unmarshaller() Creates a Unmarshaller for mapping XML input to AST objects.

Method Summary

Modifier and Type	Method and Description
void	addDependent(java.lang.Object parent, java.lang.Object child) Attaches a dependent AST child object to a given AST parent object.
void	checkIdentity(java.lang.String identity) Checks that the declared serial ID matches the actual serial ID of an AST object, as it is unmarshalled.
private java.lang.Object	coerceValue(java.lang.String value, java.lang.Class<?> type) Coerces a String value to an instance of the given type.
java.lang.Object	createObject(java.lang.String javaClassID) Factory method to create an instance of a user-defined AST class.
private java.lang.reflect.Method	getAddMethod(java.lang.Class<?> type, java.lang.Class<?> childType) Searches the given AST class type for a public add-method for the given child-type.
private java.lang.reflect.Method	getContentMethod(java.lang.Class<?> type, java.lang.reflect.Field field) Searches the given AST class type for a public content-setting method for the given content-field.
private java.lang.reflect.Field	getField(java.lang.Class<?> type, java.lang.String name) Searches the given AST class type for a Field with the given name.
private java.lang.reflect.Method	getMethodMap(java.lang.Class<?> type, java.lang.String property) Fetches a set-method for a property of an AST class, or an add-method for a named dependent child of the AST class.
private java.lang.reflect.Method	getSetMethod(java.lang.Class<?> type, java.lang.reflect.Field field) Searches the given AST class type for a public set-method for the given Field.
private void	putMethodMap(java.lang.Class<?> type, java.lang.String property, java.lang.reflect.Method method) Stores a set-method for a property of an AST class, or an add-method for a named dependent child of the AST class.
java.lang.Object	restoreReference(java.lang.String reference, java.lang.Object proxy) Restores a re-entrant reference to an object that has already been unmarshalled.
private void	semanticError(java.lang.String message) Reports model-building error, when the model constraints are violated.
void	setContent(java.lang.Object object, java.lang.String value) Sets the information content of a given AST object.
void	setProperty(java.lang.Object object, java.lang.String property, java.lang.String value) Sets a property of an AST object to the given value.

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.Integer,java.lang.Object> objectMap

The map of created AST nodes, indexed by their unique ID. Used to detect when a duplicate reference to an object is found, so that the proxy object may be replaced by the real one.

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 set- and add-methods.

Constructor Detail

Unmarshaller

public Unmarshaller()

Creates a Unmarshaller for mapping XML input to AST objects.

Method Detail

checkIdentity

public void checkIdentity(java.lang.String identity)
                   throws SemanticError

Checks that the declared serial ID matches the actual serial ID of an AST object, as it is unmarshalled. This can happen if the XML file has been edited after serialisation, and will upset the restoration of re-entrant references to objects.

Parameters:

identity - an integer serial number, as a string.

Throws:

SemanticError - if the serial ID of the object is out of step with the count of unmarshalled objects.

restoreReference

public java.lang.Object restoreReference(java.lang.String reference,
                                         java.lang.Object proxy)
                                  throws SemanticError

Restores a re-entrant reference to an object that has already been unmarshalled. The reference is the identity of some object that has been unmarshalled. The proxy is a duplicate object whose reference attribute equals the reference. Looks up the main object in the object map, checks that it has the same type as the proxy, then returns the main object.

Parameters:

reference - an integer serial number, as a string.

proxy - the proxy object, created from the reference.

Returns:

the resolved object, from the object map.

Throws:

SemanticError - if there is a type mismatch between the proxy object's type, and the type of the referenced main object.

createObject

public java.lang.Object createObject(java.lang.String javaClassID)
                              throws SemanticError

Factory method to create an instance of a user-defined AST class. Reflectively creates a default instance of the user-defined Java class with the given package-qualified class name.

Parameters:

javaClassID - the package-qualified class name.

Returns:

an instance of the named class, if it exists.

Throws:

SemanticError - if the AST class cannot be found, or cannot be instantiated.

addDependent

public void addDependent(java.lang.Object parent,
                         java.lang.Object child)
                  throws SemanticError

Attaches a dependent AST child object to a given AST parent object. Searches the class of the parent for a suitable public add-method for adding a dependent of the child's type (or of some more general type, up to but not including Object). If a method is found, uses this to add the dependent child to the parent.

Parameters:

parent - the parent AST object.

child - the child AST object.

Throws:

SemanticError - if no suitable add-method can be found, or if the add-method fails.

setProperty

public void setProperty(java.lang.Object object,
                        java.lang.String property,
                        java.lang.String value)
                 throws SemanticError

Sets a property of an AST object to the given value. Searches the class of the object for a Java field named by the property, and then searches the class for a public set-method for setting a field of this type. If a method is found, uses this to set the Java field's value, coercing the value to the expected field-type. Leading and trailing whitespace is trimmed from the value before coercion.

Parameters:

object - an AST object.

property - a field name.

value - the value to store in the field.

Throws:

SemanticError - if the AST class has no field with this name, or no public set-method can be found, or the set-method fails.

setContent

public void setContent(java.lang.Object object,
                       java.lang.String value)

Sets the information content of a given AST object. Searches the class of the object for a field named "content", and then searches the class for a method named "setContent" for setting a field of this type. If a method is found, uses this to set the field's value, coercing the value to the expected field-type. Leading and trailing whitespace is trimmed from the value before coercion.

Parameters:

object - an AST object.

value - the value to store as the content.

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.

getField

private java.lang.reflect.Field getField(java.lang.Class<?> type,
                                         java.lang.String name)
                                  throws SemanticError

Searches the given AST class type for a Field with the given name. Searches the class hierarchy, starting from the given AST class type, until either a Field with the given name is declared, or the root class Object is reached.

Parameters:

type - the AST class to search.

name - the name of the field.

Returns:

the Field object.

Throws:

SemanticError - if no such field exists.

getSetMethod

private java.lang.reflect.Method getSetMethod(java.lang.Class<?> type,
                                              java.lang.reflect.Field field)
                                       throws SemanticError

Searches the given AST class type for a public set-method for the given Field. Converts the Field's name, e.g. "property", into the expected name for a set-method, viz. "setProperty", and then searches the AST class type for a public method with this name, and that also expects a single parameter identical to the Field's type.

Parameters:

type - the AST class to search.

field - the Field to be set.

Returns:

the public set-Method for the Field.

Throws:

SemanticError - if no such method exists.

getAddMethod

private java.lang.reflect.Method getAddMethod(java.lang.Class<?> type,
                                              java.lang.Class<?> childType)
                                       throws SemanticError

Searches the given AST class type for a public add-method for the given child-type. Searches the given AST class type for a public method e.g. "addChild(Child)" for a child-type "Child" and, if none is found, searches for a more general method, viz. "addParent(Parent)" for adding a "Parent" superclass of "Child", until either a method of the right name and type is found, or the root class Object is reached.

Parameters:

type - the AST class to search.

childType - the AST class of the child.

Returns:

the public adding-Method for the child type.

Throws:

SemanticError - if no such method exists.

getContentMethod

private java.lang.reflect.Method getContentMethod(java.lang.Class<?> type,
                                                  java.lang.reflect.Field field)
                                           throws SemanticError

Searches the given AST class type for a public content-setting method for the given content-field. Searches the given AST class type for a public method named "setContent" that expects a parameter of the same type as the field.

Parameters:

type - the AST class to search.

field - the content-field to be set.

Returns:

the public content-setting method.

Throws:

SemanticError - if no such method can be found.

coerceValue

private java.lang.Object coerceValue(java.lang.String value,
                                     java.lang.Class<?> type)

Coerces a String value to an instance of the given type. If the type is String, returns the value immediately. If the type is primitive, converts to a wrapped instance of the primitive type. If the type is an enumerated type, finds the enumerated constant matching the value. Otherwise, finds a conversion constructor from String to the type. If any of this fails, returns the original value unchanged, which will raise a type exception in the caller.

Parameters:

value - the String value.

type - the desired result type.

Returns:

an object of this type.

getMethodMap

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

Fetches a set-method for a property of an AST class, or an add-method for a named dependent child of the AST class.

Parameters:

type - the AST class.

property - the property name.

Returns:

the corresponding Method, or null.

putMethodMap

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

Stores a set-method for a property of an AST class, or an add-method for a named dependent child of the AST class.

Parameters:

type - the AST class.

property - the property name.

method - the set- or add-method to use for this property.