org.entityfs.util
Class Directories

java.lang.Object
  org.entityfs.util.Directories

public final class Directories
extends Object

A utility class that contains static methods for working with Directory entities and DirectoryView:s.

The Entities utility class contains utility methods that complement the utility methods in this class.

The methods in this class will use the locking strategy for utility classes described in EntityLock.

Since:

1.0

Author:

Karl Gustafsson

See Also:

Directory, DirectoryView, Entities

Method Summary

static boolean	containsEntity(EntityHolder eh, RelativeLocation loc) Is there an entity at the given location relative to the entity holder? If this is called with a EntityAcceptingEntityView argument, only entities that are visible in that view are accounted for.
static boolean	containsEntity(EntityHolder eh, String name) Does the directory contain an entity with the supplied name? If this is called with a EntityAcceptingEntityView argument, only entities that are visible in that view are accounted for.
static boolean	containsEntityMatching(EntityListable el, Pattern p) Is there one and only one entity in the EntityListable with a name that matches the given regular expression pattern?
static boolean	containsEntityMatching(EntityListable el, String glob) Is there one and only one entity in the EntityListable with a name that matches the given glob pattern?
static Set<FoundEntity>	find(EntityListable dir, Filter<? super EntityView> filter) Find the entities in the directory hierarchy under dir that match the filter.
static Set<EntityView>	findEntities(EntityListable dir, Filter<? super EntityView> filter) Find the entities in the directory hierarchy under dir that match the filter.
static Set<DirectoryView>	getAllDirectoriesMatching(EntityListable el, Glob g) Get all directories with a name that matches the provided glob pattern.
static Set<DirectoryView>	getAllDirectoriesMatching(EntityListable el, String glob) Get all directories with a name that matches the provided glob pattern.
static Set<EntityView>	getAllEntitiesMatching(EntityListable el, Glob g) Get all files with a name that matches the provided glob pattern.
static Set<EntityView>	getAllEntitiesMatching(EntityListable el, String glob) Get all files with a name that matches the provided glob pattern.
static Set<EFile>	getAllFilesMatching(EntityListable el, Glob g) Get all files with a name that matches the provided glob pattern.
static Set<EFile>	getAllFilesMatching(EntityListable el, String glob) Get all files with a name that matches the provided glob pattern.
static RelativeLocation	getChildRelativeLocation(DirectoryView parent, EntityView child) Get the relative location of a file versus a directory that must be a parent directory somewhere in the entity's hierarchy.
static DepthFirstIterator<EntityView>	getDepthFirstIterator(EntityListable el) Create a depth-first iterator that will return all visible entities in a directory's subhierarchy.
static DepthFirstIterator<EntityView>	getDepthFirstIterator(EntityListable el, Filter<? super EntityView> filter) Create a filtered depth-first iterator that will return all visible entities in an directory's subhierarchy that matches the given filter.
static DepthLastIterator<EntityView>	getDepthLastIterator(EntityListable el) Create a depth-last (breadth-first) iterator that will return all visible entities in a directory's subhierarchy.
static DepthLastIterator<EntityView>	getDepthLastIterator(EntityListable el, Filter<? super EntityView> filter) Create a filtered depth-last (breadth-first) iterator that will return all visible entities in an directory's subhierarchy that matches the given filter.
static DirectoryView	getDirectory(EntityHolder eh, RelativeLocation loc) Get the directory with the given location relative to the entity holder.
static DirectoryView	getDirectory(EntityHolder eh, String name) Get an existing directory from the entity holder.
static DirectoryView	getDirectoryMatching(EntityListable el, Glob g) Get a directory with a name that matches the provided glob pattern.
static DirectoryView	getDirectoryMatching(EntityListable el, Pattern p) Get a directory with a name that matches the provided regular expression pattern.
static DirectoryView	getDirectoryMatching(EntityListable el, String glob) Get a directory with a name that matches the provided glob pattern.
static DirectoryView	getDirectoryMatchingOrNull(EntityListable el, Glob g) Get a directory with a name that matches the provided glob pattern, returning null if no such directory can be found.
static DirectoryView	getDirectoryMatchingOrNull(EntityListable el, Pattern p) Get a directory in the supplied directory with a name that matches the provided regular expression pattern, returning null if no such directory can be found.
static DirectoryView	getDirectoryMatchingOrNull(EntityListable el, String glob) Get a directory with a name that matches the provided glob pattern, returning null if no such directory can be found.
static DirectoryView	getDirectoryOrNull(EntityHolder eh, RelativeLocation loc) Get an existing directory with the given location relative to the entity holder, returning null if the directory does not exist or if it has been made invisible by view filters.
static DirectoryView	getDirectoryOrNull(EntityHolder eh, String name) Get an existing directory from the holder, returning null if the directory does not exist or if it has been made invisible by view filters.
static EntityView	getEntity(EntityHolder eh, RelativeLocation loc) Get an existing entity with the given location relative to the entity holder.
static EntityView	getEntity(EntityHolder eh, String name) Get an existing entity from the entity holder.
static EntityView	getEntityMatching(EntityListable el, Glob g) Get an entity with a name that matches the provided glob pattern.
static EntityView	getEntityMatching(EntityListable el, Pattern p) Get an entity in the supplied directory with a name that matches the provided regular expression pattern.
static EntityView	getEntityMatching(EntityListable el, String glob) Get an entity with a name that matches the provided glob pattern.
static EntityView	getEntityMatchingOrNull(EntityListable el, Glob g) Get an entity with a name that matches the provided glob pattern, returning null if no such entity can be found.
static EntityView	getEntityMatchingOrNull(EntityListable el, Pattern p) Get an entity in the supplied directory with a name that matches the provided regular expression pattern, returning null if no such entity can be found.
static EntityView	getEntityMatchingOrNull(EntityListable el, String glob) Get an entity with a name that matches the provided glob pattern, returning null if no such entity can be found.
static EntityView	getEntityOrNull(EntityHolder eh, RelativeLocation loc) Get an existing entity with the given location relative to the entity holder, returning null if the entity does not exist or if it has been made invisible by view filters.
static EntityView	getEntityOrNull(EntityHolder eh, String name) Get an existing entity from the entity holder, returning null if the entity does not exist or if it has been made invisible by view filters.
static EFile	getFile(EntityHolder eh, RelativeLocation loc) Get the file with the given location relative to the entity holder.
static EFile	getFile(EntityHolder eh, String name) Get the file with the given name from an entity holder.
static EFile	getFileMatching(EntityListable el, Glob g) Get a file with a name that matches the provided glob pattern.
static EFile	getFileMatching(EntityListable el, Pattern p) Get a file with a name that matches the provided regular expression pattern.
static EFile	getFileMatching(EntityListable el, String glob) Get a file with a name that matches the provided glob pattern.
static EFile	getFileMatchingOrNull(EntityListable el, Glob g) Get a file with a name that matches the provided glob pattern, returning null if no such file can be found.
static EFile	getFileMatchingOrNull(EntityListable el, Pattern p) Get a file in the supplied directory with a name that matches the provided regular expression pattern, returning null if no such file can be found.
static EFile	getFileMatchingOrNull(EntityListable el, String glob) Get a file with a name that matches the provided glob pattern, returning null if no such file can be found.
static EFile	getFileOrNull(EntityHolder eh, RelativeLocation loc) Get an existing file with the given location relative to the entity holder, returning null if the file does not exist or if it has been made invisible by view filters.
static EFile	getFileOrNull(EntityHolder eh, String name) Get an existing file from the holder, returning null if the file does not exist or if has been made invisible by view filters.
static Iterator<EntityView>	getIterator(EntityListable el) Create and return an Iterator for the directory.
static DepthFirstIterator<EntityAndRelativeLocation<EntityView>>	getLocationAwareDepthFirstIterator(EntityListable el) Get a depth-first iterator that returns EntityAndRelativeLocation objects.
static DepthFirstIterator<EntityAndRelativeLocation<EntityView>>	getLocationAwareDepthFirstIterator(EntityListable el, Filter<? super EntityView> filter) Get a depth-first iterator that returns EntityAndRelativeLocation objects.
static DepthLastIterator<EntityAndRelativeLocation<EntityView>>	getLocationAwareDepthLastIterator(EntityListable el) Get a depth-last (breadth-first) iterator that returns EntityAndRelativeLocation objects.
static DepthLastIterator<EntityAndRelativeLocation<EntityView>>	getLocationAwareDepthLastIterator(EntityListable el, Filter<? super EntityView> filter) Get a depth-last (breadth-first) iterator that returns EntityAndRelativeLocation objects.
static boolean	isEmpty(EntityListable el) Is the directory empty? A directory view is considered to be empty if it has no visible child entities.
static Set<EntityView>	listEntities(EntityListable el) List all visible entities in a directory view.
static Set<EntityView>	listEntities(EntityListable el, Comparator<? super EntityView> cmp) List all visible entities in a directory view and return a set that is sorted with the supplied Comparator.
static Set<EntityView>	listEntities(EntityListable el, Filter<? super EntityView> filter) List all entities in the directory that match the given filter.
static Set<EntityView>	listEntities(EntityListable el, Filter<? super EntityView> filter, Comparator<? super EntityView> cmp) List all entities in this directory view that match the given filter, i.e.
static <T extends DirectoryView> T	newDirectory(T dv, RelativeLocation loc) Create a new, empty directory and return a reference.
static <T extends DirectoryView> T	newDirectory(T dv, String name) Create a new, empty directory and return a reference.
static EFile	newFile(DirectoryView dv, RelativeLocation rel) Create a new, empty file in a location relative to the base directory.
static EFile	newFile(DirectoryView dv, String name) Create a new, empty file.
static <T extends DirectoryView> T	newTempDirectory(T dv, String prefix, String suffix) Create a new, empty, temporary directory and return a reference.
static EFile	newTempFile(DirectoryView dv, String prefix, String suffix) Create a new, empty, temporary file and return a reference.
static Collection<DirectoryView>	newViews(Collection<? extends DirectoryView> dv, Filter<? super EntityView> ef) For all the directory views in the collection, create a new view with the given filter and return the new views in a collection.
static <T extends DirectoryView> T	putIfAbsentDirectory(T dv, RelativeLocation location) Return a directory reference, creating the directory and all necessary parent directories if they does not exist.
static <T extends DirectoryView> T	putIfAbsentDirectory(T dv, String name) Return a directory reference, creating the directory if it does not exist.
static int	size(EntityListable el) Get the size of the directory measured in the number of child entities that it contains.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

