001: /*
002:
003: Derby - Class org.apache.derby.io.StorageFactory
004:
005: Licensed to the Apache Software Foundation (ASF) under one or more
006: contributor license agreements. See the NOTICE file distributed with
007: this work for additional information regarding copyright ownership.
008: The ASF licenses this file to You under the Apache License, Version 2.0
009: (the "License"); you may not use this file except in compliance with
010: the License. You may obtain a copy of the License at
011:
012: http://www.apache.org/licenses/LICENSE-2.0
013:
014: Unless required by applicable law or agreed to in writing, software
015: distributed under the License is distributed on an "AS IS" BASIS,
016: WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
017: See the License for the specific language governing permissions and
018: limitations under the License.
019:
020: */
021:
022: package org.apache.derby.io;
023:
024: import java.io.IOException;
025:
026: /**
027: * This interface provides basic storage functions needed for read only databases. Most storage
028: * implementations will be read-write and implement the WritableStorageFactory extension of this
029: * interface.
030: *
031: *<p>
032: * The database engine uses this interface to access storage. The normal database engine
033: * implements this interface using disk files and the standard java.io classes.
034: *
035: *<p>
036: * The storage factory must implement writable temporary files, even if the database is read-only or
037: * if the storage factory is read-only (i.e. it does not implement the WritableStorageFactory extension of this
038: * interface). Temporary files are those created under the temporary file directory. See
039: * {@link #getTempDir method getTempDir()}.
040: *
041: *<p>The database engine can be turned into a RAM based engine by providing a RAM based implementation of this interface.
042: *
043: *<p>There is one instance of the StorageFactory per database if the log files are kept in the database directory.
044: * If the log files are kept on a separate device then a second StorageFactory is instantiated to hold the log files.
045: * The database or log device name is set when the init method is called.
046: * The init method is called once per instance, before any other StorageFactory method.
047: *
048: *<p>The class implementing this interface must have a public niladic constructor. The init method will be called
049: * before any other method to set the database directory name, to tell the factory to create the database
050: * directory if necessary, and to allow the implementation to perform any initializations it requires. The
051: * database name set in the init method forms a separate name space. Different StorageFactory instances, with
052: * different database directory names, must ensure that their files do not clash. So, for instance,
053: * storageFactory1.newStorageFile( "x") must be a separate file from storageFactory2.newStorageFile( "x").
054: *
055: *<p>The database engine will call this interface's methods from its own privilege blocks. This does not give
056: * a StorageFactory implementation carte blanche: a security manager can still forbid the implemeting class from
057: * executing a privileged action. However, the security manager will not look in the calling stack beyond the
058: * database engine.
059: *
060: *<p>Each StorageFactory instance may be concurrently used by multiple threads. Each StorageFactory implementation
061: * must be thread safe.
062: *
063: *<p>A StorageFactory implementation is plugged into the database engine via a sub-protocol. Sub-protocol <i>xxx</i> is
064: * tied to a StorageFactory implementation class via the derby.subSubProtocol.<i>xxx</i> system property. So,
065: * to use StorageFactory implementation class MyStorageFactory with database myDB you would set the system
066: * property "derby.subSubProtocol.mysf=MyStorageFactory" and use the URL "jdbc:derby:mysf:myDB" to
067: * connect to the database.
068: *
069: * @see WritableStorageFactory
070: * @see StorageFile
071: * @see StorageRandomAccessFile
072: * @see <a href="http://java.sun.com/j2se/1.4.2/docs/api/java/io/File.html">java.io.File</a>
073: * @see <a href="http://java.sun.com/j2se/1.4.2/docs/api/java/io/RandomAccessFile.html">java.io.RandomAccessFile</a>
074: * @see <a href="http://java.sun.com/j2se/1.4.2/docs/api/java/io/InputStream.html">java.io.InputStream</a>
075: * @see <a href="http://java.sun.com/j2se/1.4.2/docs/api/java/io/OutputStream.html">java.io.OutputStream</a>
076: */
077: public interface StorageFactory {
078:
079: /**
080: * Classes implementing the StorageFactory interface must have a null
081: * constructor. The init method is called when the database is booted up to
082: * initialize the class. It should perform all actions necessary to start the
083: * basic storage, such as creating a temporary file directory.
084: *
085: * This method should not create the database directory.
086: *<p>
087: * The init method will be called once, before any other method is called, and will not
088: * be called again.
089: *
090: * @param home The name of the directory containing the database. It comes from the system.home system property.
091: * It may be null. A storage factory may decide to ignore this parameter. (For instance the classpath
092: * storage factory ignores it).
093: * @param databaseName The name of the database (directory). The name does not include the subsubprotocol.
094: * If null then the storage factory will only be used to deal with the directory containing
095: * the databases.
096: * @param tempDirName The name of the temporary file directory set in properties. If null then a default
097: * directory should be used. Each database should get a separate temporary file
098: * directory within this one to avoid collisions.
099: * @param uniqueName A unique name that can be used to create the temporary file directory for this database.
100: * If null then temporary files will not be created in this StorageFactory instance, and the
101: * temporary file directory should not be created.
102: *
103: * @exception IOException
104: */
105: public void init(String home, String databaseName,
106: String tempDirName, String uniqueName) throws IOException;
107:
108: /**
109: * The shutdown method is called during the normal shutdown of the database. However, the database
110: * engine cannot guarantee that shutdown will be called. If the JVM terminates abnormally then it will
111: * not be called.
112: */
113: public void shutdown();
114:
115: /**
116: * Get the canonical name of the database. This is a name that uniquely identifies it. It is system dependent.
117: *
118: * The normal, disk based implementation uses method java.io.File.getCanonicalPath on the directory holding the
119: * database to construct the canonical name.
120: *
121: * @return the canonical name
122: *
123: * @exception IOException if an IO error occurred during the construction of the name.
124: */
125: public String getCanonicalName() throws IOException;
126:
127: /**
128: * Construct a StorageFile from a path name.
129: *
130: * @param path The path name of the file. If null then return the database directory.
131: * If this parameter denotes the temp directory or a directory under the temp
132: * directory then the resulting StorageFile denotes a temporary file. Otherwise
133: * the path must be relative to the database and the resulting StorageFile denotes a
134: * regular database file (non-temporary).
135: *
136: * @return A corresponding StorageFile object
137: */
138: public StorageFile newStorageFile(String path);
139:
140: /**
141: * Construct a non-temporary StorageFile from a directory and file name.
142: *
143: * @param directoryName The directory part of the path name. If this parameter denotes the
144: * temp directory or a directory under the temp directory then the resulting
145: * StorageFile denotes a temporary file. Otherwise the directory name must be
146: * relative to the database and the resulting StorageFile denotes a
147: * regular database file (non-temporary).
148: * @param fileName The name of the file within the directory.
149: *
150: * @return A corresponding StorageFile object
151: */
152: public StorageFile newStorageFile(String directoryName,
153: 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,
168: String fileName);
169:
170: /**
171: * Get the pathname separator character used by the StorageFile implementation. This is the
172: * separator that must be used in directory and file name strings.
173: *
174: * @return the pathname separator character. (Normally '/' or '\').
175: */
176: public char getSeparator();
177:
178: /**
179: * Get the abstract name of the directory that holds temporary files.
180: *<p>
181: * The StorageFactory implementation
182: * is not required to make temporary files persistent. That is, files created in the temp directory are
183: * not required to survive a shutdown of the database engine.
184: *<p>
185: * However, files created in the temp directory must be writable, <b>even if the database is
186: * otherwise read-only</b>.
187: *
188: * @return a directory name
189: */
190: public StorageFile getTempDir();
191:
192: /**
193: * This method is used to determine whether the storage is fast (RAM based) or slow (disk based).
194: * It may be used by the database engine to determine the default size of the page cache.
195: *
196: * @return <b>true</b> if the storage is fast, <b>false</b> if it is slow.
197: */
198: public boolean isFast();
199:
200: /**
201: * Determine whether the database is read only. The database engine supports read-only databases, even
202: * in file systems that are writable.
203: *
204: * @return <b>true</b> if the storage is read only, <b>false</b> if it is writable.
205: */
206: public boolean isReadOnlyDatabase();
207:
208: /**
209: * Determine whether the storage supports random access. If random access is not supported then
210: * it will only be accessed using InputStreams and OutputStreams (if the database is writable).
211: *
212: * @return <b>true</b> if the storage supports random access, <b>false</b> if it is writable.
213: */
214: public boolean supportsRandomAccess();
215:
216: /**
217: * The version number of this version of the StorageFactory interface and its subsidiary interfaces.
218: */
219: int VERSION_NUMBER = 1;
220:
221: /**
222: * @return the StorageFactory version supported by this implementation
223: */
224: public int getStorageFactoryVersion();
225: }
|