br.com.objectos.fs
Interface Directory

All Superinterfaces:

PathName

@Generated(value="br.com.objectos.core.multirelease.processor.TemplateProcessor")
public interface Directory
extends PathName

A façade for directory only operations.

This is only a façade. More specifically, the underlying object may or may not represent an actual directory. For example, the directory may have been deleted between the time an instance of this interface is obtained and the time a method in this interface is invoked.

Unless noted, methods of this interface will reject values that resolve to a pathname that is not the directory itself or a direct child. This restriction is tested against pathnames only. In other words, the pathname might resolve to a child but it might be a symlink to a directory or a file that is not a direct child of this directory.

Since:

2

Method Summary

<R,P> R	acceptPathNameVisitor(PathNameVisitor<R,P> visitor, P p) Accept method used to implement the visitor pattern.
void	copyTo(Directory dest) Recursively copies the contents of this directory to the specified destination directory.
Directory	createDirectory(String directoryName) Creates a directory with the specified name.
RegularFile	createRegularFile(String fileName, RegularFileCreateOption... options) Creates a (regular) file with the specified file name and with the specified creation options.
void	delete() Deletes this directory or fails if the directory is not empty.
void	deleteContents() Recursively deletes the contents of this directory.
boolean	exists() Returns true if the pathname represented by this object exists.
Directory	getDirectory(String directoryName) Returns an existing subdirectory having the specified name.
String	getName() Returns the name of this directory.
RegularFile	getOrCreateRegularFile(String fileName) Returns an existing (regular) file or creates new one with the specified file name.
Directory	getParent() Returns the parent directory of this directory.
String	getPath() Returns the full path of this directory.
RegularFile	getRegularFile(String fileName) Returns an existing (regular) file with the specified file name.
boolean	isEmpty() Returns true if this directory contains no entries.
ResolvedPath	resolve(String first, String... more) Returns a new ResolvedPath object representing the resolved pathname of a descendant of this directory or returns this object if the specified names result in the empty string.
File	toFile() Returns a File representation of this pathname.
URI	toUri() Returns an URI representation of this pathname.
void	visitContents(DirectoryContentsVisitor visitor) Visits each child of this directory with the specified visitor.

Methods inherited from interface java.lang.Comparable

compareTo

Methods inherited from interface br.com.objectos.core.object.ToStringObject

formatToString

Method Detail

copyTo

void copyTo(Directory dest)
            throws FoundException,
                   IOException

Recursively copies the contents of this directory to the specified destination directory.

This operation will not overwrite any file in the destination directory nor will it proceed if a subdirectory in the destination with the same as in this directory already exists. This operation will fail at the first directory or file that cannot be created at the destination because it already exists. In this case, the result will be an incomplete (partial) copy operation.

Parameters:

dest - the destination directory

Throws:

FoundException - if any directory or file with the same relative pathname exists in the destination

IOException - if an I/O error occurs

createDirectory

Directory createDirectory(String directoryName)
                          throws FoundException,
                                 IOException

Creates a directory with the specified name. The resulting directory will be a direct child of this directory.

Parameters:

directoryName - the name of the directory to be created

Returns:

a Directory instance representing the newly created directory

Throws:

IllegalArgumentException - if the resolved pathname is not a direct child of this directory

FoundException - if the resolved pathname already exists

IOException - if an I/O error occurs

createRegularFile

RegularFile createRegularFile(String fileName,
                              RegularFileCreateOption... options)
                              throws FoundException,
                                     IOException

Creates a (regular) file with the specified file name and with the specified creation options. The resulting file will be a direct child of this directory.

The specified file name is resolved against this directory.

Parameters:

fileName - the name of the file to be created

options - file creation options

Returns:

a new file with the specified name and with the specified creation options

Throws:

IllegalArgumentException - if the resolved pathname is not a direct child of this directory

FoundException - if the resolved pathname already exists

IOException - if an I/O error occurs

delete

void delete()
            throws IOException

Deletes this directory or fails if the directory is not empty.

Throws:

IOException - if an I/O error occurs

See Also:

deleteContents()

deleteContents

void deleteContents()
                    throws IOException

Recursively deletes the contents of this directory. This directory will be empty when this operation completes normally.

Throws:

IOException - if an I/O error occurs

getDirectory

