Interface StorageFile
-
- All Known Implementing Classes:
CPFile
,DirFile
,InputStreamFile
,JarDBFile
,URLFile
,VirtualFile
public interface StorageFile
This interface abstracts file naming. Any method in this interface that also appears in the java.io.File class should behave as the java.io.File method does.When used by the database engine all files will be under either the database directory, specified by the databaseName argument of the
StorageFactory.init
method, or under the temporary file directory returned by theStorageFactory.getTempDir
method. All relative path names are relative to the database directory.The database engine will call this interface's methods from its own privilege blocks.
Different threads may operate on the same underlying file at the same time, either through the same or different StorageFile objects. The StiFile implementation must be capable of handling this.
- See Also:
- java.io.File
-
-
Field Summary
Fields Modifier and Type Field Description static int
EXCLUSIVE_FILE_LOCK
static int
EXCLUSIVE_FILE_LOCK_NOT_AVAILABLE
static int
NO_FILE_LOCK_SUPPORT
-
Method Summary
All Methods Instance Methods Abstract Methods Modifier and Type Method Description boolean
canWrite()
Determine whether the named file is writable.boolean
createNewFile()
If the named file does not already exist then create it as an empty normal file.boolean
delete()
Deletes the named file or empty directory.boolean
deleteAll()
Deletes the named file and, if it is a directory, all the files and directories it contains.boolean
exists()
Tests whether the named file exists.java.lang.String
getCanonicalPath()
Converts this StorageFile into a canonical pathname string.int
getExclusiveFileLock()
Get an exclusive lock with this name.java.io.InputStream
getInputStream()
Creates an input stream from a file name.java.lang.String
getName()
java.io.OutputStream
getOutputStream()
Creates an output stream from a file name.java.io.OutputStream
getOutputStream(boolean append)
Creates an output stream from a file name.StorageFile
getParentDir()
Get the name of the parent directory if this name includes a parent.java.lang.String
getPath()
Converts this StorageFile into a pathname string.StorageRandomAccessFile
getRandomAccessFile(java.lang.String mode)
Get a random access file.boolean
isDirectory()
Tests whether the named file is a directory, or not.void
limitAccessToOwner()
Use when creating a new file.java.lang.String[]
list()
Get the names of all files and sub-directories in the directory named by this path name.boolean
mkdir()
Creates the named directory.boolean
mkdirs()
Creates the named directory, and all nonexistent parent directories.void
releaseExclusiveFileLock()
Release the resource associated with an earlier acquired exclusive lock releaseExclusiveFileLock() may delete the fileboolean
renameTo(StorageFile newName)
Rename the file denoted by this name.boolean
setReadOnly()
Make the named file or directory read-only.
-
-
-
Field Detail
-
NO_FILE_LOCK_SUPPORT
static final int NO_FILE_LOCK_SUPPORT
- See Also:
- Constant Field Values
-
EXCLUSIVE_FILE_LOCK
static final int EXCLUSIVE_FILE_LOCK
- See Also:
- Constant Field Values
-
EXCLUSIVE_FILE_LOCK_NOT_AVAILABLE
static final int EXCLUSIVE_FILE_LOCK_NOT_AVAILABLE
- See Also:
- Constant Field Values
-
-
Method Detail
-
list
java.lang.String[] list()
Get the names of all files and sub-directories in the directory named by this path name. This method is only used in a writable database.- Returns:
- An array of the names of the files and directories in this directory denoted by this abstract pathname. The returned array will have length 0 if this directory is empty. Returns null if this StorageFile is not a directory, or if an I/O error occurs. The return value is undefined if the database is read-only.
-
canWrite
boolean canWrite()
Determine whether the named file is writable.- Returns:
- true if the file exists and is writable, false if not.
-
exists
boolean exists()
Tests whether the named file exists.- Returns:
- true if the named file exists, false if not.
-
isDirectory
boolean isDirectory()
Tests whether the named file is a directory, or not. This is only called in writable storage factories.- Returns:
- true if named file exists and is a directory, false if not. The return value is undefined if the storage is read-only.
-
delete
boolean delete()
Deletes the named file or empty directory. This method does not delete non-empty directories.- Returns:
- true if the named file or directory is successfully deleted, false if not
-
deleteAll
boolean deleteAll()
Deletes the named file and, if it is a directory, all the files and directories it contains.- Returns:
- true if the named file or directory is successfully deleted, false if not
-
getPath
java.lang.String getPath()
Converts this StorageFile into a pathname string. The character returned by StorageFactory.getSeparator() is used to separate the directory and file names in the sequence.The returned path may include the database directory. Therefore it cannot be directly used to make an StorageFile equivalent to this one.
- Returns:
- The pathname as a string.
- See Also:
StorageFactory.getSeparator()
-
getCanonicalPath
java.lang.String getCanonicalPath() throws java.io.IOException
Converts this StorageFile into a canonical pathname string. The form of the canonical path is system dependent.- Returns:
- The pathname as a string.
- Throws:
java.io.IOException
- if an I/O error occurred while finding the canonical name
-
getName
java.lang.String getName()
- Returns:
- The last segment in the path name, "" if the path name sequence is empty.
-
createNewFile
boolean createNewFile() throws java.io.IOException
If the named file does not already exist then create it as an empty normal file. The implementation must synchronize with other threads accessing the same file (in the same or a different process). If two threads both attempt to create a file with the same name at the same time then at most one should succeed.- Returns:
- true if this thread's invocation of createNewFile successfully created the named file; false if not, i.e. false if the named file already exists or if another concurrent thread created it.
- Throws:
java.io.IOException
- - If the directory does not exist or some other I/O error occurred
-
renameTo
boolean renameTo(StorageFile newName)
Rename the file denoted by this name. Note that StorageFile objects are immutable. This method renames the underlying file, it does not change this StorageFile object. The StorageFile object denotes the same name as before, however the exists() method will return false after the renameTo method executes successfully.It is not specified whether this method will succeed if a file already exists under the new name.
- Parameters:
newName
- the new name.- Returns:
- true if the rename succeeded, false if not.
-
mkdir
boolean mkdir()
Creates the named directory.- Returns:
- true if the directory was created; false if not.
-
mkdirs
boolean mkdirs()
Creates the named directory, and all nonexistent parent directories.- Returns:
- true if the directory was created, false if not
-
getParentDir
StorageFile getParentDir()
Get the name of the parent directory if this name includes a parent.- Returns:
- An StorageFile denoting the parent directory of this StorageFile, if it has a parent, null if it does not have a parent.
-
setReadOnly
boolean setReadOnly()
Make the named file or directory read-only. This interface does not specify whether this also makes the file undeletable.- Returns:
- true if the named file or directory was made read-only, or it already was read-only; false if not.
-
getOutputStream
java.io.OutputStream getOutputStream() throws java.io.FileNotFoundException
Creates an output stream from a file name. If a normal file already exists with this name it will first be truncated to zero length.- Returns:
- an output stream suitable for writing to the file.
- Throws:
java.io.FileNotFoundException
- if the file exists but is a directory rather than a regular file, does not exist but cannot be created, or cannot be opened for any other reason.
-
getOutputStream
java.io.OutputStream getOutputStream(boolean append) throws java.io.FileNotFoundException
Creates an output stream from a file name.- Parameters:
append
- If true then data will be appended to the end of the file, if it already exists. If false and a normal file already exists with this name the file will first be truncated to zero length.- Returns:
- an output stream suitable for writing to the file.
- Throws:
java.io.FileNotFoundException
- if the file exists but is a directory rather than a regular file, does not exist but cannot be created, or cannot be opened for any other reason.
-
getInputStream
java.io.InputStream getInputStream() throws java.io.FileNotFoundException
Creates an input stream from a file name.- Returns:
- an input stream suitable for reading from the file.
- Throws:
java.io.FileNotFoundException
- if the file is not found.
-
getExclusiveFileLock
int getExclusiveFileLock() throws StandardException
Get an exclusive lock with this name. This is used to ensure that two or more JVMs do not open the same database at the same time. ny StorageFile that has getExclusiveFileLock() called on it is not intended to be read from or written to. It's sole purpose is to provide a locked entity to avoid multiple instances of Derby accessing the same database. getExclusiveFileLock() may delete or overwrite any existing file.- Returns:
- EXCLUSIVE_FILE_LOCK_NOT_AVAILABLE if the lock cannot be acquired because it is already held.
EXCLUSIVE_FILE_LOCK if the lock was successfully acquired.
NO_FILE_LOCK_SUPPORT if the system does not support exclusive locks. - Throws:
StandardException
-
releaseExclusiveFileLock
void releaseExclusiveFileLock()
Release the resource associated with an earlier acquired exclusive lock releaseExclusiveFileLock() may delete the file- See Also:
getExclusiveFileLock()
-
getRandomAccessFile
StorageRandomAccessFile getRandomAccessFile(java.lang.String mode) throws java.io.FileNotFoundException
Get a random access file. This method is not called if the StorageFactory is read only. It is unspecified if the StorageFactory that created it is not a WritableStorageFactory.- Parameters:
mode
- "r", "rw", "rws", or "rwd". The "rws" and "rwd" modes specify that the data is to be written to persistent store, consistent with the java.io.RandomAccessFile class ("synchronized" with the persistent storage, in the file system meaning of the word "synchronized"). However the implementation is not required to implement the "rws" or "rwd" modes. If the "rws" andr "rwd" modes are supported then the supportsRws() method of the StorageFactory returns true. If supportsRws() returns false then the implementation may treat "rws" and "rwd" as "rw". It is up to the user of this interface to call the StorageRandomAccessFile.sync method if necessary. However, if the "rws" or "rwd" modes are supported and the RandomAccessFile was opened in "rws" or "rwd" mode then the implementation of StorageRandomAccessFile.sync need not do anything.- Returns:
- an object that can be used for random access to the file.
- Throws:
java.lang.IllegalArgumentException
- if the mode argument is not equal to one of "r", "rw", "rws", or "rwd".java.io.FileNotFoundException
- if the file exists but is a directory rather than a regular file, or cannot be opened or created for any other reason .- See Also:
- java.io.RandomAccessFile
-
limitAccessToOwner
void limitAccessToOwner() throws java.io.IOException
Use when creating a new file. By default, a file created in an underlying file system, if applicable, will have read and write access for the file owner unless the propertyderby.useDefaultFilePermissions
is set totrue
.- Throws:
java.io.IOException
-
-