containsEntity

public static boolean containsEntity(EntityHolder eh,
                                     String name)
                              throws AccessDeniedException

Does the directory contain an entity with the supplied name? If this is called with a EntityAcceptingEntityView argument, only entities that are visible in that view are accounted for.

Parameters:

eh - The entity holder, for instance a directory or directory view.

name - The entity name.

Returns:

true if the entity holder has a visible entity with the supplied name, false if there is no entity with the supplied name in the holder or if it has been made invisible by directory view filters.

Throws:

AccessDeniedException - If the client does not have execute access to the entity holder.

Permissions_required:

Execute access.

containsEntity

public static boolean containsEntity(EntityHolder eh,
                                     RelativeLocation loc)
                              throws AccessDeniedException,
                                     IllegalArgumentException

Is there an entity at the given location relative to the entity holder? If this is called with a EntityAcceptingEntityView argument, only entities that are visible in that view are accounted for.

Parameters:

eh - The entity holder, for instance a directory or directory view.

loc - The relative location of the entity compared with the holder's. If this is called on a non-entity holder, this location cannot reference the holder or a parent location of the holder.

Returns:

true if there is a visible entity at the supplied location, false if there is no entity or if it has been made invisible by directory view filters.

Throws:

AccessDeniedException - If the client does not have execute access to directories needed to find the target entity.

IllegalArgumentException - If this is called with a location that references a non-entity entity holder or a location above an entity holder, i.e. an entity holder that does not implement EntityView. (Referencing entities or parents of entities are allowed.)

Permissions_required:

Execute access to all directories visited while searching for the target entity.

containsEntityMatching

public static boolean containsEntityMatching(EntityListable el,
                                             String glob)
                                      throws AccessDeniedException,
                                             SeveralEntitiesMatchingException,
                                             PatternSyntaxException

Is there one and only one entity in the EntityListable with a name that matches the given glob pattern?

Parameters:

el - The entity listable, for instance a directory or directory view.

glob - The glob pattern that the entity's name must match.

Returns:

true if there is one entity in the listable with a name that matches the pattern, false if there is no entity with a name matching the pattern.

Throws:

PatternSyntaxException - On syntax errors in the glob pattern.

AccessDeniedException - If the current thread does not have execute access to the listable.

SeveralEntitiesMatchingException - If there are more than one entity matching the name pattern.

Permissions_required:

Execute access to the directory.

containsEntityMatching

public static boolean containsEntityMatching(EntityListable el,
                                             Pattern p)
                                      throws AccessDeniedException,
                                             SeveralEntitiesMatchingException

Is there one and only one entity in the EntityListable with a name that matches the given regular expression pattern?

Parameters:

el - The entity listable, for instance a directory or directory view.

p - The regular expression pattern that the entity's name must match.

Returns:

true if there is one entity in the listable with a name that matches the pattern, false if there is no entity with a name matching the pattern.

Throws:

AccessDeniedException - If the current thread does not have execute access to the listable.

SeveralEntitiesMatchingException - If there are more than one entity matching the name pattern.

Permissions_required:

Execute access.

getEntityOrNull

public static EntityView getEntityOrNull(EntityHolder eh,
                                         String name)
                                  throws AccessDeniedException

Get an existing entity from the entity holder, returning null if the entity does not exist or if it has been made invisible by view filters.

If the returned entity is ViewCapable, a view that is identical to the supplied directory view (same filter instances) is returned.

Parameters:

eh - The entity holder, for instance a directory or directory view.

name - The name of the entity.

Returns:

The entity, or null if it does not exist or if it has been made invisible by view filters.

Throws:

AccessDeniedException - If the client does not have execute access to the directory.

See Also:

getEntity(EntityHolder, String), getEntityOrNull(EntityHolder, RelativeLocation), getDirectoryOrNull(EntityHolder, String), getFileOrNull(EntityHolder, String)

Permissions_required:

Execute access.

getFileOrNull

public static EFile getFileOrNull(EntityHolder eh,
                                  String name)
                           throws AccessDeniedException,
                                  NotAFileException

Get an existing file from the holder, returning null if the file does not exist or if has been made invisible by view filters.

Parameters:

eh - The entity holder, for instance a directory or directory view.

name - The name of the file.

Returns:

The file, or null if it does not exist or if it has been made invisible by view filters.

Throws:

AccessDeniedException - If the client does not have execute access to the entity holder.

NotAFileException - If the entity exists but is not a file.

See Also:

getFile(EntityHolder, String), getFileOrNull(EntityHolder, RelativeLocation), getEntityOrNull(EntityHolder, String), getDirectoryOrNull(EntityHolder, String)

Permissions_required:

Execute access.

getDirectoryOrNull

public static DirectoryView getDirectoryOrNull(EntityHolder eh,
                                               String name)
                                        throws AccessDeniedException,
                                               NotADirectoryException

Get an existing directory from the holder, returning null if the directory does not exist or if it has been made invisible by view filters.

If this is called with a directory view argument, a view that is identical to the supplied directory view (same filter instances) is returned.

Parameters:

eh - The entity holder, for instance a directory or directory view.

name - The name of the directory.

Returns:

The directory, or null if it does not exist or if it has been made invisible by view filters.

Throws:

AccessDeniedException - If the client does not have execute access to the entity holder.

NotADirectoryException - If the entity exists but is not a directory.

See Also:

getEntityOrNull(EntityHolder, String), getDirectoryOrNull(EntityHolder, RelativeLocation), getDirectory(EntityHolder, String), getFileOrNull(EntityHolder, String)

Permissions_required:

Execute access.

getAllEntitiesMatching

public static Set<EntityView> getAllEntitiesMatching(EntityListable el,
                                                     String glob)
                                              throws AccessDeniedException,
                                                     PatternSyntaxException

Get all files with a name that matches the provided glob pattern. This method can be called with a glob pattern that specifies a directory hierarchy, such as dir1/d*2/f*.

Parameters:

el - The entity listable, for instance a directory or directory view.

glob - The glob pattern that the files' names must match. The glob pattern may specify a directory hierarchy.

Returns:

A file set, possibly empty but never null.

Throws:

PatternSyntaxException - On syntax errors in the glob pattern.

AccessDeniedException - If the current thread does not have execute access to the directory.

See Also:

Glob

Permissions_required:

Execute access.

getAllEntitiesMatching

public static Set<EntityView> getAllEntitiesMatching(EntityListable el,
                                                     Glob g)
                                              throws AccessDeniedException

