All Downloads are FREE. Search and download functionalities are using the official Maven repository.

org.refcodes.filesystem.FileSystem Maven / Gradle / Ivy

There is a newer version: 3.3.9
Show newest version
// /////////////////////////////////////////////////////////////////////////////
// REFCODES.ORG
// =============================================================================
// This code is copyright (c) by Siegfried Steiner, Munich, Germany, distributed
// on an "AS IS" BASIS WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, and licen-
// sed under the following (see "http://en.wikipedia.org/wiki/Multi-licensing")
// licenses:
// =============================================================================
// GNU General Public License, v3.0 ("http://www.gnu.org/licenses/gpl-3.0.html")
// together with the GPL linking exception applied; as being applied by the GNU
// Classpath ("http://www.gnu.org/software/classpath/license.html")
// =============================================================================
// Apache License, v2.0 ("http://www.apache.org/licenses/TEXT-2.0")
// =============================================================================
// Please contact the copyright holding author(s) of the software artifacts in
// question for licensing issues not being covered by the above listed licenses,
// also regarding commercial licensing models or regarding the compatibility
// with other open source licenses.
// /////////////////////////////////////////////////////////////////////////////

package org.refcodes.filesystem;

import java.io.File;
import java.io.IOException;
import java.io.InputStream;
import java.io.OutputStream;
import java.util.List;
import java.util.Map;

import org.refcodes.component.Component;
import org.refcodes.data.Delimiter;

/**
 * A file system represents an abstraction for any "physical" storage medium
 * where file (handles) can be stored and retrieved. The file (handles) are
 * structured in a hierarchy similar to a file system's hierarchy with folders
 * and files. The hierarchy may be completely virtual (the underlying system
 * just knows of "keys" and directories are simulated by key naming
 * conventions), so the underlying physical file system might be an FTP server
 * or an in-memory {@link Map} (with virtual files and folders) or a real file
 * system with a real directory and file hierarchy. The file system only
 * contains file (handle)s, any construct such as a "directory" does not exist
 * from the file system's point of view and therefore cannot be created or
 * removed explicitly. Them are created or removed implicitly when file
 * (handles) are created or removed. An implementation for, lets say, a file
 * system, should take care to remove physical folders from the file system when
 * removing a file (handle) (the corresponding file from the file system's
 * folder) in case the folder from which the file (handle) (file) was removed
 * ends up empty! In turn, when creating a file (handle), the corresponding
 * directory structure must be created in case we have a file system with a
 * "file system nature". File (handles) are never instantiated directly, them
 * are retrieved from the file system as them can be implementation specific. A
 * specific file (handle) instance therefore is always attached to a specific
 * instance of a file system. Using file (handle)s interchangeably between tow
 * different file system instances will (usually) fail. A file system and the
 * file (handle)s are a self contained systems similar to the entities of an O/R
 * mapper being attached to a specific persistence provider. Whenever an
 * operation returns a file (handle), this file (handle) is to be considered the
 * actual working copy and to be used in favor to a previous data file (handle)
 * identifying the same data. The returned file (handle) will provide updated
 * information. A file (handle) in the file system is identified by a unique
 * key, which in turn consists of a path and a name. The path and the name are
 * concatenated by a path separator, usually the slash "/". The path itself
 * might be composed with path separators. Having this, a "file system nature"
 * file system can map the file (handle)s to files in a directory hierarchy on
 * the file system. Any path or key being provided is to be normalized by an
 * implementation of the file system (using the {@link FileSystemUtility}) by
 * removing any trailing path separators. Illegal paths will aCause an
 * {@link IllegalPathException}, {@link IllegalNameException} or an
 * {@link IllegalKeyException}, i.e. path which do not start with a path
 * separator or have two or more subsequent path separators in then or any other
 * illegal characters.
 */
public interface FileSystem extends Component {

	/**
	 * The default path delimiter to be used by all implementations if this file
	 * system to ensure interoperability.
	 */

	char PATH_DELIMITER = Delimiter.PATH.getChar();

