1 /* 2 * Copyright (c) 2012, Oracle and/or its affiliates. All rights reserved. 3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. 4 * 5 * This code is free software; you can redistribute it and/or modify it 6 * under the terms of the GNU General Public License version 2 only, as 7 * published by the Free Software Foundation. Oracle designates this 8 * particular file as subject to the "Classpath" exception as provided 9 * by Oracle in the LICENSE file that accompanied this code. 10 * 11 * This code is distributed in the hope that it will be useful, but WITHOUT 12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License 14 * version 2 for more details (a copy is included in the LICENSE file that 15 * accompanied this code). 16 * 17 * You should have received a copy of the GNU General Public License version 18 * 2 along with this work; if not, write to the Free Software Foundation, 19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. 20 * 21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA 22 * or visit www.oracle.com if you need additional information or have any 23 * questions. 24 */ 25 package java.util; 26 27 import java.lang.annotation.Documented; 28 import java.lang.annotation.Retention; 29 import java.lang.annotation.RetentionPolicy; 30 31 /** 32 * An object that may (but need not) hold one or more references to 33 * resources that will be released when closed. Such objects may be 34 * used with try-with-resources or related {@code try...finally} 35 * constructions that ensure they are closed as soon as they are no 36 * longer needed. Interface {@code MayHoldCloseableResource} indicates that 37 * only a minority of usages warrant resource control constructions: 38 * those specialized to known resource-bearing instances, or those 39 * that must operate in complete generality. 40 * 41 * <p>For example, most usages of the {@link java.util.stream.Stream} 42 * classes operate on data sources such as an array, {@code 43 * Collection}, or generator function that do not require or benefit 44 * from explicit resource control. However, some uses of IO channels 45 * as data sources do. 46 * 47 * <p>Annotation {@link HoldsResource} may be used to guide users or static 48 * analysis tools to deciding whether resource-control constructions are 49 * warranted when using particular instantiations of 50 * {@code MayHoldCloseableResource}. 51 * 52 * @see AutoCloseable 53 * @see HoldsResource 54 */ 55 public interface MayHoldCloseableResource extends AutoCloseable { 56 /** 57 * Closes this resource, relinquishing any underlying resources. 58 * This method is invoked automatically on objects managed by the 59 * {@code try}-with-resources statement. 60 * 61 * Implementers of this interface are strongly encouraged 62 * to make their {@code close} methods idempotent. 63 * 64 * @see AutoCloseable#close() 65 */ 66 @Override 67 void close(); 68 69 /** 70 * Indicates that a variable holding a {@code MayHoldCloseableResource} or 71 * a method returning a {@code MayHoldCloseableResource} definitely does 72 * hold a closeable resource. 73 */ 74 @Retention(RetentionPolicy.CLASS) 75 @Documented 76 @interface HoldsResource { } 77 }