Get all files with a name that matches the provided glob pattern. This method can be called with a glob pattern that specifies a directory hierarchy, such as dir1/d*2/f*.

Parameters:

el - The entity listable, for instance a directory or directory view.

g - The glob pattern that the files' names must match. The glob pattern may specify a directory hierarchy.

Returns:

A file set, possibly empty but never null.

Throws:

AccessDeniedException - If the current thread does not have execute access to the directory.

Since:

1.1

See Also:

Glob

Permissions_required:

Execute access.

getEntityMatchingOrNull

public static EntityView getEntityMatchingOrNull(EntityListable el,
                                                 String glob)
                                          throws AccessDeniedException,
                                                 SeveralEntitiesMatchingException,
                                                 PatternSyntaxException

Get an entity with a name that matches the provided glob pattern, returning null if no such entity can be found.

Parameters:

el - The entity listable, for instance a directory or directory view.

glob - The glob pattern that the entity's name must match. The glob pattern may specify a directory hierarchy such as dir1/d*2/d.

Returns:

An entity with a name that matches the provided pattern, or null if there is no such entity in the listable or if it has been made invisible by view filters.

Throws:

PatternSyntaxException - On syntax errors in the glob pattern.

AccessDeniedException - If the current thread does not have execute access to the directory.

SeveralEntitiesMatchingException - If there are more than one entity matching the name pattern.

See Also:

Glob

Permissions_required:

Execute access.

getEntityMatchingOrNull

public static EntityView getEntityMatchingOrNull(EntityListable el,
                                                 Glob g)
                                          throws AccessDeniedException,
                                                 SeveralEntitiesMatchingException

Get an entity with a name that matches the provided glob pattern, returning null if no such entity can be found.

Parameters:

el - The entity listable, for instance a directory or directory view.

g - The glob pattern that the entity's name must match. The glob pattern may specify a directory hierarchy such as dir1/d*2/d.

Returns:

An entity with a name that matches the provided pattern, or null if there is no such entity in the listable or if it has been made invisible by view filters.

Throws:

AccessDeniedException - If the current thread does not have execute access to the directory.

SeveralEntitiesMatchingException - If there are more than one entity matching the name pattern.

Since:

1.1

See Also:

Glob

Permissions_required:

Execute access.

getEntityMatchingOrNull

public static EntityView getEntityMatchingOrNull(EntityListable el,
                                                 Pattern p)
                                          throws AccessDeniedException,
                                                 SeveralEntitiesMatchingException

Get an entity in the supplied directory with a name that matches the provided regular expression pattern, returning null if no such entity can be found.

Parameters:

el - The entity listable, for instance a directory or directory view.

p - The pattern that the entity's name must match.

Returns:

An entity with a name that matches the provided pattern, or null if no such entity can be found or if it has been made invisible by view filters.

Throws:

AccessDeniedException - If the current thread does not have execute access to the directory.

SeveralEntitiesMatchingException - If there are more than one entity matching the name pattern.

Permissions_required:

Execute access.

getAllFilesMatching

public static Set<EFile> getAllFilesMatching(EntityListable el,
                                             String glob)
                                      throws AccessDeniedException,
                                             PatternSyntaxException

Get all files with a name that matches the provided glob pattern. This method can be called with an argument that specifies a directory hierarchy, such as dir1/d*2/f*.

If there are non-file entities that match the pattern, they are ignored.

Parameters:

el - The entity listable, for instance a directory or directory view.

glob - The glob pattern that the files' names must match. The glob pattern may specify a directory hierarchy.

Returns:

A file set, possibly empty but never null.

Throws:

PatternSyntaxException - On syntax errors in the glob pattern.

AccessDeniedException - If the current thread does not have execute access to the directory.

Permissions_required:

Execute access.

getAllFilesMatching

public static Set<EFile> getAllFilesMatching(EntityListable el,
                                             Glob g)
                                      throws AccessDeniedException

Get all files with a name that matches the provided glob pattern. This method can be called with an argument that specifies a directory hierarchy, such as dir1/d*2/f*.

If there are non-file entities that match the pattern, they are ignored.

Parameters:

el - The entity listable, for instance a directory or directory view.

g - The glob pattern that the files' names must match. The glob pattern may specify a directory hierarchy.

Returns:

A file set, possibly empty but never null.

Throws:

AccessDeniedException - If the current thread does not have execute access to the directory.

Permissions_required:

Execute access.

getFileMatchingOrNull

public static EFile getFileMatchingOrNull(EntityListable el,
                                          String glob)
                                   throws AccessDeniedException,
                                          SeveralEntitiesMatchingException,
                                          PatternSyntaxException

Get a file with a name that matches the provided glob pattern, returning null if no such file can be found. This method can be called with an argument that specifies a directory hierarchy, such as dir1/d*2/f1.

If there are non-file entities that match the pattern, they are ignored.

Parameters:

el - The entity listable, for instance a directory or directory view.

glob - The glob pattern that the file's name must match. The glob pattern may specify a directory hierarchy.

Returns:

A file with a name that matches the provided pattern, or null if there is no such file in the directory or if it has been made invisible by view filters.

Throws:

PatternSyntaxException - On syntax errors in the glob pattern.

AccessDeniedException - If the current thread does not have execute access to the directory.

SeveralEntitiesMatchingException - If there are more than one file matching the name pattern.

Permissions_required:

Execute access.

getFileMatchingOrNull

public static EFile getFileMatchingOrNull(EntityListable el,
                                          Glob g)
                                   throws AccessDeniedException,
                                          SeveralEntitiesMatchingException

Get a file with a name that matches the provided glob pattern, returning null if no such file can be found. This method can be called with an argument that specifies a directory hierarchy, such as dir1/d*2/f1.

If there are non-file entities that match the pattern, they are ignored.

Parameters:

el - The entity listable, for instance a directory or directory view.

g - The glob pattern that the file's name must match. The glob pattern may specify a directory hierarchy.

Returns:

A file with a name that matches the provided pattern, or null if there is no such file in the directory or if it has been made invisible by view filters.

Throws:

AccessDeniedException - If the current thread does not have execute access to the directory.

SeveralEntitiesMatchingException - If there are more than one file matching the name pattern.

Since:

1.1

Permissions_required:

Execute access.

getFileMatchingOrNull

public static EFile getFileMatchingOrNull(EntityListable el,
                                          Pattern p)
                                   throws AccessDeniedException,
                                          SeveralEntitiesMatchingException

Get a file in the supplied directory with a name that matches the provided regular expression pattern, returning null if no such file can be found.

If there are non-file entities that match the pattern in the entity listable, they are ignored.

Parameters:

el - The entity listable, for instance a directory or directory view.

p - The regular expression pattern that the file name must match.

Returns:

A file with a name that matches the provided pattern, or null if there is no such file in the directory or if it has been made invisible by view filters.

Throws:

AccessDeniedException - If the current thread does not have execute access to the directory.

SeveralEntitiesMatchingException - If there are more than one file matching the name pattern.

Permissions_required:

Execute access.

getAllDirectoriesMatching

public static Set<DirectoryView> getAllDirectoriesMatching(EntityListable el,
                                                           String glob)
                                                    throws AccessDeniedException,
                                                           PatternSyntaxException

Get all directories with a name that matches the provided glob pattern. This method can be called with an argument that specifies a directory hierarchy, such as dir1/d*2/d*.

If there are non-directory entities that match the pattern, they are ignored.

Parameters:

el - The entity listable, for instance a directory or directory view.

glob - The glob pattern that the directories' names must match. The glob pattern may specify a directory hierarchy.

Returns:

A directory set, possibly empty but never null.

Throws:

PatternSyntaxException - On syntax errors in the glob pattern.

AccessDeniedException - If the current thread does not have execute access to the directory.

Permissions_required:

Execute access.

getAllDirectoriesMatching

public static Set<DirectoryView> getAllDirectoriesMatching(EntityListable el,
                                                           Glob g)
                                                    throws AccessDeniedException

Get all directories with a name that matches the provided glob pattern. This method can be called with an argument that specifies a directory hierarchy, such as dir1/d*2/d*.

If there are non-directory entities that match the pattern, they are ignored.

Parameters:

el - The entity listable, for instance a directory or directory view.

g - The glob pattern that the directories' names must match. The glob pattern may specify a directory hierarchy.

Returns:

A directory set, possibly empty but never null.

Throws:

AccessDeniedException - If the current thread does not have execute access to the directory.

Since:

1.1

See Also:

Glob

Permissions_required:

Execute access.

getDirectoryMatchingOrNull