	/**
	 * Tests whether the file system knows a file (handle) with the given key.
	 * 
	 * @param aKey The key which to test if there is a file (handle).
	 * 
	 * @return True in case there is a file (handle) with the given key exists.
	 * 
	 * @throws IllegalKeyException in case the path was not a valid path.
	 * @throws NoListAccessException in case listing the content in the file
	 *         system was denied.
	 * @throws UnknownFileSystemException in case the "underlying" (physical)
	 *         file system is not known (may not exist any more), i.e. it may
	 *         have been removed after the file system instance has been
	 *         created.
	 * @throws IOException in case an I/O related problem occurred while
	 *         accessing the file (handle).
	 */
	boolean hasFile( String aKey ) throws IllegalKeyException, NoListAccessException, UnknownFileSystemException, IOException;

	/**
	 * Tests whether the file system knows a file (handle) with the given path
	 * and name. Caution, path and name are not just concatenated with a path
	 * separator in between to get the key: The name must not contain any path
	 * separator! In case of a file system implementation of the file system
	 * ("file system nature") the name must actually represent the filename of
	 * the file representing the file (handle).
	 * 
	 * @param aPath The path part of the key for which to test if there is a
	 *        file (handle).
	 * @param aName The name part of the key for which to test if there is a
	 *        file (handle).
	 * 
	 * @return True in case there is a file (handle) with the given path and
	 *         name exists.
	 * 
	 * @throws IllegalPathException in case the path was not a valid path.
	 * @throws IllegalNameException in case the name was not a valid path.
	 * @throws NoListAccessException in case listing the content in the file
	 *         syste was denied.
	 * @throws UnknownFileSystemException in case the "underlying" (physical)
	 *         file system is not known (may not exist any more), i.e. it may
	 *         have been removed after the file system instance has been
	 *         created.
	 * @throws IOException in case an I/O related problem occurred while
	 *         accessing the file (handle)
	 */
	boolean hasFile( String aPath, String aName ) throws IllegalPathException, IllegalNameException, NoListAccessException, UnknownFileSystemException, IOException;

	/**
	 * Returns true in case the given file (handle) exists.
	 * 
	 * @param aFileHandle The file (handle) which's existence is to be tested.
	 * 
	 * @return True in case the file (handle) exists, else false is returned.
	 * 
	 * @throws NoListAccessException in case listing the content in the file
	 *         system was denied.
	 * @throws UnknownFileSystemException in case the "underlying" (physical)
	 *         file system is not known (may not exist any more), i.e. it may
	 *         have been removed after the file system instance has been
	 *         created.
	 * @throws IOException in case an I/O related problem occurred while
	 *         accessing the file (handle)
	 * @throws IllegalFileException in case the file handle with name and path
	 *         is not valid, i.e. the name contains a path separator.
	 */
	boolean hasFile( FileHandle aFileHandle ) throws NoListAccessException, UnknownFileSystemException, IOException, IllegalFileException;

	/**
	 * Creates a file (handle) with the given key.
	 * 
	 * @param aKey The key for which to create the file (handle).
	 * 
	 * @return The newly created file (handle).
	 * 
	 * @throws FileAlreadyExistsException in case a file (handle) with the given
	 *         key (path and name) already exists.
	 * @throws NoCreateAccessException in case create access to the file system
	 *         was denied.
	 * @throws IllegalKeyException in case the key with name and path is not
	 *         valid, i.e. the name contains a path separator.
	 * @throws UnknownFileSystemException in case the "underlying" (physical)
	 *         file system is not known (may not exist any more), i.e. it may
	 *         have been removed after the file system instance has been
	 *         created.
	 * @throws IOException in case an I/O related problem occurred while
	 *         accessing the file (handle)
	 * @throws NoListAccessException in case listing the content in the file
	 *         system was denied.
	 */
	FileHandle createFile( String aKey ) throws FileAlreadyExistsException, NoCreateAccessException, IllegalKeyException, UnknownFileSystemException, IOException, NoListAccessException;

