Overview  Package   Class  Tree  Deprecated  Index  Help 
 PREV CLASS   NEXT CLASS FRAMES    NO FRAMES    
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.entityfs
Interface EntityView

All Superinterfaces:
Comparable<EntityView>, Deletable, Lockable, Named, Observable, ReadLockable, ReadWriteLockable, WriteLockable
All Known Subinterfaces:
Directory, DirectoryImplementation, DirectoryView, DirectoryViewImplementation, EFile, EFileImplementation, Entity, EntityAcceptingEntity<T>, EntityAcceptingEntityImplementation<T>, EntityAcceptingEntityView<T>, EntityAcceptingEntityViewImplementation<T>, EntityImplementation, EntityViewImplementation, SymbolicLink, SymbolicLinkImplementation, SymbolicLinkView, SymbolicLinkViewImplementation
All Known Implementing Classes:
AbstractEntityAcceptingEntityImpl, AbstractEntityAcceptingEntityView, AbstractEntityImpl, AbstractEntityViewImpl, DirectoryImpl, DirectoryViewImpl, FileImpl, SymbolicLinkImpl, SymbolicLinkViewImpl
public interface EntityView
extends Comparable<EntityView>, Observable, ReadWriteLockable, Named, Deletable

This interface defines an abstract view of an entity. Views are supported by entities with child entities (entities inheriting EntityAcceptingEntity). The view uses a Filter instance for entities to decide which child entities that are visible. Views can also be nested; it is possible to create a view of a view.

Each entity class, Directory for instance, implement their corresponding view interface (DirectoryView), if they have one, so viewable entities are in practice views of themselves. Many entity methods work on views rather than entity objects.

All view objects are Observable for updates.

This interface inherits ReadWriteLockable. If that interface's lock methods are called on a view, the backing entity is locked. See Entity and FileSystem for more on locking.

EntityView:s (and hence all Entity objects) are Comparable based on their hashCode:s. This can be useful for implementing a locking strategy.

When the client is done with an entity view, it can be disconnect() :ed from the viewed entity or entity view. After that, all methods on the view will throw IllegalStateException:s when called.

The classes Entities and EntityViews contains static utility methods for working with entities and entity views.

Since:
1.0
Author:
Karl Gustafsson
See Also:
Entities, Filter
In_jar:
entityfs-core

Method Summary
 boolean canRead()
          Can the application read from the viewed entity, given appropriate access rights and locks?
 boolean canWrite()
          Can the application write to the viewed entity, given appropriate access rights and locks?
 Set<EntityView> copy(DirectoryView targetDir, String newName, boolean preserveAttrs, EntityLock... setupLocks)
          Copy the viewed entity to a new directory and possibly give the target another name.
 Set<EntityView> copy(DirectoryView targetDir, String newName, EntityLock... setupLocks)
          Deprecated. This method will be removed in the next release of EntityFS!
 void copyAttributes(EntityView target)
          Copy entity attributes from this entity to the target entity.
 void createLock(Object identifier)
          Create a lock in the viewed entity's EntityLockAdapter.
 void disconnect()
          Disconnect this view from its viewed entity or entity view.
<T extends EntityCapability>
T
getCapability(EntityCapabilityType<T> type)
          Get the capability for the entity.
 FileSystem getFileSystem()
          Get the FileSystem that the viewed entity belongs to.
 long getLastModified()
          Get the time of last modification of the viewed entity.
 DirectoryView getParent()
          Get the parent directory for this entity or for this entity view.
 EntityType getType()
          Get the entity's EntityType.
 EntityView getViewed()
          Get the next nested entity view or the entity itself if this is a view of an entity.
 Entity getViewedEntity()
          Get the viewed entity.
 boolean isConnected()
          Check if this view is connected with the viewed entity or with the next nested view.
 boolean isRootDirectory()
          Check if this is the file system's root directory or a view of the root directory.
 boolean isValid()
          Check if the entity or the viewed entity is still valid.
 EntityLock lock(Object identifier)
          Use the file system's LockAcquiringStrategy to acquire a reentrant lock on the entity.
 void rename(DirectoryView target, String name)
          Rename the entity and/or move it to another directory in the same file system.
 void setLastModified(long t)
          Set the last modification time of the viewed entity.
 boolean supportsCapability(EntityCapabilityType<?> type)
          Does this entity support the supplied capability type?
 void touch()
          Touch the viewed entity (updates its modification time).
 
Methods inherited from interface java.lang.Comparable
compareTo
 