public static DirectoryView getDirectoryMatchingOrNull(EntityListable el,
                                                       String glob)
                                                throws AccessDeniedException,
                                                       SeveralEntitiesMatchingException,
                                                       PatternSyntaxException

Get a directory with a name that matches the provided glob pattern, returning null if no such directory can be found. This method can be called with an argument that specifies a directory hierarchy, such as dir1/d*2/dir3.

If there are non-directory entities that match the pattern in the entity listable, they are ignored.

Parameters:

el - The entity listable, for instance a directory or directory view.

glob - The glob pattern that the directory's name must match. The glob pattern may specify a directory hierarchy.

Returns:

A directory with a name that matches the provided pattern, or null if there is no such directory in the directory or if it has been made invisible by view filters.

Throws:

PatternSyntaxException - On syntax errors in the glob pattern.

AccessDeniedException - If the current thread does not have execute access to the directory.

SeveralEntitiesMatchingException - If there are more than one directory matching the name pattern.

Permissions_required:

Execute access.

getDirectoryMatchingOrNull

public static DirectoryView getDirectoryMatchingOrNull(EntityListable el,
                                                       Glob g)
                                                throws AccessDeniedException,
                                                       SeveralEntitiesMatchingException

Get a directory with a name that matches the provided glob pattern, returning null if no such directory can be found. This method can be called with an argument that specifies a directory hierarchy, such as dir1/d*2/dir3.

If there are non-directory entities that match the pattern in the entity listable, they are ignored.

Parameters:

el - The entity listable, for instance a directory or directory view.

g - The glob pattern that the directory's name must match. The glob pattern may specify a directory hierarchy.

Returns:

A directory with a name that matches the provided pattern, or null if there is no such directory in the directory or if it has been made invisible by view filters.

Throws:

AccessDeniedException - If the current thread does not have execute access to the directory.

SeveralEntitiesMatchingException - If there are more than one directory matching the name pattern.

Since:

1.1

See Also:

Glob

Permissions_required:

Execute access.

getDirectoryMatchingOrNull

public static DirectoryView getDirectoryMatchingOrNull(EntityListable el,
                                                       Pattern p)
                                                throws AccessDeniedException,
                                                       SeveralEntitiesMatchingException

Get a directory in the supplied directory with a name that matches the provided regular expression pattern, returning null if no such directory can be found.

If there are non-directory entities that match the pattern in the entity listable, they are ignored.

Parameters:

el - The entity listable, for instance a directory or directory view.

p - The regular expression pattern that the directory name must match.

Returns:

A directory with a name that matches the provided pattern, or null if there is no such directory in the directory or if it has been made invisible by view filters.

Throws:

AccessDeniedException - If the current thread does not have execute access to the directory.

SeveralEntitiesMatchingException - If there are more than one directory matching the name pattern.

Permissions_required:

Execute access.

getEntity

public static EntityView getEntity(EntityHolder eh,
                                   String name)
                            throws EntityNotFoundException,
                                   AccessDeniedException

Get an existing entity from the entity holder.

If the returned entity is ViewCapable, a view that is identical to the supplied directory view (same filter instances) is returned.

Parameters:

eh - The entity holder, for instance a directory or directory view.

name - The name of the entity.

Returns:

The entity.

Throws:

EntityNotFoundException - If the entity does not exist or if it has been made invisible by view filters.

AccessDeniedException - If the client does not have execute access to the entity holder.

See Also:

getEntityOrNull(EntityHolder, String), getEntity(EntityHolder, RelativeLocation), getFile(EntityHolder, String), getDirectory(EntityHolder, String)

Permissions_required:

Execute access.

getFile

public static EFile getFile(EntityHolder eh,
                            String name)
                     throws EntityNotFoundException,
                            AccessDeniedException,
                            NotAFileException

Get the file with the given name from an entity holder.

Parameters:

eh - The entity holder, for instance a directory or directory view.

name - The name of the file.

Returns:

The file.

Throws:

EntityNotFoundException - If the entity does not exist, or if it has been made invisible by view filters.

AccessDeniedException - If the client does not have execute access to the entity holder.

NotAFileException - If the found entity is not a file.

See Also:

getEntity(EntityHolder, String), getDirectory(EntityHolder, String), getFile(EntityHolder, RelativeLocation)

Permissions_required:

Execute access.

getDirectory

public static DirectoryView getDirectory(EntityHolder eh,
                                         String name)
                                  throws EntityNotFoundException,
                                         AccessDeniedException,
                                         NotADirectoryException

Get an existing directory from the entity holder. If this method is called with a directory view argument, the returned directory view has uses the same filter instances as the provided view.

If this method is called with a Directory argument, the result can safely be cast to Directory.

Parameters:

eh - The entity holder, for instance a directory or directory view.

name - The name of the directory.

Returns:

The directory or directory view.

Throws:

EntityNotFoundException - If the directory does not exist or if it has been made invisible by view filters.

AccessDeniedException - If the client does not have execute access to the entity holder.

NotADirectoryException - If the found entity is not a directory

See Also:

getEntityOrNull(EntityHolder, String), getEntity(EntityHolder, RelativeLocation), getFile(EntityHolder, String)

Permissions_required:

Execute access.

getEntityMatching

public static EntityView getEntityMatching(EntityListable el,
                                           String glob)
                                    throws EntityNotFoundException,
                                           AccessDeniedException,
                                           SeveralEntitiesMatchingException,
                                           PatternSyntaxException

Get an entity with a name that matches the provided glob pattern. This method can be called with an argument that specifies a directory hierarchy, such as dir1/d*2/dir3.

Parameters:

el - The entity listable, for instance a directory or directory view.

glob - The glob pattern that the entity's name must match. The glob pattern may specify a directory hierarchy.

Returns:

A file with a name that matches the provided pattern.

Throws:

PatternSyntaxException - On syntax errors in the glob pattern.

EntityNotFoundException - If no entity that matches the pattern was found in the directory, or if the entity has been made invisible by view filters.

AccessDeniedException - If the current thread does not have execute access to the directory.

SeveralEntitiesMatchingException - If there are more than one entity matching the name pattern.

Permissions_required:

Execute access.

getEntityMatching

public static EntityView getEntityMatching(EntityListable el,
                                           Glob g)
                                    throws EntityNotFoundException,
                                           AccessDeniedException,
                                           SeveralEntitiesMatchingException,
                                           PatternSyntaxException

Get an entity with a name that matches the provided glob pattern. This method can be called with an argument that specifies a directory hierarchy, such as dir1/d*2/dir3.

Parameters:

el - The entity listable, for instance a directory or directory view.

g - The glob pattern that the entity's name must match. The glob pattern may specify a directory hierarchy.

Returns:

A file with a name that matches the provided pattern.

Throws:

EntityNotFoundException - If no entity that matches the pattern was found in the directory, or if the entity has been made invisible by view filters.

AccessDeniedException - If the current thread does not have execute access to the directory.

SeveralEntitiesMatchingException - If there are more than one entity matching the name pattern.

PatternSyntaxException

Since:

1.1

See Also:

Glob

Permissions_required:

Execute access.

getEntityMatching

public static EntityView getEntityMatching(EntityListable el,
                                           Pattern p)
                                    throws EntityNotFoundException,
                                           AccessDeniedException,
                                           SeveralEntitiesMatchingException

Get an entity in the supplied directory with a name that matches the provided regular expression pattern.

Parameters:

el - The entity listable, for instance a directory or directory view.

p - The pattern that the entity's name must match.

Returns:

An entity with a name that matches the provided pattern.

Throws:

EntityNotFoundException - If no entity that matches the pattern was found in the directory, or if the entity has been made invisible by view filters.

AccessDeniedException - If the current thread does not have execute access to the directory.

SeveralEntitiesMatchingException - If there are more than one entity matching the name pattern.

Permissions_required:

Execute access.

getFileMatching

public static EFile getFileMatching(EntityListable el,
                                    String glob)
                             throws EntityNotFoundException,
                                    AccessDeniedException,
                                    SeveralEntitiesMatchingException,
                                    PatternSyntaxException

Get a file with a name that matches the provided glob pattern.

If there are non-file entities that match the pattern in the entity listable, they are ignored.

Parameters:

el - The entity listable, for instance a directory or directory view.

glob - The glob pattern that the file's name must match.

Returns:

