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 */ 017package org.apache.commons.io.input; 018 019import static org.apache.commons.io.IOUtils.EOF; 020 021import java.io.IOException; 022import java.io.InputStream; 023 024import org.apache.commons.io.build.AbstractStreamBuilder; 025 026/** 027 * Proxy stream that closes and discards the underlying stream as soon as the 028 * end of input has been reached or when the stream is explicitly closed. 029 * Not even a reference to the underlying stream is kept after it has been 030 * closed, so any allocated in-memory buffers can be freed even if the 031 * client application still keeps a reference to the proxy stream. 032 * <p> 033 * This class is typically used to release any resources related to an open 034 * stream as soon as possible even if the client application (by not explicitly 035 * closing the stream when no longer needed) or the underlying stream (by not 036 * releasing resources once the last byte has been read) do not do that. 037 * </p> 038 * 039 * @since 1.4 040 */ 041public class AutoCloseInputStream extends ProxyInputStream { 042 043 /** 044 * Builds a new {@link AutoCloseInputStream} instance. 045 * <p> 046 * For example: 047 * </p> 048 * 049 * <pre>{@code 050 * AutoCloseInputStream s = AutoCloseInputStream.builder() 051 * .setPath(path) 052 * .get();} 053 * </pre> 054 * 055 * <pre>{@code 056 * AutoCloseInputStream s = AutoCloseInputStream.builder() 057 * .setInputStream(inputStream) 058 * .get();} 059 * </pre> 060 * 061 * @since 2.13.0 062 */ 063 public static class Builder extends AbstractStreamBuilder<AutoCloseInputStream, Builder> { 064 065 /** 066 * Constructs a new instance. 067 * <p> 068 * This builder use the aspect InputStream. 069 * </p> 070 * 071 * @return a new instance. 072 * @throws IOException if an I/O error occurs. 073 * @throws IllegalArgumentException if the buffer is not large enough to hold a complete character. 074 */ 075 @SuppressWarnings("resource") // Caller closes 076 @Override 077 public AutoCloseInputStream get() throws IOException { 078 return new AutoCloseInputStream(getInputStream()); 079 } 080 081 } 082 083 /** 084 * Constructs a new {@link Builder}. 085 * 086 * @return a new {@link Builder}. 087 * @since 2.12.0 088 */ 089 public static Builder builder() { 090 return new Builder(); 091 } 092 093 /** 094 * Constructs an automatically closing proxy for the given input stream. 095 * 096 * @param in underlying input stream 097 * @deprecated Use {@link #builder()}, {@link Builder}, and {@link Builder#get()} 098 */ 099 @Deprecated 100 public AutoCloseInputStream(final InputStream in) { 101 super(in); 102 } 103 104 /** 105 * Automatically closes the stream if the end of stream was reached. 106 * 107 * @param n number of bytes read, or -1 if no more bytes are available 108 * @throws IOException if the stream could not be closed 109 * @since 2.0 110 */ 111 @Override 112 protected void afterRead(final int n) throws IOException { 113 if (n == EOF) { 114 close(); 115 } 116 } 117 118 /** 119 * Closes the underlying input stream and replaces the reference to it 120 * with a {@link ClosedInputStream} instance. 121 * <p> 122 * This method is automatically called by the read methods when the end 123 * of input has been reached. 124 * <p> 125 * Note that it is safe to call this method any number of times. The original 126 * underlying input stream is closed and discarded only once when this 127 * method is first called. 128 * 129 * @throws IOException if the underlying input stream can not be closed 130 */ 131 @Override 132 public void close() throws IOException { 133 in.close(); 134 in = ClosedInputStream.INSTANCE; 135 } 136 137 /** 138 * Ensures that the stream is closed before it gets garbage-collected. 139 * As mentioned in {@link #close()}, this is a no-op if the stream has 140 * already been closed. 141 * @throws Throwable if an error occurs 142 */ 143 @Override 144 protected void finalize() throws Throwable { 145 close(); 146 super.finalize(); 147 } 148 149}