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 }