001: /*
002: * This file is part of PFIXCORE.
003: *
004: * PFIXCORE is free software; you can redistribute it and/or modify
005: * it under the terms of the GNU Lesser General Public License as published by
006: * the Free Software Foundation; either version 2 of the License, or
007: * (at your option) any later version.
008: *
009: * PFIXCORE is distributed in the hope that it will be useful,
010: * but WITHOUT ANY WARRANTY; without even the implied warranty of
011: * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
012: * GNU Lesser General Public License for more details.
013: *
014: * You should have received a copy of the GNU Lesser General Public License
015: * along with PFIXCORE; if not, write to the Free Software
016: * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
017: */
018:
019: package de.schlund.pfixxml.resources;
020:
021: import java.io.FileNotFoundException;
022: import java.io.IOException;
023: import java.io.InputStream;
024: import java.io.OutputStream;
025: import java.net.MalformedURLException;
026: import java.net.URI;
027: import java.net.URL;
028:
029: /**
030: * Provides access to files. This interface is similar to the
031: * {@link java.io.File} object, but is more flexible. You usually
032: * should not create your own classes implementing this interface
033: * but use the {@link de.schlund.pfixxml.resources.ResourceUtil}
034: * class to retrieve instances of this class.
035: * Note that depending on the system state, some methods might not
036: * be available, especially methods which modify a resource. These
037: * methods will then behave like being used on a file that is not
038: * writable. Note also the special behaviour of the
039: * {@link #lastModified()} method which is different from the behaviour
040: * of the corresponding method in the <code>File</code> class.
041: *
042: * @see de.schlund.pfixxml.resources.ResourceUtil
043: * @author Sebastian Marsching <sebastian.marsching@1und1.de>
044: */
045: public interface FileResource extends Comparable<FileResource> {
046: /**
047: * Tests whether the application can read the resource denoted by this
048: * object.
049: *
050: * @return <code>true</code> if and only if the resource specified by this
051: * object exists <em>and</em> can be read by the application;
052: * <code>false</code> otherwise
053: */
054: boolean canRead();
055:
056: /**
057: * Tests whether the application can modify the resource denoted by this
058: * object.
059: *
060: * @return <code>true</code> if and only if the resource denoted by this
061: * object exists <em>and</em> the application is allowed to write
062: * to the resource; <code>false</code> otherwise.
063: */
064: boolean canWrite();
065:
066: /**
067: * Atomically creates a new, empty file resource identified by this object if
068: * and only if a file with this name does not yet exist. The check for the
069: * existence of the file and the creation of the file if it does not exist
070: * are a single operation that is atomic with respect to all other
071: * filesystem activities that might affect the file.
072: * <P>
073: * Note: this method should <i>not</i> be used for file-locking, as
074: * the resulting protocol cannot be made to work reliably. The
075: * {@link java.nio.channels.FileLock FileLock}
076: * facility should be used instead.
077: *
078: * @return <code>true</code> if the named file does not exist and was
079: * successfully created; <code>false</code> if the named file
080: * already exists
081: *
082: * @throws IOException
083: * If an I/O error occurred
084: */
085: boolean createNewFile() throws IOException;
086:
087: /**
088: * Deletes the file or directory denoted by this file resource. If
089: * this resource denotes a directory, then the directory must be empty in
090: * order to be deleted.
091: *
092: * @return <code>true</code> if and only if the file or directory is
093: * successfully deleted; <code>false</code> otherwise
094: */
095: boolean delete();
096:
097: /**
098: * Tests whether the file or directory denoted by this file resource exists.
099: *
100: * @return <code>true</code> if and only if the file or directory denoted
101: * by this file resource exists; <code>false</code> otherwise
102: */
103: boolean exists();
104:
105: /**
106: * Returns the name of the file or directory denoted by this file resource.
107: * This is just the last name in the pathname's name sequence. If the
108: * pathname's name sequence is empty, then the empty string is returned.
109: *
110: * @return The name of the file or directory denoted by this file
111: * resource, or the empty string if this resource's name sequence
112: * is empty
113: */
114: String getName();
115:
116: /**
117: * Returns the file resource matching this file resource's parent,
118: * or <code>null</code> if this file resource does not have a parent
119: * directory.
120: *
121: * <p> The <em>parent</em> of an file resource consists of the
122: * pathname's prefix, if any, and each name in the pathname's name
123: * sequence except for the last. If the name sequence is empty then
124: * the pathname does not name a parent directory.
125: *
126: * @return The file resource matching the parent directory named by this
127: * file resource, or <code>null</code> if this file resource
128: * does not name a parent
129: *
130: * @since 1.2
131: */
132: FileResource getParentAsFileResource();
133:
134: /**
135: * Tests whether the resource denoted by this file resource is a
136: * directory.
137: *
138: * @return <code>true</code> if and only if the resource denoted by this
139: * object exists <em>and</em> is a directory;
140: * <code>false</code> otherwise
141: */
142: boolean isDirectory();
143:
144: /**
145: * Tests whether the file denoted by this object is a normal
146: * file. A file is <em>normal</em> if it is not a directory and, in
147: * addition, satisfies other system-dependent criteria. Any non-directory
148: * file created by a Java application is guaranteed to be a normal file.
149: *
150: * @return <code>true</code> if and only if the file denoted by this
151: * file resource exists <em>and</em> is a normal file;
152: * <code>false</code> otherwise
153: */
154: boolean isFile();
155:
156: /**
157: * Tests whether the file named by this file resource is a hidden
158: * file. The exact definition of <em>hidden</em> is system-dependent. On
159: * UNIX systems, a file is considered to be hidden if its name begins with
160: * a period character (<code>'.'</code>). On Microsoft Windows systems, a file is
161: * considered to be hidden if it has been marked as such in the filesystem.
162: *
163: * @return <code>true</code> if and only if the file denoted by this
164: * resource is hidden according to the conventions of the
165: * underlying platform
166: */
167: boolean isHidden();
168:
169: /**
170: * Returns the time that the file denoted by this resource was
171: * last modified. Might return "-1" if the last modified time is
172: * not available.
173: *
174: * @return A <code>long</code> value representing the time the file was
175: * last modified, measured in milliseconds since the epoch
176: * (00:00:00 GMT, January 1, 1970), or <code>0L</code> if the
177: * file does not exist or if an I/O error occurs
178: */
179: long lastModified();
180:
181: /**
182: * Returns an array of strings naming the files and directories in the
183: * directory denoted by this resource.
184: *
185: * <p> If this resource does not denote a directory, then this
186: * method returns <code>null</code>. Otherwise an array of strings is
187: * returned, one for each file or directory in the directory. Names
188: * denoting the directory itself and the directory's parent directory are
189: * not included in the result. Each string is a file name rather than a
190: * complete path.
191: *
192: * <p> There is no guarantee that the name strings in the resulting array
193: * will appear in any specific order; they are not, in particular,
194: * guaranteed to appear in alphabetical order.
195: *
196: * @return An array of strings naming the files and directories in the
197: * directory denoted by this file resource. The array will be
198: * empty if the directory is empty. Returns <code>null</code> if
199: * this file resource does not denote a directory, or if an
200: * I/O error occurs.
201: */
202: String[] list();
203:
204: /**
205: * Returns an array of file resource denoting the files in the
206: * directory denoted by this file resource.
207: *
208: * <p> If this file resource does not denote a directory, then this
209: * method returns <code>null</code>. Otherwise an array of
210: * <code>FileResource</code> objects is returned, one for each file or
211: * directory in the directory. Resources denoting the directory itself and the
212: * directory's parent directory are not included in the result.
213: *
214: * <p> There is no guarantee that the name strings in the resulting array
215: * will appear in any specific order; they are not, in particular,
216: * guaranteed to appear in alphabetical order.
217: *
218: * @return An array of file resources denoting the files and
219: * directories in the directory denoted by this file resource.
220: * The array will be empty if the directory is empty. Returns
221: * <code>null</code> if this abstract pathname does not denote
222: * a directory, or if an I/O error occurs.
223: */
224: FileResource[] listFileResources();
225:
226: /**
227: * Creates the directory named by this file resource.
228: *
229: * @return <code>true</code> if and only if the directory was
230: * created; <code>false</code> otherwise
231: */
232: boolean mkdir();
233:
234: /**
235: * Creates the directory named by this file resource, including any
236: * necessary but nonexistent parent directories. Note that if this
237: * operation fails it may have succeeded in creating some of the necessary
238: * parent directories.
239: *
240: * @return <code>true</code> if and only if the directory was created,
241: * along with all necessary parent directories; <code>false</code>
242: * otherwise
243: */
244: boolean mkdirs();
245:
246: /**
247: * Returns a normalized version of the URI which was used
248: * in order to create this FileResource
249: *
250: * @return URI representing this object
251: */
252: URI toURI();
253:
254: /**
255: * Returns an URL which can be used in order to access the
256: * file donoted by this object.
257: *
258: * @return URL suitable to access the resource denoted by this object
259: * @throws MalformedURLException if this object does not contain a valid path
260: */
261: URL toURL() throws MalformedURLException;
262:
263: /**
264: * Returns a stream which can be used for reading the content of
265: * the resource denoted by this object.
266: *
267: * @return stream for reading the resource
268: * @throws FileNotFoundException if resource cannot be found or read
269: */
270: InputStream getInputStream() throws FileNotFoundException;
271:
272: /**
273: * Returns a which can be used for writing to the resource
274: * denoted by this object.
275: *
276: * @return stream for writing to the resource
277: * @throws FileNotFoundException if resource cannot be found or is readonly
278: */
279: OutputStream getOutputStream() throws FileNotFoundException;
280:
281: OutputStream getOutputStream(boolean append)
282: throws FileNotFoundException;
283:
284: }
|