aoqi@0: * Some infoset serializer (such as XOP encoder, FastInfoset) uses a format aoqi@0: * that can represent binary data more efficiently than base64 encoding. aoqi@0: * Such infoset serializer may choose to implement this interface, to allow aoqi@0: * the caller to pass in binary data more efficiently without first converting aoqi@0: * it to binary data. aoqi@0: * aoqi@0: *
aoqi@0: * Callers capable of using this interface can see if the serializer supports aoqi@0: * it by simply downcasting {@link XMLStreamWriter} to {@link XMLStreamWriterEx}. aoqi@0: * aoqi@0: *
aoqi@0: * Conceptually (infoset-wise), this produces the base64-encoded binary data on the aoqi@0: * output. But this allows implementations like FastInfoset or XOP to do the smart aoqi@0: * thing. aoqi@0: * aoqi@0: *
aoqi@0: * The use of this method has some restriction to support XOP. Namely, this method aoqi@0: * must be invoked as a sole content of an element. aoqi@0: * aoqi@0: *
aoqi@0: * (data,start,len) triplet identifies the binary data to be written. aoqi@0: * After the method invocation, the callee owns the buffer. aoqi@0: * aoqi@0: * @param contentType aoqi@0: * this mandatory parameter identifies the MIME type of the binary data. aoqi@0: * If the MIME type isn't known by the caller, "application/octet-stream" can aoqi@0: * be always used to indicate "I don't know." Never null. aoqi@0: */ aoqi@0: void writeBinary(byte[] data, int start, int len, String contentType) throws XMLStreamException; aoqi@0: aoqi@0: /** aoqi@0: * Writes the binary data. aoqi@0: * aoqi@0: *
aoqi@0: * This method works like the {@link #writeBinary(byte[], int, int, String)} method, aoqi@0: * except that it takes the binary data in the form of {@link DataHandler}, which aoqi@0: * contains a MIME type ({@link DataHandler#getContentType()} as well as the payload aoqi@0: * {@link DataHandler#getInputStream()}. aoqi@0: * aoqi@0: * @param data aoqi@0: * always non-null. After this method call, the callee owns the data handler. aoqi@0: */ aoqi@0: void writeBinary(DataHandler data) throws XMLStreamException; aoqi@0: aoqi@0: /** aoqi@0: * Writes the binary data. aoqi@0: * aoqi@0: *
aoqi@0: * This version of the writeBinary method allows the caller to produce aoqi@0: * the binary data by writing it to {@link OutputStream}. aoqi@0: * aoqi@0: *
aoqi@0: * It is the caller's responsibility to write and close aoqi@0: * a stream before it invokes any other methods on {@link XMLStreamWriter}. aoqi@0: * aoqi@0: * TODO: experimental. appreciate feedback aoqi@0: * @param contentType aoqi@0: * See the content-type parameter of aoqi@0: * {@link #writeBinary(byte[], int, int, String)}. Must not be null. aoqi@0: * aoqi@0: * @return aoqi@0: * always return a non-null {@link OutputStream}. aoqi@0: */ aoqi@0: OutputStream writeBinary(String contentType) throws XMLStreamException; aoqi@0: aoqi@0: /** aoqi@0: * Writes like {@link #writeCharacters(String)} but hides aoqi@0: * actual data format. aoqi@0: * aoqi@0: * @param data aoqi@0: * The {@link CharSequence} that represents the aoqi@0: * character infoset items to be written. aoqi@0: * aoqi@0: *
aoqi@0: * The {@link CharSequence} is normally a {@link String}, aoqi@0: * but can be any other {@link CharSequence} implementation. aoqi@0: * For binary data, however, use of {@link Base64Data} is aoqi@0: * recommended (so that the consumer interested in seeing it aoqi@0: * as binary data may take advantage of mor efficient aoqi@0: * data representation.) aoqi@0: * aoqi@0: */ aoqi@0: void writePCDATA(CharSequence data) throws XMLStreamException; aoqi@0: aoqi@0: /** aoqi@0: * {@inheritDoc} aoqi@0: */ aoqi@0: NamespaceContextEx getNamespaceContext(); aoqi@0: }