aoqi@0: * Some producer of infoset (in particular, such as FastInfoset, aoqi@0: * XOP decoder), uses a native format that enables efficient aoqi@0: * treatment of binary data. For ordinary infoset consumer aoqi@0: * (that just uses {@link XMLStreamReader}, those binary data aoqi@0: * will just look like base64-encoded string, but this interface aoqi@0: * allows consumers of such infoset to access this raw binary data. aoqi@0: * Such infoset producer may choose to implement this additoinal aoqi@0: * interface, to expose this functionality. aoqi@0: * aoqi@0: *
aoqi@0: * Consumers that are capable of using this interface can query aoqi@0: * {@link XMLStreamReader} if it supports this by simply downcasting aoqi@0: * it to this interface like this: aoqi@0: * aoqi@0: *
aoqi@0: * XMLStreamReader reader = ...;
aoqi@0: * if( reader instanceof XMLStreamReaderEx ) {
aoqi@0: * // this reader supports binary data exchange
aoqi@0: * ...
aoqi@0: * } else {
aoqi@0: * // noop
aoqi@0: * ...
aoqi@0: * }
aoqi@0: *
aoqi@0: *
aoqi@0: * aoqi@0: * Also note that it is also allowed for the infoset producer aoqi@0: * to implement this interface in such a way that {@link #getPCDATA()} aoqi@0: * always delegate to {@link #getText()}, although it's not desirable. aoqi@0: * aoqi@0: *
aoqi@0: * This interface is a private contract between such producers aoqi@0: * and consumers to allow them to exchange binary data without aoqi@0: * converting it to base64. aoqi@0: * aoqi@0: * @see XMLStreamWriterEx aoqi@0: * @author Kohsuke Kawaguchi aoqi@0: * @author Paul Sandoz aoqi@0: */ aoqi@0: public interface XMLStreamReaderEx extends XMLStreamReader { aoqi@0: ///** aoqi@0: // * Works like {@link XMLStreamReader#getText()} aoqi@0: // * but returns text as {@link DataSource}. aoqi@0: // * aoqi@0: // *
aoqi@0: // * This method can be invoked whenever {@link XMLStreamReader#getText()} aoqi@0: // * can be invoked. Invoking this method means the caller is assuming aoqi@0: // * that the text is (conceptually) base64-encoded binary data. aoqi@0: // * aoqi@0: // *
aoqi@0: // * This abstraction is necessary to treat XOP as infoset encoding. aoqi@0: // * That is, you can either access the XOP-attached binary through aoqi@0: // * {@link XMLStreamReader#getText()} (in which case you'll see the aoqi@0: // * base64 encoded string), or you can access it as a binary data aoqi@0: // * directly by using this method. aoqi@0: // * aoqi@0: // *
aoqi@0: // * Note that even if you are reading from non XOP-aware {@link XMLStreamReader}, aoqi@0: // * this method must be still supported; if the reader is pointing aoqi@0: // * to a text, this method is responsible for decoding base64 and aoqi@0: // * producing a {@link DataHandler} with "application/octet-stream" aoqi@0: // * as the content type. aoqi@0: // * aoqi@0: // * @return aoqi@0: // * always non-null valid object. aoqi@0: // * Invocations of this method may return the same object as long aoqi@0: // * as the {@link XMLStreamReader#next()} method is not used, aoqi@0: // * but otherwise {@link DataSource} object returned from this method aoqi@0: // * is considered to be owned by the client, and therefore it shouldn't aoqi@0: // * be reused by the implementation of this method. aoqi@0: // * aoqi@0: // *
aoqi@0: // * The returned {@link DataSource} is read-only, and the caller aoqi@0: // * must not invoke {@link DataSource#getOutputStream()}. aoqi@0: // * aoqi@0: // * @throws IllegalStateException aoqi@0: // * if the parser is not pointing at characters infoset item. aoqi@0: // * @throws XMLStreamException aoqi@0: // * if the parser points to text but text is not base64-encoded text, aoqi@0: // * or if some other parsing error occurs (such as if the <xop:Include> aoqi@0: // * points to a non-existing attachment.) aoqi@0: // * aoqi@0: // *
aoqi@0: // * It is also OK for this method to return successfully, only to fail aoqi@0: // * during an {@link InputStream} is read from {@link DataSource}. aoqi@0: // */ aoqi@0: //DataSource getTextAsDataHandler() throws XMLStreamException; aoqi@0: aoqi@0: ///** aoqi@0: // * Works like {@link XMLStreamReader#getText()} aoqi@0: // * but returns text as {@link byte[]}. aoqi@0: // * aoqi@0: // *
aoqi@0: // * The contract of this method is mostly the same as aoqi@0: // * {@link #getTextAsDataHandler()}, except that this aoqi@0: // * method returns the binary datas as an exact-size byte[]. aoqi@0: // * aoqi@0: // *
aoqi@0: // * This method is also not capable of reporting the content type aoqi@0: // * of this binary data, even if it is available to the parser. aoqi@0: // * aoqi@0: // * @see #getTextAsDataHandler() aoqi@0: // */ aoqi@0: //byte[] getTextAsByteArray() throws XMLStreamException; aoqi@0: aoqi@0: /** aoqi@0: * Works like {@link #getText()} aoqi@0: * but hides the actual data representation. aoqi@0: * aoqi@0: * @return aoqi@0: * The {@link CharSequence} that represents the aoqi@0: * character infoset items at the current position. aoqi@0: * aoqi@0: *
aoqi@0: * The {@link CharSequence} is normally a {@link String}, aoqi@0: * but can be any other {@link CharSequence} implementation. aoqi@0: * For binary data, however, use of {@link Base64Data} is aoqi@0: * recommended (so that the consumer interested in seeing it aoqi@0: * as binary data may take advantage of mor efficient aoqi@0: * data representation.) aoqi@0: * aoqi@0: *
aoqi@0: * The object returned from this method belongs to the parser, aoqi@0: * and its content is guaranteed to be the same only until aoqi@0: * the {@link #next()} method is invoked. aoqi@0: * aoqi@0: * @throws IllegalStateException aoqi@0: * if the parser is not pointing at characters infoset item. aoqi@0: * aoqi@0: * TODO: aoqi@0: * fix the dependency to JAXB internal class. aoqi@0: */ aoqi@0: CharSequence getPCDATA() throws XMLStreamException; aoqi@0: aoqi@0: /** aoqi@0: * {@inheritDoc} aoqi@0: */ aoqi@0: NamespaceContextEx getNamespaceContext(); aoqi@0: aoqi@0: /** aoqi@0: * Works like {@link #getElementText()} but trims the leading aoqi@0: * and trailing whitespace. aoqi@0: * aoqi@0: *
aoqi@0: * The parser can often do this more efficiently than aoqi@0: * {@code getElementText().trim()}. aoqi@0: * aoqi@0: * @see #getElementText() aoqi@0: */ aoqi@0: String getElementTextTrim() throws XMLStreamException; aoqi@0: }