org.entityfs.util
Class Entities

java.lang.Object
  org.entityfs.util.Entities

public final class Entities
extends Object

Entities contains static methods for working with Entity:s and EntityView:s.

The Files and Directories utility classes contains utility methods that complement the 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:

Entity, EntityView, Files, Directories

In_jar:

entityfs-util

Method Summary

static boolean	canRead(EntityView ev) Can the application read from the supplied entity, given the right access rights and locks?
static boolean	canWrite(EntityView ev) Can the application write to the supplied entity, given the right access rights and locks?
static Collection<EntityView>	copy(Collection<? extends EntityView> c, EntityAcceptingEntityView<?> targetDir) Copy a collection of entities to a target directory.
static Collection<EntityView>	copy(Collection<? extends EntityView> c, EntityAcceptingEntityView<?> targetE, EntityCopySpecification spec) Copy a collection of entities to a target directory.
static Collection<? extends EntityView>	copy(EntityView ent, EntityAcceptingEntityView<?> targetDir) Copies the contents of the entity to a new entity in the target directory.
static Collection<? extends EntityView>	copy(EntityView ent, EntityAcceptingEntityView<?> targetDir, boolean preserveAttr) Copies the contents of the entity to a new entity in the target directory.
static Collection<? extends EntityView>	copy(EntityView ent, EntityAcceptingEntityView<?> targetDir, EntityCopySpecification spec) Copies the contents of the entity to an entity in the target directory.
static Collection<? extends EntityView>	copy(EntityView ent, EntityAcceptingEntityView<?> targetDir, String newName) Copies the contents of the entity to an entity with another name in the target directory.
static Collection<? extends EntityView>	copy(EntityView ent, EntityAcceptingEntityView<?> targetDir, String newName, boolean preserveAttr) Copies the contents of the entity to an entity with another name in the target directory.
static Collection<? extends EntityView>	copy(EntityView ent, EntityLocation<? extends EntityLocation<?>> el) Copies the contents of the entity to a new entity in a directory.
static void	copyAttributes(EntityView e1, EntityView e2) Copy attributes from e1 to e2.
static EFile	copyFileContents(NamedReadableFile f, EntityAcceptingEntityView<?> targetE) Copy the contents of the NamedReadableFile to a new file with the same name in the supplied EntityAcceptingEntityView (commonly a Directory).
static EFile	copyFileContents(ReadableFile f, EntityAcceptingEntityView<?> targetE, String targetName) Copy the contents of the ReadableFile to a new file in the supplied EntityAcceptingEntityView (commonly a Directory ).
static void	delete(EntityView ent) Delete the entity.
static void	deleteEntity(EntityView ent) This methods does the same as the delete(EntityView).
static void	deleteRecursively(EntityView ent) Delete an entity recursively.
static void	deleteRecursively(EntityView ent, boolean deleteRoot) Delete an entity recursively.
static AbsoluteLocation	getAbsoluteLocation(EntityView ev) Get the absolute location of an entity.
static AbsoluteLocation	getCanonicalLocation(EntityView ent) Return the canonical location for the entity.
static long	getLastModified(EntityView ev) Get the last modification time of an entity.
static String	getName(Named n) Get the entity's name.
static Directory	getParent(Entity ent) Get the entity's parent directory.
static DirectoryView	getParent(EntityView ev) Get the entity's parent directory.
static RelativeLocation	getRelativeLocation(EntityView e1, EntityView e2) Get the location of e1, relative to e2.
static Pair<List<EntityView>>	getSmallestDifferentHierarchies(Entity e1, Entity e2) Get the smallest possible entity hierarchy with a common root entity for the two entities.
static <T extends EntityView> T	getValidEntity(T ent) Get a valid entity object for the same absolute location in the file system as the supplied entity.
static EntityView	getValidEntityOrNull(EntityView ev, boolean mustBeOfSameType) Get a valid entity object for the same absolute location in the file system as the supplied entity.
static boolean	isDeleted(EntityView ev) Is the entity deleted?
static boolean	isValid(EntityView ev) Is the entity valid? Deleting an entity invalidates the entity object.
static List<EntityLock>	lockHierarchies(Pair<? extends List<? extends EntityView>> h, Collection<? extends EntityView> entitiesToWriteLock) Lock the two hierarchies sharing a root element top-down.
static <T extends EntityView> T	move(T ent, EntityAcceptingEntityView<?> target) Move the entity to a new directory in the same file system.
static <T extends EntityView> T	move(T ent, EntityLocation<?> to) Move the entity to the directory referenced by the entity location in the same file system.
static <T extends EntityView> T	rename(T ent, EntityAcceptingEntityView<?> target, EntityRenameSpecification spec) Move and/or rename the entity using the supplied settings.
static <T extends EntityView> T	rename(T ent, EntityAcceptingEntityView<?> target, String newName) Rename the entity and move it to a new directory in the same file system.
static <T extends EntityView> T	rename(T ent, EntityLocation<?> to) Rename and/or move the entity to the target location.
static <T extends EntityView> T	rename(T ent, String newName) Rename the entity.
static <T extends EntityView> T	replace(EntityView e1, T e2) Replace the entity e1 with the entity e2.
static <T extends EntityView> T	setLastModified(T ev, long t) Set the last modification time of an entity.
static <T extends EntityView> T	touch(T ev) Touch the entity.