A file with a name that matches the provided pattern. The glob pattern may specify a directory hierarchy such as dir1/d*2/*.txt.

Throws:

PatternSyntaxException - On syntax errors in the glob pattern.

EntityNotFoundException - If no file that matches the pattern was found in the directory, or if it has been made invisible by view filters.

AccessDeniedException - If the current thread does not have execute access to the directory.

SeveralEntitiesMatchingException - If there are more than one file matching the name pattern.

Permissions_required:

Execute access.

getFileMatching

public static EFile getFileMatching(EntityListable el,
                                    Glob g)
                             throws EntityNotFoundException,
                                    AccessDeniedException,
                                    SeveralEntitiesMatchingException

Get a file with a name that matches the provided glob pattern.

If there are non-file entities that match the pattern in the entity listable, they are ignored.

Parameters:

el - The entity listable, for instance a directory or directory view.

g - The glob pattern that the file's name must match. The glob pattern may specify a directory hierarchy such as dir1/d*2/*.txt.

Returns:

A file with a name that matches the provided pattern.

Throws:

EntityNotFoundException - If no file that matches the pattern was found in the directory, or if it has been made invisible by view filters.

AccessDeniedException - If the current thread does not have execute access to the directory.

SeveralEntitiesMatchingException - If there are more than one file matching the name pattern.

Since:

1.1

See Also:

Glob

Permissions_required:

Execute access.

getFileMatching

public static EFile getFileMatching(EntityListable el,
                                    Pattern p)
                             throws EntityNotFoundException,
                                    AccessDeniedException,
                                    SeveralEntitiesMatchingException

Get a file with a name that matches the provided regular expression pattern.

If there are non-file entities that match the pattern in the entity listable, they are ignored.

Parameters:

el - The entity listable, for instance a directory or directory view.

p - The pattern that the file's name must match.

Returns:

A file with a name that matches the provided pattern.

Throws:

EntityNotFoundException - If no file that matches the pattern was found in the directory, or if it has been made invisible by view filters.

AccessDeniedException - If the current thread does not have execute access to the directory.

SeveralEntitiesMatchingException - If there are more than one file matching the name pattern.

Permissions_required:

Execute access.

getDirectoryMatching

public static DirectoryView getDirectoryMatching(EntityListable el,
                                                 String glob)
                                          throws EntityNotFoundException,
                                                 AccessDeniedException,
                                                 SeveralEntitiesMatchingException,
                                                 PatternSyntaxException

Get a directory with a name that matches the provided glob pattern. This method can be called with an argument that specifies a directory hierarchy, such as dir1/d*2/dir3.

If there are non-directory entities that match the pattern, they are ignored.

Parameters:

el - The entity listable, for instance a directory or directory view.

glob - The glob pattern that the directory's name must match. The glob pattern may specify a directory hierarchy.

Returns:

A directory with a name that matches the provided pattern.

Throws:

PatternSyntaxException - On syntax errors in the glob pattern.

EntityNotFoundException - If no directory that matches the pattern was found in the directory, or if it has been made invisible by view filters.

AccessDeniedException - If the current thread does not have execute access to the directory.

SeveralEntitiesMatchingException - If there are more than one directory matching the name pattern.

Permissions_required:

Execute access.

getDirectoryMatching

public static DirectoryView getDirectoryMatching(EntityListable el,
                                                 Glob g)
                                          throws EntityNotFoundException,
                                                 AccessDeniedException,
                                                 SeveralEntitiesMatchingException

Get a directory with a name that matches the provided glob pattern. This method can be called with an argument that specifies a directory hierarchy, such as dir1/d*2/dir3.

If there are non-directory entities that match the pattern, they are ignored.

Parameters:

el - The entity listable, for instance a directory or directory view.

g - The glob pattern that the directory's name must match. The glob pattern may specify a directory hierarchy.

Returns:

A directory with a name that matches the provided pattern.

Throws:

EntityNotFoundException - If no directory that matches the pattern was found in the directory, or if it has been made invisible by view filters.

AccessDeniedException - If the current thread does not have execute access to the directory.

SeveralEntitiesMatchingException - If there are more than one directory matching the name pattern.

Since:

1.1

See Also:

Glob

Permissions_required:

Execute access.

getDirectoryMatching

public static DirectoryView getDirectoryMatching(EntityListable el,
                                                 Pattern p)
                                          throws EntityNotFoundException,
                                                 AccessDeniedException,
                                                 SeveralEntitiesMatchingException

Get a directory with a name that matches the provided regular expression pattern.

If there are non-directory entities that match the pattern in the directory, they are ignored.

Parameters:

el - The entity listable, for instance a directory or directory view.

p - The pattern that the directory's name must match.

Returns:

A directory with a name that matches the provided pattern.

Throws:

EntityNotFoundException - If no directory that matches the pattern was found in the directory, or if it has been made invisible by view filters.

AccessDeniedException - If the current thread does not have execute access to the directory.

SeveralEntitiesMatchingException - If there are more than one directory matching the name pattern.

Permissions_required:

Execute access.

getEntityOrNull

public static EntityView getEntityOrNull(EntityHolder eh,
                                         RelativeLocation loc)
                                  throws AccessDeniedException,
                                         IllegalArgumentException

Get an existing entity with the given location relative to the entity holder, returning null if the entity does not exist or if it has been made invisible by view filters.

If the returned entity is ViewCapable, a view that is identical (same filter instances) to the supplied directory view is returned.

Parameters:

eh - The entity holder, for instance a directory or directory view.

loc - The relative location of the entity compared with the holder's. If this is called on a non-entity holder, this location cannot reference the holder or a location above the holder.

Returns:

The entity, or null if the entity does not exist or has been made invisible by view filters.

Throws:

AccessDeniedException - If the client does not have execute access to directories needed to find the target entity.

IllegalArgumentException - If this is called with a location that references a non-entity entity holder or a location above an entity holder, i.e. an entity holder that does not implement EntityView. (Referencing entities or parents of entities are allowed.)

See Also:

getEntityOrNull(EntityHolder, String), getEntity(EntityHolder, RelativeLocation), getFileOrNull(EntityHolder, RelativeLocation), getDirectoryOrNull(EntityHolder, RelativeLocation)

Permissions_required:

Execute access to all directories between eh (inclusive) and the requested entity.

getFileOrNull

public static EFile getFileOrNull(EntityHolder eh,
                                  RelativeLocation loc)
                           throws AccessDeniedException,
                                  NotAFileException,
                                  IllegalArgumentException

Get an existing file with the given location relative to the entity holder, returning null if the file does not exist or if it has been made invisible by view filters.

Parameters:

eh - The entity holder, for instance a directory or directory view.

loc - The relative location of the file compared with the holder's. If this is called on a non-entity holder, this location cannot reference the holder or a location above the holder.

Returns:

The file, or null if it does not exist or has been made invisible by the directory view's filters.

Throws:

AccessDeniedException - If the client does not have execute access to directories needed to find the target entity.

NotAFileException - If the entity exists but is not a file.

IllegalArgumentException - If this is called with a location that references a non-entity entity holder or a location above an entity holder, i.e. an entity holder that does not implement EntityView. (Referencing entities or parents of entities are allowed.)

See Also:

getEntityOrNull(EntityHolder, RelativeLocation), getDirectoryOrNull(EntityHolder, RelativeLocation), getFileOrNull(EntityHolder, String), getFile(EntityHolder, RelativeLocation)

Permissions_required:

Execute access to all directories between eh (inclusive) and the requested file.

getDirectoryOrNull

public static DirectoryView getDirectoryOrNull(EntityHolder eh,
                                               RelativeLocation loc)
                                        throws AccessDeniedException,
                                               NotADirectoryException,
                                               IllegalArgumentException

Get an existing directory with the given location relative to the entity holder, returning null if the directory does not exist or if it has been made invisible by view filters.

If this method is called with a directory view argument, the returned directory is an identical (same filter instances) view of the requested directory.

Parameters:

eh - The entity holder, for instance a directory or directory view.

loc - The relative location of the directory compared with the holder's. If this is called on a non-entity holder, this location cannot reference the holder or a location above the holder.

Returns:

The directory, or null if it does not exist or has been made invisible by view filters.

Throws:

AccessDeniedException - If the client does not have execute access to directories needed to find the target entity.

NotADirectoryException - If the entity exists but is not a directory.

IllegalArgumentException - If this is called with a location that references a non-entity entity holder or a location above an entity holder, i.e. an entity holder that does not implement EntityView. (Referencing entities or parents of entities are allowed.)

See Also:

getDirectoryOrNull(EntityHolder, String), getDirectory(EntityHolder, RelativeLocation), getEntityOrNull(EntityHolder, RelativeLocation), getDirectoryOrNull(EntityHolder, RelativeLocation)

Permissions_required:

Execute access to all directories between eh (inclusive) and the requested directory (exclusive).

getEntity

public static EntityView getEntity(EntityHolder eh,
                                   RelativeLocation loc)
                            throws EntityNotFoundException,
                                   AccessDeniedException,
                                   IllegalArgumentException

Get an existing entity with the given location relative to the entity holder.

If the returned entity is ViewCapable, a view that is identical to the supplied directory view (same filter instances) is returned.

Parameters:

eh - The entity holder, for instance a directory or directory view.

loc - The relative location of the entity compared with the holder's. If this is called on a non-entity holder, this location cannot reference the holder or a location above the holder.

Returns:

The entity.

Throws:

EntityNotFoundException - If the entity does not exist, or if it has been made invisible by view filters.

AccessDeniedException - If the client does not have execute access to directories needed to find the target entity.

IllegalArgumentException - If this is called with a location that references a non-entity entity holder or a location above an entity holder, i.e. an entity holder that does not implement EntityView. (Referencing entities or parents of entities are allowed.)

See Also:

getEntityOrNull(EntityHolder, RelativeLocation), getEntity(EntityHolder, String)

Permissions_required:

Execute access to all directories between eh (inclusive) and the requested entity.

getFile

public static EFile getFile(EntityHolder eh,
                            RelativeLocation loc)
                     throws EntityNotFoundException,
                            AccessDeniedException,
                            NotAFileException,
                            IllegalArgumentException

Get the file with the given location relative to the entity holder.

Parameters:

eh - The entity holder, for instance a directory or directory view.

loc - The relative location of the file compared with the holder's. If this is called on a non-entity holder, this location cannot reference the holder or a location above the holder.

Returns:

The file.

Throws:

EntityNotFoundException - If the entity does not exist, or if it has been med invisible by view filters.

AccessDeniedException - If the client does not have execute access to directories needed to find the target file.

NotAFileException - If the found entity is not a file.

IllegalArgumentException - If this is called with a location that references a non-entity entity holder or a location above an entity holder, i.e. an entity holder that does not implement EntityView. (Referencing entities or parents of entities are allowed.)

See Also:

getFile(EntityHolder, String), getEntity(EntityHolder, RelativeLocation), getDirectory(EntityHolder, RelativeLocation)

Permissions_required:

Execute access to all directories between eh (inclusive) and the requested file.

getDirectory

public static DirectoryView getDirectory(EntityHolder eh,
                                         RelativeLocation loc)
                                  throws EntityNotFoundException,
                                         AccessDeniedException,
                                         NotADirectoryException,
                                         IllegalArgumentException

Get the directory with the given location relative to the entity holder. If this is called with a directory view argument, the returned directory view uses the same filter instances as the provided directory view.

If this method is called with a Directory argument, the result can safely be cast to Directory.

Parameters:

eh - The entity holder, for instance a directory or directory view.

loc - The relative location of the directory compared with the holder's. If this is called on a non-entity holder, this location cannot reference the holder or a location above the holder.

Returns:

The directory or directory view.

Throws:

EntityNotFoundException - If the directory does not exist or if it has been made invisible by view filters.

AccessDeniedException - If the client does not have execute access to the entity holder.

NotADirectoryException - If the found entity is not a directory

IllegalArgumentException - If this is called with a location that references a non-entity entity holder or a location above an entity holder, i.e. an entity holder that does not implement EntityView. (Referencing entities or parents of entities are allowed.)

See Also:

getEntity(EntityHolder, RelativeLocation), getFile(EntityHolder, RelativeLocation), getDirectory(EntityHolder, String)

Permissions_required:

Execute access to all directories between eh (inclusive) and the requested directory (exclusive).

listEntities

public static Set<EntityView> listEntities(EntityListable el,
                                           Filter<? super EntityView> filter)
                                    throws AccessDeniedException

List all entities in the directory that match the given filter.

If this is called with a directory view argument, only entities that match the view's filters are returned and all returned ViewCapable entities inherit the directory view's filters.

Parameters:

el - The entity listable, for instance a directory or directory view.

filter - The Filter. The filter is often of the type EntityFilter.

Returns:

A set of entities, possibly empty but never null.

Throws:

AccessDeniedException - If the client does not have execute access to the directory.

Permissions_required:

Execute access and the access required by the filter(s).

listEntities

public static Set<EntityView> listEntities(EntityListable el)
                                    throws AccessDeniedException

List all visible entities in a directory view. If this is called with a directory view argument, only entities that match the view's filters are returned and all returned ViewCapable entities inherit the directory view's filters.

Parameters:

el - The entity listable, for instance a directory or directory view.

Returns:

A set of entities, possibly empty but never null.

Throws:

AccessDeniedException - If the client does not have execute access to the directory.

Permissions_required:

Execute access.

listEntities

public static Set<EntityView> listEntities(EntityListable el,
                                           Comparator<? super EntityView> cmp)

List all visible entities in a directory view and return a set that is sorted with the supplied Comparator. If this is called with a directory view argument, only entities that match the view's filters are returned and all returned ViewCapable entities inherit the directory view's filters.

Parameters:

el - The entity listable, for instance a directory or directory view.

cmp - The comparator.

Returns:

A set of entities, possibly empty but never null.

Throws:

AccessDeniedException - If the client does not have execute access to the directory.

Permissions_required:

Execute access.

listEntities

public static Set<EntityView> listEntities(EntityListable el,
                                           Filter<? super EntityView> filter,
                                           Comparator<? super EntityView> cmp)

List all entities in this directory view that match the given filter, i.e. all entities in the directory that match both the directory view's filters and the given filter. The result is sorted using the provided Comparator. If this is called with a directory view argument, only entities that match the view's filters are returned and all returned ViewCapable entities inherit the directory view's filters.

Parameters:

el - The entity listable, for instance a directory or directory view.

filter - The Filter. The filter is often of the type EntityFilter.

cmp - The comparator.

Returns:

A set of entities, possibly empty but never null.

Throws:

AccessDeniedException - If the client does not have execute access to the directory.

Permissions_required:

Execute access and the access required by the filter(s).

isEmpty

public static boolean isEmpty(EntityListable el)
                       throws AccessDeniedException

Is the directory empty? A directory view is considered to be empty if it has no visible child entities.

Parameters:

el - The entity listable, for instance a directory or directory view.

Returns:

true if there are no visible entities in the directory view, false otherwise.

Throws:

AccessDeniedException - If the client does not have execute access to the directory.

Permissions_required:

Execute access.

size

public static int size(EntityListable el)
                throws AccessDeniedException

Get the size of the directory measured in the number of child entities that it contains.

Parameters:

el - The entity listable, for instance a directory or directory view.

Returns:

The number of child entities in the directory.

Throws:

AccessDeniedException - If the client does not have execute access to the directory.

Permissions_required:

Execute access.

putIfAbsentDirectory

public static <T extends DirectoryView> T putIfAbsentDirectory(T dv,
                                                               String name)
                                                    throws EntityFoundException,
                                                           IllegalArgumentException,
                                                           AccessDeniedException,
                                                           ReadOnlyException

Return a directory reference, creating the directory if it does not exist.

If the returned entity is ViewCapable, a view that inherits the directory view's filters is returned.

Parameters:

dv - The directory or directory view.

name - The name of the directory.

Returns:

The directory.

Throws:

EntityFoundException - If a non-directory entity with the same name already exists in the directory.

IllegalArgumentException - If the directory name is not valid.

AccessDeniedException - If the client does not have sufficient access rights to the directory.

ReadOnlyException - If the directory does not exist and this is called on a read only directory.

Permissions_required:

Execute access to the directory. Write access too if the requested directory has to be created.

putIfAbsentDirectory

public static <T extends DirectoryView> T putIfAbsentDirectory(T dv,
                                                               RelativeLocation location)
                                                    throws EntityFoundException,
                                                           IllegalArgumentException,
                                                           AccessDeniedException,
                                                           ReadOnlyException

Return a directory reference, creating the directory and all necessary parent directories if they does not exist.

If the returned entity is ViewCapable, a view that is identical (same filter instances) to the supplied directory view is returned.

Parameters:

dv - The directory or directory view.

location - The location of the directory relative to this directory.

Returns:

The requested directory.

Throws:

EntityFoundException - If an entity that cannot be dereferenced exists somewhere in the given location (i.e. a file in the path, a file with the same name as the new directory, etc.)

IllegalArgumentException - If the directory name is not valid.

AccessDeniedException - If the client does not have sufficient access rights to the directory.

ReadOnlyException - If the directory does not exist and this is called on a read only directory.

Permissions_required:

Execute access to all directories between dv (inclusive) and the requested directory. Write access to the parents of all directories that have to be created.

getIterator

public static Iterator<EntityView> getIterator(EntityListable el)
                                        throws AccessDeniedException

Create and return an Iterator for the directory.

If the directory is in a locking file system, it has to be locked for reading each time next or hasNext is called on the returned iterator.

Parameters:

el - The entity listable, for instance a directory or directory view.

Returns:

An iterator.

Throws:

AccessDeniedException - If the client does not have execute access to the directory.

Permissions_required:

Execute access.

getDepthFirstIterator

public static DepthFirstIterator<EntityView> getDepthFirstIterator(EntityListable el)

Create a depth-first iterator that will return all visible entities in a directory's subhierarchy. Entities in each sub directory will be returned in no special order.

If this is called with a directory or directory view argument, that will be returned as the last entity from the iterator.

If this is called with a directory view argument, all ViewCapable entities returned from the iterator will inherit the directory view's filters.

The iterator acquires locks on the directories it processes as it processes them. The entities returned from the iterator are not locked, however. For an iterator that locks entities it returns, see the classes in the org.entityfs.util.itr package.

EntityFS iterators are not thread safe. Don't use them concurrently from several threads without synchronizing access to them.

Parameters:

el - The entity listable, for instance a directory or directory view.

Returns:

A depth-first iterator.

Permissions_required:

Execute access to el and all visible subdirectories. Access controls are performed when using the returned iterator.

getLocationAwareDepthFirstIterator

public static DepthFirstIterator<EntityAndRelativeLocation<EntityView>> getLocationAwareDepthFirstIterator(EntityListable el)

Get a depth-first iterator that returns EntityAndRelativeLocation objects. The relative location of the returned objects is their entity's relative location to the root directory of the iteration.

The iterator acquires locks on the directories it processes as it processes them. The entities returned from the iterator are not locked, however. For an iterator that locks entities it returns, see the classes in the org.entityfs.util.itr package.

EntityFS iterators are not thread safe. Don't use them concurrently from several threads without synchronizing access to them.

Parameters:

el - The root directory of the iteration.

Returns:

A location-aware depth-first iterator.

Permissions_required:

Execute access to el and all visible subdirectories. Access controls are performed when using the returned iterator.

getDepthFirstIterator

public static DepthFirstIterator<EntityView> getDepthFirstIterator(EntityListable el,
                                                                   Filter<? super EntityView> filter)

Create a filtered depth-first iterator that will return all visible entities in an directory's subhierarchy that matches the given filter. Entities in each sub directory will be returned in no special order.

If this is called with a directory or directory view argument, that will be returned as the last entity from the iterator, if it passes the filter.

If this is called with a directory view argument, all ViewCapable entities returned from the iterator will inherit the directory view's filters.

This iterator will not visit sub directories that are made invisible by the supplied filter. For an iterator that only filters on the entities it returns, see the FilteringIterator.

The iterator acquires locks on the directories it processes as it processes them. The entities returned from the iterator are not locked, however. For an iterator that locks entities it returns, see the classes in the org.entityfs.util.itr package.

EntityFS iterators are not thread safe. Don't use them concurrently from several threads without synchronizing access to them.

Parameters:

el - The entity listable, for instance a directory or directory view.

filter - The filter. The filter is often of the type EntityFilter.

Returns:

A filtering depth-first iterator

See Also:

FilteringIterator

Permissions_required:

Execute access to el and all visible subdirectories. Access controls are performed when using the returned iterator.

getLocationAwareDepthFirstIterator

public static DepthFirstIterator<EntityAndRelativeLocation<EntityView>> getLocationAwareDepthFirstIterator(EntityListable el,
                                                                                                           Filter<? super EntityView> filter)

Get a depth-first iterator that returns EntityAndRelativeLocation objects. The relative location of the returned objects is their entity's relative location to the root directory of the iteration.

This iterator will not visit sub directories that are made invisible by the supplied filter. For an iterator that only filters on the entities it returns, see the FilteringIterator.

The iterator acquires locks on the directories it processes as it processes them. The entities returned from the iterator are not locked, however. For an iterator that locks entities it returns, see the classes in the org.entityfs.util.itr package.

EntityFS iterators are not thread safe. Don't use them concurrently from several threads without synchronizing access to them.

Parameters:

el - The root directory of the iteration.

filter - Only the entities that pass this filter will be returned from the iterator. If this is set to null, all entities under el are returned. The filter is often of the type EntityFilter.

Returns:

A location-aware depth-first iterator.

Permissions_required:

Execute access to el and all visible subdirectories. Access controls are performed when using the returned iterator.

getDepthLastIterator

public static DepthLastIterator<EntityView> getDepthLastIterator(EntityListable el)

Create a depth-last (breadth-first) iterator that will return all visible entities in a directory's subhierarchy. Entities in each sub directory will be returned in no special order.

If this is called with a directory or directory view argument, that will be returned as the first entity from the iterator.

If this is called with a directory view argument, all ViewCapable entities returned from the iterator will inherit the directory view's filters.

The iterator acquires locks on the directories it processes as it processes them. The entities returned from the iterator are not locked, however. For an iterator that locks entities it returns, see the classes in the org.entityfs.util.itr package.

This method should have been named getBreadthFirstIterator...

EntityFS iterators are not thread safe. Don't use them concurrently from several threads without synchronizing access to them.

Parameters:

el - The entity listable, for instance a directory or directory view.

Returns:

A depth-last (breadth-first) iterator.

Permissions_required:

Execute access to el and all subdirectories. Access controls are performed when using the returned iterator.

getLocationAwareDepthLastIterator

public static DepthLastIterator<EntityAndRelativeLocation<EntityView>> getLocationAwareDepthLastIterator(EntityListable el)

Get a depth-last (breadth-first) iterator that returns EntityAndRelativeLocation objects. The relative location of the returned objects is their entity's relative location to the root directory of the iteration.

The iterator acquires locks on the directories it processes as it processes them. The entities returned from the iterator are not locked, however. For an iterator that locks entities it returns, see the classes in the org.entityfs.util.itr package.

EntityFS iterators are not thread safe. Don't use them concurrently from several threads without synchronizing access to them.

Parameters:

el - The root directory of the iteration.

Returns:

A location-aware depth-last (breadth-first) iterator.

Permissions_required:

Execute access to el and all visible subdirectories. Access controls are performed when using the returned iterator.

getDepthLastIterator

public static DepthLastIterator<EntityView> getDepthLastIterator(EntityListable el,
                                                                 Filter<? super EntityView> filter)

Create a filtered depth-last (breadth-first) iterator that will return all visible entities in an directory's subhierarchy that matches the given filter. Entities in each sub directory will be returned in no special order.

If this is called with a directory or directory view argument, that will be returned as the first entity from the iterator, if it passes the filter.

If this is called with a directory view argument, all ViewCapable entities returned from the iterator will inherit the directory view's filters.

This iterator will not visit sub directories that are made invisible by the filter. For an iterator that only filters on the entities it returns, see the FilteringIterator.

The iterator acquires locks on the directories it processes as it processes them. The entities returned from the iterator are not locked, however. For an iterator that locks entities it returns, see the classes in the org.entityfs.util.itr package.

This method should have been named getBreadthFirstIterator...

EntityFS iterators are not thread safe. Don't use them concurrently from several threads without synchronizing access to them.

Parameters:

el - The entity listable, for instance a directory or directory view.

filter - The filter. The filter is often of the type EntityFilter.

Returns:

A filtered depth-last (breadth-first) iterator.

See Also:

FilteringIterator

Permissions_required:

Execute access to el and all visible subdirectories. Access controls are performed when using the returned iterator.

getLocationAwareDepthLastIterator

public static DepthLastIterator<EntityAndRelativeLocation<EntityView>> getLocationAwareDepthLastIterator(EntityListable el,
                                                                                                         Filter<? super EntityView> filter)

Get a depth-last (breadth-first) iterator that returns EntityAndRelativeLocation objects. The relative location of the returned objects is their entity's relative location to the root directory of the iteration.

This iterator will not visit sub directories that are made invisible by the supplied filter. For an iterator that only filters on the entities it returns, see the FilteringIterator.

The iterator acquires locks on the directories it processes as it processes them. The entities returned from the iterator are not locked, however. For an iterator that locks entities it returns, see the classes in the org.entityfs.util.itr package.

EntityFS iterators are not thread safe. Don't use them concurrently from several threads without synchronizing access to them.

Parameters:

el - The root directory of the iteration.

filter - Only the entities that pass this filter will be returned from the iterator. If this is set to null, all entities are returned. The filter is often of the type EntityFilter.

Returns:

A location-aware depth-last (breadth-first) iterator.

Permissions_required:

Execute access to el and all visible subdirectories. Access controls are performed when using the returned iterator.

newFile

public static EFile newFile(DirectoryView dv,
                            String name)
                     throws EntityFoundException,
                            IllegalArgumentException,
                            ReadOnlyException,
                            AccessDeniedException

Create a new, empty file. The created file may or may not be visible in the supplied directory view. It is created anyway.

Parameters:

dv - The directory or directory view

name - The file name.

Returns:

An empty file.

Throws:

EntityFoundException - If an entity with the same name already exists.

IllegalArgumentException - If the file name is invalid.

ReadOnlyException - If this is called on a read only directory.

AccessDeniedException - If the client does not have execute and write access to the directory.

Permissions_required:

Execute and write access.

newFile

public static EFile newFile(DirectoryView dv,
                            RelativeLocation rel)
                     throws EntityFoundException,
                            IllegalArgumentException,
                            ReadOnlyException,
                            AccessDeniedException

Create a new, empty file in a location relative to the base directory. Directories that don't exist up to the file's parent directory are created.

The created file may or may not be visible in the supplied directory view. It is created anyway.

Parameters:

dv - The base directory or directory view

rel - The file's location relative to the base directory.

Returns:

An empty file.

Throws:

EntityFoundException - If an entity with the same name already exists.

IllegalArgumentException - If the file name is invalid.

ReadOnlyException - If this is called on a read only directory.

AccessDeniedException - If the client does not have execute and write access to the directory.

Permissions_required:

Execute access to all directories between dv (inclusive) and the requested file. Write access to the parents of all entities that have to be created.

newTempFile

public static EFile newTempFile(DirectoryView dv,
                                String prefix,
                                String suffix)
                         throws IllegalArgumentException,
                                ReadOnlyException,
                                AccessDeniedException

Create a new, empty, temporary file and return a reference. The created file may or may not be visible in the supplied directory view. It is created anyway.

Parameters:

dv - The directory or directory view

prefix - The prefix string to be used in generating the file name. Must contain at least three characters.

suffix - The suffix string to be used in generating the file name. If set to null, the suffix .tmp will be used.

Returns:

An empty file.

Throws:

IllegalArgumentException - If the prefix contains fewer than three characters.

ReadOnlyException - If this is called on a read only directory.

AccessDeniedException - If the client does not have execute and write access to the directory.

Permissions_required:

Execute and write access.

newDirectory

public static <T extends DirectoryView> T newDirectory(T dv,
                                                       String name)
                                            throws EntityFoundException,
                                                   IllegalArgumentException,
                                                   ReadOnlyException,
                                                   AccessDeniedException

Create a new, empty directory and return a reference.

The created directory may or may not be visible in the supplied directory view. It is created anyway.

If this is called on a directory view, the returned directory view inherits the parent directory's filters.

Type Parameters:

T - The type of directory to create. (A directory or directory view.)

Parameters:

dv - The parent directory or directory view

name - The directory name.

Returns:

An empty directory.

Throws:

EntityFoundException - If an entity with the same name already exists.

IllegalArgumentException - If the name is not a valid directory name.

ReadOnlyException - If this is called on a read only directory.

AccessDeniedException - If the client does not have execute and write access to the directory.

See Also:

newDirectory(DirectoryView, RelativeLocation)

Permissions_required:

Execute and write access.

newDirectory

public static <T extends DirectoryView> T newDirectory(T dv,
                                                       RelativeLocation loc)
                                            throws EntityFoundException,
                                                   IllegalArgumentException,
                                                   ReadOnlyException,
                                                   AccessDeniedException

Create a new, empty directory and return a reference. Directories that don't exist up to the directory's parent directory are created.

The created directory may or may not be visible in the supplied directory view. It is created anyway.

If this is called on a directory view, the returned directory view inherits the parent directory's filters.

Type Parameters:

T - The type of directory to create. (A directory or directory view.)

Parameters:

dv - The base directory or directory view.

loc - The relative location of the new directory relative to the base directory.

Returns:

An empty directory.

Throws:

EntityFoundException - If an entity with the same name and location already exists.

IllegalArgumentException - If the directory name is invalid.

ReadOnlyException - If this is called on a read only directory.

AccessDeniedException - If the client does not have execute and write access to all required directories.

Since:

1.1

See Also:

newDirectory(DirectoryView, String)

Permissions_required:

Execute access to all existing directories traversed when searching for the parent of the new directory. Write access to all directories where a new child directories has to be created.

newTempDirectory

public static <T extends DirectoryView> T newTempDirectory(T dv,
                                                           String prefix,
                                                           String suffix)
                                                throws IllegalArgumentException,
                                                       ReadOnlyException,
                                                       AccessDeniedException

Create a new, empty, temporary directory and return a reference. The created directory may or may not be visible in the supplied directory view; it is created anyway.

If this is called on a directory view, the returned directory view inherits the parent directory's filters.

Parameters:

dv - The directory or directory view

prefix - The prefix string to be used in generating the file name. Must contain at least three characters.

suffix - The suffix string to be used in generating the file name. If set to null, the suffix .tmp will be used.

Returns:

An empty directory.

Throws:

IllegalArgumentException - If the prefix contains fewer than three characters.

ReadOnlyException - If this is called on a read only directory.

AccessDeniedException - If the client does not have execute and write access to the directory.

Permissions_required:

Execute and write access.

newViews

public static Collection<DirectoryView> newViews(Collection<? extends DirectoryView> dv,
                                                 Filter<? super EntityView> ef)

For all the directory views in the collection, create a new view with the given filter and return the new views in a collection.

Parameters:

dv - A collection of directories or directory views. If this parameter is null, the method returns null.

ef - The filter. The filter is often of the type EntityFilter.

Returns:

A collection of directory views or null.

Permissions_required:

None

getChildRelativeLocation

public static RelativeLocation getChildRelativeLocation(DirectoryView parent,
                                                        EntityView child)
                                                 throws NotAChildException,
                                                        AccessDeniedException

Get the relative location of a file versus a directory that must be a parent directory somewhere in the entity's hierarchy.

Parameters:

parent - The parent directory.

child - The child entity.

Returns:

The location of the child entity, relative to the parent directory.

Throws:

NotAChildException - If the directory view is not a parent directory somewhere in the child entity's hierarchy.

AccessDeniedException - If the client does not have execute access to a parent directory.

See Also:

Entities.getRelativeLocation(EntityView, EntityView)

Permissions_required:

Execute access to all directories between parent (inclusive) and child.

find

public static Set<FoundEntity> find(EntityListable dir,
                                    Filter<? super EntityView> filter)
                             throws AccessDeniedException

Find the entities in the directory hierarchy under dir that match the filter. The supplied filter is not used to select which directories to scan; all directories under dir are scanned.

The difference between this method and the findEntities(EntityListable, Filter) method is in the type of objects returned.

Parameters:

dir - The directory to start searching from.

filter - The filter to use to select the entities to return. The filter is often of the type EntityFilter.

Returns:

A set of FoundEntity objects representing the found entities. A FoundEntity object contains the found entity as well as its relative location from dir. If dir passes the filter, it is returned.

Throws:

AccessDeniedException - If the client does not have execute access to a parent directory.

Since:

1.1

See Also:

findEntities(EntityListable, Filter)

Permissions_required:

Execute access to dir and all of its subdirectories in addition to the access requirement of the filter that is used.

findEntities

public static Set<EntityView> findEntities(EntityListable dir,
                                           Filter<? super EntityView> filter)
                                    throws AccessDeniedException

Find the entities in the directory hierarchy under dir that match the filter. The supplied filter is not used to select which directories to scan; all directories under dir are scanned.

The difference between this method and the find(EntityListable, Filter) method is in the type of objects returned.

Parameters:

dir - The directory to start searching from. If dir passes the filter, it is returned.

filter - The filter to use to select the entities to return. The filter is often of the type EntityFilter.

Returns:

The set of found entities.

Throws:

AccessDeniedException - If the client does not have execute access to a parent directory.

Since:

1.1

See Also:

find(EntityListable, Filter)

Permissions_required:

Execute access to dir and all of its subdirectories in addition to the access requirement of the filter that is used.