1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/src/share/jaxws_classes/com/sun/xml/internal/org/jvnet/staxex/XMLStreamWriterEx.java Tue Mar 06 16:09:35 2012 -0800
1.3 @@ -0,0 +1,154 @@
1.4 +/*
1.5 + * Copyright (c) 1997, 2010, Oracle and/or its affiliates. All rights reserved.
1.6 + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
1.7 + *
1.8 + * This code is free software; you can redistribute it and/or modify it
1.9 + * under the terms of the GNU General Public License version 2 only, as
1.10 + * published by the Free Software Foundation. Oracle designates this
1.11 + * particular file as subject to the "Classpath" exception as provided
1.12 + * by Oracle in the LICENSE file that accompanied this code.
1.13 + *
1.14 + * This code is distributed in the hope that it will be useful, but WITHOUT
1.15 + * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
1.16 + * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
1.17 + * version 2 for more details (a copy is included in the LICENSE file that
1.18 + * accompanied this code).
1.19 + *
1.20 + * You should have received a copy of the GNU General Public License version
1.21 + * 2 along with this work; if not, write to the Free Software Foundation,
1.22 + * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
1.23 + *
1.24 + * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
1.25 + * or visit www.oracle.com if you need additional information or have any
1.26 + * questions.
1.27 + */
1.28 +
1.29 +package com.sun.xml.internal.org.jvnet.staxex;
1.30 +
1.31 +import javax.activation.DataHandler;
1.32 +import javax.xml.stream.XMLStreamException;
1.33 +import javax.xml.stream.XMLStreamWriter;
1.34 +import java.io.OutputStream;
1.35 +
1.36 +/**
1.37 + * {@link XMLStreamWriter} extended to support XOP.
1.38 + *
1.39 + * <p>
1.40 + * Some infoset serializer (such as XOP encoder, FastInfoset) uses a format
1.41 + * that can represent binary data more efficiently than base64 encoding.
1.42 + * Such infoset serializer may choose to implement this interface, to allow
1.43 + * the caller to pass in binary data more efficiently without first converting
1.44 + * it to binary data.
1.45 + *
1.46 + * <p>
1.47 + * Callers capable of using this interface can see if the serializer supports
1.48 + * it by simply downcasting {@link XMLStreamWriter} to {@link XMLStreamWriterEx}.
1.49 + *
1.50 + * <h2>TODO</h2>
1.51 + * <ol>
1.52 + * <li>
1.53 + * Add methods to write other primitive types, such as hex and integers
1.54 + * (and arrays of).
1.55 + * A textual implementation would write characters in accordance
1.56 + * to the canonical lexical definitions specified in W3C XML Schema: datatypes.
1.57 + * A MTOM implementation would write characters except for the case where octets
1.58 + * that would otherwise be base64 encoded when using the textual implementation.
1.59 + * A Fast Infoset implementation would encoded binary data the primitive types in
1.60 + * binary form.
1.61 + * <li>
1.62 + * Consider renaming writeBinary to writeBytesAsBase64 to be consistent with
1.63 + * infoset abstraction.
1.64 + * <li>
1.65 + * Add the ability to writeStart and writeEnd on attributes so that the same
1.66 + * methods for writing primitive types (and characters, which will require new methods)
1.67 + * can be used for writing attribute values as well as element content.
1.68 + * </ol>
1.69 + *
1.70 + * @see XMLStreamReaderEx
1.71 + * @author Kohsuke Kawaguchi
1.72 + * @author Paul Sandoz
1.73 + */
1.74 +public interface XMLStreamWriterEx extends XMLStreamWriter {
1.75 +
1.76 + /**
1.77 + * Write the binary data.
1.78 + *
1.79 + * <p>
1.80 + * Conceptually (infoset-wise), this produces the base64-encoded binary data on the
1.81 + * output. But this allows implementations like FastInfoset or XOP to do the smart
1.82 + * thing.
1.83 + *
1.84 + * <p>
1.85 + * The use of this method has some restriction to support XOP. Namely, this method
1.86 + * must be invoked as a sole content of an element.
1.87 + *
1.88 + * <p>
1.89 + * (data,start,len) triplet identifies the binary data to be written.
1.90 + * After the method invocation, the callee owns the buffer.
1.91 + *
1.92 + * @param contentType
1.93 + * this mandatory parameter identifies the MIME type of the binary data.
1.94 + * If the MIME type isn't known by the caller, "application/octet-stream" can
1.95 + * be always used to indicate "I don't know." Never null.
1.96 + */
1.97 + void writeBinary(byte[] data, int start, int len, String contentType) throws XMLStreamException;
1.98 +
1.99 + /**
1.100 + * Writes the binary data.
1.101 + *
1.102 + * <p>
1.103 + * This method works like the {@link #writeBinary(byte[], int, int, String)} method,
1.104 + * except that it takes the binary data in the form of {@link DataHandler}, which
1.105 + * contains a MIME type ({@link DataHandler#getContentType()} as well as the payload
1.106 + * {@link DataHandler#getInputStream()}.
1.107 + *
1.108 + * @param data
1.109 + * always non-null. After this method call, the callee owns the data handler.
1.110 + */
1.111 + void writeBinary(DataHandler data) throws XMLStreamException;
1.112 +
1.113 + /**
1.114 + * Writes the binary data.
1.115 + *
1.116 + * <p>
1.117 + * This version of the writeBinary method allows the caller to produce
1.118 + * the binary data by writing it to {@link OutputStream}.
1.119 + *
1.120 + * <p>
1.121 + * It is the caller's responsibility to write and close
1.122 + * a stream before it invokes any other methods on {@link XMLStreamWriter}.
1.123 + *
1.124 + * TODO: experimental. appreciate feedback
1.125 + * @param contentType
1.126 + * See the content-type parameter of
1.127 + * {@link #writeBinary(byte[], int, int, String)}. Must not be null.
1.128 + *
1.129 + * @return
1.130 + * always return a non-null {@link OutputStream}.
1.131 + */
1.132 + OutputStream writeBinary(String contentType) throws XMLStreamException;
1.133 +
1.134 + /**
1.135 + * Writes like {@link #writeCharacters(String)} but hides
1.136 + * actual data format.
1.137 + *
1.138 + * @param data
1.139 + * The {@link CharSequence} that represents the
1.140 + * character infoset items to be written.
1.141 + *
1.142 + * <p>
1.143 + * The {@link CharSequence} is normally a {@link String},
1.144 + * but can be any other {@link CharSequence} implementation.
1.145 + * For binary data, however, use of {@link Base64Data} is
1.146 + * recommended (so that the consumer interested in seeing it
1.147 + * as binary data may take advantage of mor efficient
1.148 + * data representation.)
1.149 + *
1.150 + */
1.151 + void writePCDATA(CharSequence data) throws XMLStreamException;
1.152 +
1.153 + /**
1.154 + * {@inheritDoc}
1.155 + */
1.156 + NamespaceContextEx getNamespaceContext();
1.157 +}