Methods inherited from class java.lang.Object

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

Method Detail

isValid

public static boolean isValid(EntityView ev)

Is the entity valid? Deleting an entity invalidates the entity object.

Parameters:

ev - The entity to check.

Returns:

true if the entity is valid, false if it is invalid.

See Also:

EntityView.isValid(), isDeleted(EntityView)

Permissions_required:

None

isDeleted

public static boolean isDeleted(EntityView ev)

Is the entity deleted?

Parameters:

ev - The entity to check.

Returns:

true if the entity is deleted

See Also:

Deletable.isDeleted(), isValid(EntityView)

Permissions_required:

None

canRead

public static boolean canRead(EntityView ev)

Can the application read from the supplied entity, given the right access rights and locks?

Parameters:

ev - The entity to investigate. The entity is temporarily locked for reading by the method.

Returns:

true if the application can read from the entity

Permissions_required:

Read access.

canWrite

public static boolean canWrite(EntityView ev)

Can the application write to the supplied entity, given the right access rights and locks?

Parameters:

ev - The entity to investigate. The entity is temporarily locked for reading by the method.

Returns:

true if the application can write to the entity

Permissions_required:

Write access.

getSmallestDifferentHierarchies

public static Pair<List<EntityView>> getSmallestDifferentHierarchies(Entity e1,
                                                                     Entity e2)

Get the smallest possible entity hierarchy with a common root entity for the two entities.

The returned hierarchies may not be valid by the time this method returns since no entities are locked; another thread might have moved entities around. The client has to verify that the hierarchies are still valid before using them.

Parameters:

e1 - An entity.

e2 - Another entity.

Returns:

A pair of two lists. Each list starts with the common root entity as the first element. The last entity in the first list is e1 and the last entity in the second list is e2. The other entities in the lists are parent entities of e1 and e2, respectively.

See Also:

lockHierarchies(Pair, Collection)

Permissions_required:

Execute access to all directories visited while establishing the hierarchies.

lockHierarchies

public static List<EntityLock> lockHierarchies(Pair<? extends List<? extends EntityView>> h,
                                               Collection<? extends EntityView> entitiesToWriteLock)

Lock the two hierarchies sharing a root element top-down.

Parameters:

h - A Pair of entity hierarchies sharing the same root entity. (The first entity returned from each collection.)

entitiesToWriteLock - A collection of entities that should be locked for writing. All other entities are locked for reading. The collection can be null if all entities should be locked for reading.

Returns:

The list of locks, or null any of the hierarchies are invalid.

See Also:

getSmallestDifferentHierarchies(Entity, Entity)

Permissions_required:

None

move

public static <T extends EntityView> T move(T ent,
                                            EntityAcceptingEntityView<?> target)
                                 throws EntityFoundException,
                                        EntityNotFoundException,
                                        NotADirectoryException,
                                        AccessDeniedException,
                                        ReadOnlyException

Move the entity to a new directory in the same file system.

If the entity supports some ECEntityAttributes capability, the entities attributes are also moved.

Parameters:

ent - The entity to move.

target - A directory or an entity that can be dereferenced to a directory.

Returns:

ent

Throws:

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

NotADirectoryException - If the target entity is not a directory and references an entity that is not a directory.

EntityNotFoundException - If the target entity is not a directory and does not reference an entity at all.

AccessDeniedException - If the caller does not have sufficient access rights.

ReadOnlyException - If the target directory is read only.

See Also:

EntityView.rename(DirectoryView, String), move(EntityView, EntityLocation), rename(EntityView, EntityAcceptingEntityView, String), rename(EntityView, EntityAcceptingEntityView, EntityRenameSpecification)

Permissions_required:

Write access to the entity and its parent directory. Write and execute access to the target directory. If the target is a symbolic link, execute access to all entities visited while dereferencing the link target.

move

public static <T extends EntityView> T move(T ent,
                                            EntityLocation<?> to)
                                 throws EntityFoundException,
                                        EntityNotFoundException,
                                        NotADirectoryException,
                                        AccessDeniedException,
                                        ReadOnlyException

Move the entity to the directory referenced by the entity location in the same file system. If the location is a relative entity location, the target location is relative to the parent directory's location.

If the entity supports some ECEntityAttributes capability, the entities attributes are also moved.

Parameters:

ent - The entity to move.

to - The target location.

Returns:

ent

Throws:

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

NotADirectoryException - If the target entity is not a directory and does not reference an entity that is a directory.

EntityNotFoundException - If the target directory does not exist.

AccessDeniedException - If the caller does not have sufficient access rights.

ReadOnlyException - If the target directory is read only.

See Also:

move(EntityView, EntityAcceptingEntityView), rename(EntityView, EntityLocation), rename(EntityView, EntityAcceptingEntityView, EntityRenameSpecification)

Permissions_required:

Write access to the entity and its parent directory. Write and execute access to the target directory. Execute access to all directories needed to find the target. If the target is a symbolic link, execute access to all entities visited while dereferencing the link target.

rename

public static <T extends EntityView> T rename(T ent,
                                              EntityLocation<?> to)
                                   throws EntityFoundException,
                                          EntityNotFoundException,
                                          NotADirectoryException,
                                          AccessDeniedException,
                                          ReadOnlyException

Rename and/or move the entity to the target location. If the target location is a relative entity location, the target location is relative to the parent directory's location.