	/**
	 * Creates a file (handle) with the given path and name. Caution, path and
	 * name are not just concatenated with a path separator in between to get
	 * the key: The name must not contain any path separator! In case of a file
	 * system implementation of the file system ("file system alternative") the
	 * name will actually represent the filename of the file representing the
	 * file handle.
	 * 
	 * @param aPath The path part of the key for which to create the file
	 *        (handle).
	 * @param aName The name part of the key for which to create the file
	 *        (handle).
	 * 
	 * @return The newly created file (handle).
	 * 
	 * @throws FileAlreadyExistsException in case a file (handle) with the given
	 *         key (path and name) already exists.
	 * @throws NoCreateAccessException in case create access to the file system
	 *         was denied.
	 * @throws IllegalNameException in case the name was not a valid path.
	 * @throws IllegalPathException in case the path was not a valid path.
	 * @throws UnknownFileSystemException in case the "underlying" (physical)
	 *         file system is not known (may not exist any more), i.e. it may
	 *         have been removed after the file system instance has been
	 *         created.
	 * @throws IOException in case an I/O related problem occurred while
	 *         accessing the file (handle)
	 * @throws NoListAccessException in case listing the content in the file
	 *         system was denied.
	 */
	FileHandle createFile( String aPath, String aName ) throws FileAlreadyExistsException, NoCreateAccessException, IllegalNameException, IllegalPathException, UnknownFileSystemException, IOException, NoListAccessException;

	/**
	 * Gets a file (handle) with the given key from the file system.
	 * 
	 * @param aKey The key for which to retrieve the file (handle).
	 * 
	 * @return The retrieved file (handle).
	 * 
	 * @throws NoListAccessException in case listing the content in the file
	 *         system was denied.
	 * @throws IllegalKeyException in case the key with name and path is not
	 *         valid, i.e. the name contains a path separator.
	 * @throws UnknownFileSystemException in case the "underlying" (physical)
	 *         file system is not known (may not exist any more), i.e. it may
	 *         have been removed after the file system instance has been
	 *         created.
	 * @throws IOException in case an I/O related problem occurred while
	 *         accessing the file (handle)
	 * @throws UnknownKeyException in case the given key (path and name) does
	 *         not exist in the file system.
	 */
	FileHandle getFileHandle( String aKey ) throws NoListAccessException, IllegalKeyException, UnknownFileSystemException, IOException, UnknownKeyException;

	/**
	 * Gets a file (handle) with the given path and name from the file system.
	 * Caution, path and name are not just concatenated with a path separator in
	 * between to get the key: The name must not contain any path separator! In
	 * case of a file system implementation of the file system ("file system
	 * nature") the name will actually represent the filename of the file
	 * representing the file (handle).
	 * 
	 * @param aPath The path part of the key for which to retrieve the file
	 *        (handle).
	 * @param aName The name part of the key for which to retrieve the file
	 *        (handle).
	 * 
	 * @return The retrieved file (handle).
	 * 
	 * @throws NoListAccessException in case listing the content in the file
	 *         system was denied.
	 * @throws IllegalNameException in case the name was not a valid path.
	 * @throws IllegalPathException in case the path was not a valid path.
	 * @throws UnknownFileSystemException in case the "underlying" (physical)
	 *         file system is not known (may not exist any more), i.e. it may
	 *         have been removed after the file system instance has been
	 *         created.
	 * @throws IOException in case an I/O related problem occurred while
	 *         accessing the file (handle)
	 * @throws UnknownKeyException in case the given key (path and name) does
	 *         not exist in the file system.
	 */
	FileHandle getFileHandle( String aPath, String aName ) throws NoListAccessException, IllegalNameException, IllegalPathException, UnknownFileSystemException, IOException, UnknownKeyException;