Methods inherited from interface org.entityfs.event.Observable
addObserver, countObservers, deleteObserver, deleteObservers
 
Methods inherited from interface org.entityfs.Named
getName
 
Methods inherited from interface org.entityfs.lock.ReadLockable
getReadLock, isReadLockedByCurrentThread, lockForReading
 
Methods inherited from interface org.entityfs.Deletable
delete, isDeleted
 
Methods inherited from interface org.entityfs.lock.WriteLockable
getWriteLock, isWriteLockedByCurrentThread, lockForWriting
 

Method Detail

isRootDirectory

boolean isRootDirectory()
Check if this is the file system's root directory or a view of the root directory.

Returns:
true if this is this file system's root directory.
Locks_required:
none
Permissions_required:
none

getParent

DirectoryView getParent()
                        throws IllegalStateException
Get the parent directory for this entity or for this entity view. If this is called on an entity view, an identical view for the parent is returned (same Filter instances, same number of nested views). If this is called on an entity, the parent Directory instance is returned.

Returns:
If called on an entity, the entity's parent Directory. If called on an entity view, an identical view of the parent directory. If this is called on the root directory or on a view of the root directory, the method returns null.
Throws:
IllegalStateException - If the view is disconnected.
ReadLockRequiredException - If the client does not have a read lock for the viewed entity or for its parent.
Locks_required:
A read lock on the entity or on its parent directory.
Permissions_required:
none

disconnect

void disconnect()
                throws UnsupportedOperationException,
                       IllegalStateException
Disconnect this view from its viewed entity or entity view. Any subsequent calls to methods in this view will fail with IllegalStateException:s.

The reason for having a disconnect method is to have a simple method to call when a view is not needed anymore. Implementations are responsible for doing all the necessary cleanup, such as deregistering observers, JMX MBeans, etc.

Throws:
UnsupportedOperationException - If this method is called on an Entity.
IllegalStateException - If the view already is disconnected.
Locks_required:
none
Permissions_required:
none

isConnected

boolean isConnected()
Check if this view is connected with the viewed entity or with the next nested view.

Returns:
true if this view is connected or if this is called on an entity object, false otherwise.
Locks_required:
none
Permissions_required:
none

getFileSystem

FileSystem getFileSystem()
                         throws IllegalStateException
Get the FileSystem that the viewed entity belongs to.

Returns:
The FileSystem the viewed entity belongs to.
Throws:
IllegalStateException - If the view is disconnected.
Locks_required:
none
Permissions_required:
none

getType

EntityType getType()
                   throws IllegalStateException
Get the entity's EntityType.

Returns:
The entity's EntityType
Throws:
IllegalStateException - If the view is disconnected.
Locks_required:
none
Permissions_required:
none

getLastModified

long getLastModified()
                     throws IllegalStateException,
                            ReadLockRequiredException
Get the time of last modification of the viewed entity.

Returns:
The time of last modification of the viewed entity.
Throws:
IllegalStateException - If the view is disconnected.
ReadLockRequiredException - If the client does not have a read lock for the viewed entity.
Locks_required:
A read lock on this entity or on its parent directory.
Permissions_required:
none

setLastModified

void setLastModified(long t)
                     throws IllegalStateException,
                            WriteLockRequiredException,
                            ReadOnlyException
Set the last modification time of the viewed entity.

Parameters:
t - The new last modified time.
Throws:
IllegalStateException - If the view is disconnected.
WriteLockRequiredException - If the client does not have a write lock for the viewed entity.
ReadOnlyException - If the file system is read only.
Locks_required:
A write lock on this entity or on its parent directory.
Permissions_required:
Write access to this entity.

touch

void touch()
           throws IllegalStateException,
                  WriteLockRequiredException,
                  AccessDeniedException
Touch the viewed entity (updates its modification time).

Throws:
IllegalStateException - If the view is disconnected.
WriteLockRequiredException - If the client does not have a write lock for the viewed entity.
AccessDeniedException - If the client does not have write access to the entity.
Locks_required:
A write lock on the entity.
Permissions_required:
Write access to the entity.
Generates_events:
EntityModifiedEvent on this., ChildEntityModifiedEvent on this's parent.

canRead

boolean canRead()
                throws IllegalStateException,
                       ReadLockRequiredException,
                       AccessDeniedException
Can the application read from the viewed entity, given appropriate access rights and locks?