If the entity supports some ECEntityAttributes capability, the entities attributes are also moved.

Parameters:

ent - The entity to rename.

to - The new location. If the location is a RelativeLocation , it is taken to be relative to the entity's current parent directory.

Returns:

ent

Throws:

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

NotADirectoryException - If the target entity is not a directory and does not reference an entity that is a directory.

EntityNotFoundException - If the target directory does not exist.

AccessDeniedException - If the caller does not have sufficient access rights.

ReadOnlyException - If the target directory is read only.

See Also:

move(EntityView, EntityLocation), rename(EntityView, String), rename(EntityView, EntityAcceptingEntityView, String), rename(EntityView, EntityAcceptingEntityView, EntityRenameSpecification)

Permissions_required:

Write access to the entity and its parent directory. Write and execute access to the target directory. Execute access to all directories needed to find the target. If the target is a symbolic link, execute access to all entities visited while dereferencing the link target.

rename

public static <T extends EntityView> T rename(T ent,
                                              String newName)
                                   throws AccessDeniedException,
                                          ReadOnlyException

Rename the entity.

If the entity supports some ECEntityAttributes capability, the entities attributes are also moved.

Parameters:

ent - The entity to rename.

newName - The new name.

Returns:

ent

Throws:

AccessDeniedException - If the caller does not have sufficient access rights.

ReadOnlyException - If the entity is read only.

See Also:

rename(EntityView, EntityLocation), rename(EntityView, EntityAcceptingEntityView, EntityRenameSpecification)

Permissions_required:

Write access to the entity. Write and execute access to its parent directory.

rename

public static <T extends EntityView> T rename(T ent,
                                              EntityAcceptingEntityView<?> target,
                                              String newName)
                                   throws EntityFoundException,
                                          NotADirectoryException,
                                          EntityNotFoundException,
                                          AccessDeniedException,
                                          ReadOnlyException

Rename the entity and move it to a new directory in the same file system.

If the entity supports some ECEntityAttributes capability, the entities attributes are also moved.

Parameters:

ent - The entity to move and rename.

target - A directory or an entity that can be dereferenced to a directory.

newName - The new name.

Returns:

ent

Throws:

EntityFoundException - If an entity with the new name already exists in the target directory.

NotADirectoryException - If the target entity is not a directory and references an entity that is not a directory.

EntityNotFoundException - If the target entity is not a directory and does not reference an entity at all.

AccessDeniedException - If the caller does not have sufficient access rights.

ReadOnlyException - If the target directory is read only.

See Also:

move(EntityView, EntityAcceptingEntityView), rename(EntityView, EntityLocation), rename(EntityView, String), rename(EntityView, EntityAcceptingEntityView, EntityRenameSpecification)

Permissions_required:

Write access to the entity and its parent directory. Write and execute access to the target directory. If the target is a symbolic link, execute access to all entities visited while dereferencing the link target.

rename

public static <T extends EntityView> T rename(T ent,
                                              EntityAcceptingEntityView<?> target,
                                              EntityRenameSpecification spec)
                                   throws EntityFoundException,
                                          NotADirectoryException,
                                          EntityNotFoundException,
                                          AccessDeniedException,
                                          ReadOnlyException

Move and/or rename the entity using the supplied settings.

If the entity supports some ECEntityAttributes capability, the entities attributes are also moved.

Parameters:

ent - The entity to move and/or rename.

target - A directory or an entity that can be dereferenced to a directory.

spec - Settings for the move and/or rename operation.

Returns:

ent

Throws:

EntityFoundException - If an entity with the new name already exists in the target directory.

NotADirectoryException - If the target entity is not a directory and references an entity that is not a directory.

EntityNotFoundException - If the target entity is not a directory and does not reference an entity at all.

AccessDeniedException - If the caller does not have sufficient access rights.

ReadOnlyException - If the target directory is read only.

See Also:

move(EntityView, EntityAcceptingEntityView), rename(EntityView, EntityLocation), rename(EntityView, String), rename(EntityView, EntityAcceptingEntityView, String)

Permissions_required:

Write access to the entity and its parent directory. Write and execute access to the target directory. If the target is a symbolic link, execute access to all entities visited while dereferencing the link target.

copy

public static Collection<? extends EntityView> copy(EntityView ent,
                                                    EntityLocation<? extends EntityLocation<?>> el)
                                             throws EntityNotFoundException,
                                                    EntityFoundException,
                                                    ReadOnlyException,
                                                    AccessDeniedException,
                                                    UncheckedInterruptedException

Copies the contents of the entity to a new entity in a directory.

If the entity supports some ECEntityAttributes capability, those attributes are not copied.

Parameters:

el - The location of the target directory. If the target is a RelativeLocation, it is taken to be relative to the source entity's parent directory, unless the source entity is the root directory.

Returns:

A collection of new entities, see EntityView.copy(DirectoryView, String, EntityLock[]).

Throws:

EntityNotFoundException - If a directory or an entity that might reference a directory cannot be found at the target location.

EntityFoundException - If there already is an entity with the same name as the entity to copy in the target directory.

ReadOnlyException - If the target directory is read only.

AccessDeniedException - If the calling thread has insufficient access rights.

UncheckedInterruptionException - May be thrown if the copy operation is interrupted. (It is up to the file system implementation to honor this.)

UncheckedInterruptedException

See Also:

