Save This Page
1 /*
2
3 Derby - Class org.apache.derby.io.StorageFactory
4
5 Licensed to the Apache Software Foundation (ASF) under one or more
6 contributor license agreements. See the NOTICE file distributed with
7 this work for additional information regarding copyright ownership.
8 The ASF licenses this file to You under the Apache License, Version 2.0
9 (the "License"); you may not use this file except in compliance with
10 the License. You may obtain a copy of the License at
11
12 http://www.apache.org/licenses/LICENSE-2.0
13
14 Unless required by applicable law or agreed to in writing, software
15 distributed under the License is distributed on an "AS IS" BASIS,
16 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
17 See the License for the specific language governing permissions and
18 limitations under the License.
19
20 */
21
22 package org.apache.derby.io;
23
24 import java.io.IOException;
25
26 /**
27 * This interface provides basic storage functions needed for read only databases. Most storage
28 * implementations will be read-write and implement the WritableStorageFactory extension of this
29 * interface.
30 *
31 *<p>
32 * The database engine uses this interface to access storage. The normal database engine
33 * implements this interface using disk files and the standard java.io classes.
34 *
35 *<p>
36 * The storage factory must implement writable temporary files, even if the database is read-only or
37 * if the storage factory is read-only (i.e. it does not implement the WritableStorageFactory extension of this
38 * interface). Temporary files are those created under the temporary file directory. See
39 * {@link #getTempDir method getTempDir()}.
40 *
41 *<p>The database engine can be turned into a RAM based engine by providing a RAM based implementation of this interface.
42 *
43 *<p>There is one instance of the StorageFactory per database if the log files are kept in the database directory.
44 * If the log files are kept on a separate device then a second StorageFactory is instantiated to hold the log files.
45 * The database or log device name is set when the init method is called.
46 * The init method is called once per instance, before any other StorageFactory method.
47 *
48 *<p>The class implementing this interface must have a public niladic constructor. The init method will be called
49 * before any other method to set the database directory name, to tell the factory to create the database
50 * directory if necessary, and to allow the implementation to perform any initializations it requires. The
51 * database name set in the init method forms a separate name space. Different StorageFactory instances, with
52 * different database directory names, must ensure that their files do not clash. So, for instance,
53 * storageFactory1.newStorageFile( "x") must be a separate file from storageFactory2.newStorageFile( "x").
54 *
55 *<p>The database engine will call this interface's methods from its own privilege blocks. This does not give
56 * a StorageFactory implementation carte blanche: a security manager can still forbid the implemeting class from
57 * executing a privileged action. However, the security manager will not look in the calling stack beyond the
58 * database engine.
59 *
60 *<p>Each StorageFactory instance may be concurrently used by multiple threads. Each StorageFactory implementation
61 * must be thread safe.
62 *
63 *<p>A StorageFactory implementation is plugged into the database engine via a sub-protocol. Sub-protocol <i>xxx</i> is
64 * tied to a StorageFactory implementation class via the derby.subSubProtocol.<i>xxx</i> system property. So,
65 * to use StorageFactory implementation class MyStorageFactory with database myDB you would set the system
66 * property "derby.subSubProtocol.mysf=MyStorageFactory" and use the URL "jdbc:derby:mysf:myDB" to
67 * connect to the database.
68 *
69 * @see WritableStorageFactory
70 * @see StorageFile
71 * @see StorageRandomAccessFile
72 * @see <a href="http://java.sun.com/j2se/1.4.2/docs/api/java/io/File.html">java.io.File</a>
73 * @see <a href="http://java.sun.com/j2se/1.4.2/docs/api/java/io/RandomAccessFile.html">java.io.RandomAccessFile</a>
74 * @see <a href="http://java.sun.com/j2se/1.4.2/docs/api/java/io/InputStream.html">java.io.InputStream</a>
75 * @see <a href="http://java.sun.com/j2se/1.4.2/docs/api/java/io/OutputStream.html">java.io.OutputStream</a>
76 */
77 public interface StorageFactory
78 {
79
80 /**
81 * Classes implementing the StorageFactory interface must have a null
82 * constructor. The init method is called when the database is booted up to
83 * initialize the class. It should perform all actions necessary to start the
84 * basic storage, such as creating a temporary file directory.
85 *
86 * This method should not create the database directory.
87 *<p>
88 * The init method will be called once, before any other method is called, and will not
89 * be called again.
90 *
91 * @param home The name of the directory containing the database. It comes from the system.home system property.
92 * It may be null. A storage factory may decide to ignore this parameter. (For instance the classpath
93 * storage factory ignores it).
94 * @param databaseName The name of the database (directory). The name does not include the subsubprotocol.
95 * If null then the storage factory will only be used to deal with the directory containing
96 * the databases.
97 * @param tempDirName The name of the temporary file directory set in properties. If null then a default
98 * directory should be used. Each database should get a separate temporary file
99 * directory within this one to avoid collisions.
100 * @param uniqueName A unique name that can be used to create the temporary file directory for this database.
101 * If null then temporary files will not be created in this StorageFactory instance, and the
102 * temporary file directory should not be created.
103 *
104 * @exception IOException
105 */
106 public void init( String home, String databaseName, String tempDirName, String uniqueName)
107 throws IOException;
108
109 /**
110 * The shutdown method is called during the normal shutdown of the database. However, the database
111 * engine cannot guarantee that shutdown will be called. If the JVM terminates abnormally then it will
112 * not be called.
113 */
114 public void shutdown();
115
116 /**
117 * Get the canonical name of the database. This is a name that uniquely identifies it. It is system dependent.
118 *
119 * The normal, disk based implementation uses method java.io.File.getCanonicalPath on the directory holding the
120 * database to construct the canonical name.
121 *
122 * @return the canonical name
123 *
124 * @exception IOException if an IO error occurred during the construction of the name.
125 */
126 public String getCanonicalName() throws IOException;
127
128 /**
129 * Construct a StorageFile from a path name.
130 *
131 * @param path The path name of the file. If null then return the database directory.
132 * If this parameter denotes the temp directory or a directory under the temp
133 * directory then the resulting StorageFile denotes a temporary file. Otherwise
134 * the path must be relative to the database and the resulting StorageFile denotes a
135 * regular database file (non-temporary).
136 *
137 * @return A corresponding StorageFile object
138 */
139 public StorageFile newStorageFile( String path);
140
141 /**
142 * Construct a non-temporary StorageFile from a directory and file name.
143 *
144 * @param directoryName The directory part of the path name. If this parameter denotes the
145 * temp directory or a directory under the temp directory then the resulting
146 * StorageFile denotes a temporary file. Otherwise the directory name must be
147 * relative to the database and the resulting StorageFile denotes a
148 * regular database file (non-temporary).
149 * @param fileName The name of the file within the directory.
150 *
151 * @return A corresponding StorageFile object
152 */
153 public StorageFile newStorageFile( String directoryName, String fileName);
154
155 /**
156 * Construct a StorageFile from a directory and file name. The StorageFile may denote a temporary file
157 * or a non-temporary database file, depending upon the directoryName parameter.
158 *
159 * @param directoryName The directory part of the path name. If this parameter denotes the
160 * temp directory or a directory under the temp directory then the resulting
161 * StorageFile denotes a temporary file. Otherwise the resulting StorageFile denotes a
162 * regular database file (non-temporary).
163 * @param fileName The name of the file within the directory.
164 *
165 * @return A corresponding StorageFile object
166 */
167 public StorageFile newStorageFile( StorageFile directoryName, String fileName);
168
169 /**
170 * Get the pathname separator character used by the StorageFile implementation. This is the
171 * separator that must be used in directory and file name strings.
172 *
173 * @return the pathname separator character. (Normally '/' or '\').
174 */
175 public char getSeparator();
176
177 /**
178 * Get the abstract name of the directory that holds temporary files.
179 *<p>
180 * The StorageFactory implementation
181 * is not required to make temporary files persistent. That is, files created in the temp directory are
182 * not required to survive a shutdown of the database engine.
183 *<p>
184 * However, files created in the temp directory must be writable, <b>even if the database is
185 * otherwise read-only</b>.
186 *
187 * @return a directory name
188 */
189 public StorageFile getTempDir();
190
191 /**
192 * This method is used to determine whether the storage is fast (RAM based) or slow (disk based).
193 * It may be used by the database engine to determine the default size of the page cache.
194 *
195 * @return <b>true</b> if the storage is fast, <b>false</b> if it is slow.
196 */
197 public boolean isFast();
198
199 /**
200 * Determine whether the database is read only. The database engine supports read-only databases, even
201 * in file systems that are writable.
202 *
203 * @return <b>true</b> if the storage is read only, <b>false</b> if it is writable.
204 */
205 public boolean isReadOnlyDatabase();
206
207 /**
208 * Determine whether the storage supports random access. If random access is not supported then
209 * it will only be accessed using InputStreams and OutputStreams (if the database is writable).
210 *
211 * @return <b>true</b> if the storage supports random access, <b>false</b> if it is writable.
212 */
213 public boolean supportsRandomAccess();
214
215 /**
216 * The version number of this version of the StorageFactory interface and its subsidiary interfaces.
217 */
218 int VERSION_NUMBER = 1;
219
220 /**
221 * @return the StorageFactory version supported by this implementation
222 */
223 public int getStorageFactoryVersion();
224
225 /**
226 * Create and returns a temporary file in temporary file system of database
227 * @param prefix String to prefix the random name generator. It can be null
228 * @param suffix String to suffix the random name generator. ".tmp" will be
229 * used if null.
230 * @return StorageFile
231 */
232 public StorageFile createTemporaryFile (String prefix, String suffix)
233 throws IOException;
234 }