Xml to java marshalling

The Marshaller class is responsible for governing the process of serializing Java content trees back into XML data. It provides the basic marshalling methods: Assume the following setup code for all following code fragments:

JAXBContext jc = JAXBContext.newInstance( "com.acme.foo" ); Unmarshaller u = jc.createUnmarshaller(); Object element = u.unmarshal( new File( "foo.xml" ) ); Marshaller m = jc.createMarshaller();

OutputStream os = new FileOutputStream( "nosferatu.xml" ); m.marshal( element, os );

// assume MyContentHandler instanceof ContentHandler m.marshal( element, new MyContentHandler() );

DocumentBuilderFactory dbf = DocumentBuilderFactory.newInstance(); dbf.setNamespaceAware(true); DocumentBuilder db = dbf.newDocumentBuilder(); Document doc = db.newDocument(); m.marshal( element, doc );

m.marshal( element, System.out );

m.marshal( element, new PrintWriter( System.out ) );

// assume MyContentHandler instanceof ContentHandler SAXResult result = new SAXResult( new MyContentHandler() ); m.marshal( element, result );

DOMResult result = new DOMResult(); m.marshal( element, result );

StreamResult result = new StreamResult( System.out ); m.marshal( element, result );

XMLStreamWriter xmlStreamWriter = XMLOutputFactory.newInstance().createXMLStreamWriter( . ); m.marshal( element, xmlStreamWriter );

XMLEventWriter xmlEventWriter = XMLOutputFactory.newInstance().createXMLEventWriter( . ); m.marshal( element, xmlEventWriter );

The first parameter of the overloaded Marshaller.marshal(java.lang.Object, . ) methods must be a JAXB element as computed by JAXBIntrospector.isElement(java.lang.Object) ; otherwise, a Marshaller.marshal method must throw a MarshalException . There exist two mechanisms to enable marshalling an instance that is not a JAXB element. One method is to wrap the instance as a value of a JAXBElement , and pass the wrapper element as the first parameter to a Marshaller.marshal method. For java to schema binding, it is also possible to simply annotate the instance’s class with @ XmlRootElement .

Client applications are not required to validate the Java content tree prior to calling any of the marshal API’s. Furthermore, there is no requirement that the Java content tree be valid with respect to its original schema in order to marshal it back into XML data. Different JAXB Providers will support marshalling invalid Java content trees at varying levels, however all JAXB Providers must be able to marshal a valid content tree back to XML data. A JAXB Provider must throw a MarshalException when it is unable to complete the marshal operation due to invalid content. Some JAXB Providers will fully allow marshalling invalid content, others will fail on the first validation error. Even when schema validation is not explictly enabled for the marshal operation, it is possible that certain types of validation events will be detected during the operation. Validation events will be reported to the registered event handler. If the client application has not registered an event handler prior to invoking one of the marshal API’s, then events will be delivered to a default event handler which will terminate the marshal operation after encountering the first error or fatal error. Note that for JAXB 2.0 and later versions, DefaultValidationEventHandler is no longer used.

marshal(Object,ContentHandler) — the Marshaller won’t invoke ContentHandler.startDocument() and ContentHandler.endDocument() .
marshal(Object,Node) — the property has no effect on this API.
marshal(Object,OutputStream) — the Marshaller won’t generate an xml declaration.
marshal(Object,Writer) — the Marshaller won’t generate an xml declaration.
marshal(Object,Result) — depends on the kind of Result object, see semantics for Node, ContentHandler, and Stream APIs
marshal(Object,XMLEventWriter) — the Marshaller will not generate XMLStreamConstants.START_DOCUMENT and XMLStreamConstants.END_DOCUMENT events.
marshal(Object,XMLStreamWriter) — the Marshaller will not generate XMLStreamConstants.START_DOCUMENT and XMLStreamConstants.END_DOCUMENT events.

Marshal Event Callbacks

«The Marshaller provides two styles of callback mechanisms that allow application specific processing during key points in the unmarshalling process. In ‘class defined’ event callbacks, application specific code placed in JAXB mapped classes is triggered during marshalling. ‘External listeners’ allow for centralized processing of marshal events in one callback method rather than by type event callbacks.

Class defined event callback methods allow any JAXB mapped class to specify its own specific callback methods by defining methods with the following method signatures:

// Invoked by Marshaller after it has created an instance of this object. boolean beforeMarshal(Marshaller); // Invoked by Marshaller after it has marshalled all properties of this object. void afterMarshal(Marshaller);

The class defined event callback methods should be used when the callback method requires access to non-public methods and/or fields of the class.

The external listener callback mechanism enables the registration of a Marshaller.Listener instance with a setListener(Listener) . The external listener receives all callback events, allowing for more centralized processing than per class defined callback methods.

The ‘class defined’ and external listener event callback methods are independent of each other, both can be called for one event. The invocation ordering when both listener callback methods exist is defined in Marshaller.Listener.beforeMarshal(Object) and Marshaller.Listener.afterMarshal(Object) .

An event callback method throwing an exception terminates the current marshal process.

Nested Class Summary

Field Summary

