Mercurial > jdk8-mips64-public > jaxws / file revision

 /*

  * Copyright (c) 1997, 2012, Oracle and/or its affiliates. All rights reserved.

  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.

  *

  * This code is free software; you can redistribute it and/or modify it

  * under the terms of the GNU General Public License version 2 only, as

  * published by the Free Software Foundation.  Oracle designates this

  * particular file as subject to the "Classpath" exception as provided

  * by Oracle in the LICENSE file that accompanied this code.

  *

  * This code is distributed in the hope that it will be useful, but WITHOUT

  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or

  * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License

  * version 2 for more details (a copy is included in the LICENSE file that

  * accompanied this code).

  *

  * You should have received a copy of the GNU General Public License version

  * 2 along with this work; if not, write to the Free Software Foundation,

  * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.

  *

  * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA

  * or visit www.oracle.com if you need additional information or have any

  * questions.

  */

 package com.sun.xml.internal.org.jvnet.staxex;

 import javax.xml.stream.XMLStreamReader;

 import javax.xml.stream.XMLStreamException;

 /**

  * {@link XMLStreamReader} extended for reading binary data.

  *

  * <p>

  * 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.

  *

  * <p>

  * 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:

  *

  * <pre>

  * XMLStreamReader reader = ...;

  * if( reader instanceof XMLStreamReaderEx ) {

  *   // this reader supports binary data exchange

  *   ...

  * } else {

  *   // noop

  *   ...

  * }

  * </pre>

  *

  * <p>

  * 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.

  *

  * <p>

  * 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}.

     // *

     // * <p>

     // * 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.

     // *

     // * <p>

     // * 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.

     // *

     // * <p>

     // * 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.

     // *

     // *      <p>

     // *      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.)

     // *

     // *      <p>

     // *      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[]}.

     // *

     // * <p>

     // * 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[].

     // *

     // * <p>

     // * 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.

      *

      *      <p>

      *      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.)

      *

      *      <p>

      *      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.

      *

      * <p>

      * The parser can often do this more efficiently than

      * {@code getElementText().trim()}.

      *

      * @see #getElementText()

      */

     String getElementTextTrim() throws XMLStreamException;

 }