	/**
	 * The data contained in the given file (handle) is written to the provided
	 * output stream. This may be used to write the file (handle) to a file.
	 * 
	 * @param aFromFileHandle The file (handle) which is to be written to the
	 *        output stream.
	 * @param aOutputStream The stream to which to write.
	 * 
	 * @throws ConcurrentAccessException in case the file (handle) is
	 *         concurrently read, modified or deleted.
	 * @throws UnknownFileException in case none such file (handle) was found in
	 *         the file system.
	 * @throws NoReadAccessException in case read access to the file system was
	 *         denied.
	 * @throws UnknownFileSystemException in case the "underlying" (physical)
	 *         file system is not known (may not exist any more), i.e. it may
	 *         have been removed after the file system instance has been
	 *         created.
	 * @throws IOException in case an I/O related problem occurred while
	 *         accessing the file (handle)
	 * @throws NoListAccessException in case listing the content in the file
	 *         system was denied.
	 * @throws IllegalFileException in case the file handle with name and path
	 *         is not valid, i.e. the name contains a path separator.
	 */
	void fromFile( FileHandle aFromFileHandle, OutputStream aOutputStream ) throws ConcurrentAccessException, UnknownFileException, NoReadAccessException, UnknownFileSystemException, IOException, NoListAccessException, IllegalFileException;

	/**
	 * Data provided by the given input stream is written to the file (handle)
	 * (or appended to the file (handle)'s data in case the file (handle) did
	 * already contain data). This may be used to store data from a file in a
	 * file (handle).
	 * 
	 * @param aToFileHandle The file (handle) to which data is to be written.
	 * @param aInputStream The input stream from which to read the data which is
	 *        to be written to the file (handle).
	 * 
	 * @throws ConcurrentAccessException in case the file (handle) is
	 *         concurrently read, modified or deleted.
	 * @throws UnknownFileException in case none such file (handle) was found in
	 *         the file system.
	 * @throws NoWriteAccessException in case write access to the file system
	 *         was denied.
	 * @throws UnknownFileSystemException in case the "underlying" (physical)
	 *         file system is not known (may not exist any more), i.e. it may
	 *         have been removed after the file system instance has been
	 *         created.
	 * @throws IOException in case an I/O related problem occurred while
	 *         accessing the file (handle)
	 * @throws NoListAccessException in case listing the content in the file
	 *         system was denied.
	 * @throws IllegalFileException in case the file handle with name and path
	 *         is not valid, i.e. the name contains a path separator.
	 */
	void toFile( FileHandle aToFileHandle, InputStream aInputStream ) throws ConcurrentAccessException, UnknownFileException, NoWriteAccessException, UnknownFileSystemException, IOException, NoListAccessException, IllegalFileException;

	/**
	 * An input stream is being provided from which the data of the file
	 * (handle) may be read.
	 *
	 * @param aFromFileHandle The file (handle) for which to get the input
	 *        stream.
	 * 
	 * @return The input stream providing the data of the file (handle).
	 * 
	 * @throws ConcurrentAccessException in case the file (handle) is
	 *         concurrently read, modified or deleted.
	 * @throws UnknownFileException in case none such file (handle) was found in
	 *         the file system.
	 * @throws UnknownFileException in case none such file (handle) was found in
	 *         the file system.
	 * @throws NoReadAccessException in case read access to the file system was
	 *         denied.
	 * @throws UnknownFileSystemException in case the "underlying" (physical)
	 *         file system is not known (may not exist any more), i.e. it may
	 *         have been removed after the file system instance has been
	 *         created.
	 * @throws IOException in case an I/O related problem occurred while
	 *         accessing the file (handle)
	 * @throws NoListAccessException in case listing the content in the file
	 *         system was denied.
	 * @throws IllegalFileException in case the file handle with name and path
	 *         is not valid, i.e. the name contains a path separator.
	 */
	InputStream fromFile( FileHandle aFromFileHandle ) throws ConcurrentAccessException, UnknownFileException, NoReadAccessException, UnknownFileSystemException, IOException, NoListAccessException, IllegalFileException;