The name of the property used to specify whether or not the marshalled XML data is formatted with linefeeds and indentation.

The name of the property used to specify whether or not the marshaller will generate document level events (ie calling startDocument or endDocument).

The name of the property used to specify the xsi:noNamespaceSchemaLocation attribute value to place in the marshalled XML output.

The name of the property used to specify the xsi:schemaLocation attribute value to place in the marshalled XML output.

Method Summary

Associate a context that enables binary data within an XML document to be transmitted as XML-binary optimized attachment.

Specify the JAXP 1.3 Schema object that should be used to validate subsequent marshal operations against.

Field Detail

JAXB_ENCODING

JAXB_FORMATTED_OUTPUT

The name of the property used to specify whether or not the marshalled XML data is formatted with linefeeds and indentation.

JAXB_SCHEMA_LOCATION

The name of the property used to specify the xsi:schemaLocation attribute value to place in the marshalled XML output.

JAXB_NO_NAMESPACE_SCHEMA_LOCATION

static final String JAXB_NO_NAMESPACE_SCHEMA_LOCATION

The name of the property used to specify the xsi:noNamespaceSchemaLocation attribute value to place in the marshalled XML output.

JAXB_FRAGMENT

The name of the property used to specify whether or not the marshaller will generate document level events (ie calling startDocument or endDocument).

Method Detail

marshal

void marshal(Object jaxbElement, Result result) throws JAXBException

Marshal the content tree rooted at jaxbElement into the specified javax.xml.transform.Result. All JAXB Providers must at least support DOMResult , SAXResult , and StreamResult . It can support other derived classes of Result as well.

marshal

void marshal(Object jaxbElement, OutputStream os) throws JAXBException

marshal

void marshal(Object jaxbElement, File output) throws JAXBException

marshal

void marshal(Object jaxbElement, Writer writer) throws JAXBException

marshal

void marshal(Object jaxbElement, ContentHandler handler) throws JAXBException

marshal

void marshal(Object jaxbElement, Node node) throws JAXBException

marshal

void marshal(Object jaxbElement, XMLStreamWriter writer) throws JAXBException

marshal

void marshal(Object jaxbElement, XMLEventWriter writer) throws JAXBException

getNode

Node getNode(Object contentTree) throws JAXBException

Get a DOM tree view of the content tree(Optional). If the returned DOM tree is updated, these changes are also visible in the content tree. Use marshal(Object, org.w3c.dom.Node) to force a deep copy of the content tree to a DOM representation.

setProperty

void setProperty(String name, Object value) throws PropertyException

Set the particular property in the underlying implementation of Marshaller. This method can only be used to set one of the standard JAXB defined properties above or a provider specific property. Attempting to set an undefined property will result in a PropertyException being thrown. See Supported Properties.

getProperty

Object getProperty(String name) throws PropertyException

Get the particular property in the underlying implementation of Marshaller. This method can only be used to get one of the standard JAXB defined properties above or a provider specific property. Attempting to get an undefined property will result in a PropertyException being thrown. See Supported Properties.

setEventHandler

void setEventHandler(ValidationEventHandler handler) throws JAXBException

Allow an application to register a validation event handler. The validation event handler will be called by the JAXB Provider if any validation errors are encountered during calls to any of the marshal API’s. If the client application does not register a validation event handler before invoking one of the marshal methods, then validation events will be handled by the default event handler which will terminate the marshal operation after the first error or fatal error is encountered. Calling this method with a null parameter will cause the Marshaller to revert back to the default default event handler.

getEventHandler

ValidationEventHandler getEventHandler() throws JAXBException

setAdapter

Associates a configured instance of XmlAdapter with this marshaller. This is a convenience method that invokes setAdapter(adapter.getClass(),adapter); .

setAdapter

Associates a configured instance of XmlAdapter with this marshaller. Every marshaller internally maintains a Map , which it uses for marshalling classes whose fields/methods are annotated with XmlJavaTypeAdapter . This method allows applications to use a configured instance of XmlAdapter . When an instance of an adapter is not given, a marshaller will create one by invoking its default constructor.

getAdapter

Gets the adapter associated with the specified type. This is the reverse operation of the setAdapter(javax.xml.bind.annotation.adapters.XmlAdapter) method.

setAttachmentMarshaller

Associate a context that enables binary data within an XML document to be transmitted as XML-binary optimized attachment. The attachment is referenced from the XML document content model by content-id URIs(cid) references stored within the xml document.

getAttachmentMarshaller

setSchema

Specify the JAXP 1.3 Schema object that should be used to validate subsequent marshal operations against. Passing null into this method will disable validation. This method allows the caller to validate the marshalled XML as it’s marshalled. Initially this property is set to null.

getSchema

Get the JAXP 1.3 Schema object being used to perform marshal-time validation. If there is no Schema set on the marshaller, then this method will return null indicating that marshal-time validation will not be performed.

setListener

Register marshal event callback Marshaller.Listener with this Marshaller . There is only one Listener per Marshaller. Setting a Listener replaces the previous set Listener. One can unregister current Listener by setting listener to null.

getListener

Источник