1/* 2 * Copyright (c) 1997, 2013, Oracle and/or its affiliates. All rights reserved. 3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. 4 * 5 * This code is free software; you can redistribute it and/or modify it 6 * under the terms of the GNU General Public License version 2 only, as 7 * published by the Free Software Foundation. Oracle designates this 8 * particular file as subject to the "Classpath" exception as provided 9 * by Oracle in the LICENSE file that accompanied this code. 10 * 11 * This code is distributed in the hope that it will be useful, but WITHOUT 12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License 14 * version 2 for more details (a copy is included in the LICENSE file that 15 * accompanied this code). 16 * 17 * You should have received a copy of the GNU General Public License version 18 * 2 along with this work; if not, write to the Free Software Foundation, 19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. 20 * 21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA 22 * or visit www.oracle.com if you need additional information or have any 23 * questions. 24 */ 25 26package com.sun.xml.internal.org.jvnet.staxex; 27 28import javax.activation.DataHandler; 29import javax.xml.stream.XMLStreamException; 30import javax.xml.stream.XMLStreamWriter; 31import java.io.OutputStream; 32 33/** 34 * {@link XMLStreamWriter} extended to support XOP. 35 * 36 * <p> 37 * Some infoset serializer (such as XOP encoder, FastInfoset) uses a format 38 * that can represent binary data more efficiently than base64 encoding. 39 * Such infoset serializer may choose to implement this interface, to allow 40 * the caller to pass in binary data more efficiently without first converting 41 * it to binary data. 42 * 43 * <p> 44 * Callers capable of using this interface can see if the serializer supports 45 * it by simply downcasting {@link XMLStreamWriter} to {@link XMLStreamWriterEx}. 46 * 47 * <h2>TODO</h2> 48 * <ol> 49 * <li> 50 * Add methods to write other primitive types, such as hex and integers 51 * (and arrays of). 52 * A textual implementation would write characters in accordance 53 * to the canonical lexical definitions specified in W3C XML Schema: datatypes. 54 * A MTOM implementation would write characters except for the case where octets 55 * that would otherwise be base64 encoded when using the textual implementation. 56 * A Fast Infoset implementation would encoded binary data the primitive types in 57 * binary form. 58 * <li> 59 * Consider renaming writeBinary to writeBytesAsBase64 to be consistent with 60 * infoset abstraction. 61 * <li> 62 * Add the ability to writeStart and writeEnd on attributes so that the same 63 * methods for writing primitive types (and characters, which will require new methods) 64 * can be used for writing attribute values as well as element content. 65 * </ol> 66 * 67 * @see XMLStreamReaderEx 68 * @author Kohsuke Kawaguchi 69 * @author Paul Sandoz 70 */ 71public interface XMLStreamWriterEx extends XMLStreamWriter { 72 73 /** 74 * Write the binary data. 75 * 76 * <p> 77 * Conceptually (infoset-wise), this produces the base64-encoded binary data on the 78 * output. But this allows implementations like FastInfoset or XOP to do the smart 79 * thing. 80 * 81 * <p> 82 * The use of this method has some restriction to support XOP. Namely, this method 83 * must be invoked as a sole content of an element. 84 * 85 * <p> 86 * (data,start,len) triplet identifies the binary data to be written. 87 * After the method invocation, the callee owns the buffer. 88 * 89 * @param contentType 90 * this mandatory parameter identifies the MIME type of the binary data. 91 * If the MIME type isn't known by the caller, "application/octet-stream" can 92 * be always used to indicate "I don't know." Never null. 93 */ 94 void writeBinary(byte[] data, int start, int len, String contentType) throws XMLStreamException; 95 96 /** 97 * Writes the binary data. 98 * 99 * <p> 100 * This method works like the {@link #writeBinary(byte[], int, int, String)} method, 101 * except that it takes the binary data in the form of {@link DataHandler}, which 102 * contains a MIME type ({@link DataHandler#getContentType()} as well as the payload 103 * {@link DataHandler#getInputStream()}. 104 * 105 * @param data 106 * always non-null. After this method call, the callee owns the data handler. 107 */ 108 void writeBinary(DataHandler data) throws XMLStreamException; 109 110 /** 111 * Writes the binary data. 112 * 113 * <p> 114 * This version of the writeBinary method allows the caller to produce 115 * the binary data by writing it to {@link OutputStream}. 116 * 117 * <p> 118 * It is the caller's responsibility to write and close 119 * a stream before it invokes any other methods on {@link XMLStreamWriter}. 120 * 121 * TODO: experimental. appreciate feedback 122 * @param contentType 123 * See the content-type parameter of 124 * {@link #writeBinary(byte[], int, int, String)}. Must not be null. 125 * 126 * @return 127 * always return a non-null {@link OutputStream}. 128 */ 129 OutputStream writeBinary(String contentType) throws XMLStreamException; 130 131 /** 132 * Writes like {@link #writeCharacters(String)} but hides 133 * actual data format. 134 * 135 * @param data 136 * The {@link CharSequence} that represents the 137 * character infoset items to be written. 138 * 139 * <p> 140 * The {@link CharSequence} is normally a {@link String}, 141 * but can be any other {@link CharSequence} implementation. 142 * For binary data, however, use of {@link Base64Data} is 143 * recommended (so that the consumer interested in seeing it 144 * as binary data may take advantage of mor efficient 145 * data representation.) 146 * 147 */ 148 void writePCDATA(CharSequence data) throws XMLStreamException; 149 150 /** 151 * {@inheritDoc} 152 */ 153 NamespaceContextEx getNamespaceContext(); 154} 155