Interface StorageFactory

  • All Known Subinterfaces:
    WritableStorageFactory
    All Known Implementing Classes:
    BaseStorageFactory, CPStorageFactory, DirStorageFactory, JarStorageFactory, URLStorageFactory, VFMemoryStorageFactory

    public interface StorageFactory
    This interface provides basic storage functions needed for read only databases. Most storage implementations will be read-write and implement the WritableStorageFactory extension of this interface.

    The database engine uses this interface to access storage. The normal database engine implements this interface using disk files and the standard java.io classes.

    The storage factory must implement writable temporary files, even if the database is read-only or if the storage factory is read-only (i.e. it does not implement the WritableStorageFactory extension of this interface). Temporary files are those created under the temporary file directory. See method getTempDir().

    The database engine can be turned into a RAM based engine by providing a RAM based implementation of this interface.

    There is one instance of the StorageFactory per database if the log files are kept in the database directory. If the log files are kept on a separate device then a second StorageFactory is instantiated to hold the log files. The database or log device name is set when the init method is called. The init method is called once per instance, before any other StorageFactory method.

    The class implementing this interface must have a public niladic constructor. The init method will be called before any other method to set the database directory name, to tell the factory to create the database directory if necessary, and to allow the implementation to perform any initializations it requires. The database name set in the init method forms a separate name space. Different StorageFactory instances, with different database directory names, must ensure that their files do not clash. So, for instance, storageFactory1.newStorageFile( "x") must be a separate file from storageFactory2.newStorageFile( "x").

    The database engine will call this interface's methods from its own privilege blocks. This does not give a StorageFactory implementation carte blanche: a security manager can still forbid the implemeting class from executing a privileged action. However, the security manager will not look in the calling stack beyond the database engine.

    Each StorageFactory instance may be concurrently used by multiple threads. Each StorageFactory implementation must be thread safe.

    A StorageFactory implementation is plugged into the database engine via a sub-protocol. Sub-protocol xxx is tied to a StorageFactory implementation class via the derby.subSubProtocol.xxx system property. So, to use StorageFactory implementation class MyStorageFactory with database myDB you would set the system property "derby.subSubProtocol.mysf=MyStorageFactory" and use the URL "jdbc:derby:mysf:myDB" to connect to the database.

    See Also:
    WritableStorageFactory, StorageFile, StorageRandomAccessFile, java.io.File, java.io.RandomAccessFile, java.io.InputStream, java.io.OutputStream
    • Field Summary

      Fields 
      Modifier and Type Field Description
      static int VERSION_NUMBER
      The version number of this version of the StorageFactory interface and its subsidiary interfaces.
    • Method Summary

      All Methods Instance Methods Abstract Methods 
      Modifier and Type Method Description
      StorageFile createTemporaryFile​(java.lang.String prefix, java.lang.String suffix)
      Create and returns a temporary file in temporary file system of database
      java.lang.String getCanonicalName()
      Get the canonical name of the database.
      char getSeparator()
      Get the pathname separator character used by the StorageFile implementation.
      int getStorageFactoryVersion()  
      StorageFile getTempDir()
      Get the abstract name of the directory that holds temporary files.
      void init​(java.lang.String home, java.lang.String databaseName, java.lang.String tempDirName, java.lang.String uniqueName)
      Classes implementing the StorageFactory interface must have a null constructor.
      boolean isFast()
      This method is used to determine whether the storage is fast (RAM based) or slow (disk based).
      boolean isReadOnlyDatabase()
      Determine whether the database is read only.
      StorageFile newStorageFile​(java.lang.String path)
      Construct a StorageFile from a path name.
      StorageFile newStorageFile​(java.lang.String directoryName, java.lang.String fileName)
      Construct a non-temporary StorageFile from a directory and file name.
      StorageFile newStorageFile​(StorageFile directoryName, java.lang.String fileName)
      Construct a StorageFile from a directory and file name.
      void setCanonicalName​(java.lang.String name)
      Set the canonicalName.
      void shutdown()
      The shutdown method is called during the normal shutdown of the database.
      boolean supportsRandomAccess()
      Determine whether the storage supports random access.
    • Field Detail

      • VERSION_NUMBER

        static final int VERSION_NUMBER
        The version number of this version of the StorageFactory interface and its subsidiary interfaces.
        See Also:
        Constant Field Values
    • Method Detail

      • init

        void init​(java.lang.String home,
                  java.lang.String databaseName,
                  java.lang.String tempDirName,
                  java.lang.String uniqueName)
           throws java.io.IOException
        Classes implementing the StorageFactory interface must have a null constructor. The init method is called when the database is booted up to initialize the class. It should perform all actions necessary to start the basic storage, such as creating a temporary file directory. This method should not create the database directory.

        The init method will be called once, before any other method is called, and will not be called again.

        Parameters:
        home - The name of the directory containing the database. It comes from the system.home system property. It may be null. A storage factory may decide to ignore this parameter. (For instance the classpath storage factory ignores it).
        databaseName - The name of the database (directory). The name does not include the subsubprotocol. If null then the storage factory will only be used to deal with the directory containing the databases.
        tempDirName - The name of the temporary file directory set in properties. If null then a default directory should be used. Each database should get a separate temporary file directory within this one to avoid collisions.
        uniqueName - A unique name that can be used to create the temporary file directory for this database. If null then temporary files will not be created in this StorageFactory instance, and the temporary file directory should not be created.
        Throws:
        java.io.IOException
      • shutdown

        void shutdown()
        The shutdown method is called during the normal shutdown of the database. However, the database engine cannot guarantee that shutdown will be called. If the JVM terminates abnormally then it will not be called.
      • getCanonicalName

        java.lang.String getCanonicalName()
                                   throws java.io.IOException
        Get the canonical name of the database. This is a name that uniquely identifies it. It is system dependent. The normal, disk based implementation uses method java.io.File.getCanonicalPath on the directory holding the database to construct the canonical name.
        Returns:
        the canonical name
        Throws:
        java.io.IOException - if an IO error occurred during the construction of the name.
      • newStorageFile

        StorageFile newStorageFile​(java.lang.String path)
        Construct a StorageFile from a path name.
        Parameters:
        path - The path name of the file. If null then return the database directory. If this parameter denotes the temp directory or a directory under the temp directory then the resulting StorageFile denotes a temporary file. Otherwise the path must be relative to the database and the resulting StorageFile denotes a regular database file (non-temporary).
        Returns:
        A corresponding StorageFile object
      • newStorageFile

        StorageFile newStorageFile​(java.lang.String directoryName,
                                   java.lang.String fileName)
        Construct a non-temporary StorageFile from a directory and file name.
        Parameters:
        directoryName - The directory part of the path name. If this parameter denotes the temp directory or a directory under the temp directory then the resulting StorageFile denotes a temporary file. Otherwise the directory name must be relative to the database and the resulting StorageFile denotes a regular database file (non-temporary).
        fileName - The name of the file within the directory.
        Returns:
        A corresponding StorageFile object
      • newStorageFile

        StorageFile newStorageFile​(StorageFile directoryName,
                                   java.lang.String fileName)
        Construct a StorageFile from a directory and file name. The StorageFile may denote a temporary file or a non-temporary database file, depending upon the directoryName parameter.
        Parameters:
        directoryName - The directory part of the path name. If this parameter denotes the temp directory or a directory under the temp directory then the resulting StorageFile denotes a temporary file. Otherwise the resulting StorageFile denotes a regular database file (non-temporary).
        fileName - The name of the file within the directory.
        Returns:
        A corresponding StorageFile object
      • getSeparator

        char getSeparator()
        Get the pathname separator character used by the StorageFile implementation. This is the separator that must be used in directory and file name strings.
        Returns:
        the pathname separator character. (Normally '/' or '\').
      • getTempDir

        StorageFile getTempDir()
        Get the abstract name of the directory that holds temporary files.

        The StorageFactory implementation is not required to make temporary files persistent. That is, files created in the temp directory are not required to survive a shutdown of the database engine.

        However, files created in the temp directory must be writable, even if the database is otherwise read-only.

        Returns:
        a directory name
      • isFast

        boolean isFast()
        This method is used to determine whether the storage is fast (RAM based) or slow (disk based). It may be used by the database engine to determine the default size of the page cache.
        Returns:
        true if the storage is fast, false if it is slow.
      • isReadOnlyDatabase

        boolean isReadOnlyDatabase()
        Determine whether the database is read only. The database engine supports read-only databases, even in file systems that are writable.
        Returns:
        true if the storage is read only, false if it is writable.
      • supportsRandomAccess

        boolean supportsRandomAccess()
        Determine whether the storage supports random access. If random access is not supported then it will only be accessed using InputStreams and OutputStreams (if the database is writable).
        Returns:
        true if the storage supports random access, false if it is writable.
      • getStorageFactoryVersion

        int getStorageFactoryVersion()
        Returns:
        the StorageFactory version supported by this implementation
      • createTemporaryFile

        StorageFile createTemporaryFile​(java.lang.String prefix,
                                        java.lang.String suffix)
                                 throws java.io.IOException
        Create and returns a temporary file in temporary file system of database
        Parameters:
        prefix - String to prefix the random name generator. It can be null
        suffix - String to suffix the random name generator. ".tmp" will be used if null.
        Returns:
        StorageFile
        Throws:
        java.io.IOException
      • setCanonicalName

        void setCanonicalName​(java.lang.String name)
        Set the canonicalName. May need adjustment due to DERBY-5096
        Parameters:
        name - uniquely identifiable name for this database