• file
• revisions
• annotate
• diff
• comparison
• raw

src/share/jaxws_classes/com/sun/xml/internal/org/jvnet/staxex/XMLStreamReaderEx.java@9c07ef4934dd (annotated)

src/share/jaxws_classes/com/sun/xml/internal/org/jvnet/staxex/XMLStreamReaderEx.java

Thu, 31 Aug 2017 15:18:52 +0800

author

aoqi

date

Thu, 31 Aug 2017 15:18:52 +0800

changeset 637

9c07ef4934dd

parent 368

0989ad8c0860

parent 0

373ffda63c9a

permissions

-rw-r--r--

merge

aoqi@0	1	/*
aoqi@0	2	* Copyright (c) 1997, 2012, Oracle and/or its affiliates. All rights reserved.
aoqi@0	3	* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
aoqi@0	4	*
aoqi@0	5	* This code is free software; you can redistribute it and/or modify it
aoqi@0	6	* under the terms of the GNU General Public License version 2 only, as
aoqi@0	7	* published by the Free Software Foundation. Oracle designates this
aoqi@0	8	* particular file as subject to the "Classpath" exception as provided
aoqi@0	9	* by Oracle in the LICENSE file that accompanied this code.
aoqi@0	10	*
aoqi@0	11	* This code is distributed in the hope that it will be useful, but WITHOUT
aoqi@0	12	* ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
aoqi@0	13	* FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
aoqi@0	14	* version 2 for more details (a copy is included in the LICENSE file that
aoqi@0	15	* accompanied this code).
aoqi@0	16	*
aoqi@0	17	* You should have received a copy of the GNU General Public License version
aoqi@0	18	* 2 along with this work; if not, write to the Free Software Foundation,
aoqi@0	19	* Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
aoqi@0	20	*
aoqi@0	21	* Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
aoqi@0	22	* or visit www.oracle.com if you need additional information or have any
aoqi@0	23	* questions.
aoqi@0	24	*/
aoqi@0	25
aoqi@0	26	package com.sun.xml.internal.org.jvnet.staxex;
aoqi@0	27
aoqi@0	28	import javax.xml.stream.XMLStreamReader;
aoqi@0	29	import javax.xml.stream.XMLStreamException;
aoqi@0	30
aoqi@0	31	/**
aoqi@0	32	* {@link XMLStreamReader} extended for reading binary data.
aoqi@0	33	*
aoqi@0	34	* <p>
aoqi@0	35	* Some producer of infoset (in particular, such as FastInfoset,
aoqi@0	36	* XOP decoder), uses a native format that enables efficient
aoqi@0	37	* treatment of binary data. For ordinary infoset consumer
aoqi@0	38	* (that just uses {@link XMLStreamReader}, those binary data
aoqi@0	39	* will just look like base64-encoded string, but this interface
aoqi@0	40	* allows consumers of such infoset to access this raw binary data.
aoqi@0	41	* Such infoset producer may choose to implement this additoinal
aoqi@0	42	* interface, to expose this functionality.
aoqi@0	43	*
aoqi@0	44	* <p>
aoqi@0	45	* Consumers that are capable of using this interface can query
aoqi@0	46	* {@link XMLStreamReader} if it supports this by simply downcasting
aoqi@0	47	* it to this interface like this:
aoqi@0	48	*
aoqi@0	49	* <pre>
aoqi@0	50	* XMLStreamReader reader = ...;
aoqi@0	51	* if( reader instanceof XMLStreamReaderEx ) {
aoqi@0	52	* // this reader supports binary data exchange
aoqi@0	53	* ...
aoqi@0	54	* } else {
aoqi@0	55	* // noop
aoqi@0	56	* ...
aoqi@0	57	* }
aoqi@0	58	* </pre>
aoqi@0	59	*
aoqi@0	60	* <p>
aoqi@0	61	* Also note that it is also allowed for the infoset producer
aoqi@0	62	* to implement this interface in such a way that {@link #getPCDATA()}
aoqi@0	63	* always delegate to {@link #getText()}, although it's not desirable.
aoqi@0	64	*
aoqi@0	65	* <p>
aoqi@0	66	* This interface is a private contract between such producers
aoqi@0	67	* and consumers to allow them to exchange binary data without
aoqi@0	68	* converting it to base64.
aoqi@0	69	*
aoqi@0	70	* @see XMLStreamWriterEx
aoqi@0	71	* @author Kohsuke Kawaguchi
aoqi@0	72	* @author Paul Sandoz
aoqi@0	73	*/
aoqi@0	74	public interface XMLStreamReaderEx extends XMLStreamReader {
aoqi@0	75	///**
aoqi@0	76	// * Works like {@link XMLStreamReader#getText()}
aoqi@0	77	// * but returns text as {@link DataSource}.
aoqi@0	78	// *
aoqi@0	79	// * <p>
aoqi@0	80	// * This method can be invoked whenever {@link XMLStreamReader#getText()}
aoqi@0	81	// * can be invoked. Invoking this method means the caller is assuming
aoqi@0	82	// * that the text is (conceptually) base64-encoded binary data.
aoqi@0	83	// *
aoqi@0	84	// * <p>
aoqi@0	85	// * This abstraction is necessary to treat XOP as infoset encoding.
aoqi@0	86	// * That is, you can either access the XOP-attached binary through
aoqi@0	87	// * {@link XMLStreamReader#getText()} (in which case you'll see the
aoqi@0	88	// * base64 encoded string), or you can access it as a binary data
aoqi@0	89	// * directly by using this method.
aoqi@0	90	// *
aoqi@0	91	// * <p>
aoqi@0	92	// * Note that even if you are reading from non XOP-aware {@link XMLStreamReader},
aoqi@0	93	// * this method must be still supported; if the reader is pointing
aoqi@0	94	// * to a text, this method is responsible for decoding base64 and
aoqi@0	95	// * producing a {@link DataHandler} with "application/octet-stream"
aoqi@0	96	// * as the content type.
aoqi@0	97	// *
aoqi@0	98	// * @return
aoqi@0	99	// * always non-null valid object.
aoqi@0	100	// * Invocations of this method may return the same object as long
aoqi@0	101	// * as the {@link XMLStreamReader#next()} method is not used,
aoqi@0	102	// * but otherwise {@link DataSource} object returned from this method
aoqi@0	103	// * is considered to be owned by the client, and therefore it shouldn't
aoqi@0	104	// * be reused by the implementation of this method.
aoqi@0	105	// *
aoqi@0	106	// * <p>
aoqi@0	107	// * The returned {@link DataSource} is read-only, and the caller
aoqi@0	108	// * must not invoke {@link DataSource#getOutputStream()}.
aoqi@0	109	// *
aoqi@0	110	// * @throws IllegalStateException
aoqi@0	111	// * if the parser is not pointing at characters infoset item.
aoqi@0	112	// * @throws XMLStreamException
aoqi@0	113	// * if the parser points to text but text is not base64-encoded text,
aoqi@0	114	// * or if some other parsing error occurs (such as if the &lt;xop:Include>
aoqi@0	115	// * points to a non-existing attachment.)
aoqi@0	116	// *
aoqi@0	117	// * <p>
aoqi@0	118	// * It is also OK for this method to return successfully, only to fail
aoqi@0	119	// * during an {@link InputStream} is read from {@link DataSource}.
aoqi@0	120	// */
aoqi@0	121	//DataSource getTextAsDataHandler() throws XMLStreamException;
aoqi@0	122
aoqi@0	123	///**
aoqi@0	124	// * Works like {@link XMLStreamReader#getText()}
aoqi@0	125	// * but returns text as {@link byte[]}.
aoqi@0	126	// *
aoqi@0	127	// * <p>
aoqi@0	128	// * The contract of this method is mostly the same as
aoqi@0	129	// * {@link #getTextAsDataHandler()}, except that this
aoqi@0	130	// * method returns the binary datas as an exact-size byte[].
aoqi@0	131	// *
aoqi@0	132	// * <p>
aoqi@0	133	// * This method is also not capable of reporting the content type
aoqi@0	134	// * of this binary data, even if it is available to the parser.
aoqi@0	135	// *
aoqi@0	136	// * @see #getTextAsDataHandler()
aoqi@0	137	// */
aoqi@0	138	//byte[] getTextAsByteArray() throws XMLStreamException;
aoqi@0	139
aoqi@0	140	/**
aoqi@0	141	* Works like {@link #getText()}
aoqi@0	142	* but hides the actual data representation.
aoqi@0	143	*
aoqi@0	144	* @return
aoqi@0	145	* The {@link CharSequence} that represents the
aoqi@0	146	* character infoset items at the current position.
aoqi@0	147	*
aoqi@0	148	* <p>
aoqi@0	149	* The {@link CharSequence} is normally a {@link String},
aoqi@0	150	* but can be any other {@link CharSequence} implementation.
aoqi@0	151	* For binary data, however, use of {@link Base64Data} is
aoqi@0	152	* recommended (so that the consumer interested in seeing it
aoqi@0	153	* as binary data may take advantage of mor efficient
aoqi@0	154	* data representation.)
aoqi@0	155	*
aoqi@0	156	* <p>
aoqi@0	157	* The object returned from this method belongs to the parser,
aoqi@0	158	* and its content is guaranteed to be the same only until
aoqi@0	159	* the {@link #next()} method is invoked.
aoqi@0	160	*
aoqi@0	161	* @throws IllegalStateException
aoqi@0	162	* if the parser is not pointing at characters infoset item.
aoqi@0	163	*
aoqi@0	164	* TODO:
aoqi@0	165	* fix the dependency to JAXB internal class.
aoqi@0	166	*/
aoqi@0	167	CharSequence getPCDATA() throws XMLStreamException;
aoqi@0	168
aoqi@0	169	/**
aoqi@0	170	* {@inheritDoc}
aoqi@0	171	*/
aoqi@0	172	NamespaceContextEx getNamespaceContext();
aoqi@0	173
aoqi@0	174	/**
aoqi@0	175	* Works like {@link #getElementText()} but trims the leading
aoqi@0	176	* and trailing whitespace.
aoqi@0	177	*
aoqi@0	178	* <p>
aoqi@0	179	* The parser can often do this more efficiently than
aoqi@0	180	* {@code getElementText().trim()}.
aoqi@0	181	*
aoqi@0	182	* @see #getElementText()
aoqi@0	183	*/
aoqi@0	184	String getElementTextTrim() throws XMLStreamException;
aoqi@0	185	}