325N/A * Copyright (c) 1997, 2010, Oracle and/or its affiliates. All rights reserved. 325N/A * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. 325N/A * This code is free software; you can redistribute it and/or modify it 325N/A * under the terms of the GNU General Public License version 2 only, as 325N/A * published by the Free Software Foundation. Oracle designates this 325N/A * particular file as subject to the "Classpath" exception as provided 325N/A * by Oracle in the LICENSE file that accompanied this code. 325N/A * This code is distributed in the hope that it will be useful, but WITHOUT 325N/A * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 325N/A * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License 325N/A * version 2 for more details (a copy is included in the LICENSE file that 325N/A * accompanied this code). 325N/A * You should have received a copy of the GNU General Public License version 325N/A * 2 along with this work; if not, write to the Free Software Foundation, 325N/A * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. 325N/A * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA 325N/A * or visit www.oracle.com if you need additional information or have any 325N/A * {@link XMLStreamWriter} extended to support XOP. 325N/A * Some infoset serializer (such as XOP encoder, FastInfoset) uses a format 325N/A * that can represent binary data more efficiently than base64 encoding. 325N/A * Such infoset serializer may choose to implement this interface, to allow 325N/A * the caller to pass in binary data more efficiently without first converting 325N/A * Callers capable of using this interface can see if the serializer supports 325N/A * it by simply downcasting {@link XMLStreamWriter} to {@link XMLStreamWriterEx}. 325N/A * Add methods to write other primitive types, such as hex and integers 325N/A * A textual implementation would write characters in accordance 325N/A * to the canonical lexical definitions specified in W3C XML Schema: datatypes. 325N/A * A MTOM implementation would write characters except for the case where octets 325N/A * that would otherwise be base64 encoded when using the textual implementation. 325N/A * A Fast Infoset implementation would encoded binary data the primitive types in 325N/A * Consider renaming writeBinary to writeBytesAsBase64 to be consistent with 325N/A * Add the ability to writeStart and writeEnd on attributes so that the same 325N/A * methods for writing primitive types (and characters, which will require new methods) 325N/A * can be used for writing attribute values as well as element content. 325N/A * @see XMLStreamReaderEx 325N/A * @author Kohsuke Kawaguchi 325N/A * Write the binary data. 325N/A * Conceptually (infoset-wise), this produces the base64-encoded binary data on the 325N/A * output. But this allows implementations like FastInfoset or XOP to do the smart 325N/A * The use of this method has some restriction to support XOP. Namely, this method 325N/A * must be invoked as a sole content of an element. 325N/A * (data,start,len) triplet identifies the binary data to be written. 325N/A * After the method invocation, the callee owns the buffer. 325N/A * this mandatory parameter identifies the MIME type of the binary data. 325N/A * be always used to indicate "I don't know." Never null. 325N/A * Writes the binary data. 325N/A * This method works like the {@link #writeBinary(byte[], int, int, String)} method, 325N/A * except that it takes the binary data in the form of {@link DataHandler}, which 325N/A * contains a MIME type ({@link DataHandler#getContentType()} as well as the payload 325N/A * {@link DataHandler#getInputStream()}. 325N/A * always non-null. After this method call, the callee owns the data handler. 325N/A * Writes the binary data. 325N/A * This version of the writeBinary method allows the caller to produce 325N/A * the binary data by writing it to {@link OutputStream}. 325N/A * It is the caller's responsibility to write and close 325N/A * a stream before it invokes any other methods on {@link XMLStreamWriter}. 325N/A * TODO: experimental. appreciate feedback 325N/A * See the content-type parameter of 325N/A * {@link #writeBinary(byte[], int, int, String)}. Must not be null. 325N/A * always return a non-null {@link OutputStream}. 325N/A * Writes like {@link #writeCharacters(String)} but hides 325N/A * The {@link CharSequence} that represents the 325N/A * character infoset items to be written. 325N/A * The {@link CharSequence} is normally a {@link String}, 325N/A * but can be any other {@link CharSequence} implementation. 325N/A * For binary data, however, use of {@link Base64Data} is 325N/A * recommended (so that the consumer interested in seeing it 325N/A * as binary data may take advantage of mor efficient 325N/A * data representation.)