001 /*
002 * Licensed to the Apache Software Foundation (ASF) under one or more
003 * contributor license agreements. See the NOTICE file distributed with
004 * this work for additional information regarding copyright ownership.
005 * The ASF licenses this file to You under the Apache License, Version 2.0
006 * (the "License"); you may not use this file except in compliance with
007 * the License. You may obtain a copy of the License at
008 *
009 * http://www.apache.org/licenses/LICENSE-2.0
010 *
011 * Unless required by applicable law or agreed to in writing, software
012 * distributed under the License is distributed on an "AS IS" BASIS,
013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014 * See the License for the specific language governing permissions and
015 * limitations under the License.
016 */
017 package org.apache.commons.io.input;
018
019 import java.io.IOException;
020 import java.io.InputStream;
021
022 /**
023 * Proxy stream that closes and discards the underlying stream as soon as the
024 * end of input has been reached or when the stream is explicitly closed.
025 * Not even a reference to the underlying stream is kept after it has been
026 * closed, so any allocated in-memory buffers can be freed even if the
027 * client application still keeps a reference to the proxy stream.
028 * <p>
029 * This class is typically used to release any resources related to an open
030 * stream as soon as possible even if the client application (by not explicitly
031 * closing the stream when no longer needed) or the underlying stream (by not
032 * releasing resources once the last byte has been read) do not do that.
033 *
034 * @version $Id: AutoCloseInputStream.java 610010 2008-01-08 14:50:59Z niallp $
035 * @since Commons IO 1.4
036 */
037 public class AutoCloseInputStream extends ProxyInputStream {
038
039 /**
040 * Creates an automatically closing proxy for the given input stream.
041 *
042 * @param in underlying input stream
043 */
044 public AutoCloseInputStream(InputStream in) {
045 super(in);
046 }
047
048 /**
049 * Closes the underlying input stream and replaces the reference to it
050 * with a {@link ClosedInputStream} instance.
051 * <p>
052 * This method is automatically called by the read methods when the end
053 * of input has been reached.
054 * <p>
055 * Note that it is safe to call this method any number of times. The original
056 * underlying input stream is closed and discarded only once when this
057 * method is first called.
058 *
059 * @throws IOException if the underlying input stream can not be closed
060 */
061 public void close() throws IOException {
062 in.close();
063 in = new ClosedInputStream();
064 }
065
066 /**
067 * Reads and returns a single byte from the underlying input stream.
068 * If the underlying stream returns -1, the {@link #close()} method is
069 * called to automatically close and discard the stream.
070 *
071 * @return next byte in the stream, or -1 if no more bytes are available
072 * @throws IOException if the stream could not be read or closed
073 */
074 public int read() throws IOException {
075 int n = in.read();
076 if (n == -1) {
077 close();
078 }
079 return n;
080 }
081
082 /**
083 * Reads and returns bytes from the underlying input stream to the given
084 * buffer. If the underlying stream returns -1, the {@link #close()} method
085 * i called to automatically close and discard the stream.
086 *
087 * @param b buffer to which bytes from the stream are written
088 * @return number of bytes read, or -1 if no more bytes are available
089 * @throws IOException if the stream could not be read or closed
090 */
091 public int read(byte[] b) throws IOException {
092 int n = in.read(b);
093 if (n == -1) {
094 close();
095 }
096 return n;
097 }
098
099 /**
100 * Reads and returns bytes from the underlying input stream to the given
101 * buffer. If the underlying stream returns -1, the {@link #close()} method
102 * i called to automatically close and discard the stream.
103 *
104 * @param b buffer to which bytes from the stream are written
105 * @param off start offset within the buffer
106 * @param len maximum number of bytes to read
107 * @return number of bytes read, or -1 if no more bytes are available
108 * @throws IOException if the stream could not be read or closed
109 */
110 public int read(byte[] b, int off, int len) throws IOException {
111 int n = in.read(b, off, len);
112 if (n == -1) {
113 close();
114 }
115 return n;
116 }
117
118 /**
119 * Ensures that the stream is closed before it gets garbage-collected.
120 * As mentioned in {@link #close()}, this is a no-op if the stream has
121 * already been closed.
122 * @throws Throwable if an error occurs
123 */
124 protected void finalize() throws Throwable {
125 close();
126 super.finalize();
127 }
128
129 }