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