--- /dev/null
+/*\r
+\r
+ Derby - Class org.apache.derby.io.StorageFactory\r
+\r
+ Licensed to the Apache Software Foundation (ASF) under one or more\r
+ contributor license agreements. See the NOTICE file distributed with\r
+ this work for additional information regarding copyright ownership.\r
+ The ASF licenses this file to You under the Apache License, Version 2.0\r
+ (the "License"); you may not use this file except in compliance with\r
+ the License. You may obtain a copy of the License at\r
+\r
+ http://www.apache.org/licenses/LICENSE-2.0\r
+\r
+ Unless required by applicable law or agreed to in writing, software\r
+ distributed under the License is distributed on an "AS IS" BASIS,\r
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\r
+ See the License for the specific language governing permissions and\r
+ limitations under the License.\r
+\r
+ */\r
+\r
+package org.apache.derby.io;\r
+\r
+import java.io.IOException;\r
+\r
+/**\r
+ * This interface provides basic storage functions needed for read only databases. Most storage\r
+ * implementations will be read-write and implement the WritableStorageFactory extension of this\r
+ * interface.\r
+ *\r
+ *<p>\r
+ * The database engine uses this interface to access storage. The normal database engine\r
+ * implements this interface using disk files and the standard java.io classes.\r
+ *\r
+ *<p>\r
+ * The storage factory must implement writable temporary files, even if the database is read-only or\r
+ * if the storage factory is read-only (i.e. it does not implement the WritableStorageFactory extension of this\r
+ * interface). Temporary files are those created under the temporary file directory. See\r
+ * {@link #getTempDir method getTempDir()}.\r
+ *\r
+ *<p>The database engine can be turned into a RAM based engine by providing a RAM based implementation of this interface.\r
+ *\r
+ *<p>There is one instance of the StorageFactory per database if the log files are kept in the database directory.\r
+ * If the log files are kept on a separate device then a second StorageFactory is instantiated to hold the log files.\r
+ * The database or log device name is set when the init method is called.\r
+ * The init method is called once per instance, before any other StorageFactory method.\r
+ *\r
+ *<p>The class implementing this interface must have a public niladic constructor. The init method will be called\r
+ * before any other method to set the database directory name, to tell the factory to create the database\r
+ * directory if necessary, and to allow the implementation to perform any initializations it requires. The\r
+ * database name set in the init method forms a separate name space. Different StorageFactory instances, with\r
+ * different database directory names, must ensure that their files do not clash. So, for instance,\r
+ * storageFactory1.newStorageFile( "x") must be a separate file from storageFactory2.newStorageFile( "x").\r
+ *\r
+ *<p>The database engine will call this interface's methods from its own privilege blocks. This does not give\r
+ * a StorageFactory implementation carte blanche: a security manager can still forbid the implemeting class from\r
+ * executing a privileged action. However, the security manager will not look in the calling stack beyond the\r
+ * database engine.\r
+ *\r
+ *<p>Each StorageFactory instance may be concurrently used by multiple threads. Each StorageFactory implementation\r
+ * must be thread safe.\r
+ *\r
+ *<p>A StorageFactory implementation is plugged into the database engine via a sub-protocol. Sub-protocol <i>xxx</i> is\r
+ * tied to a StorageFactory implementation class via the derby.subSubProtocol.<i>xxx</i> system property. So,\r
+ * to use StorageFactory implementation class MyStorageFactory with database myDB you would set the system\r
+ * property "derby.subSubProtocol.mysf=MyStorageFactory" and use the URL "jdbc:derby:mysf:myDB" to\r
+ * connect to the database.\r
+ *\r
+ * @see WritableStorageFactory\r
+ * @see StorageFile\r
+ * @see StorageRandomAccessFile\r
+ * @see <a href="http://java.sun.com/j2se/1.4.2/docs/api/java/io/File.html">java.io.File</a>\r
+ * @see <a href="http://java.sun.com/j2se/1.4.2/docs/api/java/io/RandomAccessFile.html">java.io.RandomAccessFile</a>\r
+ * @see <a href="http://java.sun.com/j2se/1.4.2/docs/api/java/io/InputStream.html">java.io.InputStream</a>\r
+ * @see <a href="http://java.sun.com/j2se/1.4.2/docs/api/java/io/OutputStream.html">java.io.OutputStream</a>\r
+ */\r
+public interface StorageFactory\r
+{\r
+\r
+ /**\r
+ * Classes implementing the StorageFactory interface must have a null\r
+ * constructor. The init method is called when the database is booted up to\r
+ * initialize the class. It should perform all actions necessary to start the\r
+ * basic storage, such as creating a temporary file directory.\r
+ *\r
+ * This method should not create the database directory.\r
+ *<p>\r
+ * The init method will be called once, before any other method is called, and will not\r
+ * be called again.\r
+ *\r
+ * @param home The name of the directory containing the database. It comes from the system.home system property.\r
+ * It may be null. A storage factory may decide to ignore this parameter. (For instance the classpath\r
+ * storage factory ignores it).\r
+ * @param databaseName The name of the database (directory). The name does not include the subsubprotocol.\r
+ * If null then the storage factory will only be used to deal with the directory containing\r
+ * the databases.\r
+ * @param tempDirName The name of the temporary file directory set in properties. If null then a default\r
+ * directory should be used. Each database should get a separate temporary file\r
+ * directory within this one to avoid collisions.\r
+ * @param uniqueName A unique name that can be used to create the temporary file directory for this database.\r
+ * If null then temporary files will not be created in this StorageFactory instance, and the\r
+ * temporary file directory should not be created.\r
+ *\r
+ * @exception IOException\r
+ */\r
+ public void init( String home, String databaseName, String tempDirName, String uniqueName)\r
+ throws IOException;\r
+\r
+ /**\r
+ * The shutdown method is called during the normal shutdown of the database. However, the database\r
+ * engine cannot guarantee that shutdown will be called. If the JVM terminates abnormally then it will\r
+ * not be called.\r
+ */\r
+ public void shutdown();\r
+\r
+ /**\r
+ * Get the canonical name of the database. This is a name that uniquely identifies it. It is system dependent.\r
+ *\r
+ * The normal, disk based implementation uses method java.io.File.getCanonicalPath on the directory holding the\r
+ * database to construct the canonical name.\r
+ *\r
+ * @return the canonical name\r
+ *\r
+ * @exception IOException if an IO error occurred during the construction of the name.\r
+ */\r
+ public String getCanonicalName() throws IOException;\r
+ \r
+ /**\r
+ * Construct a StorageFile from a path name.\r
+ *\r
+ * @param path The path name of the file. If null then return the database directory.\r
+ * If this parameter denotes the temp directory or a directory under the temp\r
+ * directory then the resulting StorageFile denotes a temporary file. Otherwise\r
+ * the path must be relative to the database and the resulting StorageFile denotes a\r
+ * regular database file (non-temporary).\r
+ *\r
+ * @return A corresponding StorageFile object\r
+ */\r
+ public StorageFile newStorageFile( String path);\r
+\r
+ /**\r
+ * Construct a non-temporary StorageFile from a directory and file name.\r
+ *\r
+ * @param directoryName The directory part of the path name. If this parameter denotes the\r
+ * temp directory or a directory under the temp directory then the resulting\r
+ * StorageFile denotes a temporary file. Otherwise the directory name must be\r
+ * relative to the database and the resulting StorageFile denotes a\r
+ * regular database file (non-temporary).\r
+ * @param fileName The name of the file within the directory.\r
+ *\r
+ * @return A corresponding StorageFile object\r
+ */\r
+ public StorageFile newStorageFile( String directoryName, String fileName);\r
+\r
+ /**\r
+ * Construct a StorageFile from a directory and file name. The StorageFile may denote a temporary file\r
+ * or a non-temporary database file, depending upon the directoryName parameter.\r
+ *\r
+ * @param directoryName The directory part of the path name. If this parameter denotes the\r
+ * temp directory or a directory under the temp directory then the resulting\r
+ * StorageFile denotes a temporary file. Otherwise the resulting StorageFile denotes a\r
+ * regular database file (non-temporary).\r
+ * @param fileName The name of the file within the directory.\r
+ *\r
+ * @return A corresponding StorageFile object\r
+ */\r
+ public StorageFile newStorageFile( StorageFile directoryName, String fileName);\r
+\r
+ /**\r
+ * Get the pathname separator character used by the StorageFile implementation. This is the\r
+ * separator that must be used in directory and file name strings.\r
+ *\r
+ * @return the pathname separator character. (Normally '/' or '\').\r
+ */\r
+ public char getSeparator();\r
+\r
+ /**\r
+ * Get the abstract name of the directory that holds temporary files.\r
+ *<p>\r
+ * The StorageFactory implementation\r
+ * is not required to make temporary files persistent. That is, files created in the temp directory are\r
+ * not required to survive a shutdown of the database engine.\r
+ *<p>\r
+ * However, files created in the temp directory must be writable, <b>even if the database is\r
+ * otherwise read-only</b>.\r
+ *\r
+ * @return a directory name\r
+ */\r
+ public StorageFile getTempDir();\r
+\r
+ /**\r
+ * This method is used to determine whether the storage is fast (RAM based) or slow (disk based).\r
+ * It may be used by the database engine to determine the default size of the page cache.\r
+ *\r
+ * @return <b>true</b> if the storage is fast, <b>false</b> if it is slow.\r
+ */\r
+ public boolean isFast();\r
+\r
+ /**\r
+ * Determine whether the database is read only. The database engine supports read-only databases, even\r
+ * in file systems that are writable.\r
+ *\r
+ * @return <b>true</b> if the storage is read only, <b>false</b> if it is writable.\r
+ */\r
+ public boolean isReadOnlyDatabase();\r
+\r
+ /**\r
+ * Determine whether the storage supports random access. If random access is not supported then\r
+ * it will only be accessed using InputStreams and OutputStreams (if the database is writable).\r
+ *\r
+ * @return <b>true</b> if the storage supports random access, <b>false</b> if it is writable.\r
+ */\r
+ public boolean supportsRandomAccess();\r
+\r
+ /**\r
+ * The version number of this version of the StorageFactory interface and its subsidiary interfaces.\r
+ */\r
+ int VERSION_NUMBER = 1;\r
+\r
+ /**\r
+ * @return the StorageFactory version supported by this implementation\r
+ */\r
+ public int getStorageFactoryVersion();\r
+\r
+ /**\r
+ * Create and returns a temporary file in temporary file system of database\r
+ * @param prefix String to prefix the random name generator. It can be null\r
+ * @param suffix String to suffix the random name generator. ".tmp" will be\r
+ * used if null.\r
+ * @return StorageFile\r
+ */\r
+ public StorageFile createTemporaryFile (String prefix, String suffix)\r
+ throws IOException;\r
+}\r
projects / Benchmarks_CSolver.git / blobdiff