copy(EntityView, EntityAcceptingEntityView), copy(EntityView, EntityAcceptingEntityView, String), copy(EntityView, EntityAcceptingEntityView, EntityCopySpecification), copyFileContents(ReadableFile, EntityAcceptingEntityView, String)

Permissions_required:

Read access to the entity. Write and execute access to the target directory. Execute access to all directories necessary to find the target. If the target is a symbolic link, execute access to all entities visited while dereferencing it.

copy

public static Collection<? extends EntityView> copy(EntityView ent,
                                                    EntityAcceptingEntityView<?> targetDir)
                                             throws EntityFoundException,
                                                    EntityNotFoundException,
                                                    NotADirectoryException,
                                                    ReadOnlyException,
                                                    AccessDeniedException,
                                                    UncheckedInterruptedException

Copies the contents of the entity to a new entity in the target directory. The target directory may be in another file system.

If the entity supports some ECEntityAttributes capability, those attributes are not copied.

Parameters:

ent - The entity to copy.

targetDir - The target directory or an entity that can be dereferenced to a target directory. May be in another file system.

Returns:

A collection of new entities, see EntityView.copy(DirectoryView, String, EntityLock[]).

Throws:

EntityFoundException - If there already is an entity with the same name in the target directory.

NotADirectoryException - If the target entity is not a directory and does not reference an entity that is a directory.

EntityNotFoundException - If the target entity is not a directory and does not reference an entity at all.

UncheckedInterruptionException - May be thrown if the copy operation is interrupted. (It is up to the file system implementation to honor this.)

AccessDeniedException - If the calling thread has insufficient access rights.

ReadOnlyException - If the target directory is read only.

UncheckedInterruptedException

See Also:

copy(EntityView, EntityLocation), copy(EntityView, EntityAcceptingEntityView, String), copy(EntityView, EntityAcceptingEntityView, EntityCopySpecification), copyFileContents(ReadableFile, EntityAcceptingEntityView, String)

Permissions_required:

Read access to the entity. Write and execute access to the target directory. If the target is a symbolic link, execute access to all entities visited while dereferencing it., Read access to the entity. Write and execute access to the target directory. If the target is a symbolic link, execute access to all entities visited while dereferencing it.

copy

public static Collection<? extends EntityView> copy(EntityView ent,
                                                    EntityAcceptingEntityView<?> targetDir,
                                                    boolean preserveAttr)
                                             throws EntityFoundException,
                                                    EntityNotFoundException,
                                                    NotADirectoryException,
                                                    ReadOnlyException,
                                                    AccessDeniedException,
                                                    UncheckedInterruptedException

Copies the contents of the entity to a new entity in the target directory. The target directory may be in another file system.

If the entity supports some ECEntityAttributes capability, those attributes are copied if preserveAttr is set to true.

Parameters:

ent - The entity to copy.

targetDir - The target directory or an entity that can be dereferenced to a target directory. May be in another file system.

preserveAttr - Should entity attributes such as the last modification time be copied to the target entity?

Returns:

A collection of new entities, see EntityView.copy(DirectoryView, String, EntityLock[]).

Throws:

EntityFoundException - If there already is an entity with the same name in the target directory.

NotADirectoryException - If the target entity is not a directory and does not reference an entity that is a directory.

EntityNotFoundException - If the target entity is not a directory and does not reference an entity at all.

UncheckedInterruptionException - May be thrown if the copy operation is interrupted. (It is up to the file system implementation to honor this.)

AccessDeniedException - If the calling thread has insufficient access rights.

ReadOnlyException - If the target directory is read only.

UncheckedInterruptedException

See Also:

copy(EntityView, EntityLocation), copy(EntityView, EntityAcceptingEntityView, String), copy(EntityView, EntityAcceptingEntityView, EntityCopySpecification), copyFileContents(ReadableFile, EntityAcceptingEntityView, String)

Permissions_required:

Read access to the entity. Write and execute access to the target directory. If the target is a symbolic link, execute access to all entities visited while dereferencing it., Read access to the entity. Write and execute access to the target directory. If the target is a symbolic link, execute access to all entities visited while dereferencing it.

copy

public static Collection<? extends EntityView> copy(EntityView ent,
                                                    EntityAcceptingEntityView<?> targetDir,
                                                    String newName)
                                             throws EntityFoundException,
                                                    EntityNotFoundException,
                                                    NotADirectoryException,
                                                    ReadOnlyException,
                                                    AccessDeniedException,
                                                    UncheckedInterruptedException

Copies the contents of the entity to an entity with another name in the target directory. The target directory may be in another file system.

If the entity supports some ECEntityAttributes capability, those attributes are not copied.

Parameters:

ent - The entity to copy.

targetDir - The target directory or an entity that can be dereferenced to a target directory. May be in another file system.

newName - The name of the target entity.

Returns:

A collection of new entities, see EntityView.copy(DirectoryView, String, EntityLock[]).

Throws:

EntityFoundException - If there already is an entity with the same name as the target.

NotADirectoryException - If the target entity is not a directory and does not reference an entity that is a directory.

EntityNotFoundException - If the target entity is not a directory and does not reference an entity at all.

UncheckedInterruptionException - May be thrown if the copy operation is interrupted. (It is up to the file system implementation to honor this.)

AccessDeniedException - If the calling thread has insufficient access rights.