	/**
	 * Returns an output stream which may be used to write (or append, in case
	 * data did already exist for the file system) data to a file (handle).
	 * 
	 * @param aToFileHandle The file (handle) to which to write data.
	 * 
	 * @return The output stream to be used to write data to.
	 * 
	 * @throws ConcurrentAccessException in case the file (handle) is
	 *         concurrently read, modified or deleted.
	 * @throws UnknownFileException in case none such file (handle) was found in
	 *         the file system.
	 * @throws NoWriteAccessException in case write access to the file system
	 *         was denied.
	 * @throws UnknownFileSystemException in case the "underlying" (physical)
	 *         file system is not known (may not exist any more), i.e. it may
	 *         have been removed after the file system instance has been
	 *         created.
	 * @throws IOException in case an I/O related problem occurred while
	 *         accessing the file (handle)
	 * @throws IllegalFileException in case the file handle with name and path
	 *         is not valid, i.e. the name contains a path separator.
	 */
	OutputStream toFile( FileHandle aToFileHandle ) throws ConcurrentAccessException, UnknownFileException, NoWriteAccessException, UnknownFileSystemException, IOException, IllegalFileException;

	/**
	 * The data contained in the given file (handle) is written to the provided
	 * file.
	 * 
	 * @param aFromFileHandle The file (handle) which is to be written to the
	 *        output stream.
	 * @param aToFile The file to which the data is to be written.
	 * 
	 * @throws ConcurrentAccessException in case the file (handle) is
	 *         concurrently read, modified or deleted.
	 * @throws UnknownFileException in case none such file (handle) was found in
	 *         the file system.
	 * @throws NoReadAccessException in case read access to the file system was
	 *         denied.
	 * @throws UnknownFileSystemException in case the "underlying" (physical)
	 *         file system is not known (may not exist any more), i.e. it may
	 *         have been removed after the file system instance has been
	 *         created.
	 * @throws IOException in case an I/O related problem occurred while
	 *         accessing the file (handle)
	 * @throws NoListAccessException in case listing the content in the file
	 *         system was denied.
	 * @throws IllegalFileException in case the file handle with name and path
	 *         is not valid, i.e. the name contains a path separator.
	 */
	void fromFile( FileHandle aFromFileHandle, File aToFile ) throws ConcurrentAccessException, UnknownFileException, NoReadAccessException, UnknownFileSystemException, IOException, NoListAccessException, IllegalFileException;

	/**
	 * Data provided by the given input stream is written to the file (handle)
	 * (or appended to the file (handle)'s data in case the file (handle) did
	 * already contain data). This may be used to store data from a file in a
	 * file (handle).
	 * 
	 * @param aToFileHandle The file (handle) to which data is to be written.
	 * @param aFromFile The file from which to read the data which is to be
	 *        written to the file (handle).
	 * 
	 * @throws ConcurrentAccessException in case the file (handle) is
	 *         concurrently read, modified or deleted.
	 * @throws UnknownFileException in case none such file (handle) was found in
	 *         the file system.
	 * @throws NoWriteAccessException in case write access to the file system
	 *         was denied.
	 * @throws UnknownFileSystemException in case the "underlying" (physical)
	 *         file system is not known (may not exist any more), i.e. it may
	 *         have been removed after the file system instance has been
	 *         created.
	 * @throws IOException in case an I/O related problem occurred while
	 *         accessing the file (handle)
	 * @throws NoListAccessException in case listing the content in the file
	 *         system was denied.
	 * @throws IllegalFileException in case the file handle with name and path
	 *         is not valid, i.e. the name contains a path separator.
	 */
	void toFile( FileHandle aToFileHandle, File aFromFile ) throws ConcurrentAccessException, UnknownFileException, NoWriteAccessException, UnknownFileSystemException, IOException, NoListAccessException, IllegalFileException;

	/**
	 * Data provided by the given buffer is written to the file (handle) (or
	 * appended to the file (handle)'s data in case the file (handle) did
	 * already contain data). This may be used to store data from a string or
	 * other data structure.
	 * 
	 * @param aToFileHandle The file (handle) to which data is to be written.
	 * @param aBuffer The buffer from which to read the data which is to be
	 *        written to the file (handle).
	 * 
	 * @throws ConcurrentAccessException in case the file (handle) is
	 *         concurrently read, modified or deleted.
	 * @throws UnknownFileException in case none such file (handle) was found in
	 *         the file system.
	 * @throws NoWriteAccessException in case write access to the file system
	 *         was denied.
	 * @throws UnknownFileSystemException in case the "underlying" (physical)
	 *         file system is not known (may not exist any more), i.e. it may
	 *         have been removed after the file system instance has been
	 *         created.
	 * @throws IOException in case an I/O related problem occurred while
	 *         accessing the file (handle)
	 * @throws NoListAccessException in case listing the content in the file
	 *         system was denied.
	 * @throws IllegalFileException in case the file handle with name and path
	 *         is not valid, i.e. the name contains a path separator.
	 */
	void toFile( FileHandle aToFileHandle, byte[] aBuffer ) throws ConcurrentAccessException, UnknownFileException, NoWriteAccessException, UnknownFileSystemException, IOException, NoListAccessException, IllegalFileException;