Returns:
true if the client can read from the entity, false otherwise.
Throws:
IllegalStateException - If the view is disconnected.
ReadLockRequiredException - If the client does not have a read lock for the viewed entity.
AccessDeniedException - If the client does not have read access to the entity.
Locks_required:
A read lock on the entity or on its parent directory.
Permissions_required:
Read access to the entity.

canWrite

boolean canWrite()
                 throws IllegalStateException,
                        ReadLockRequiredException,
                        AccessDeniedException
Can the application write to the viewed entity, given appropriate access rights and locks?

Returns:
true if the client can write to the entity, false otherwise.
Throws:
IllegalStateException - If the view is disconnected.
ReadLockRequiredException - If the client does not have a read lock for the viewed entity.
AccessDeniedException - If the client does not have write access to the entity.
Locks_required:
A read lock on the entity or on its parent directory.
Permissions_required:
Write access to the entity.

isValid

boolean isValid()
                throws IllegalStateException,
                       ReadLockRequiredException
Check if the entity or the viewed entity is still valid. An entity object becomes invalid when it has been deleted or when it has disappeared from the backing file system.

This method uses the file system's EntityValidityControlStrategy to control if the entity is still valid.

Returns:
true if the entity object is valid, false otherwise.
Throws:
IllegalStateException - If the view is disconnected.
ReadLockRequiredException - If the client does not have a read lock for the viewed entity.
See Also:
Deletable.isDeleted()
Locks_required:
A read lock on the entity or on its parent directory.
Permissions_required:
none

getViewed

EntityView getViewed()
                     throws IllegalStateException
Get the next nested entity view or the entity itself if this is a view of an entity.

Returns:
The viewed entity view. If this is called on an entity, it returns the entity.
Throws:
IllegalStateException - If the view is disconnected.
Locks_required:
none
Permissions_required:
none

getViewedEntity

Entity getViewedEntity()
                       throws IllegalStateException
Get the viewed entity.

Returns:
The viewed Entity. Always returns the viewed Entity, even if this view is nested.
Throws:
IllegalStateException - If the view, or any other view in the view nest chain is disconnected.
Locks_required:
none
Permissions_required:
none

lock

EntityLock lock(Object identifier)
                throws IllegalStateException
Use the file system's LockAcquiringStrategy to acquire a reentrant lock on the entity. This can be used instead of synchronized to get a lock for an entity using the same strategy as the other file system methods.

To avoid deadlocks, clients should use a consequent locking strategy for how custom locks relate to the standard read and write locks on an entity and to other custom locks.

This method always returns a lock for a valid identifier, even if the file system is not locking.

Parameters:
identifier - An identifier for the lock. Each different lock for an entity has an identifier that is unique for the entity. (A constant Object instance, for instance.)
Returns:
A locked reentrant lock, or null if no lock is defined for the identifier.
Throws:
IllegalStateException - If the view is disconnected.
Locks_required:
None
Permissions_required:
none

createLock

void createLock(Object identifier)
                throws IllegalStateException,
                       WriteLockRequiredException,
                       IllegalArgumentException
Create a lock in the viewed entity's EntityLockAdapter. After creating it, it can be locked by calling the lock(Object) method.

To create standalone locks (locks that are not tied to any specific entity), use the file system's EntityLockAdapter directly.

Parameters:
identifier -
Throws:
IllegalStateException
WriteLockRequiredException - If the client does not have a write lock for the viewed entity.
IllegalArgumentException - If there already is a lock defined for the same identifier.
Locks_required:
A write lock on the entity.
Permissions_required:
none

copy

@Deprecated
Set<EntityView> copy(DirectoryView targetDir,
                                String newName,
                                EntityLock... setupLocks)
                     throws EntityFoundException,
                            ReadOnlyException,
                            UncheckedInterruptedException,
                            LockRequiredException,
                            IllegalStateException,
                            AccessDeniedException
Deprecated. This method will be removed in the next release of EntityFS!

Copy the viewed entity to a new directory and possibly give the target another name. The target directory may be in another file system. If this is called on an entity view, an identical view of the new entity is returned (same Filter instances). If an entity view is copied is copied into a directory view, the both view's filters are combined in the returned view.

This method returns a list of entity view objects rather than just a single EntityView object. The reason for this is that the target file system may have different ideas about what constitutes an entity compared with the source file system. An entity in one file system might be three entities in another file system, or no entity at all. When copying within the same file system or between file systems with the same set of capabilities, the returned list always has one entity view in it.

This method does not copy directories recursively. To do that, use the IteratorCopier.