ReadOnlyException - If the target directory is read only.

UncheckedInterruptedException

See Also:

copy(EntityView, EntityLocation), copy(EntityView, EntityAcceptingEntityView, String), copy(EntityView, EntityAcceptingEntityView, EntityCopySpecification), copyFileContents(ReadableFile, EntityAcceptingEntityView, String)

Permissions_required:

Read access to the entity. Write and execute access to the target directory. If the target is a symbolic link, execute access to all entities visited while dereferencing it.

copy

public static Collection<? extends EntityView> copy(EntityView ent,
                                                    EntityAcceptingEntityView<?> targetDir,
                                                    String newName,
                                                    boolean preserveAttr)
                                             throws EntityFoundException,
                                                    EntityNotFoundException,
                                                    NotADirectoryException,
                                                    ReadOnlyException,
                                                    AccessDeniedException,
                                                    UncheckedInterruptedException

Copies the contents of the entity to an entity with another name in the target directory. The target directory may be in another file system.

If the entity supports some ECEntityAttributes capability, those attributes are copied if preserveAttr is set to true.

Parameters:

ent - The entity to copy.

targetDir - The target directory or an entity that can be dereferenced to a target directory. May be in another file system.

newName - The name of the target entity.

preserveAttr - Should entity attributes such as the last modification time be copied to the target?

Returns:

A collection of new entities, see EntityView.copy(DirectoryView, String, EntityLock[]).

Throws:

EntityFoundException - If there already is an entity with the same name as the target.

NotADirectoryException - If the target entity is not a directory and does not reference an entity that is a directory.

EntityNotFoundException - If the target entity is not a directory and does not reference an entity at all.

UncheckedInterruptionException - May be thrown if the copy operation is interrupted. (It is up to the file system implementation to honor this.)

AccessDeniedException - If the calling thread has insufficient access rights.

ReadOnlyException - If the target directory is read only.

UncheckedInterruptedException

See Also:

copy(EntityView, EntityLocation), copy(EntityView, EntityAcceptingEntityView, String), copy(EntityView, EntityAcceptingEntityView, EntityCopySpecification), copyFileContents(ReadableFile, EntityAcceptingEntityView, String)

Permissions_required:

Read access to the entity. Write and execute access to the target directory. If the target is a symbolic link, execute access to all entities visited while dereferencing it.

copy

public static Collection<? extends EntityView> copy(EntityView ent,
                                                    EntityAcceptingEntityView<?> targetDir,
                                                    EntityCopySpecification spec)
                                             throws EntityFoundException,
                                                    EntityNotFoundException,
                                                    NotADirectoryException,
                                                    ReadOnlyException,
                                                    AccessDeniedException,
                                                    UncheckedInterruptedException

Copies the contents of the entity to an entity in the target directory. The supplied EntityCopySpecification object determines the settings for the copy operation.

The target directory may be in another file system.

Parameters:

ent - The entity to copy.

targetDir - The target directory or an entity that can be dereferenced to a target directory. May be in another file system.

spec - Settings for the copy operation.

Returns:

A collection of new entities, see EntityView.copy(DirectoryView, String, EntityLock[]). If an overwrite strategy that doesn't overwrite existing entities and doesn't throw an exception is used, and there is already an entity on the target location, the returned collection contains that entity as its single element.

Throws:

EntityFoundException - If there already is an entity with the same name as the target and that entity cannot be overwritten.

NotADirectoryException - If the target entity is not a directory and does not reference an entity that is a directory.

EntityNotFoundException - If the target entity is not a directory and does not reference an entity at all.

UncheckedInterruptionException - May be thrown if the copy operation is interrupted. (It is up to the file system implementation to honor this.)

AccessDeniedException - If the calling thread has insufficient access rights.

ReadOnlyException - If the target directory is read only.

UncheckedInterruptedException

Since:

1.1

Permissions_required:

Read access to the entity. Write and execute access to the target directory. If the target is a symbolic link, execute access to all entities visited while dereferencing it.

copy

public static Collection<EntityView> copy(Collection<? extends EntityView> c,
                                          EntityAcceptingEntityView<?> targetE,
                                          EntityCopySpecification spec)
                                   throws EntityFoundException,
                                          EntityNotFoundException,
                                          NotADirectoryException,
                                          ReadOnlyException,
                                          AccessDeniedException,
                                          UncheckedInterruptedException

Copy a collection of entities to a target directory. The supplied EntityCopySpecification object determines the settings for the copy operation. The name property of the specification object is ignored; the names of the copied entities are preserved in the new target directory.

The target directory may be in another file system.

Parameters:

c - The collection of entities to copy.

targetE - The target directory or an entity that can be dereferenced to a target directory.

spec - Settings for the copy operation. The name property of the settings is ignored; names are preserved in the target directory.

Returns:

A collection of new entities in the target directory. If an overwrite strategy that doesn't overwrite existing entities and doesn't throw an exception is used, the returned collection contains the entities that could not be overwritten, if any.

Throws:

EntityFoundException - If there already is an entity with the same name as a copied entity at the target and that entity cannot be overwritten.

NotADirectoryException - If the target entity is not a directory and does not reference an entity that is a directory.

EntityNotFoundException - If the target entity is not a directory and does not reference an entity at all.

UncheckedInterruptionException - May be thrown if the copy operation is interrupted. (It is up to the file system implementation to honor this.)

