Module com.sun.xml.bind

Package com.sun.xml.bind.v2.runtime

Class JaxBeanInfo<BeanT>

java.lang.Object

com.sun.xml.bind.v2.runtime.JaxBeanInfo<BeanT>

Direct Known Subclasses:

ClassBeanInfoImpl, CompositeStructureBeanInfo, ElementBeanInfoImpl

public abstract class JaxBeanInfo<BeanT>
extends java.lang.Object

Encapsulates various JAXB operations on objects bound by JAXB. Immutable and thread-safe.

Each JAXB-bound class has a corresponding JaxBeanInfo object, which performs all the JAXB related operations on behalf of the JAXB-bound object.

Given a class, the corresponding JaxBeanInfo can be located via JAXBContextImpl.getBeanInfo(Class,boolean).

Typically, JaxBeanInfo implementations should be generated by XJC/JXC. Those impl classes will register themselves to their master ObjectFactory class.

The type parameter BeanT is the Java class of the bean that this represents.

Author:

Kohsuke Kawaguchi ([email protected])

Field Summary

Fields

Modifier and Type	Field	Description
protected short	flag	Various boolean flags combined into one field to improve memory footprint.
protected boolean	isNilIncluded
java.lang.Class<BeanT>	jaxbType	Gets the JAXB bound class type that this JaxBeanInfo handles.

Constructor Summary

Constructors

Modifier	Constructor	Description
protected	JaxBeanInfo(JAXBContextImpl grammar, RuntimeTypeInfo rti, java.lang.Class<BeanT> jaxbType, boolean isElement, boolean isImmutable, boolean hasLifecycleEvents)	For JaxBeanInfo that has no type names.
protected	JaxBeanInfo(JAXBContextImpl grammar, RuntimeTypeInfo rti, java.lang.Class<BeanT> jaxbType, javax.xml.namespace.QName[] typeNames, boolean isElement, boolean isImmutable, boolean hasLifecycleEvents)	For JaxBeanInfo that has multiple type names.
protected	JaxBeanInfo(JAXBContextImpl grammar, RuntimeTypeInfo rti, java.lang.Class<BeanT> jaxbType, javax.xml.namespace.QName typeName, boolean isElement, boolean isImmutable, boolean hasLifecycleEvents)	For JaxBeanInfo that has one type name.

Method Summary

