org.jvnet.staxex.XMLStreamWriterEx Maven / Gradle / Ivy
Show all versions of webservices-rt Show documentation
/*
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.
*
* Copyright (c) 1997-2012 Oracle and/or its affiliates. All rights reserved.
*
* The contents of this file are subject to the terms of either the GNU
* General Public License Version 2 only ("GPL") or the Common Development
* and Distribution License("CDDL") (collectively, the "License"). You
* may not use this file except in compliance with the License. You can
* obtain a copy of the License at
* http://glassfish.java.net/public/CDDL+GPL_1_1.html
* or packager/legal/LICENSE.txt. See the License for the specific
* language governing permissions and limitations under the License.
*
* When distributing the software, include this License Header Notice in each
* file and include the License file at packager/legal/LICENSE.txt.
*
* GPL Classpath Exception:
* Oracle designates this particular file as subject to the "Classpath"
* exception as provided by Oracle in the GPL Version 2 section of the License
* file that accompanied this code.
*
* Modifications:
* If applicable, add the following below the License Header, with the fields
* enclosed by brackets [] replaced by your own identifying information:
* "Portions Copyright [year] [name of copyright owner]"
*
* Contributor(s):
* If you wish your version of this file to be governed by only the CDDL or
* only the GPL Version 2, indicate your decision by adding "[Contributor]
* elects to include this software in this distribution under the [CDDL or GPL
* Version 2] license." If you don't indicate a single choice of license, a
* recipient has the option to distribute your version of this file under
* either the CDDL, the GPL Version 2 or to extend the choice of license to
* its licensees as provided above. However, if you add GPL Version 2 code
* and therefore, elected the GPL Version 2 license, then the option applies
* only if the new code is made subject to such option by the copyright
* holder.
*/
package org.jvnet.staxex;
import javax.activation.DataHandler;
import javax.xml.stream.XMLStreamException;
import javax.xml.stream.XMLStreamWriter;
import java.io.OutputStream;
/**
* {@link 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 {@link XMLStreamWriter} to {@link XMLStreamWriterEx}.
*
*
TODO
*
* -
* 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.
*
-
* Consider renaming writeBinary to writeBytesAsBase64 to be consistent with
* infoset abstraction.
*
-
* 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.
*
*
* @see XMLStreamReaderEx
* @author Kohsuke Kawaguchi
* @author Paul Sandoz
*/
public interface XMLStreamWriterEx extends XMLStreamWriter {
/**
* 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.
*
* @param contentType
* 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.
*/
void writeBinary(byte[] data, int start, int len, String contentType) throws XMLStreamException;
/**
* Writes the binary data.
*
*
* This method works like the {@link #writeBinary(byte[], int, int, String)} method,
* except that it takes the binary data in the form of {@link DataHandler}, which
* contains a MIME type ({@link DataHandler#getContentType()} as well as the payload
* {@link DataHandler#getInputStream()}.
*
* @param data
* always non-null. After this method call, the callee owns the data handler.
*/
void writeBinary(DataHandler data) throws XMLStreamException;
/**
* Writes the binary data.
*
*
* This version of the writeBinary method allows the caller to produce
* the binary data by writing it to {@link OutputStream}.
*
*
* It is the caller's responsibility to write and close
* a stream before it invokes any other methods on {@link XMLStreamWriter}.
*
* TODO: experimental. appreciate feedback
* @param contentType
* See the content-type parameter of
* {@link #writeBinary(byte[], int, int, String)}. Must not be null.
*
* @return
* always return a non-null {@link OutputStream}.
*/
OutputStream writeBinary(String contentType) throws XMLStreamException;
/**
* Writes like {@link #writeCharacters(String)} but hides
* actual data format.
*
* @param data
* The {@link CharSequence} that represents the
* character infoset items to be written.
*
*
* The {@link CharSequence} is normally a {@link String},
* but can be any other {@link CharSequence} implementation.
* For binary data, however, use of {@link Base64Data} is
* recommended (so that the consumer interested in seeing it
* as binary data may take advantage of mor efficient
* data representation.)
*
*/
void writePCDATA(CharSequence data) throws XMLStreamException;
/**
* {@inheritDoc}
*/
NamespaceContextEx getNamespaceContext();
}