AccessDeniedException - If the calling thread has insufficient access rights.

ReadOnlyException - If the target directory is read only.

UncheckedInterruptedException

Since:

1.1.1

copy

public static Collection<EntityView> copy(Collection<? extends EntityView> c,
                                          EntityAcceptingEntityView<?> targetDir)
                                   throws EntityFoundException,
                                          EntityNotFoundException,
                                          NotADirectoryException,
                                          ReadOnlyException,
                                          AccessDeniedException,
                                          UncheckedInterruptedException

Copy a collection of entities to a target directory. The default EntityCopySpecification settings are used.

The target directory may be in another file system.

Parameters:

c - The collection of entities to copy.

targetDir - The target directory or an entity that can be dereferenced to a target directory.

Returns:

A collection of new entities in the target directory. If an overwrite strategy that doesn't overwrite existing entities and doesn't throw an exception is used, the returned collection contains the entities that could not be overwritten, if any.

Throws:

EntityFoundException - If there already is an entity with the same name as a copied entity at the target and that entity cannot be overwritten.

NotADirectoryException - If the target entity is not a directory and does not reference an entity that is a directory.

EntityNotFoundException - If the target entity is not a directory and does not reference an entity at all.

UncheckedInterruptionException - May be thrown if the copy operation is interrupted. (It is up to the file system implementation to honor this.)

AccessDeniedException - If the calling thread has insufficient access rights.

ReadOnlyException - If the target directory is read only.

UncheckedInterruptedException

Since:

1.1.1

copyFileContents

public static EFile copyFileContents(ReadableFile f,
                                     EntityAcceptingEntityView<?> targetE,
                                     String targetName)
                              throws EntityFoundException,
                                     EntityNotFoundException,
                                     NotADirectoryException,
                                     ReadOnlyException,
                                     AccessDeniedException,
                                     UncheckedInterruptedException,
                                     WrappedIOException

Copy the contents of the ReadableFile to a new file in the supplied EntityAcceptingEntityView (commonly a Directory ).

The difference between this method and the copy(EntityView, EntityAcceptingEntityView) methods is that this method only copies the file contents; it does not try to copy metadata and other extra information that may be associated with the source file.

If the entity supports some ECEntityAttributes capability, those attributes are not copied.

Parameters:

f - The file to copy.

targetE - The target directory or an entity that can be dereferenced to a target directory. May be in another file system.

targetName - The name of the file to create.

Returns:

The new file.

Throws:

EntityFoundException - If there already is an entity with the same name as the target.

NotADirectoryException - If the target entity is not a directory and references an entity that is not a directory.

EntityNotFoundException - If the target entity is not a directory and does not reference an entity at all.

UncheckedInterruptionException - May be thrown if the copy operation is interrupted. (It is up to the file system implementation to honor this.)

AccessDeniedException - If the calling thread has insufficient access rights.

ReadOnlyException - If the target directory is read only.

WrappedIOException - On I/O errors when copying the file.

UncheckedInterruptedException

See Also:

copyFileContents(NamedReadableFile, EntityAcceptingEntityView), copy(EntityView, EntityAcceptingEntityView)

Permissions_required:

Read access to the entity. Write and execute access to the target directory. If the target is a symbolic link, execute access to all entities visited while dereferencing it.

copyFileContents

public static EFile copyFileContents(NamedReadableFile f,
                                     EntityAcceptingEntityView<?> targetE)
                              throws EntityFoundException,
                                     NotADirectoryException,
                                     ReadOnlyException,
                                     AccessDeniedException,
                                     UncheckedInterruptedException,
                                     WrappedIOException

Copy the contents of the NamedReadableFile to a new file with the same name in the supplied EntityAcceptingEntityView (commonly a Directory).

The difference between this method and the copy(EntityView, EntityAcceptingEntityView) methods is that this method only copies the file contents; it does not try to copy metadata and other extra information that may be associated with the source file.

If the entity supports some ECEntityAttributes capability, those attributes are not copied.

Parameters:

f - The file to copy.

targetE - The target directory or an entity that can be dereferenced to a target directory. May be in another file system.

Returns:

The new file.

Throws:

EntityFoundException - If there already is an entity with the same name as the target.

NotADirectoryException - If the target entity is not a directory and references an entity that is not a directory.

EntityNotFoundException - If the target entity is not a directory and does not reference an entity at all.

UncheckedInterruptionException - May be thrown if the copy operation is interrupted. (It is up to the file system implementation to honor this.)

AccessDeniedException - If the calling thread has insufficient access rights.

ReadOnlyException - If the target directory is read only.

WrappedIOException - On I/O errors when copying the file.

UncheckedInterruptedException

See Also:

copyFileContents(ReadableFile, EntityAcceptingEntityView, String), copy(EntityView, EntityAcceptingEntityView)

Permissions_required:

Read access to the entity. Write and execute access to the target directory. If the target is a symbolic link, execute access to all entities visited while dereferencing it.

copyAttributes

public static void copyAttributes(EntityView e1,
                                  EntityView e2)
                           throws ReadOnlyException,
                                  AccessDeniedException,
                                  WrappedIOException

Copy attributes from e1 to e2.

For ordinary file systems, the attributes only consist of the entity's latest modification time. Capabilities may add more attributes.

Parameters:

e1 - The entity to copy attributes from

e2 - The entity to copy attributes to

