aoqi@0: * Each JAXB-bound class has a corresponding {@link JaxBeanInfo} object, aoqi@0: * which performs all the JAXB related operations on behalf of aoqi@0: * the JAXB-bound object. aoqi@0: * aoqi@0: *
aoqi@0: * Given a class, the corresponding {@link JaxBeanInfo} can be located aoqi@0: * via {@link JAXBContextImpl#getBeanInfo(Class,boolean)}. aoqi@0: * aoqi@0: *
aoqi@0: * Typically, {@link JaxBeanInfo} implementations should be generated aoqi@0: * by XJC/JXC. Those impl classes will register themselves to their aoqi@0: * master ObjectFactory class. aoqi@0: * aoqi@0: *
aoqi@0: * The type parameter BeanT is the Java class of the bean that this represents.
aoqi@0: *
aoqi@0: * @author
aoqi@0: * Kohsuke Kawaguchi (kohsuke.kawaguchi@sun.com)
aoqi@0: */
aoqi@0: public abstract class JaxBeanInfo
aoqi@0: * IOW, when a bean info object is requested for T,
aoqi@0: * sometimes the bean info for one of its base classes might be
aoqi@0: * returned.
aoqi@0: */
aoqi@0: public final Class
aoqi@0: * When this method returns true, {@link #getElementNamespaceURI(Object)}
aoqi@0: * and {@link #getElementLocalName(Object)} returns the element name of
aoqi@0: * the bean.
aoqi@0: */
aoqi@0: public final boolean isElement() {
aoqi@0: return (flag&FLAG_IS_ELEMENT)!=0;
aoqi@0: }
aoqi@0:
aoqi@0: /**
aoqi@0: * Returns true if the bean is immutable.
aoqi@0: *
aoqi@0: *
aoqi@0: * If this is true, Binder won't try to ueuse this object, and the unmarshaller
aoqi@0: * won't create a new instance of it before it starts.
aoqi@0: */
aoqi@0: public final boolean isImmutable() {
aoqi@0: return (flag&FLAG_IS_IMMUTABLE)!=0;
aoqi@0: }
aoqi@0:
aoqi@0: /**
aoqi@0: * True if this bean has an element-only content model.
aoqi@0: *
aoqi@0: * If this flag is true, the unmarshaller can work
aoqi@0: * faster by ignoring whitespaces more efficiently.
aoqi@0: */
aoqi@0: public final boolean hasElementOnlyContentModel() {
aoqi@0: return (flag&FLAG_HAS_ELEMENT_ONLY_CONTENTMODEL)!=0;
aoqi@0: }
aoqi@0:
aoqi@0: /**
aoqi@0: * True if this bean has an element-only content model.
aoqi@0: *
aoqi@0: * Should be considered immutable, though I can't mark it final
aoqi@0: * because it cannot be computed in this constructor.
aoqi@0: */
aoqi@0: protected final void hasElementOnlyContentModel(boolean value) {
aoqi@0: if(value)
aoqi@0: flag |= FLAG_HAS_ELEMENT_ONLY_CONTENTMODEL;
aoqi@0: else
aoqi@0: flag &= ~FLAG_HAS_ELEMENT_ONLY_CONTENTMODEL;
aoqi@0: }
aoqi@0:
aoqi@0: public boolean isNilIncluded() {
aoqi@0: return isNilIncluded;
aoqi@0: }
aoqi@0:
aoqi@0: /**
aoqi@0: * This method is used to determine which of the sub-classes should be
aoqi@0: * interrogated for the existence of lifecycle methods.
aoqi@0: *
aoqi@0: * @return true if the un|marshaller should look for lifecycle methods
aoqi@0: * on this beanInfo, false otherwise.
aoqi@0: */
aoqi@0: public boolean lookForLifecycleMethods() {
aoqi@0: return (flag&FLAG_HAS_LIFECYCLE_EVENTS)!=0;
aoqi@0: }
aoqi@0:
aoqi@0: /**
aoqi@0: * Returns the namespace URI portion of the element name,
aoqi@0: * if the bean that this class represents is mapped from/to
aoqi@0: * an XML element.
aoqi@0: *
aoqi@0: * @throws UnsupportedOperationException
aoqi@0: * if {@link #isElement} is false.
aoqi@0: */
aoqi@0: public abstract String getElementNamespaceURI(BeanT o);
aoqi@0:
aoqi@0: /**
aoqi@0: * Returns the local name portion of the element name,
aoqi@0: * if the bean that this class represents is mapped from/to
aoqi@0: * an XML element.
aoqi@0: *
aoqi@0: * @throws UnsupportedOperationException
aoqi@0: * if {@link #isElement} is false.
aoqi@0: */
aoqi@0: public abstract String getElementLocalName(BeanT o);
aoqi@0:
aoqi@0: /**
aoqi@0: * Type names associated with this {@link JaxBeanInfo}.
aoqi@0: *
aoqi@0: * @see #getTypeNames()
aoqi@0: */
aoqi@0: private final Object typeName; // either null, QName, or QName[]. save memory since most of them have just one.
aoqi@0:
aoqi@0: /**
aoqi@0: * Returns XML Schema type names if the bean is mapped from
aoqi@0: * a complex/simple type of XML Schema.
aoqi@0: *
aoqi@0: *
aoqi@0: * This is an ugly necessity to correctly handle
aoqi@0: * the type substitution semantics of XML Schema.
aoqi@0: *
aoqi@0: *
aoqi@0: * A single Java class maybe mapped to more than one
aoqi@0: * XML types. All the types listed here are recognized
aoqi@0: * when we are unmarshalling XML.
aoqi@0: *
aoqi@0: *
aoqi@0: * null if the class is not bound to a named schema type.
aoqi@0: *
aoqi@0: *
aoqi@0: */
aoqi@0: public Collection
aoqi@0: * Most of the times the type can be determined regardless of the actual
aoqi@0: * instance, but there's a few exceptions (most notably {@link XMLGregorianCalendar}),
aoqi@0: * so as a general rule we need an instance to determine it.
aoqi@0: */
aoqi@0: public QName getTypeName(@NotNull BeanT instance) {
aoqi@0: if(typeName==null) return null;
aoqi@0: if(typeName instanceof QName) return (QName)typeName;
aoqi@0: return ((QName[])typeName)[0];
aoqi@0: }
aoqi@0:
aoqi@0: /**
aoqi@0: * Creates a new instance of the bean.
aoqi@0: *
aoqi@0: *
aoqi@0: * This operation is only supported when {@link #isImmutable} is false.
aoqi@0: *
aoqi@0: * @param context
aoqi@0: * Sometimes the created bean remembers the corresponding source location,
aoqi@0: */
aoqi@0: public abstract BeanT createInstance(UnmarshallingContext context) throws IllegalAccessException, InvocationTargetException, InstantiationException, SAXException;
aoqi@0:
aoqi@0: /**
aoqi@0: * Resets the object to the initial state, as if the object
aoqi@0: * is created fresh.
aoqi@0: *
aoqi@0: *
aoqi@0: * This is used to reuse an existing object for unmarshalling.
aoqi@0: *
aoqi@0: * @param context
aoqi@0: * used for reporting any errors.
aoqi@0: *
aoqi@0: * @return
aoqi@0: * true if the object was successfuly resetted.
aoqi@0: * False if the object is not resettable, in which case the object will be
aoqi@0: * discarded and new one will be created.
aoqi@0: *
aoqi@0: * If the object is resettable but failed by an error, it should be reported to the context,
aoqi@0: * then return false. If the object is not resettable to begin with, do not report an error.
aoqi@0: *
aoqi@0: * @throws SAXException
aoqi@0: * as a result of reporting an error, the context may throw a {@link SAXException}.
aoqi@0: */
aoqi@0: public abstract boolean reset( BeanT o, UnmarshallingContext context ) throws SAXException;
aoqi@0:
aoqi@0: /**
aoqi@0: * Gets the ID value of the given bean, if it has an ID value.
aoqi@0: * Otherwise return null.
aoqi@0: */
aoqi@0: public abstract String getId(BeanT o, XMLSerializer target) throws SAXException;
aoqi@0:
aoqi@0: /**
aoqi@0: * Serializes child elements and texts into the specified target.
aoqi@0: */
aoqi@0: public abstract void serializeBody( BeanT o, XMLSerializer target ) throws SAXException, IOException, XMLStreamException;
aoqi@0:
aoqi@0: /**
aoqi@0: * Serializes attributes into the specified target.
aoqi@0: */
aoqi@0: public abstract void serializeAttributes( BeanT o, XMLSerializer target ) throws SAXException, IOException, XMLStreamException;
aoqi@0:
aoqi@0: /**
aoqi@0: * Serializes the bean as the root element.
aoqi@0: *
aoqi@0: *
aoqi@0: * In the java-to-schema binding, an object might marshal in two different
aoqi@0: * ways depending on whether it is used as the root of the graph or not.
aoqi@0: * In the former case, an object could marshal as an element, whereas
aoqi@0: * in the latter case, it marshals as a type.
aoqi@0: *
aoqi@0: *
aoqi@0: * This method is used to marshal the root of the object graph to allow
aoqi@0: * this semantics to be implemented.
aoqi@0: *
aoqi@0: *
aoqi@0: * It is doubtful to me if it's a good idea for an object to marshal
aoqi@0: * in two ways depending on the context.
aoqi@0: *
aoqi@0: *
aoqi@0: * For schema-to-java, this is equivalent to {@link #serializeBody(Object, XMLSerializer)}.
aoqi@0: */
aoqi@0: public abstract void serializeRoot( BeanT o, XMLSerializer target ) throws SAXException, IOException, XMLStreamException;
aoqi@0:
aoqi@0: /**
aoqi@0: * Declares all the namespace URIs this object is using at
aoqi@0: * its top-level scope into the specified target.
aoqi@0: */
aoqi@0: public abstract void serializeURIs( BeanT o, XMLSerializer target ) throws SAXException;
aoqi@0:
aoqi@0: /**
aoqi@0: * Gets the {@link Loader} that will unmarshall the given object.
aoqi@0: *
aoqi@0: * @param context
aoqi@0: * The {@link JAXBContextImpl} object that governs this object.
aoqi@0: * This object is taken as a parameter so that {@link JaxBeanInfo} doesn't have
aoqi@0: * to store them on its own.
aoqi@0: *
aoqi@0: * When this method is invoked from within the unmarshaller, tihs parameter can be
aoqi@0: * null (because the loader is constructed already.)
aoqi@0: *
aoqi@0: * @param typeSubstitutionCapable
aoqi@0: * If true, the returned {@link Loader} is capable of recognizing @xsi:type (if necessary)
aoqi@0: * and unmarshals a subtype. This allowes an optimization where this bean info
aoqi@0: * is guaranteed not to have a type substitution.
aoqi@0: * If false, the returned {@link Loader} doesn't look for @xsi:type.
aoqi@0: * @return
aoqi@0: * must return non-null valid object
aoqi@0: */
aoqi@0: public abstract Loader getLoader(JAXBContextImpl context, boolean typeSubstitutionCapable);
aoqi@0:
aoqi@0: /**
aoqi@0: * If the bean's representation in XML is just a text,
aoqi@0: * this method return a {@link Transducer} that lets you convert
aoqi@0: * values between the text and the bean.
aoqi@0: */
aoqi@0: public abstract Transducer