Modifier and Type	Method	Description
abstract BeanT	createInstance(UnmarshallingContext context)	Creates a new instance of the bean.
abstract java.lang.String	getElementLocalName(BeanT o)	Returns the local name portion of the element name, if the bean that this class represents is mapped from/to an XML element.
abstract java.lang.String	getElementNamespaceURI(BeanT o)	Returns the namespace URI portion of the element name, if the bean that this class represents is mapped from/to an XML element.
abstract java.lang.String	getId(BeanT o, XMLSerializer target)	Gets the ID value of the given bean, if it has an ID value.
com.sun.xml.bind.v2.runtime.LifecycleMethods	getLifecycleMethods()	Return the LifecycleMethods cache for this ClassBeanInfo's corresponding jaxbType if it exists, else return null.
abstract Loader	getLoader(JAXBContextImpl context, boolean typeSubstitutionCapable)	Gets the Loader that will unmarshall the given object.
abstract Transducer<BeanT>	getTransducer()	If the bean's representation in XML is just a text, this method return a Transducer that lets you convert values between the text and the bean.
javax.xml.namespace.QName	getTypeName(BeanT instance)	Returns the XML type name to be used to marshal the specified instance.
java.util.Collection<javax.xml.namespace.QName>	getTypeNames()	Returns XML Schema type names if the bean is mapped from a complex/simple type of XML Schema.
boolean	hasAfterMarshalMethod()	True if jaxbType has the lifecycle method.
boolean	hasAfterUnmarshalMethod()	True if jaxbType has the lifecycle method.
boolean	hasBeforeMarshalMethod()	True if jaxbType has the lifecycle method.
boolean	hasBeforeUnmarshalMethod()	True if jaxbType has the lifecycle method.
boolean	hasElementOnlyContentModel()	True if this bean has an element-only content model.
protected void	hasElementOnlyContentModel(boolean value)	True if this bean has an element-only content model.
void	invokeAfterUnmarshalMethod(UnmarshallerImpl unm, java.lang.Object child, java.lang.Object parent)	Invokes the afterUnmarshal method if applicable.
void	invokeBeforeUnmarshalMethod(UnmarshallerImpl unm, java.lang.Object child, java.lang.Object parent)	Invokes the beforeUnmarshal method if applicable.
boolean	isElement()	Returns true if the bean is mapped to/from an XML element.
boolean	isImmutable()	Returns true if the bean is immutable.
boolean	isNilIncluded()
protected void	link(JAXBContextImpl grammar)	Called after all the JaxBeanInfos are created.
boolean	lookForLifecycleMethods()	This method is used to determine which of the sub-classes should be interrogated for the existence of lifecycle methods.
abstract boolean	reset(BeanT o, UnmarshallingContext context)	Resets the object to the initial state, as if the object is created fresh.
abstract void	serializeAttributes(BeanT o, XMLSerializer target)	Serializes attributes into the specified target.
abstract void	serializeBody(BeanT o, XMLSerializer target)	Serializes child elements and texts into the specified target.
abstract void	serializeRoot(BeanT o, XMLSerializer target)	Serializes the bean as the root element.
abstract void	serializeURIs(BeanT o, XMLSerializer target)	Declares all the namespace URIs this object is using at its top-level scope into the specified target.
protected void	setLifecycleFlags()	use reflection to determine which of the 4 object lifecycle methods exist on the JAXB bound type.
void	wrapUp()	Called at the end of the JAXBContext initialization phase to clean up any unnecessary references.

Methods inherited from class java.lang.Object

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

Field Detail

isNilIncluded

protected boolean isNilIncluded

flag

protected short flag

Various boolean flags combined into one field to improve memory footprint.

jaxbType

public final java.lang.Class<BeanT> jaxbType

Gets the JAXB bound class type that this JaxBeanInfo handles.

IOW, when a bean info object is requested for T, sometimes the bean info for one of its base classes might be returned.

Constructor Detail

JaxBeanInfo

protected JaxBeanInfo(JAXBContextImpl grammar,
                      RuntimeTypeInfo rti,
                      java.lang.Class<BeanT> jaxbType,
                      javax.xml.namespace.QName[] typeNames,
                      boolean isElement,
                      boolean isImmutable,
                      boolean hasLifecycleEvents)

For JaxBeanInfo that has multiple type names.

JaxBeanInfo

protected JaxBeanInfo(JAXBContextImpl grammar,
                      RuntimeTypeInfo rti,
                      java.lang.Class<BeanT> jaxbType,
                      javax.xml.namespace.QName typeName,
                      boolean isElement,
                      boolean isImmutable,
                      boolean hasLifecycleEvents)

For JaxBeanInfo that has one type name.

JaxBeanInfo

protected JaxBeanInfo(JAXBContextImpl grammar,
                      RuntimeTypeInfo rti,
                      java.lang.Class<BeanT> jaxbType,
                      boolean isElement,
                      boolean isImmutable,
                      boolean hasLifecycleEvents)

For JaxBeanInfo that has no type names.

Method Detail

hasBeforeUnmarshalMethod

public final boolean hasBeforeUnmarshalMethod()

True if jaxbType has the lifecycle method.

hasAfterUnmarshalMethod

public final boolean hasAfterUnmarshalMethod()

True if jaxbType has the lifecycle method.

hasBeforeMarshalMethod

public final boolean hasBeforeMarshalMethod()

True if jaxbType has the lifecycle method.

hasAfterMarshalMethod