Throws:

AccessDeniedException - If the calling thread has insufficient access rights.

ReadOnlyException - If the target directory is read only.

WrappedIOException - On I/O errors when copying the attributes.

See Also:

EntityView.copyAttributes(EntityView)

Permissions_required:

Read access to the source entity and its parent directory. Write access to the target entity and its parent directory.

deleteEntity

public static void deleteEntity(EntityView ent)
                         throws ReadOnlyException,
                                AccessDeniedException

This methods does the same as the delete(EntityView). When using EntityFS from JavaScript (from a Schmant script, for instance), the method name delete is reserved for JavaScript. Use this method instead.

Parameters:

ent - The entity to delete.

Throws:

AccessDeniedException - If the calling thread has insufficient access rights.

ReadOnlyException - If the target entity is read only.

See Also:

delete(EntityView)

Permissions_required:

Write access to the entity and its parent directory.

delete

public static void delete(EntityView ent)
                   throws ReadOnlyException,
                          AccessDeniedException

Delete the entity.

Parameters:

ent - The entity to delete.

Throws:

AccessDeniedException - If the calling thread has insufficient access rights.

ReadOnlyException - If the target entity is read only.

See Also:

Deletable.delete(), deleteEntity(EntityView)

Permissions_required:

Write access to the entity and its parent directory.

replace

public static <T extends EntityView> T replace(EntityView e1,
                                               T e2)
                                    throws ReadOnlyException,
                                           AccessDeniedException,
                                           DirectoryNotEmptyException

Replace the entity e1 with the entity e2. e1 is deleted and e2 is moved to e1's previous location. The entities must be in the same file system.

Parameters:

e1 - The entity to replace.

e2 - The entity to replace it with.

Returns:

e2

Throws:

AccessDeniedException - If the calling thread has insufficient access rights.

ReadOnlyException - If the target entity is read only.

DirectoryNotEmptyException - If the target is a non-empty directory

Permissions_required:

Write access to the two entities and their parent directories. Execute access to the target entity's parent directory.

getAbsoluteLocation

public static AbsoluteLocation getAbsoluteLocation(EntityView ev)
                                            throws AccessDeniedException

Get the absolute location of an entity.

Try to avoid working with absolute locations as much as possible, as constructing an absolute location will require read locking the entity's entire parent hierarchy up to the root directory.

Returns:

The entity's absolute location in the file system.

Throws:

AccessDeniedException - If the calling thread has insufficient access rights.

Permissions_required:

Read access to the entity. Execute access to all of its parent directories up to the file system root directory.

getCanonicalLocation

public static AbsoluteLocation getCanonicalLocation(EntityView ent)
                                             throws CircularReferenceException,
                                                    AccessDeniedException

Return the canonical location for the entity. For file systems that don't support any other entity-accepting entities than directories (don't support symbolic links), this always returns the entity's absolute location.

Parameters:

ent - The entity.

Returns:

The entity's canonical location.

Throws:

CircularReferenceException - If there is a circular reference in a chain of entity-accepting entities that have to be dereferenced in order to find the entity.

AccessDeniedException - If the calling thread does not have execute access to the entities necessary for creating the canonical location.

See Also:

FileSystems.getCanonicalLocation(org.entityfs.FileSystem, AbsoluteLocation), File.getCanonicalFile()

Permissions_required:

Read access to the entity. Execute access to all entities visited while creating the canonical location.

getRelativeLocation

public static RelativeLocation getRelativeLocation(EntityView e1,
                                                   EntityView e2)
                                            throws AccessDeniedException,
                                                   FileSystemException

Get the location of e1, relative to e2. Both entities must be in the same file system.

Parameters:

e1 - The first entity.

e2 - The second entity.

Returns:

The location of e1 relative to e2.

Throws:

AccessDeniedException - If the calling thread has insufficient access rights.

FileSystemException - If the entities are not in the same file system. (And on other errors.)

See Also:

Directories.getChildRelativeLocation(DirectoryView, EntityView)

Permissions_required:

Read access to the two entities. Execute access to all parent directories needed to establish the entities' relative location. (Possibly all of the entities' parent directories up to the file system root directory.)

getLastModified

public static long getLastModified(EntityView ev)
                            throws AccessDeniedException

Get the last modification time of an entity.

Parameters:

ev - The entity.

Returns:

The last modification time for the entity.

Throws:

AccessDeniedException - If the calling thread does not have read access to the entity.

See Also:

EntityView.getLastModified(), setLastModified(EntityView, long)

Permissions_required:

Read access.

setLastModified

public static <T extends EntityView> T setLastModified(T ev,
                                                       long t)
                                            throws AccessDeniedException,
                                                   ReadOnlyException

Set the last modification time of an entity.

Parameters:

ev - The entity.

t - The new last modification time for the entity.

Returns:

ev

Throws:

AccessDeniedException - If the calling thread does not have write access to the entity.

ReadOnlyException - If the file system is read only.

See Also:

EntityView.setLastModified(long), getLastModified(EntityView)

Permissions_required:

Write access.

touch

public static <T extends EntityView> T touch(T ev)
                                  throws ReadOnlyException,
                                         AccessDeniedException

Touch the entity.

Parameters:

ev - The entity.

Returns:

ev

Throws:

AccessDeniedException - If the calling thread does not have write access to the entity.

