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 26 package com.sun.xml.internal.org.jvnet.staxex; 27 28 import javax.xml.stream.XMLStreamReader; 29 import javax.xml.stream.XMLStreamException; 30 31 /** 32 * {@link XMLStreamReader} extended for reading binary data. 33 * 34 * <p> 35 * Some producer of infoset (in particular, such as FastInfoset, 36 * XOP decoder), uses a native format that enables efficient 37 * treatment of binary data. For ordinary infoset consumer 38 * (that just uses {@link XMLStreamReader}, those binary data 39 * will just look like base64-encoded string, but this interface 40 * allows consumers of such infoset to access this raw binary data. 41 * Such infoset producer may choose to implement this additoinal 42 * interface, to expose this functionality. 43 * 44 * <p> 45 * Consumers that are capable of using this interface can query 46 * {@link XMLStreamReader} if it supports this by simply downcasting 47 * it to this interface like this: 48 * 49 * <pre> 50 * XMLStreamReader reader = ...; 51 * if( reader instanceof XMLStreamReaderEx ) { 52 * // this reader supports binary data exchange 53 * ... 54 * } else { 55 * // noop 56 * ... 57 * } 58 * </pre> 59 * 60 * <p> 61 * Also note that it is also allowed for the infoset producer 62 * to implement this interface in such a way that {@link #getPCDATA()} 63 * always delegate to {@link #getText()}, although it's not desirable. 64 * 65 * <p> 66 * This interface is a private contract between such producers 67 * and consumers to allow them to exchange binary data without 68 * converting it to base64. 69 * 70 * @see XMLStreamWriterEx 71 * @author Kohsuke Kawaguchi 72 * @author Paul Sandoz 73 */ 74 public interface XMLStreamReaderEx extends XMLStreamReader { 75 ///** 76 // * Works like {@link XMLStreamReader#getText()} 77 // * but returns text as {@link DataSource}. 78 // * 79 // * <p> 80 // * This method can be invoked whenever {@link XMLStreamReader#getText()} 81 // * can be invoked. Invoking this method means the caller is assuming 82 // * that the text is (conceptually) base64-encoded binary data. 83 // * 84 // * <p> 85 // * This abstraction is necessary to treat XOP as infoset encoding. 86 // * That is, you can either access the XOP-attached binary through 87 // * {@link XMLStreamReader#getText()} (in which case you'll see the 88 // * base64 encoded string), or you can access it as a binary data 89 // * directly by using this method. 90 // * 91 // * <p> 92 // * Note that even if you are reading from non XOP-aware {@link XMLStreamReader}, 93 // * this method must be still supported; if the reader is pointing 94 // * to a text, this method is responsible for decoding base64 and 95 // * producing a {@link DataHandler} with "application/octet-stream" 96 // * as the content type. 97 // * 98 // * @return 99 // * always non-null valid object. 100 // * Invocations of this method may return the same object as long 101 // * as the {@link XMLStreamReader#next()} method is not used, 102 // * but otherwise {@link DataSource} object returned from this method 103 // * is considered to be owned by the client, and therefore it shouldn't 104 // * be reused by the implementation of this method. 105 // * 106 // * <p> 107 // * The returned {@link DataSource} is read-only, and the caller 108 // * must not invoke {@link DataSource#getOutputStream()}. 109 // * 110 // * @throws IllegalStateException 111 // * if the parser is not pointing at characters infoset item. 112 // * @throws XMLStreamException 113 // * if the parser points to text but text is not base64-encoded text, 114 // * or if some other parsing error occurs (such as if the <xop:Include> 115 // * points to a non-existing attachment.) 116 // * 117 // * <p> 118 // * It is also OK for this method to return successfully, only to fail 119 // * during an {@link InputStream} is read from {@link DataSource}. 120 // */ 121 //DataSource getTextAsDataHandler() throws XMLStreamException; 122 123 ///** 124 // * Works like {@link XMLStreamReader#getText()} 125 // * but returns text as {@link byte[]}. 126 // * 127 // * <p> 128 // * The contract of this method is mostly the same as 129 // * {@link #getTextAsDataHandler()}, except that this 130 // * method returns the binary datas as an exact-size byte[]. 131 // * 132 // * <p> 133 // * This method is also not capable of reporting the content type 134 // * of this binary data, even if it is available to the parser. 135 // * 136 // * @see #getTextAsDataHandler() 137 // */ 138 //byte[] getTextAsByteArray() throws XMLStreamException; 139 140 /** 141 * Works like {@link #getText()} 142 * but hides the actual data representation. 143 * 144 * @return 145 * The {@link CharSequence} that represents the 146 * character infoset items at the current position. 147 * 148 * <p> 149 * The {@link CharSequence} is normally a {@link String}, 150 * but can be any other {@link CharSequence} implementation. 151 * For binary data, however, use of {@link Base64Data} is 152 * recommended (so that the consumer interested in seeing it 153 * as binary data may take advantage of mor efficient 154 * data representation.) 155 * 156 * <p> 157 * The object returned from this method belongs to the parser, 158 * and its content is guaranteed to be the same only until 159 * the {@link #next()} method is invoked. 160 * 161 * @throws IllegalStateException 162 * if the parser is not pointing at characters infoset item. 163 * 164 * TODO: 165 * fix the dependency to JAXB internal class. 166 */ 167 CharSequence getPCDATA() throws XMLStreamException; 168 169 /** 170 * {@inheritDoc} 171 */ 172 NamespaceContextEx getNamespaceContext(); 173 174 /** 175 * Works like {@link #getElementText()} but trims the leading 176 * and trailing whitespace. 177 * 178 * <p> 179 * The parser can often do this more efficiently than 180 * {@code getElementText().trim()}. 181 * 182 * @see #getElementText() 183 */ 184 String getElementTextTrim() throws XMLStreamException; 185 }