This method can release locks that are only necessary for setting up the target entity before data is copied to it. This may be the write lock for the target directory.

If the client wants that the target directory should still be locked after the method call, just increment the write lock's lock count by calling its lock() method before calling this method.

If the copied entity supports any ECEntityAttributes capability, its attributes are not copied by this method. (An entity's attributes is a property of its parent directory.)

Note: This method is deprecated and will be removed in a future release (pretty soon). Use copy(DirectoryView, String, boolean, EntityLock...) instead. This method does not copy any attributes to the target entity.

Parameters:
targetDir - A view of the target directory.
newName - The target entity's name.
setupLocks - Locks only necessary for setting up the target entity. They are unlocked before data is copied to the target entity. The method is guaranteed to release locks given here, even if it throws an exception.
Returns:
A collection of entities that were created as a result of the copy operation viewed through the same set of filters as this view. When copying within the same file system (or between file systems with the same set of capabilities), this list always contains just one entity view. If the new entity is invisible in the target directory view, the entity view object is returned anyway.
Throws:
EntityFoundException - If there already is an entity with the target name in the target directory.
ReadOnlyException - If the target directory is read only.
UncheckedInterruptedException - If the current thread is interrupted during the copy. It is up to the entity implementation to actually honor this. If it does, it clears the thread's interrupt flag before throwing the exception.
LockRequiredException - If the caller does not hold any one of the required locks.
IllegalStateException - If any of this or the target views are disconnected.
AccessDeniedException - If the client does not have read access to the source entity or write access to the target directory.
Locks_required:
A read lock on the entity and a write lock on the target directory.
Permissions_required:
Read access to the entity and write and execute access to the target directory.
Generates_events:
NewEntityEvent for all created entities., ChildEntityAddedEvent for targetDir., ChildEntityModifiedEvent for targetDir's parent.

copy

Set<EntityView> copy(DirectoryView targetDir,
                     String newName,
                     boolean preserveAttrs,
                     EntityLock... setupLocks)
                     throws EntityFoundException,
                            ReadOnlyException,
                            UncheckedInterruptedException,
                            LockRequiredException,
                            IllegalStateException,
                            AccessDeniedException
Copy the viewed entity to a new directory and possibly give the target another name. The target directory may be in another file system. If this is called on an entity view, an identical view of the new entity is returned (same Filter instances). If an entity view is copied is copied into a directory view, the both view's filters are combined in the returned view.

This method returns a list of entity view objects rather than just a single EntityView object. The reason for this is that the target file system may have different ideas about what constitutes an entity compared with the source file system. An entity in one file system might be three entities in another file system, or no entity at all. When copying within the same file system or between file systems with the same set of capabilities, the returned list always has one and only one entity view in it.

This method does not copy directories recursively. To do that, use the IteratorCopier.

This method can release locks that are only necessary for setting up the target entity before data is copied to it. This may be the write lock for the target directory and the read lock for the source entity's parent directory. See the setupLocks parameter.

If the copied entity supports any ECEntityAttributes capability, its attributes are copied by this method if the preserveAttrs parameter is set to true.

Parameters:
targetDir - A view of the target directory.
newName - The target entity's name.
preserveAttrs - Should attributes from the source entity be copied to the target entity? An example of an entity attribute is its latest modification time. Capabilities may add their own attributes; see the documentation for each capability for details.
setupLocks - Locks only necessary for setting up the target entity. They are unlocked before data is copied to the target entity. The method is guaranteed to release locks given here, even if it throws an exception. The read lock on the source parent directory and/or the write lock on the target directory can be supplied in this collection. If any or both of the locks are, they are unlocked before any file data is copied to the target entity.
Returns:
A collection of entities that were created as a result of the copy operation viewed through the same set of filters as this view. When copying within the same file system (or between file systems with the same set of capabilities), this list always contains just one entity view. If the new entity is invisible in the target directory view, the entity view object is returned anyway.
Throws:
EntityFoundException - If there already is an entity with the target name in the target directory.
ReadOnlyException - If the target directory is read only.
UncheckedInterruptedException - If the current thread is interrupted during the copy. It is up to the entity implementation to actually honor this. If it does, it clears the thread's interrupt flag before throwing the exception.
LockRequiredException - If the caller does not hold any one of the required locks.
IllegalStateException - If any of this or the target views are disconnected.
AccessDeniedException - If the client does not have read access to the source entity or write access to the target directory.
Locks_required:
A read lock on the entity, on its parent directory and a write lock on the target directory. The parent directory read lock can be supplied in the setupLocks parameter. In that case, it is released by this method before file data is copied.
Permissions_required:
Read access to the entity and write and execute access to the target directory.
Generates_events:
NewEntityEvent for all created entities., ChildEntityAddedEvent for targetDir., ChildEntityModifiedEvent for targetDir's parent.

copyAttributes

void copyAttributes(EntityView target)
                    throws ReadOnlyException,
                           LockRequiredException,
                           IllegalStateException,
                           AccessDeniedException
Copy entity attributes from this entity to the target entity. Only the attributes that are supported by the target entity are copied.

This method sets the latest modification time on the target entity to be the same as on this entity. Capability providers may provide their own attributes that are copied by this method. For instance, entity attribute capabilities copy their entity attributes, but metadata capabilities do not copy metadata to the target entity.

Parameters:
target - The entity to set the attributes on. Only the attributes supported by this entity are set.
Throws:
ReadOnlyException - If the target entity is read only.
LockRequiredException - If the caller does not have any of the required entity locks.
IllegalStateException - If this view or the target view is disconnected.
AccessDeniedException - If the caller does not have read access to this entity or its parent directory or write access to the target entity and its parent directory.
Locks_required:
A read lock on the entity, on its parent directory and a write lock on the target entity and its parent directory
Permissions_required:
Read access to the entity and its parent directory, read and write access to the target entity and write access to its parent directory.
Generates_events:
EntityModifiedEvent for target., ChildEntityModifiedEvent for target's parent directory.

rename

void rename(DirectoryView target,
            String name)
            throws EntityFoundException,
                   ReadOnlyException,
                   WriteLockRequiredException,
                   AccessDeniedException,
                   IllegalStateException
Rename the entity and/or move it to another directory in the same file system.

If the entity supports any ECEntityAttributes capability, its attributes are also moved.

Warning: this method does not verify that a directory is not moved to a sub directory of itself. That may give random errors, or worse: work.

Parameters:
target - The entity's new parent directory. It can be the same directory as the current parent directory, but not null. The target directory must be in the same file system as the entity.
name - The entity's new name. This might be the current name, but not null.
Throws:
EntityFoundException - If an entity with the same name already exists in the target directory.
ReadOnlyException - If the file system is read only.
WriteLockRequiredException - If the caller does not hold all required write locks.
AccessDeniedException - If the caller does not have write access to all required entities.
IllegalStateException - If any of this or the target views are disconnected.
Locks_required:
A write lock on the entity, on its parent directory and on the target directory.
Permissions_required:
Write access to the entity, to its parent directory and to the target directory.
Generates_events:
EntityRenamedEvent for this., EntityModifiedEvent for this's current parent directory., ChildEntityRenamedEvent for target if target is the same as the this's current parent directory., ChildEntityRemovedEvent for this's parent directory if it is different from target., ChildEntityAddedEvent for target if it is different from this's current parent directory., EntityModifiedEvent for target, if it is different from this's current parent directory (i.e. this event is only generated once for the parent directory if the entity is renamed)., ChildEntityModifiedEvent for this's parent directory., ChildEntityModifiedEvent for target's parent directory if it is different from this's current parent directory.

supportsCapability

boolean supportsCapability(EntityCapabilityType<?> type)
                           throws IllegalStateException
Does this entity support the supplied capability type?

Parameters:
type - The capability type.
Returns:
true if the entity supports the capability type.
Throws:
IllegalStateException - If any of this or the target views are disconnected.
See Also:
FileSystem.supportsCapabilityForEntity(EntityView, EntityCapabilityType), getCapability(EntityCapabilityType)
Locks_required:
none
Permissions_required:
none

getCapability

<T extends EntityCapability> T getCapability(EntityCapabilityType<T> type)
                                         throws UnsupportedCapabilityException,
                                                IllegalStateException
Get the capability for the entity.

Parameters:
type - The capability type.
Returns:
The capability object for the entity.
Throws:
UnsupportedCapabilityException - If the entity does not support the requested capability.
IllegalStateException - If any of this or the target views are disconnected.
See Also:
FileSystem.getCapabilityForEntity(EntityView, EntityCapabilityType), supportsCapability(EntityCapabilityType)
Locks_required:
none
Permissions_required:
none
Overview  Package   Class  Tree  Deprecated  Index  Help 
 PREV CLASS   NEXT CLASS FRAMES    NO FRAMES    
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD