1 /*
2  * Copyright (C) 2007 The Android Open Source Project
3  *
4  * Licensed under the Apache License, Version 2.0 (the "License");
5  * you may not use this file except in compliance with the License.
6  * You may obtain a copy of the License at
7  *
8  *      http://www.apache.org/licenses/LICENSE-2.0
9  *
10  * Unless required by applicable law or agreed to in writing, software
11  * distributed under the License is distributed on an "AS IS" BASIS,
12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13  * See the License for the specific language governing permissions and
14  * limitations under the License.
15  */
16 
17 package android.database.sqlite;
18 
19 import android.compat.annotation.UnsupportedAppUsage;
20 
21 import java.io.Closeable;
22 
23 /**
24  * An object created from a SQLiteDatabase that can be closed.
25  *
26  * This class implements a primitive reference counting scheme for database objects.
27  */
28 public abstract class SQLiteClosable implements Closeable {
29     @UnsupportedAppUsage
30     private int mReferenceCount = 1;
31 
32     /**
33      * Called when the last reference to the object was released by
34      * a call to {@link #releaseReference()} or {@link #close()}.
35      */
onAllReferencesReleased()36     protected abstract void onAllReferencesReleased();
37 
38     /**
39      * Called when the last reference to the object was released by
40      * a call to {@link #releaseReferenceFromContainer()}.
41      *
42      * @deprecated Do not use.
43      */
44     @Deprecated
onAllReferencesReleasedFromContainer()45     protected void onAllReferencesReleasedFromContainer() {
46         onAllReferencesReleased();
47     }
48 
49     /**
50      * Acquires a reference to the object.
51      *
52      * @throws IllegalStateException if the last reference to the object has already
53      * been released.
54      */
acquireReference()55     public void acquireReference() {
56         synchronized(this) {
57             if (mReferenceCount <= 0) {
58                 throw new IllegalStateException(
59                         "attempt to re-open an already-closed object: " + this);
60             }
61             mReferenceCount++;
62         }
63     }
64 
65     /**
66      * Releases a reference to the object, closing the object if the last reference
67      * was released.
68      *
69      * @see #onAllReferencesReleased()
70      */
releaseReference()71     public void releaseReference() {
72         boolean refCountIsZero = false;
73         synchronized(this) {
74             refCountIsZero = --mReferenceCount == 0;
75         }
76         if (refCountIsZero) {
77             onAllReferencesReleased();
78         }
79     }
80 
81     /**
82      * Releases a reference to the object that was owned by the container of the object,
83      * closing the object if the last reference was released.
84      *
85      * @see #onAllReferencesReleasedFromContainer()
86      * @deprecated Do not use.
87      */
88     @Deprecated
releaseReferenceFromContainer()89     public void releaseReferenceFromContainer() {
90         boolean refCountIsZero = false;
91         synchronized(this) {
92             refCountIsZero = --mReferenceCount == 0;
93         }
94         if (refCountIsZero) {
95             onAllReferencesReleasedFromContainer();
96         }
97     }
98 
99     /**
100      * Releases a reference to the object, closing the object if the last reference
101      * was released.
102      *
103      * Calling this method is equivalent to calling {@link #releaseReference}.
104      *
105      * @see #releaseReference()
106      * @see #onAllReferencesReleased()
107      */
close()108     public void close() {
109         releaseReference();
110     }
111 }
112