public final boolean hasAfterMarshalMethod()

True if jaxbType has the lifecycle method.

isElement

public final boolean isElement()

Returns true if the bean is mapped to/from an XML element.

When this method returns true, getElementNamespaceURI(Object) and getElementLocalName(Object) returns the element name of the bean.

isImmutable

public final boolean isImmutable()

Returns true if the bean is immutable.

If this is true, Binder won't try to ueuse this object, and the unmarshaller won't create a new instance of it before it starts.

hasElementOnlyContentModel

public final boolean hasElementOnlyContentModel()

True if this bean has an element-only content model.

If this flag is true, the unmarshaller can work faster by ignoring whitespaces more efficiently.

hasElementOnlyContentModel

protected final void hasElementOnlyContentModel(boolean value)

True if this bean has an element-only content model.

Should be considered immutable, though I can't mark it final because it cannot be computed in this constructor.

isNilIncluded

public boolean isNilIncluded()

lookForLifecycleMethods

public boolean lookForLifecycleMethods()

This method is used to determine which of the sub-classes should be interrogated for the existence of lifecycle methods.

Returns:

true if the un|marshaller should look for lifecycle methods on this beanInfo, false otherwise.

getElementNamespaceURI

public abstract java.lang.String getElementNamespaceURI(BeanT o)

Returns the namespace URI portion of the element name, if the bean that this class represents is mapped from/to an XML element.

Throws:

java.lang.UnsupportedOperationException - if isElement() is false.

getElementLocalName

public abstract java.lang.String getElementLocalName(BeanT o)

Returns the local name portion of the element name, if the bean that this class represents is mapped from/to an XML element.

Throws:

java.lang.UnsupportedOperationException - if isElement() is false.

getTypeNames

public java.util.Collection<javax.xml.namespace.QName> getTypeNames()

Returns XML Schema type names if the bean is mapped from a complex/simple type of XML Schema.

This is an ugly necessity to correctly handle the type substitution semantics of XML Schema.

A single Java class maybe mapped to more than one XML types. All the types listed here are recognized when we are unmarshalling XML.

null if the class is not bound to a named schema type.

getTypeName

public javax.xml.namespace.QName getTypeName(@NotNull
                                             BeanT instance)

Returns the XML type name to be used to marshal the specified instance.

Most of the times the type can be determined regardless of the actual instance, but there's a few exceptions (most notably XMLGregorianCalendar), so as a general rule we need an instance to determine it.

createInstance

public abstract BeanT createInstance(UnmarshallingContext context)
                              throws java.lang.IllegalAccessException,
                                     java.lang.reflect.InvocationTargetException,
                                     java.lang.InstantiationException,
                                     org.xml.sax.SAXException

Creates a new instance of the bean.

This operation is only supported when isImmutable() is false.

Parameters:

context - Sometimes the created bean remembers the corresponding source location,

Throws:

java.lang.IllegalAccessException

java.lang.reflect.InvocationTargetException

java.lang.InstantiationException

org.xml.sax.SAXException

reset

public abstract boolean reset(BeanT o,
                              UnmarshallingContext context)
                       throws org.xml.sax.SAXException

Resets the object to the initial state, as if the object is created fresh.

This is used to reuse an existing object for unmarshalling.

Parameters:

context - used for reporting any errors.

Returns:

true if the object was successfuly resetted. False if the object is not resettable, in which case the object will be discarded and new one will be created.

If the object is resettable but failed by an error, it should be reported to the context, then return false. If the object is not resettable to begin with, do not report an error.

Throws:

org.xml.sax.SAXException - as a result of reporting an error, the context may throw a SAXException.

getId

public abstract java.lang.String getId(BeanT o,
                                       XMLSerializer target)
                                throws org.xml.sax.SAXException

Gets the ID value of the given bean, if it has an ID value. Otherwise return null.

Throws:

org.xml.sax.SAXException

serializeBody

