1 /*
2  * Copyright (C) 2011 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 java.util.ArrayList;
20 import java.util.Locale;
21 import java.util.regex.Pattern;
22 
23 /**
24  * Describes how to configure a database.
25  * <p>
26  * The purpose of this object is to keep track of all of the little
27  * configuration settings that are applied to a database after it
28  * is opened so that they can be applied to all connections in the
29  * connection pool uniformly.
30  * </p><p>
31  * Each connection maintains its own copy of this object so it can
32  * keep track of which settings have already been applied.
33  * </p>
34  *
35  * @hide
36  */
37 public final class SQLiteDatabaseConfiguration {
38     // The pattern we use to strip email addresses from database paths
39     // when constructing a label to use in log messages.
40     private static final Pattern EMAIL_IN_DB_PATTERN =
41             Pattern.compile("[\\w\\.\\-]+@[\\w\\.\\-]+");
42 
43     /**
44      * Special path used by in-memory databases.
45      */
46     public static final String MEMORY_DB_PATH = ":memory:";
47 
48     /**
49      * The database path.
50      */
51     public final String path;
52 
53     /**
54      * The label to use to describe the database when it appears in logs.
55      * This is derived from the path but is stripped to remove PII.
56      */
57     public final String label;
58 
59     /**
60      * The flags used to open the database.
61      */
62     public int openFlags;
63 
64     /**
65      * The maximum size of the prepared statement cache for each database connection.
66      * Must be non-negative.
67      *
68      * Default is 25.
69      */
70     public int maxSqlCacheSize;
71 
72     /**
73      * The database locale.
74      *
75      * Default is the value returned by {@link Locale#getDefault()}.
76      */
77     public Locale locale;
78 
79     /**
80      * True if foreign key constraints are enabled.
81      *
82      * Default is false.
83      */
84     public boolean foreignKeyConstraintsEnabled;
85 
86     /**
87      * The custom functions to register.
88      */
89     public final ArrayList<SQLiteCustomFunction> customFunctions =
90             new ArrayList<SQLiteCustomFunction>();
91 
92     /**
93      * The size in bytes of each lookaside slot
94      *
95      * <p>If negative, the default lookaside configuration will be used
96      */
97     public int lookasideSlotSize = -1;
98 
99     /**
100      * The total number of lookaside memory slots per database connection
101      *
102      * <p>If negative, the default lookaside configuration will be used
103      */
104     public int lookasideSlotCount = -1;
105 
106     /**
107      * The number of milliseconds that SQLite connection is allowed to be idle before it
108      * is closed and removed from the pool.
109      * <p>By default, idle connections are not closed
110      */
111     public long idleConnectionTimeoutMs = Long.MAX_VALUE;
112 
113     /**
114      * Journal mode to use when {@link SQLiteDatabase#ENABLE_WRITE_AHEAD_LOGGING} is not set.
115      * <p>Default is returned by {@link SQLiteGlobal#getDefaultJournalMode()}
116      */
117     public String journalMode;
118 
119     /**
120      * Synchronous mode to use.
121      * <p>Default is returned by {@link SQLiteGlobal#getDefaultSyncMode()}
122      * or {@link SQLiteGlobal#getWALSyncMode()} depending on journal mode
123      */
124     public String syncMode;
125 
126     /**
127      * Creates a database configuration with the required parameters for opening a
128      * database and default values for all other parameters.
129      *
130      * @param path The database path.
131      * @param openFlags Open flags for the database, such as {@link SQLiteDatabase#OPEN_READWRITE}.
132      */
SQLiteDatabaseConfiguration(String path, int openFlags)133     public SQLiteDatabaseConfiguration(String path, int openFlags) {
134         if (path == null) {
135             throw new IllegalArgumentException("path must not be null.");
136         }
137 
138         this.path = path;
139         label = stripPathForLogs(path);
140         this.openFlags = openFlags;
141 
142         // Set default values for optional parameters.
143         maxSqlCacheSize = 25;
144         locale = Locale.getDefault();
145     }
146 
147     /**
148      * Creates a database configuration as a copy of another configuration.
149      *
150      * @param other The other configuration.
151      */
SQLiteDatabaseConfiguration(SQLiteDatabaseConfiguration other)152     public SQLiteDatabaseConfiguration(SQLiteDatabaseConfiguration other) {
153         if (other == null) {
154             throw new IllegalArgumentException("other must not be null.");
155         }
156 
157         this.path = other.path;
158         this.label = other.label;
159         updateParametersFrom(other);
160     }
161 
162     /**
163      * Updates the non-immutable parameters of this configuration object
164      * from the other configuration object.
165      *
166      * @param other The object from which to copy the parameters.
167      */
updateParametersFrom(SQLiteDatabaseConfiguration other)168     public void updateParametersFrom(SQLiteDatabaseConfiguration other) {
169         if (other == null) {
170             throw new IllegalArgumentException("other must not be null.");
171         }
172         if (!path.equals(other.path)) {
173             throw new IllegalArgumentException("other configuration must refer to "
174                     + "the same database.");
175         }
176 
177         openFlags = other.openFlags;
178         maxSqlCacheSize = other.maxSqlCacheSize;
179         locale = other.locale;
180         foreignKeyConstraintsEnabled = other.foreignKeyConstraintsEnabled;
181         customFunctions.clear();
182         customFunctions.addAll(other.customFunctions);
183         lookasideSlotSize = other.lookasideSlotSize;
184         lookasideSlotCount = other.lookasideSlotCount;
185         idleConnectionTimeoutMs = other.idleConnectionTimeoutMs;
186         journalMode = other.journalMode;
187         syncMode = other.syncMode;
188     }
189 
190     /**
191      * Returns true if the database is in-memory.
192      * @return True if the database is in-memory.
193      */
isInMemoryDb()194     public boolean isInMemoryDb() {
195         return path.equalsIgnoreCase(MEMORY_DB_PATH);
196     }
197 
useCompatibilityWal()198     boolean useCompatibilityWal() {
199         return journalMode == null && syncMode == null
200                 && (openFlags & SQLiteDatabase.DISABLE_COMPATIBILITY_WAL) == 0;
201     }
202 
stripPathForLogs(String path)203     private static String stripPathForLogs(String path) {
204         if (path.indexOf('@') == -1) {
205             return path;
206         }
207         return EMAIL_IN_DB_PATTERN.matcher(path).replaceAll("XX@YY");
208     }
209 
isLookasideConfigSet()210     boolean isLookasideConfigSet() {
211         return lookasideSlotCount >= 0 && lookasideSlotSize >= 0;
212     }
213 }
214