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 &lt;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 }