1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/src/share/jaxws_classes/com/sun/xml/internal/org/jvnet/staxex/StreamingDataHandler.java Tue Mar 06 16:09:35 2012 -0800
1.3 @@ -0,0 +1,145 @@
1.4 +/*
1.5 + * Copyright (c) 2010, Oracle and/or its affiliates. All rights reserved.
1.6 + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
1.7 + *
1.8 + * This code is free software; you can redistribute it and/or modify it
1.9 + * under the terms of the GNU General Public License version 2 only, as
1.10 + * published by the Free Software Foundation. Oracle designates this
1.11 + * particular file as subject to the "Classpath" exception as provided
1.12 + * by Oracle in the LICENSE file that accompanied this code.
1.13 + *
1.14 + * This code is distributed in the hope that it will be useful, but WITHOUT
1.15 + * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
1.16 + * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
1.17 + * version 2 for more details (a copy is included in the LICENSE file that
1.18 + * accompanied this code).
1.19 + *
1.20 + * You should have received a copy of the GNU General Public License version
1.21 + * 2 along with this work; if not, write to the Free Software Foundation,
1.22 + * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
1.23 + *
1.24 + * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
1.25 + * or visit www.oracle.com if you need additional information or have any
1.26 + * questions.
1.27 + */
1.28 +
1.29 +package com.sun.xml.internal.org.jvnet.staxex;
1.30 +
1.31 +import javax.activation.DataHandler;
1.32 +import javax.activation.DataSource;
1.33 +import java.io.BufferedInputStream;
1.34 +import java.io.Closeable;
1.35 +import java.io.File;
1.36 +import java.io.IOException;
1.37 +import java.io.InputStream;
1.38 +import java.net.URL;
1.39 +
1.40 +/**
1.41 + * {@link DataHandler} extended to offer better buffer management
1.42 + * in a streaming environment.
1.43 + *
1.44 + * <p>
1.45 + * {@link DataHandler} is used commonly as a data format across
1.46 + * multiple systems (such as JAXB/WS.) Unfortunately, {@link DataHandler}
1.47 + * has the semantics of "read as many times as you want", so this makes
1.48 + * it difficult for involving parties to handle a BLOB in a streaming fashion.
1.49 + *
1.50 + * <p>
1.51 + * {@link StreamingDataHandler} solves this problem by offering methods
1.52 + * that enable faster bulk "consume once" read operation.
1.53 + *
1.54 + * @author Jitendra Kotamraju
1.55 + */
1.56 +public abstract class StreamingDataHandler extends DataHandler implements Closeable {
1.57 +
1.58 + public StreamingDataHandler(Object o, String s) {
1.59 + super(o, s);
1.60 + }
1.61 +
1.62 + public StreamingDataHandler(URL url) {
1.63 + super(url);
1.64 + }
1.65 +
1.66 + public StreamingDataHandler(DataSource dataSource) {
1.67 + super(dataSource);
1.68 + }
1.69 +
1.70 + /**
1.71 + * Works like {@link #getInputStream()} except that this method
1.72 + * can be invoked only once.
1.73 + *
1.74 + * <p>
1.75 + * This is used as a signal from the caller that there will
1.76 + * be no further {@link #getInputStream()} invocation nor
1.77 + * {@link #readOnce()} invocation on this object (which would
1.78 + * result in {@link IOException}.)
1.79 + *
1.80 + * <p>
1.81 + * When {@link DataHandler} is backed by a streaming BLOB
1.82 + * (such as an attachment in a web service read from the network),
1.83 + * this allows the callee to avoid unnecessary buffering.
1.84 + *
1.85 + * <p>
1.86 + * Note that it is legal to call {@link #getInputStream()}
1.87 + * multiple times and then call {@link #readOnce()} afterward.
1.88 + * Streams created such a way can be read in any order —
1.89 + * there's no requirement that streams created earlier must be read
1.90 + * first.
1.91 + *
1.92 + * @return
1.93 + * always non-null. Represents the content of this BLOB.
1.94 + * The returned stream is generally not buffered, so for
1.95 + * better performance read in a big batch or wrap this into
1.96 + * {@link BufferedInputStream}.
1.97 + * @throws IOException
1.98 + * if any i/o error
1.99 + */
1.100 + public abstract InputStream readOnce() throws IOException;
1.101 +
1.102 + /**
1.103 + * Obtains the BLOB into a specified file.
1.104 + *
1.105 + * <p>
1.106 + * Semantically, this method is roughly equivalent to the following
1.107 + * code, except that the actual implementation is likely to be a lot faster.
1.108 + *
1.109 + * <pre>
1.110 + * InputStream i = getInputStream();
1.111 + * OutputStream o = new FileOutputStream(dst);
1.112 + * int ch;
1.113 + * while((ch=i.read())!=-1) o.write(ch);
1.114 + * i.close();
1.115 + * o.close();
1.116 + * </pre>
1.117 + *
1.118 + * <p>
1.119 + * The main motivation behind this method is that often
1.120 + * {@link DataHandler} that reads data from a streaming source
1.121 + * will use a temporary file as a data store to hold data
1.122 + * (think of commons-fileupload.) In such case this method
1.123 + * can be as fast as calling {@link File#renameTo(File)}.
1.124 + *
1.125 + * <p>
1.126 + * This method shouldn't be called when there are any
1.127 + * open streams.
1.128 + *
1.129 + * <p>
1.130 + * After this method is invoked, {@link #readOnce()} and
1.131 + * {@link #getInputStream()} will simply open the destination
1.132 + * file you've specified as an argument. So if you further
1.133 + * move the file or delete this file, those methods will
1.134 + * behave in undefined fashion. For a simliar reason,
1.135 + * calling this method multiple times will cause
1.136 + * undefined behavior.
1.137 + */
1.138 + public abstract void moveTo(File dst) throws IOException;
1.139 +
1.140 + /**
1.141 + * Releases any resources associated with this DataHandler.
1.142 + * (such as an attachment in a web service read from a temp
1.143 + * file will be deleted.) After calling this method, it is
1.144 + * illegal to call any other methods.
1.145 + */
1.146 + public abstract void close() throws IOException;
1.147 +
1.148 +}