public abstract void serializeBody(BeanT o,
                                   XMLSerializer target)
                            throws org.xml.sax.SAXException,
                                   java.io.IOException,
                                   javax.xml.stream.XMLStreamException

Serializes child elements and texts into the specified target.

Throws:

org.xml.sax.SAXException

java.io.IOException

javax.xml.stream.XMLStreamException

serializeAttributes

public abstract void serializeAttributes(BeanT o,
                                         XMLSerializer target)
                                  throws org.xml.sax.SAXException,
                                         java.io.IOException,
                                         javax.xml.stream.XMLStreamException

Serializes attributes into the specified target.

Throws:

org.xml.sax.SAXException

java.io.IOException

javax.xml.stream.XMLStreamException

serializeRoot

public abstract void serializeRoot(BeanT o,
                                   XMLSerializer target)
                            throws org.xml.sax.SAXException,
                                   java.io.IOException,
                                   javax.xml.stream.XMLStreamException

Serializes the bean as the root element.

In the java-to-schema binding, an object might marshal in two different ways depending on whether it is used as the root of the graph or not. In the former case, an object could marshal as an element, whereas in the latter case, it marshals as a type.

This method is used to marshal the root of the object graph to allow this semantics to be implemented.

It is doubtful to me if it's a good idea for an object to marshal in two ways depending on the context.

For schema-to-java, this is equivalent to serializeBody(Object, XMLSerializer).

Throws:

org.xml.sax.SAXException

java.io.IOException

javax.xml.stream.XMLStreamException

serializeURIs

public abstract void serializeURIs(BeanT o,
                                   XMLSerializer target)
                            throws org.xml.sax.SAXException

Declares all the namespace URIs this object is using at its top-level scope into the specified target.

Throws:

org.xml.sax.SAXException

getLoader

public abstract Loader getLoader(JAXBContextImpl context,
                                 boolean typeSubstitutionCapable)

Gets the Loader that will unmarshall the given object.

Parameters:

context - The JAXBContextImpl object that governs this object. This object is taken as a parameter so that JaxBeanInfo doesn't have to store them on its own. When this method is invoked from within the unmarshaller, tihs parameter can be null (because the loader is constructed already.)

typeSubstitutionCapable - If true, the returned Loader is capable of recognizing @xsi:type (if necessary) and unmarshals a subtype. This allowes an optimization where this bean info is guaranteed not to have a type substitution. If false, the returned Loader doesn't look for @xsi:type.

Returns:

must return non-null valid object

getTransducer

public abstract Transducer<BeanT> getTransducer()

If the bean's representation in XML is just a text, this method return a Transducer that lets you convert values between the text and the bean.

link

protected void link(JAXBContextImpl grammar)

Called after all the JaxBeanInfos are created.

Parameters:

grammar -

wrapUp

public void wrapUp()

Called at the end of the JAXBContext initialization phase to clean up any unnecessary references.

setLifecycleFlags

protected final void setLifecycleFlags()

use reflection to determine which of the 4 object lifecycle methods exist on the JAXB bound type.

getLifecycleMethods

public final com.sun.xml.bind.v2.runtime.LifecycleMethods getLifecycleMethods()

Return the LifecycleMethods cache for this ClassBeanInfo's corresponding jaxbType if it exists, else return null.

invokeBeforeUnmarshalMethod

public final void invokeBeforeUnmarshalMethod(UnmarshallerImpl unm,
                                              java.lang.Object child,
                                              java.lang.Object parent)
                                       throws org.xml.sax.SAXException

Invokes the beforeUnmarshal method if applicable.

Throws:

org.xml.sax.SAXException

invokeAfterUnmarshalMethod

public final void invokeAfterUnmarshalMethod(UnmarshallerImpl unm,
                                             java.lang.Object child,
                                             java.lang.Object parent)
                                      throws org.xml.sax.SAXException

Invokes the afterUnmarshal method if applicable.

Throws:

org.xml.sax.SAXException