+ * Each JAXB-bound class has a corresponding {@link JaxBeanInfo} object, + * which performs all the JAXB related operations on behalf of + * the JAXB-bound object. + * + *
+ * Given a class, the corresponding {@link JaxBeanInfo} can be located + * via {@link JAXBContextImpl#getBeanInfo(Class,boolean)}. + * + *
+ * Typically, {@link 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 (kohsuke.kawaguchi@sun.com)
+ */
+public abstract class JaxBeanInfo
+ * IOW, when a bean info object is requested for T,
+ * sometimes the bean info for one of its base classes might be
+ * returned.
+ */
+ public final Class
+ * When this method returns true, {@link #getElementNamespaceURI(Object)}
+ * and {@link #getElementLocalName(Object)} returns the element name of
+ * the bean.
+ */
+ public final boolean isElement() {
+ return (flag&FLAG_IS_ELEMENT)!=0;
+ }
+
+ /**
+ * 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.
+ */
+ public final boolean isImmutable() {
+ return (flag&FLAG_IS_IMMUTABLE)!=0;
+ }
+
+ /**
+ * 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.
+ */
+ public final boolean hasElementOnlyContentModel() {
+ return (flag&FLAG_HAS_ELEMENT_ONLY_CONTENTMODEL)!=0;
+ }
+
+ /**
+ * 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.
+ */
+ protected final void hasElementOnlyContentModel(boolean value) {
+ if(value)
+ flag |= FLAG_HAS_ELEMENT_ONLY_CONTENTMODEL;
+ else
+ flag &= ~FLAG_HAS_ELEMENT_ONLY_CONTENTMODEL;
+ }
+
+ public boolean isNilIncluded() {
+ return isNilIncluded;
+ }
+
+ /**
+ * This method is used to determine which of the sub-classes should be
+ * interrogated for the existence of lifecycle methods.
+ *
+ * @return true if the un|marshaller should look for lifecycle methods
+ * on this beanInfo, false otherwise.
+ */
+ public boolean lookForLifecycleMethods() {
+ return (flag&FLAG_HAS_LIFECYCLE_EVENTS)!=0;
+ }
+
+ /**
+ * Returns the namespace URI portion of the element name,
+ * if the bean that this class represents is mapped from/to
+ * an XML element.
+ *
+ * @throws UnsupportedOperationException
+ * if {@link #isElement} is false.
+ */
+ public abstract String getElementNamespaceURI(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 UnsupportedOperationException
+ * if {@link #isElement} is false.
+ */
+ public abstract String getElementLocalName(BeanT o);
+
+ /**
+ * Type names associated with this {@link JaxBeanInfo}.
+ *
+ * @see #getTypeNames()
+ */
+ private final Object typeName; // either null, QName, or QName[]. save memory since most of them have just one.
+
+ /**
+ * 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.
+ *
+ *
+ */
+ public Collection
+ * Most of the times the type can be determined regardless of the actual
+ * instance, but there's a few exceptions (most notably {@link XMLGregorianCalendar}),
+ * so as a general rule we need an instance to determine it.
+ */
+ public QName getTypeName(@NotNull BeanT instance) {
+ if(typeName==null) return null;
+ if(typeName instanceof QName) return (QName)typeName;
+ return ((QName[])typeName)[0];
+ }
+
+ /**
+ * Creates a new instance of the bean.
+ *
+ *
+ * This operation is only supported when {@link #isImmutable} is false.
+ *
+ * @param context
+ * Sometimes the created bean remembers the corresponding source location,
+ */
+ public abstract BeanT createInstance(UnmarshallingContext context) throws IllegalAccessException, InvocationTargetException, InstantiationException, 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.
+ *
+ * @param context
+ * used for reporting any errors.
+ *
+ * @return
+ * 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 SAXException
+ * as a result of reporting an error, the context may throw a {@link SAXException}.
+ */
+ public abstract boolean reset( BeanT o, UnmarshallingContext context ) throws SAXException;
+
+ /**
+ * Gets the ID value of the given bean, if it has an ID value.
+ * Otherwise return null.
+ */
+ public abstract String getId(BeanT o, XMLSerializer target) throws SAXException;
+
+ /**
+ * Serializes child elements and texts into the specified target.
+ */
+ public abstract void serializeBody( BeanT o, XMLSerializer target ) throws SAXException, IOException, XMLStreamException;
+
+ /**
+ * Serializes attributes into the specified target.
+ */
+ public abstract void serializeAttributes( BeanT o, XMLSerializer target ) throws SAXException, IOException, 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 {@link #serializeBody(Object, XMLSerializer)}.
+ */
+ public abstract void serializeRoot( BeanT o, XMLSerializer target ) throws SAXException, IOException, XMLStreamException;
+
+ /**
+ * Declares all the namespace URIs this object is using at
+ * its top-level scope into the specified target.
+ */
+ public abstract void serializeURIs( BeanT o, XMLSerializer target ) throws SAXException;
+
+ /**
+ * Gets the {@link Loader} that will unmarshall the given object.
+ *
+ * @param context
+ * The {@link JAXBContextImpl} object that governs this object.
+ * This object is taken as a parameter so that {@link 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.)
+ *
+ * @param typeSubstitutionCapable
+ * If true, the returned {@link 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 {@link Loader} doesn't look for @xsi:type.
+ * @return
+ * must return non-null valid object
+ */
+ public abstract Loader getLoader(JAXBContextImpl context, boolean typeSubstitutionCapable);
+
+ /**
+ * If the bean's representation in XML is just a text,
+ * this method return a {@link Transducer} that lets you convert
+ * values between the text and the bean.
+ */
+ public abstract Transducer