001: /*
002: * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.
003: *
004: * Copyright 1997-2007 Sun Microsystems, Inc. All rights reserved.
005: *
006: * The contents of this file are subject to the terms of either the GNU
007: * General Public License Version 2 only ("GPL") or the Common Development
008: * and Distribution License("CDDL") (collectively, the "License"). You
009: * may not use this file except in compliance with the License. You can obtain
010: * a copy of the License at https://glassfish.dev.java.net/public/CDDL+GPL.html
011: * or glassfish/bootstrap/legal/LICENSE.txt. See the License for the specific
012: * language governing permissions and limitations under the License.
013: *
014: * When distributing the software, include this License Header Notice in each
015: * file and include the License file at glassfish/bootstrap/legal/LICENSE.txt.
016: * Sun designates this particular file as subject to the "Classpath" exception
017: * as provided by Sun in the GPL Version 2 section of the License file that
018: * accompanied this code. If applicable, add the following below the License
019: * Header, with the fields enclosed by brackets [] replaced by your own
020: * identifying information: "Portions Copyrighted [year]
021: * [name of copyright owner]"
022: *
023: * Contributor(s):
024: *
025: * If you wish your version of this file to be governed by only the CDDL or
026: * only the GPL Version 2, indicate your decision by adding "[Contributor]
027: * elects to include this software in this distribution under the [CDDL or GPL
028: * Version 2] license." If you don't indicate a single choice of license, a
029: * recipient has the option to distribute your version of this file under
030: * either the CDDL, the GPL Version 2 or to extend the choice of license to
031: * its licensees as provided above. However, if you add GPL Version 2 code
032: * and therefore, elected the GPL Version 2 license, then the option applies
033: * only if the new code is made subject to such option by the copyright
034: * holder.
035: */
036:
037: package org.jvnet.staxex;
038:
039: import javax.xml.stream.XMLStreamReader;
040: import javax.xml.stream.XMLStreamException;
041:
042: /**
043: * {@link XMLStreamReader} extended for reading binary data.
044: *
045: * <p>
046: * Some producer of infoset (in particular, such as FastInfoset,
047: * XOP deecoder), usees a native format that enables efficient
048: * treatment of binary data. For ordinary infoset consumer
049: * (that just uses {@link XMLStreamReader}, those binary data
050: * will just look like base64-encoded string, but this interface
051: * allows consumers of such infoset to access this raw binary data.
052: * Such infoset producer may choose to implement this additoinal
053: * interface, to expose this functionality.
054: *
055: * <p>
056: * Consumers that are capable of using this interface can query
057: * {@link XMLStreamReader} if it supports this by simply downcasting
058: * it to this interface like this:
059: *
060: * <pre>
061: * XMLStreamReader reader = ...;
062: * if( reader instanceof XMLStreamReaderEx ) {
063: * // this reader supports binary data exchange
064: * ...
065: * } else {
066: * // noop
067: * ...
068: * }
069: * </pre>
070: *
071: * <p>
072: * Also note that it is also allowed for the infoset producer
073: * to implement this interface in such a way that {@link #getPCDATA()}
074: * always delegate to {@link #getText()}, although it's not desirable.
075: *
076: * <p>
077: * This interface is a private contract between such producers
078: * and consumers to allow them to exchange binary data without
079: * converting it to base64.
080: *
081: * @see XMLStreamWriterEx
082: * @author Kohsuke Kawaguchi
083: * @author Paul Sandoz
084: */
085: public interface XMLStreamReaderEx extends XMLStreamReader {
086: ///**
087: // * Works like {@link XMLStreamReader#getText()}
088: // * but returns text as {@link DataSource}.
089: // *
090: // * <p>
091: // * This method can be invoked whenever {@link XMLStreamReader#getText()}
092: // * can be invoked. Invoking this method means the caller is assuming
093: // * that the text is (conceptually) base64-encoded binary data.
094: // *
095: // * <p>
096: // * This abstraction is necessary to treat XOP as infoset encoding.
097: // * That is, you can either access the XOP-attached binary through
098: // * {@link XMLStreamReader#getText()} (in which case you'll see the
099: // * base64 encoded string), or you can access it as a binary data
100: // * directly by using this method.
101: // *
102: // * <p>
103: // * Note that even if you are reading from non XOP-aware {@link XMLStreamReader},
104: // * this method must be still supported; if the reader is pointing
105: // * to a text, this method is responsible for decoding base64 and
106: // * producing a {@link DataHandler} with "application/octet-stream"
107: // * as the content type.
108: // *
109: // * @return
110: // * always non-null valid object.
111: // * Invocations of this method may return the same object as long
112: // * as the {@link XMLStreamReader#next()} method is not used,
113: // * but otherwise {@link DataSource} object returned from this method
114: // * is considered to be owned by the client, and therefore it shouldn't
115: // * be reused by the implementation of this method.
116: // *
117: // * <p>
118: // * The returned {@link DataSource} is read-only, and the caller
119: // * must not invoke {@link DataSource#getOutputStream()}.
120: // *
121: // * @throws IllegalStateException
122: // * if the parser is not pointing at characters infoset item.
123: // * @throws XMLStreamException
124: // * if the parser points to text but text is not base64-encoded text,
125: // * or if some other parsing error occurs (such as if the <xop:Include>
126: // * points to a non-existing attachment.)
127: // *
128: // * <p>
129: // * It is also OK for this method to return successfully, only to fail
130: // * during an {@link InputStream} is read from {@link DataSource}.
131: // */
132: //DataSource getTextAsDataHandler() throws XMLStreamException;
133:
134: ///**
135: // * Works like {@link XMLStreamReader#getText()}
136: // * but returns text as {@link byte[]}.
137: // *
138: // * <p>
139: // * The contract of this method is mostly the same as
140: // * {@link #getTextAsDataHandler()}, except that this
141: // * method returns the binary datas as an exact-size byte[].
142: // *
143: // * <p>
144: // * This method is also not capable of reporting the content type
145: // * of this binary data, even if it is available to the parser.
146: // *
147: // * @see #getTextAsDataHandler()
148: // */
149: //byte[] getTextAsByteArray() throws XMLStreamException;
150:
151: /**
152: * Works like {@link #getText()}
153: * but hides the actual data representation.
154: *
155: * @return
156: * The {@link CharSequence} that represents the
157: * character infoset items at the current position.
158: *
159: * <p>
160: * The {@link CharSequence} is normally a {@link String},
161: * but can be any other {@link CharSequence} implementation.
162: * For binary data, however, use of {@link Base64Data} is
163: * recommended (so that the consumer interested in seeing it
164: * as binary data may take advantage of mor efficient
165: * data representation.)
166: *
167: * <p>
168: * The object returned from this method belongs to the parser,
169: * and its content is guaranteed to be the same only until
170: * the {@link #next()} method is invoked.
171: *
172: * @throws IllegalStateException
173: * if the parser is not pointing at characters infoset item.
174: *
175: * TODO:
176: * fix the dependency to JAXB internal class.
177: */
178: CharSequence getPCDATA() throws XMLStreamException;
179:
180: /**
181: * {@inheritDoc}
182: */
183: NamespaceContextEx getNamespaceContext();
184:
185: /**
186: * Works like {@link #getElementText()} but trims the leading
187: * and trailing whitespace.
188: *
189: * <p>
190: * The parser can often do this more efficiently than
191: * {@code getElementText().trim()}.
192: *
193: * @see #getElementText()
194: */
195: String getElementTextTrim() throws XMLStreamException;
196: }
|