jdk8-mips64-public/jaxws: src/share/jaxws_classes/com/sun/xml/internal/org/jvnet/staxex/StreamingDataHandler.java@b0610cd08440 (annotated)

src/share/jaxws_classes/com/sun/xml/internal/org/jvnet/staxex/StreamingDataHandler.java@b0610cd08440 (annotated)

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

Fri, 04 Oct 2013 16:21:34 +0100

author: mkos
date: Fri, 04 Oct 2013 16:21:34 +0100
changeset 408: b0610cd08440
parent 286: f50545b5e2f1
child 637: 9c07ef4934dd
permissions: -rw-r--r--

8025054: Update JAX-WS RI integration to 2.2.9-b130926.1035
Reviewed-by: chegar

 /*
  * Copyright (c) 2010, 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.activation.DataHandler;
 import javax.activation.DataSource;
 import java.io.BufferedInputStream;
 import java.io.Closeable;
 import java.io.File;
 import java.io.IOException;
 import java.io.InputStream;
 import java.net.URL;
 /**
  * {@link DataHandler} extended to offer better buffer management
  * in a streaming environment.
  *
  * <p>
  * {@link DataHandler} is used commonly as a data format across
  * multiple systems (such as JAXB/WS.) Unfortunately, {@link DataHandler}
  * has the semantics of "read as many times as you want", so this makes
  * it difficult for involving parties to handle a BLOB in a streaming fashion.
  *
  * <p>
  * {@link StreamingDataHandler} solves this problem by offering methods
  * that enable faster bulk "consume once" read operation.
  *
  * @author Jitendra Kotamraju
  */
 public abstract class StreamingDataHandler extends DataHandler implements Closeable {
     public StreamingDataHandler(Object o, String s) {
         super(o, s);
     }
     public StreamingDataHandler(URL url) {
         super(url);
     }
     public StreamingDataHandler(DataSource dataSource) {
         super(dataSource);
     }
     /**
      * Works like {@link #getInputStream()} except that this method
      * can be invoked only once.
      *
      * <p>
      * This is used as a signal from the caller that there will
      * be no further {@link #getInputStream()} invocation nor
      * {@link #readOnce()} invocation on this object (which would
      * result in {@link IOException}.)
      *
      * <p>
      * When {@link DataHandler} is backed by a streaming BLOB
      * (such as an attachment in a web service read from the network),
      * this allows the callee to avoid unnecessary buffering.
      *
      * <p>
      * Note that it is legal to call {@link #getInputStream()}
      * multiple times and then call {@link #readOnce()} afterward.
      * Streams created such a way can be read in any order &mdash;
      * there's no requirement that streams created earlier must be read
      * first.
      *
      * @return
      *      always non-null. Represents the content of this BLOB.
      *      The returned stream is generally not buffered, so for
      *      better performance read in a big batch or wrap this into
      *      {@link BufferedInputStream}.
      * @throws IOException
      *      if any i/o error
      */
     public abstract InputStream readOnce() throws IOException;
     /**
      * Obtains the BLOB into a specified file.
      *
      * <p>
      * Semantically, this method is roughly equivalent to the following
      * code, except that the actual implementation is likely to be a lot faster.
      *
      * <pre>
      * InputStream i = getInputStream();
      * OutputStream o = new FileOutputStream(dst);
      * int ch;
      * while((ch=i.read())!=-1)  o.write(ch);
      * i.close();
      * o.close();
      * </pre>
      *
      * <p>
      * The main motivation behind this method is that often
      * {@link DataHandler} that reads data from a streaming source
      * will use a temporary file as a data store to hold data
      * (think of commons-fileupload.) In such case this method
      * can be as fast as calling {@link File#renameTo(File)}.
      *
      * <p>
      * This method shouldn't be called when there are any
      * open streams.
      *
      * <p>
      * After this method is invoked, {@link #readOnce()} and
      * {@link #getInputStream()} will simply open the destination
      * file you've specified as an argument. So if you further
      * move the file or delete this file, those methods will
      * behave in undefined fashion. For a simliar reason,
      * calling this method multiple times will cause
      * undefined behavior.
      */
     public abstract void moveTo(File dst) throws IOException;
     /**
      * Releases any resources associated with this DataHandler.
      * (such as an attachment in a web service read from a temp
      * file will be deleted.) After calling this method, it is
      * illegal to call any other methods.
      */
     public abstract void close() throws IOException;
 }

Mercurial > jdk8-mips64-public > jaxws / annotate

src/share/jaxws_classes/com/sun/xml/internal/org/jvnet/staxex/StreamingDataHandler.java@b0610cd08440 (annotated)

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