ReadOnlyException - If the entity is read only.

See Also:

EntityView.touch()

Permissions_required:

Write access.

getParent

public static DirectoryView getParent(EntityView ev)
                               throws AccessDeniedException

Get the entity's parent directory.

Parameters:

ev - The entity.

Returns:

The entity's parent directory, or null if the entity is the root directory.

Throws:

AccessDeniedException - If the calling thread does not have read access to the entity.

See Also:

EntityView.getParent(), getParent(Entity)

Permissions_required:

Read access.

getParent

public static Directory getParent(Entity ent)
                           throws AccessDeniedException

Get the entity's parent directory.

Since the entity supplied to this method is not a view, the method can convert the result to a Directory.

Parameters:

ent - The entity.

Returns:

The entity's parent directory, or null if the entity is the root directory.

Throws:

AccessDeniedException - If the calling thread does not have read access to the entity.

See Also:

EntityView.getParent(), getParent(EntityView)

Permissions_required:

Read access.

getName

public static String getName(Named n)
                      throws AccessDeniedException

Get the entity's name.

Parameters:

n - The entity

Returns:

The entity's name.

Throws:

AccessDeniedException - If the calling thread does not have read access to the entity.

See Also:

Named.getName()

Permissions_required:

Read access.

getValidEntityOrNull

public static EntityView getValidEntityOrNull(EntityView ev,
                                              boolean mustBeOfSameType)
                                       throws WrongEntityTypeException,
                                              AccessDeniedException

Get a valid entity object for the same absolute location in the file system as the supplied entity. If the supplied entity is invalid (deleted), this method tries to find a valid entity that occupies the same absolute location in the file system as the invalid entity did.

Parameters:

ev - The entity.

mustBeOfSameType - Require that the valid entity is of the same entity type as ev. If this is set and this method finds a valid entity of another type (file vs. directory, for instance), this method will throw a WrongEntityTypeException.

Returns:

If ev is still valid, it is returned. Otherwise this method returns the valid entity that occupies the same absolute location in the file system, if there is one. If no such entity can be found, null is returned.

Throws:

WrongEntityTypeException - If it is required that the found entity should be of the same type as ev, and a valid entity is found that is not, this exception is thrown.

AccessDeniedException

Since:

1.1

See Also:

getValidEntity(EntityView)

Permissions_required:

Read access to the entity and read and execute access to the entity's parent directories.

getValidEntity

public static <T extends EntityView> T getValidEntity(T ent)
                                           throws EntityNotFoundException,
                                                  WrongEntityTypeException,
                                                  AccessDeniedException

Get a valid entity object for the same absolute location in the file system as the supplied entity. If the supplied entity is invalid (deleted), this method tries to find a valid entity of the same type (file or directory) that occupies the same absolute location in the file system as the invalid entity did.

Type Parameters:

T - The type of the entity.

Parameters:

ent - The entity.

Returns:

A valid entity that occupies the same absolute location in the file system as ent. If ent still is valid, it is returned.

Throws:

EntityNotFoundException - If no valid entity occupies the same absolute location in the file system as ent did.

WrongEntityTypeException - If the valid entity with the same absolute location in the file system as ent is of another type (file vs. directory, for instance).

AccessDeniedException - If the calling thread does not have the required access rights.

Since:

1.1

See Also:

getValidEntityOrNull(EntityView, boolean)

Permissions_required:

Read access to the entity and read and execute access to the entity's parent directories.

deleteRecursively

public static void deleteRecursively(EntityView ent)
                              throws ReadOnlyException,
                                     AccessDeniedException,
                                     EntityFoundException

Delete an entity recursively. If the supplied entity is a directory, all of its child entities will be deleted too.

This method will lock entities and their parent entities for writing when it deletes the entities.

If this method throws an exception, some of the entities to delete may have been deleted before the exception is thrown.

Parameters:

ent - The entity to delete recursively.

Throws:

ReadOnlyException - If a read only entity is encountered.

AccessDeniedException - If the calling thread does not have the required permissions to delete an entity.

EntityFoundException - If this method tries to delete a non-empty directory. This may happen if the supplied entity is a DirectoryView that uses a Filter that hides at least one of its child entities.

Since:

1.1

See Also:

IteratorDeleter, deleteRecursively(EntityView, boolean)

Permissions_required:

Write access to all entities that should be deleted and their parent directories.

deleteRecursively

public static void deleteRecursively(EntityView ent,
                                     boolean deleteRoot)
                              throws ReadOnlyException,
                                     AccessDeniedException,
                                     EntityFoundException

Delete an entity recursively. If the supplied entity is a directory, all of its child entities will be deleted.

If the deleteRoot argument is set to false, the ent entity itself will not be deleted.

This method will lock entities and their parent entities for writing when it deletes the entities.

If this method throws an exception, some of the entities to delete may have been deleted before the exception is thrown.

Parameters:

ent - The entity to delete recursively.

Throws:

ReadOnlyException - If a read only entity is encountered.

AccessDeniedException - If the calling thread does not have the required permissions to delete an entity.

EntityFoundException - If this method tries to delete a non-empty directory. This may happen if the supplied entity is a DirectoryView that uses a Filter that hides at least one of its child entities.

Since:

1.1.2

See Also:

IteratorDeleter, deleteRecursively(EntityView)

Permissions_required:

Write access to all entities that should be deleted and their parent directories.