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