com.openharbor.beck.id
Interface Identifier

All Known Implementing Classes:

SerialNumber

public interface Identifier

An algorithm for marshalling multiple references to a single Java object. The general strategy is to marshal the complete object when it first appears, but marshal a brief reference at its subsequent appearances. The first appearance may include additional 'anchor' data that correlates with data in the subsequent references. A typical identifier configuration:

<when class="java.lang.Class">
     <choose identifier="SerialNumber"/>
 </when>

An Identifier is allocated to a MapFromXML or MapToXML, not to any single XMLThing or Object. Consequently any implementation of Identifier must be reentrant, although it need not be thread-safe.

Field Summary

static XMLWriter.MapKey	IDREF_TO_DANGLING_REFERENCES
static XMLWriter.MapKey	IDREF_TO_REFERENT

Method Summary

XMLThing	getIdReference(java.lang.Object parent, Getter getter, java.lang.Object source, XMLThing referent, XMLWriter writer) Construct an XML reference to the given XML element or attribute.
XMLThing	getIdReferent(java.lang.Object parent, Getter getter, java.lang.Object source, XMLThing referent, XMLWriter writer) Add anchor data to the XML element or attribute for a given Java object.
XMLThing	getReferenceKey(Unmarshaller reference) Extract the essential data of the given XML reference to an XML element or attribute.
XMLThing	getReferentKey(Unmarshaller referent) Extract the essential data of a given XML element or attribute.
java.lang.Class	getUnmarshallerClass(MapFromXML mapper, Unmarshaller parent, XMLThing source, XMLContext context) If the given source is a cross-reference, return the class of Unmarshaller for it.

Field Detail

IDREF_TO_REFERENT

public static final XMLWriter.MapKey IDREF_TO_REFERENT

IDREF_TO_DANGLING_REFERENCES

public static final XMLWriter.MapKey IDREF_TO_DANGLING_REFERENCES

Method Detail

getIdReferent

public XMLThing getIdReferent(java.lang.Object parent,
                              Getter getter,
                              java.lang.Object source,
                              XMLThing referent,
                              XMLWriter writer)

Add anchor data to the XML element or attribute for a given Java object.

If the returned thing is an element with a null value, the caller should output the element and also additional attributes and/or content mapped from the source object. If the returned thing is an attribute or an element with a non-null value, the caller should output the returned thing without additions.

The implementation can and should simply return the given referent, if it can't be referred to or already contains the necessary anchor data. The parameters provide enough context to enable sophisticated algorithms, but many implementations won't need them.

Parameters:

parent - the object that contains source, or null if source is the root object

getter - the relationship from parent to source

source - the Java object to be marshalled

referent - the caller's choice of XML (from a MapToXML, usually)

writer - whither this object will be marshalled

Returns:

the XML thing for this object, or null to indicate that this object should not be marshalled.

getIdReference

public XMLThing getIdReference(java.lang.Object parent,
                               Getter getter,
                               java.lang.Object source,
                               XMLThing referent,
                               XMLWriter writer)

Construct an XML reference to the given XML element or attribute. The reference should uniquely identify the object, among all objects that have been or could be marshalled to the given writer's current XML document.

Returns:

an element or attribute that refers to the given referent, or null to indicate it's not possible to refer to the given referent.

getReferentKey

public XMLThing getReferentKey(Unmarshaller referent)

Extract the essential data of a given XML element or attribute. The returned object must be uniquely a function of the referent, among all XML that has been or could be unmarshalled from the current XML document (assuming the document is valid).

getReferenceKey

public XMLThing getReferenceKey(Unmarshaller reference)

Extract the essential data of the given XML reference to an XML element or attribute. The returned object must be uniquely a function of the referent, among all XML that has been or could be unmarshalled from the current XML document (assuming the document is valid).

getUnmarshallerClass

public java.lang.Class getUnmarshallerClass(MapFromXML mapper,
                                            Unmarshaller parent,
                                            XMLThing source,
                                            XMLContext context)

If the given source is a cross-reference, return the class of Unmarshaller for it. The parameters provide enough context to enable sophisticated algorithms, but many implementations won't need them.

Parameters:

mapper -

parent -

source -

context -

Returns:

the class of Unmarshaller to use, or null to indicate that this source is not a reference.