	/**
	 * Renames the file (handle), the name part of the key will be renamed to
	 * the new name. The name must not contain any path separator.
	 * 
	 * @param aFileHandle The file (handle) to be renamed.
	 * @param aNewName The new name of the file (handle).
	 * 
	 * @return The resulting file (handle) in case the operation was successful.
	 * 
	 * @throws UnknownFileException in case none such file (handle) was found in
	 *         the file system.
	 * @throws ConcurrentAccessException in case the file (handle) is
	 *         concurrently read, modified or deleted.
	 * @throws FileAlreadyExistsException in case a file (handle) with the given
	 *         key (path and name) already exists.
	 * @throws NoCreateAccessException in case create access to the file system
	 *         was denied.
	 * @throws NoDeleteAccessException in case create access to the file system
	 *         was denied.
	 * @throws IllegalNameException in case the name was not a valid path.
	 * @throws UnknownFileSystemException in case the "underlying" (physical)
	 *         file system is not known (may not exist any more), i.e. it may
	 *         have been removed after the file system instance has been
	 *         created.
	 * @throws IOException in case an I/O related problem occurred while
	 *         accessing the file (handle)
	 * @throws NoListAccessException in case listing the content in the file
	 *         system was denied.
	 * @throws IllegalFileException in case the file handle with name and path
	 *         is not valid, i.e. the name contains a path separator.
	 */
	FileHandle renameFile( FileHandle aFileHandle, String aNewName ) throws UnknownFileException, ConcurrentAccessException, FileAlreadyExistsException, NoCreateAccessException, NoDeleteAccessException, IllegalNameException, UnknownFileSystemException, IOException, NoListAccessException, IllegalFileException;

	/**
	 * Renames the file (handle), it will be accessible via the provided key.
	 *
	 * @param aFileHandle The file (handle) to be renamed.
	 * @param aNewKey The new key (path and name) of the file (handle).
	 * 
	 * @return the file handle
	 * 
	 * @throws UnknownFileException in case none such file (handle) was found in
	 *         the file system.
	 * @throws ConcurrentAccessException in case the file (handle) is
	 *         concurrently read, modified or deleted.
	 * @throws FileAlreadyExistsException in case a file (handle) with the given
	 *         key (path and name) already exists.
	 * @throws NoCreateAccessException in case create access to the file system
	 *         was denied.
	 * @throws NoDeleteAccessException in case create access to the file system
	 *         was denied.
	 * @throws IllegalKeyException in case the key with name and path is not
	 *         valid, i.e. the name contains a path separator.
	 * @throws UnknownFileSystemException in case the "underlying" (physical)
	 *         file system is not known (may not exist any more), i.e. it may
	 *         have been removed after the file system instance has been
	 *         created.
	 * @throws IOException in case an I/O related problem occurred while
	 *         accessing the file (handle)
	 * @throws NoListAccessException in case listing the content in the file
	 *         system was denied.
	 * @throws IllegalFileException in case the file handle with name and path
	 *         is not valid, i.e. the name contains a path separator.
	 */
	FileHandle moveFile( FileHandle aFileHandle, String aNewKey ) throws UnknownFileException, ConcurrentAccessException, FileAlreadyExistsException, NoCreateAccessException, NoDeleteAccessException, IllegalKeyException, UnknownFileSystemException, IOException, NoListAccessException, IllegalFileException;

