jtulach@119
|
1 |
/*
|
jtulach@119
|
2 |
* Copyright (c) 2009, 2011, Oracle and/or its affiliates. All rights reserved.
|
jtulach@119
|
3 |
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
|
jtulach@119
|
4 |
*
|
jtulach@119
|
5 |
* This code is free software; you can redistribute it and/or modify it
|
jtulach@119
|
6 |
* under the terms of the GNU General Public License version 2 only, as
|
jtulach@119
|
7 |
* published by the Free Software Foundation. Oracle designates this
|
jtulach@119
|
8 |
* particular file as subject to the "Classpath" exception as provided
|
jtulach@119
|
9 |
* by Oracle in the LICENSE file that accompanied this code.
|
jtulach@119
|
10 |
*
|
jtulach@119
|
11 |
* This code is distributed in the hope that it will be useful, but WITHOUT
|
jtulach@119
|
12 |
* ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
|
jtulach@119
|
13 |
* FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
|
jtulach@119
|
14 |
* version 2 for more details (a copy is included in the LICENSE file that
|
jtulach@119
|
15 |
* accompanied this code).
|
jtulach@119
|
16 |
*
|
jtulach@119
|
17 |
* You should have received a copy of the GNU General Public License version
|
jtulach@119
|
18 |
* 2 along with this work; if not, write to the Free Software Foundation,
|
jtulach@119
|
19 |
* Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
|
jtulach@119
|
20 |
*
|
jtulach@119
|
21 |
* Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
|
jtulach@119
|
22 |
* or visit www.oracle.com if you need additional information or have any
|
jtulach@119
|
23 |
* questions.
|
jtulach@119
|
24 |
*/
|
jtulach@119
|
25 |
|
jtulach@119
|
26 |
package java.lang;
|
jtulach@119
|
27 |
|
jtulach@119
|
28 |
/**
|
jtulach@119
|
29 |
* A resource that must be closed when it is no longer needed.
|
jtulach@119
|
30 |
*
|
jtulach@119
|
31 |
* @author Josh Bloch
|
jtulach@119
|
32 |
* @since 1.7
|
jtulach@119
|
33 |
*/
|
jtulach@119
|
34 |
public interface AutoCloseable {
|
jtulach@119
|
35 |
/**
|
jtulach@119
|
36 |
* Closes this resource, relinquishing any underlying resources.
|
jtulach@119
|
37 |
* This method is invoked automatically on objects managed by the
|
jtulach@119
|
38 |
* {@code try}-with-resources statement.
|
jtulach@119
|
39 |
*
|
jtulach@119
|
40 |
* <p>While this interface method is declared to throw {@code
|
jtulach@119
|
41 |
* Exception}, implementers are <em>strongly</em> encouraged to
|
jtulach@119
|
42 |
* declare concrete implementations of the {@code close} method to
|
jtulach@119
|
43 |
* throw more specific exceptions, or to throw no exception at all
|
jtulach@119
|
44 |
* if the close operation cannot fail.
|
jtulach@119
|
45 |
*
|
jtulach@119
|
46 |
* <p><em>Implementers of this interface are also strongly advised
|
jtulach@119
|
47 |
* to not have the {@code close} method throw {@link
|
jtulach@119
|
48 |
* InterruptedException}.</em>
|
jtulach@119
|
49 |
*
|
jtulach@119
|
50 |
* This exception interacts with a thread's interrupted status,
|
jtulach@119
|
51 |
* and runtime misbehavior is likely to occur if an {@code
|
jtulach@119
|
52 |
* InterruptedException} is {@linkplain Throwable#addSuppressed
|
jtulach@119
|
53 |
* suppressed}.
|
jtulach@119
|
54 |
*
|
jtulach@119
|
55 |
* More generally, if it would cause problems for an
|
jtulach@119
|
56 |
* exception to be suppressed, the {@code AutoCloseable.close}
|
jtulach@119
|
57 |
* method should not throw it.
|
jtulach@119
|
58 |
*
|
jtulach@119
|
59 |
* <p>Note that unlike the {@link java.io.Closeable#close close}
|
jtulach@119
|
60 |
* method of {@link java.io.Closeable}, this {@code close} method
|
jtulach@119
|
61 |
* is <em>not</em> required to be idempotent. In other words,
|
jtulach@119
|
62 |
* calling this {@code close} method more than once may have some
|
jtulach@119
|
63 |
* visible side effect, unlike {@code Closeable.close} which is
|
jtulach@119
|
64 |
* required to have no effect if called more than once.
|
jtulach@119
|
65 |
*
|
jtulach@119
|
66 |
* However, implementers of this interface are strongly encouraged
|
jtulach@119
|
67 |
* to make their {@code close} methods idempotent.
|
jtulach@119
|
68 |
*
|
jtulach@119
|
69 |
* @throws Exception if this resource cannot be closed
|
jtulach@119
|
70 |
*/
|
jtulach@119
|
71 |
void close() throws Exception;
|
jtulach@119
|
72 |
}
|