Top Description Methods
org.jvnet.staxex

public Interface XMLStreamWriterEx

extends XMLStreamWriter
Imports
jakarta.activation.DataHandler, javax.xml.stream.XMLStreamException, .XMLStreamWriter, java.io.OutputStream
XMLStreamWriter extended to support XOP.

Some infoset serializer (such as XOP encoder, FastInfoset) uses a format that can represent binary data more efficiently than base64 encoding. Such infoset serializer may choose to implement this interface, to allow the caller to pass in binary data more efficiently without first converting it to binary data.

Callers capable of using this interface can see if the serializer supports it by simply downcasting XMLStreamWriter to XMLStreamWriterEx.

TODO

  1. Add methods to write other primitive types, such as hex and integers (and arrays of). A textual implementation would write characters in accordance to the canonical lexical definitions specified in W3C XML Schema: datatypes. A MTOM implementation would write characters except for the case where octets that would otherwise be base64 encoded when using the textual implementation. A Fast Infoset implementation would encoded binary data the primitive types in binary form.
  2. Consider renaming writeBinary to writeBytesAsBase64 to be consistent with infoset abstraction.
  3. Add the ability to writeStart and writeEnd on attributes so that the same methods for writing primitive types (and characters, which will require new methods) can be used for writing attribute values as well as element content.
Authors
Kohsuke Kawaguchi, Paul Sandoz
See Also
XMLStreamReaderEx

Method Summary

Modifier and TypeMethod and Description
public NamespaceContextEx
getNamespaceContext()

Redeclares javax.xml.stream.XMLStreamWriter.getNamespaceContext.

Returns the current namespace context.

public void
writeBinary(byte[] data, int start, int len, String
this mandatory parameter identifies the MIME type of the binary data. If the MIME type isn't known by the caller, "application/octet-stream" can be always used to indicate "I don't know." Never null.
contentType)

Write the binary data.

public void
writeBinary(DataHandler
always non-null. After this method call, the callee owns the data handler.
data)

Writes the binary data.

public OutputStream

Returns:

always return a non-null OutputStream.
writeBinary(String
See the content-type parameter of writeBinary(byte[], int, int, String). Must not be null.
contentType)

Writes the binary data.

public void
writePCDATA(CharSequence
The CharSequence that represents the character infoset items to be written.

The CharSequence is normally a String, but can be any other CharSequence implementation. For binary data, however, use of Base64Data is recommended (so that the consumer interested in seeing it as binary data may take advantage of mor efficient data representation.)

data)

Writes like writeCharacters(String) but hides actual data format.

Inherited from javax.xml.stream.XMLStreamWriter:
closeflushgetPrefixgetPropertysetDefaultNamespacesetNamespaceContextsetPrefixwriteAttributewriteAttributewriteAttributewriteCDatawriteCharacterswriteCharacterswriteCommentwriteDefaultNamespacewriteDTDwriteEmptyElementwriteEmptyElementwriteEmptyElementwriteEndDocumentwriteEndElementwriteEntityRefwriteNamespacewriteProcessingInstructionwriteProcessingInstructionwriteStartDocumentwriteStartDocumentwriteStartDocumentwriteStartElementwriteStartElementwriteStartElement

Method Detail

getNamespaceContextback to summary
public NamespaceContextEx getNamespaceContext()

Redeclares javax.xml.stream.XMLStreamWriter.getNamespaceContext.

Doc from javax.xml.stream.XMLStreamWriter.getNamespaceContext.

Returns the current namespace context.

Annotations
@Override
writeBinaryback to summary
public void writeBinary(byte[] data, int start, int len, String contentType) throws XMLStreamException

Write the binary data.

Conceptually (infoset-wise), this produces the base64-encoded binary data on the output. But this allows implementations like FastInfoset or XOP to do the smart thing.

The use of this method has some restriction to support XOP. Namely, this method must be invoked as a sole content of an element.

(data,start,len) triplet identifies the binary data to be written. After the method invocation, the callee owns the buffer.

Parameters
contentType:String

this mandatory parameter identifies the MIME type of the binary data. If the MIME type isn't known by the caller, "application/octet-stream" can be always used to indicate "I don't know." Never null.

Exceptions
XMLStreamException:
for errors
writeBinaryback to summary
public void writeBinary(DataHandler data) throws XMLStreamException

Writes the binary data.

This method works like the writeBinary(byte[], int, int, String) method, except that it takes the binary data in the form of DataHandler, which contains a MIME type (DataHandler#getContentType() as well as the payload DataHandler#getInputStream().

Parameters
data:DataHandler

always non-null. After this method call, the callee owns the data handler.

Exceptions
XMLStreamException:
for errors
writeBinaryback to summary
public OutputStream writeBinary(String contentType) throws XMLStreamException

Writes the binary data.

This version of the writeBinary method allows the caller to produce the binary data by writing it to OutputStream.

It is the caller's responsibility to write and close a stream before it invokes any other methods on XMLStreamWriter.

Todo

experimental. appreciate feedback

Parameters
contentType:String

See the content-type parameter of writeBinary(byte[], int, int, String). Must not be null.

Returns:OutputStream

always return a non-null OutputStream.

Exceptions
XMLStreamException:
for errors
writePCDATAback to summary
public void writePCDATA(CharSequence data) throws XMLStreamException

Writes like writeCharacters(String) but hides actual data format.

Parameters
data:CharSequence

The CharSequence that represents the character infoset items to be written.

The CharSequence is normally a String, but can be any other CharSequence implementation. For binary data, however, use of Base64Data is recommended (so that the consumer interested in seeing it as binary data may take advantage of mor efficient data representation.)

Exceptions
XMLStreamException:
for errors