Directory getDirectory(String directoryName)
                       throws NotFoundException,
                              NotDirectoryException,
                              IOException

Returns an existing subdirectory having the specified name. The resulting directory will be a direct child of this directory.

Parameters:

directoryName - the name of the directory to be located

Returns:

an existent subdirectory

Throws:

IllegalArgumentException - if the resolved pathname is not a direct child of this directory

NotFoundException - if the resolved pathname does not exist

NotDirectoryException - if the resolved pathname exists but it is not a directory (it is a regular file, for example)

IOException - if an I/O error occurs

getName

String getName()

Returns the name of this directory.

Returns:

the name of this directory

getOrCreateRegularFile

RegularFile getOrCreateRegularFile(String fileName)
                                   throws NotRegularFileException,
                                          IOException

Returns an existing (regular) file or creates new one with the specified file name. The resulting file will be a direct child of this directory.

The specified file name is resolved against this directory.

Parameters:

fileName - the name of the file to be created

Returns:

an existing file with the specified file name or a new file with the specified name

Throws:

IllegalArgumentException - if the resolved pathname is not a direct child of this directory

NotRegularFileException - if the resolved pathname exists but it is not a regular file (it is a directory, for example)

IOException - if an I/O error occurs

getParent

Directory getParent()
                    throws NotFoundException

Returns the parent directory of this directory.

Returns:

the parent directory of this directory

Throws:

NotFoundException - if a parent for this directory cannot be found

getPath

String getPath()

Returns the full path of this directory.

Returns:

the full path of this directory

getRegularFile

RegularFile getRegularFile(String fileName)
                           throws NotFoundException,
                                  NotRegularFileException,
                                  IOException

Returns an existing (regular) file with the specified file name. The resulting file will be a direct child of this directory.

Parameters:

fileName - the name of the file to be located

Returns:

an existing (regular) file with the specified file name

Throws:

IllegalArgumentException - if the resolved pathname is not a direct child of this directory

NotFoundException - if the resolved pathname does not exist

NotRegularFileException - if the resolved pathname exists but it is not a regular file (it is a directory, for example)

IOException - if an I/O error occurs

isEmpty

boolean isEmpty()

Returns true if this directory contains no entries.

Returns:

true if this directory contains no entries

visitContents

void visitContents(DirectoryContentsVisitor visitor)
                   throws IOException

Visits each child of this directory with the specified visitor.

Parameters:

visitor - the visitor instance

Throws:

IOException - if an I/O error occurs

acceptPathNameVisitor

<R,P> R acceptPathNameVisitor(PathNameVisitor<R,P> visitor,
                              P p)
                        throws IOException

Accept method used to implement the visitor pattern.

Type Parameters:

R - the result type of this operation

P - the type of the additional object

Parameters:

visitor - the visitor operating on this PathName instance

p - additional object passed to the visitor

Returns:

the value returned from the visitor method

Throws:

IOException - if an I/O error occurs

exists

boolean exists()

Returns true if the pathname represented by this object exists.

Returns:

true if the pathname represented by this object exists

toFile

File toFile()

Returns a File representation of this pathname.

Returns:

a File representation of this pathname

toUri

URI toUri()

Returns an URI representation of this pathname.

Returns:

an URI representation of this pathname

resolve

ResolvedPath resolve(String first,
                     String... more)

Returns a new ResolvedPath object representing the resolved pathname of a descendant of this directory or returns this object if the specified names result in the empty string.

All of the specified names are combined together, in a system dependant manner, resulting in a relative pathname. This pathname is resolved against this directory.

Usage example (for a system with a name separator "/"):

     Directory tmp = ... // for example "/tmp"
     tmp.resolve("a"); // resolves to "/tmp/a"
     tmp.resolve("x", "..", "z"); // resolves to "/tmp/x/../z" (eq. to "/tmp/z")
     tmp.resolve(""); // resolves to "/tmp"
     tmp.resolve("..", "root", ".ssh"); // fails with IllegalArgumentException (not descendant)
     tmp.resolve("/root"); // fails with IllegalArgumentException (absolute)
 

Parameters:

first - the first part of the pathname relative to this directory

more - the remaining parts of the pathname relative to this directory

Returns:

a ResolvedPath representing the pathname of a descendant of this directory

Throws:

IllegalArgumentException - if the resolved pathname is not a descendant of this directory