001: /*
002:
003: Derby - Class org.apache.derby.io.StorageFile
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.InputStream;
025: import java.io.OutputStream;
026: import java.io.FileNotFoundException;
027: import java.io.IOException;
028: import java.net.URL;
029: import java.net.MalformedURLException;
030:
031: /**
032: * This interface abstracts file naming. Any method in this interface
033: * that also appears in the java.io.File class should behave as the java.io.File method does.
034: *<p>
035: * When used by the database engine all files will be under either the database
036: * directory, specified by the databaseName argument of the {@link
037: * StorageFactory#init StorageFactory.init} method, or under the temporary file
038: * directory returned by the {@link StorageFactory#getTempDir
039: * StorageFactory.getTempDir} method. All relative path names are relative to
040: * the database directory.
041: *<p>
042: * The database engine will call this interface's methods from its own privilege blocks.
043: *<p>
044: * Different threads may operate on the same underlying file at the same time, either through the
045: * same or different StorageFile objects. The StiFile implementation must be capable of handling this.
046: *<p>
047: * @see <a href="http://java.sun.com/j2se/1.4.2/docs/api/java/io/File.html">java.io.File</a>
048: */
049: public interface StorageFile {
050:
051: //constant values related to exclusive lock mechanism
052: public static final int NO_FILE_LOCK_SUPPORT = 0;
053: public static final int EXCLUSIVE_FILE_LOCK = 1;
054: public static final int EXCLUSIVE_FILE_LOCK_NOT_AVAILABLE = 2;
055:
056: /**
057: * Get the names of all files and sub-directories in the directory named by this path name.
058: *
059: * This method is only used in a writable database.
060: *
061: * @return An array of the names of the files and directories in this
062: * directory denoted by this abstract pathname. The returned array will have length 0
063: * if this directory is empty. Returns null if this StorageFile is not a directory, or
064: * if an I/O error occurs. The return value is undefined if the database is read-only.
065: */
066: public String[] list();
067:
068: /**
069: * Determine whether the named file is writable.
070: *
071: * @return <b>true</b> if the file exists and is writable, <b>false</b> if not.
072: */
073: public boolean canWrite();
074:
075: /**
076: * Tests whether the named file exists.
077: *
078: * @return <b>true</b> if the named file exists, <b>false</b> if not.
079: */
080: public boolean exists();
081:
082: /**
083: * Tests whether the named file is a directory, or not. This is only called in writable storage factories.
084: *
085: * @return <b>true</b> if named file exists and is a directory, <b>false</b> if not.
086: * The return value is undefined if the storage is read-only.
087: */
088: public boolean isDirectory();
089:
090: /**
091: * Deletes the named file or empty directory. This method does not delete non-empty directories.
092: *
093: * @return <b>true</b> if the named file or directory is successfully deleted, <b>false</b> if not
094: */
095: public boolean delete();
096:
097: /**
098: * Deletes the named file and, if it is a directory, all the files and directories it contains.
099: *
100: * @return <b>true</b> if the named file or directory is successfully deleted, <b>false</b> if not
101: */
102: public boolean deleteAll();
103:
104: /**
105: * Converts this StorageFile into a pathname string. The character returned by StorageFactory.getSeparator()
106: * is used to separate the directory and file names in the sequence.
107: *
108: *<p>
109: *<b>The returned path may include the database directory. Therefore it cannot be directly used to make an StorageFile
110: * equivalent to this one.</b>
111: *
112: * @return The pathname as a string.
113: *
114: * @see StorageFactory#getSeparator
115: */
116: public String getPath();
117:
118: /**
119: * Converts this StorageFile into a canonical pathname string. The form of the canonical path is system dependent.
120: *
121: * @return The pathname as a string.
122: *
123: * @exception IOException if an I/O error occurred while finding the canonical name
124: */
125: public String getCanonicalPath() throws IOException;
126:
127: /**
128: * @return The last segment in the path name, "" if the path name sequence is empty.
129: */
130: public String getName();
131:
132: /**
133: * Get a URL representing this file. A valid URL does not indicate the file exists,
134: * it may just be a URL that will fail on opening. Some implementations
135: * return null if the file does not exist.
136: * @throws MalformedURLException File cannot be represented as a URL.
137: */
138: public URL getURL() throws MalformedURLException;
139:
140: /**
141: * If the named file does not already exist then create it as an empty normal file.
142: *
143: * The implementation
144: * must synchronize with other threads accessing the same file (in the same or a different process).
145: * If two threads both attempt to create a file with the same name
146: * at the same time then at most one should succeed.
147: *
148: * @return <b>true</b> if this thread's invocation of createNewFile successfully created the named file;
149: * <b>false</b> if not, i.e. <b>false</b> if the named file already exists or if another concurrent thread created it.
150: *
151: * @exception IOException - If the directory does not exist or some other I/O error occurred
152: */
153: public boolean createNewFile() throws IOException;
154:
155: /**
156: * Rename the file denoted by this name. Note that StorageFile objects are immutable. This method
157: * renames the underlying file, it does not change this StorageFile object. The StorageFile object denotes the
158: * same name as before, however the exists() method will return false after the renameTo method
159: * executes successfully.
160: *
161: *<p>It is not specified whether this method will succeed if a file already exists under the new name.
162: *
163: * @param newName the new name.
164: *
165: * @return <b>true</b> if the rename succeeded, <b>false</b> if not.
166: */
167: public boolean renameTo(StorageFile newName);
168:
169: /**
170: * Creates the named directory.
171: *
172: * @return <b>true</b> if the directory was created; <b>false</b> if not.
173: */
174: public boolean mkdir();
175:
176: /**
177: * Creates the named directory, and all nonexistent parent directories.
178: *
179: * @return <b>true</b> if the directory was created, <b>false</b> if not
180: */
181: public boolean mkdirs();
182:
183: /**
184: * Returns the length of the named file if it is not a directory. The return value is not specified
185: * if the file is a directory.
186: *
187: * @return The length, in bytes, of the named file if it exists and is not a directory,
188: * 0 if the file does not exist, or any value if the named file is a directory.
189: */
190: public long length();
191:
192: /**
193: * Get the name of the parent directory if this name includes a parent.
194: *
195: * @return An StorageFile denoting the parent directory of this StorageFile, if it has a parent, null if
196: * it does not have a parent.
197: */
198: public StorageFile getParentDir();
199:
200: /**
201: * Make the named file or directory read-only. This interface does not specify whether this
202: * also makes the file undeletable.
203: *
204: * @return <b>true</b> if the named file or directory was made read-only, or it already was read-only;
205: * <b>false</b> if not.
206: */
207: public boolean setReadOnly();
208:
209: /**
210: * Creates an output stream from a file name. If a normal file already exists with this name it
211: * will first be truncated to zero length.
212: *
213: * @return an output stream suitable for writing to the file.
214: *
215: * @exception FileNotFoundException if the file exists but is a directory
216: * rather than a regular file, does not exist but cannot be created, or
217: * cannot be opened for any other reason.
218: */
219: public OutputStream getOutputStream() throws FileNotFoundException;
220:
221: /**
222: * Creates an output stream from a file name.
223: *
224: * @param append If true then data will be appended to the end of the file, if it already exists.
225: * If false and a normal file already exists with this name the file will first be truncated
226: * to zero length.
227: *
228: * @return an output stream suitable for writing to the file.
229: *
230: * @exception FileNotFoundException if the file exists but is a directory
231: * rather than a regular file, does not exist but cannot be created, or
232: * cannot be opened for any other reason.
233: */
234: public OutputStream getOutputStream(boolean append)
235: throws FileNotFoundException;
236:
237: /**
238: * Creates an input stream from a file name.
239: *
240: * @return an input stream suitable for reading from the file.
241: *
242: * @exception FileNotFoundException if the file is not found.
243: */
244: public InputStream getInputStream() throws FileNotFoundException;
245:
246: /**
247: * Get an exclusive lock with this name. This is used to ensure that two or more JVMs do not open the same database
248: * at the same time.
249: *
250: * @return EXCLUSIVE_FILE_LOCK_NOT_AVAILABLE if the lock cannot be acquired because it is already held.<br>
251: * EXCLUSIVE_FILE_LOCK if the lock was successfully acquired.<br>
252: * NO_FILE_LOCK_SUPPORT if the system does not support exclusive locks.<br>
253: */
254: public int getExclusiveFileLock();
255:
256: /**
257: * Release the resource associated with an earlier acquired exclusive lock
258: *
259: * @see #getExclusiveFileLock
260: */
261: public void releaseExclusiveFileLock();
262:
263: /**
264: * Get a random access file.
265: *
266: * This method is not called if the StorageFactory is read only. It is unspecified if the StorageFactory
267: * that created it is not a WritableStorageFactory.
268: *
269: * @param mode "r", "rw", "rws", or "rwd". The "rws" and "rwd" modes specify
270: * that the data is to be written to persistent store, consistent with the
271: * java.io.RandomAccessFile class ("synchronized" with the persistent
272: * storage, in the file system meaning of the word "synchronized"). However
273: * the implementation is not required to implement the "rws" or "rwd"
274: * modes. If the "rws" andr "rwd" modes are supported then the supportsRws() method
275: * of the StorageFactory returns true. If supportsRws() returns false then the
276: * implementation may treat "rws" and "rwd" as "rw". It is up to
277: * the user of this interface to call the StorageRandomAccessFile.sync
278: * method if necessary. However, if the "rws" or "rwd" modes are supported and the
279: * RandomAccessFile was opened in "rws" or "rwd" mode then the
280: * implementation of StorageRandomAccessFile.sync need not do anything.
281: *
282: * @return an object that can be used for random access to the file.
283: *
284: * @exception IllegalArgumentException if the mode argument is not equal to one of "r", "rw", "rws", or "rwd".
285: * @exception FileNotFoundException if the file exists but is a directory rather than a regular
286: * file, or cannot be opened or created for any other reason .
287: *
288: * @see <a href="http://java.sun.com/j2se/1.4.2/docs/api/java/io/RandomAccessFile.html">java.io.RandomAccessFile</a>
289: */
290: public StorageRandomAccessFile getRandomAccessFile(String mode)
291: throws FileNotFoundException;
292: }
|