org.entityfs
Interface EntityHolder

All Superinterfaces:
Lockable, ReadLockable
All Known Subinterfaces:
Directory, DirectoryView, EntityAcceptingEntity<T>, EntityAcceptingEntityView<T>, EntityRepository
All Known Implementing Classes:
AggregatingEntityRepository, CompoundEntityHolder

public interface EntityHolder
extends ReadLockable

The EntityHolder is an interface that defines an object that can be used to retrieve entities by their names, such as a symbolic link or a Directory.

Objects implementing this interface can be used with some of the utility methods of Entities and Directories.

Since:
1.0
Author:
Karl Gustafsson

Method Summary
 boolean containsEntity(EntityView ent)
          Does this entity holder contain the supplied entity? If this is called on a symbolic link, it is checked if the link target is a directory and that directory contains the entity.
 boolean containsEntity(String name)
          Can an entity with the given name be retrieved from this object? If this is called on a symbolic link, it is checked if the link target is a directory and that directory contains an entity with the given name.
 EntityView getEntityOrNull(String name)
          Get the named entity.
 
Methods inherited from interface org.entityfs.lock.ReadLockable
getReadLock, isReadLockedByCurrentThread, lockForReading
 

Method Detail

containsEntity

boolean containsEntity(String name)
                       throws IllegalStateException,
                              NotADirectoryException,
                              CircularReferenceException
Can an entity with the given name be retrieved from this object? If this is called on a symbolic link, it is checked if the link target is a directory and that directory contains an entity with the given name.

Parameters:
name - The name of the entity.
Returns:
true if there is an entity with the given name referenced by this holder.
Throws:
IllegalStateException - If this is called on a disconnected view.
NotADirectoryException - If an entity in a symbolic link target path is not a directory or cannot be dereferenced to a directory.
CircularReferenceException - If symbolic link references are circular. For instance l1 -> l2, l2 -> l1.
Locks_required:
A read lock on this entity and, for symbolic links, read locks on all entities visited while dereferencing it.
Permissions_required:
Execute access to this entity and, for symbolic links, execute access to every entity visited while dereferencing it.

containsEntity

boolean containsEntity(EntityView ent)
                       throws IllegalStateException,
                              NotADirectoryException,
                              CircularReferenceException
Does this entity holder contain the supplied entity? If this is called on a symbolic link, it is checked if the link target is a directory and that directory contains the entity.

Parameters:
ent - The entity (or a view of it).
Returns:
true If the entity holder contains the supplied entity.
Throws:
IllegalStateException - If this is called on a disconnected view.
NotADirectoryException - If an entity in a symbolic link target path is not a directory or cannot be dereferenced to a directory.
CircularReferenceException - If symbolic link references are circular. For instance l1 -> l2, l2 -> l1.
Locks_required:
A read lock on this entity and, for symbolic links, read locks on all entities visited while dereferencing it.
Permissions_required:
Execute access to this entity and, for symbolic links, execute access to every entity visited while dereferencing it.

getEntityOrNull

EntityView getEntityOrNull(String name)
                           throws IllegalStateException,
                                  NotADirectoryException,
                                  CircularReferenceException
Get the named entity. For directories, this is an entity in the directory. For a symbolic link pointing to a directory, this is an entity in the target directory.

If this is called on a directory view, and the returned entity is ViewCapable, the returned entity view inherits the same view settings as the directory view (same filter instances).

If this is called on an EntityHolder that contains several entities with the same name, the implementation may choose how to deal with that. This can never happen for directories since entity names in a directory are required to be unique.

Parameters:
name - The name of the entity.
Returns:
An EntityView or null. If this method is called on a DirectoryView and the returned entity is ViewCapable , the returned object inherits the view settings of the parent. If the returned entity is a file, the returned object can be cast to an EFile, if it is a directory, it can be cast to a DirectoryView (or a Directory if this method is called on a Directory rather than a DirectoryView). The type of the returned object can be determined by calling its EntityView.getType() method or by using instanceof.
Throws:
IllegalStateException - If the view is disconnected.
NotADirectoryException - If an entity in the symbolic link target path is not a directory or cannot be dereferenced to a directory.
CircularReferenceException - If the symbolic link references are circular. For instance l1 -> l2, l2 -> l1.
Locks_required:
A read lock on this entity and, for symbolic links, read locks on all entities visited while dereferencing it.
Permissions_required:
Execute access to this entity and, for symbolic links, execute access to every entity visited while dereferencing it.