	/**
	 * Deletes a file (handle) from the file system. In case a path is "empty"
	 * after deletion then the path will stop existing as well.
	 * 
	 * @param aFileHandle The file (handle) to be deleted.
	 * 
	 * @throws ConcurrentAccessException in case the file (handle) is
	 *         concurrently read, modified or deleted.
	 * @throws UnknownFileException in case none such file (handle) was found in
	 *         the file system.
	 * @throws NoDeleteAccessException in case create access to the file system
	 *         was denied.
	 * @throws UnknownFileSystemException in case the "underlying" (physical)
	 *         file system is not known (may not exist any more), i.e. it may
	 *         have been removed after the file system instance has been
	 *         created.
	 * @throws IOException in case an I/O related problem occurred while
	 *         accessing the file (handle)
	 * @throws NoListAccessException in case listing the content in the file
	 *         system was denied.
	 * @throws IllegalFileException in case the file handle with name and path
	 *         is not valid, i.e. the name contains a path separator.
	 */
	void deleteFile( FileHandle aFileHandle ) throws ConcurrentAccessException, UnknownFileException, NoDeleteAccessException, UnknownFileSystemException, IOException, NoListAccessException, IllegalFileException;

	/**
	 * Determines whether there is any file (handle)s found for the given path.
	 * In case the recursive flag is set, then the specified path and all
	 * children of that path (separated by the path separator) are examined,
	 * else exactly the specified path is examined. Speaking of a set recursive
	 * flag, it is merely checked whether the given path is part of any key of
	 * the file (handle)s stored in the file system by taking the path
	 * separators into account. I.e. the given path must match a key from the
	 * beginning till the end of the path and the key must either continue from
	 * then on with a path separator as next character or must end there (be
	 * equal to the path). I.e. matches in between a key where the next position
	 * of the key does not contain a path separator are ignored. Example: A
	 * given path is "/a/bc/def", a given key is "a/bc/defg", the path does not
	 * match the key, although the path is contained in the key! A given path is
	 * "/a/bc/def", a given key is "a/bc/def/g", the path does match the key as
	 * the key continues the path with a path separator "/".
	 * 
	 * @param aPath The path where to look whether there are file (handle)s or
	 *        not.
	 * @param isRecursively When true all children of that path are examined as
	 *        well.
	 * 
	 * @return True in case file (handle)s were found.
	 * 
	 * @throws NoListAccessException in case listing the content in the file
	 *         system was denied.
	 * @throws IllegalPathException in case the path was not a valid path.
	 * @throws UnknownFileSystemException in case the "underlying" (physical)
	 *         file system is not known (may not exist any more), i.e. it may
	 *         have been removed after the file system instance has been
	 *         created.
	 * @throws IOException in case an I/O related problem occurred while
	 *         accessing the file (handle)
	 */
	boolean hasFiles( String aPath, boolean isRecursively ) throws NoListAccessException, IllegalPathException, UnknownFileSystemException, IOException;

	/**
	 * With the behavior of the {@link #hasFiles(String, boolean)} method, all
	 * file (handle)s found for the path are returned.
	 * Ehttps://www.metacodes.proly the recursive flag is described in the
	 * method {@link #hasFiles(String, boolean)}.
	 *
	 * @param aPath The path where to search for the file (handle)s.
	 * @param isRecursively the is recursively
	 * 
	 * @return A list with the file (handle)s found or an empty list.
	 * 
	 * @throws NoListAccessException in case listing the content in the file
	 *         system was denied.
	 * @throws UnknownPathException in case the given path did not exist in the
	 *         file system.
	 * @throws IllegalPathException in case the path was not a valid path.
	 * @throws UnknownFileSystemException in case the "underlying" (physical)
	 *         file system is not known (may not exist any more), i.e. it may
	 *         have been removed after the file system instance has been
	 *         created.
	 * @throws IOException in case an I/O related problem occurred while
	 *         accessing the file (handle)
	 */
	List getFileHandles( String aPath, boolean isRecursively ) throws NoListAccessException, UnknownPathException, IllegalPathException, UnknownFileSystemException, IOException;
}




© 2015 - 2024 Weber Informatics LLC | Privacy Policy