View Javadoc
1   /*
2    * Copyright (c) 1997, 2012, 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 }