org.entityfs.impl
Interface EntityDelegate

All Known Subinterfaces:

AttributesEntityDelegate<T>, DirectoryDelegate, FileDelegate, MetadataEnablingEntityDelegate, SymbolicLinkDelegate

All Known Implementing Classes:

AbstractDirectoryDelegateProxy, AbstractEntityDelegateImpl, AbstractEntityDelegateProxy, AbstractFileDelegateProxy, AbstractSymbolicLinkDelegateProxy, AttributesEnablingDirectoryDelegateProxy, AttributesEnablingFileDelegateProxy, DirectoryDelegateImpl, FileDelegateImpl, SymbolicLinkDelegateImpl, SymbolicLinkEnablingDirectoryDelegateProxy

public interface EntityDelegate

Entity delegates are EntityFS' mechanism of having an extensible entity implementation without having to modify the entity objects themselves. (Remember that since object identity is important for entities, they must not be proxied by, for instance, capability implementations.) The EntityImplementation implementations take care of implementing the entity aspects of each entity type, and they never have to be touched by capability providers, other than when they want to introduce entirely new entity types. Entity implementations delegate responsibility for the aspects closer to what the different entity types actually do (open a file, etc) to their chain of entity delegates. Capability providers extend the functionality of existing entity types by inserting new entity delegate implementations in the entity's delegate chain.

An entity delegate implementation is either the implementation of a delegate for a certain entity type, or a capability provider's implementation of extended functionality for an existing entity type. In the first case, the delegate implementation uses the entity's EntityAdapter to do its work, in the second case it mostly uses its proxied delegate, but it can also use entity adapters if the capability is such that it can make assumptions about the backend implementation. (Some capabilities require certain backend implementations.) The delegate also can make callbacks to the entity object that owns it, but they should only be made to methods that don't do any entity locking.

A capability that requires another capability to work can get that capability's implementation through the getDelegateOfTypeOrNull(Class) method. It is up to each capability implementation to decide which API it wants to publish to other capabilities.

The entity implementation takes care of (at least) the following before calling its delegate chain:

• Locking. (Delegates can safely assume that its parent entity is properly locked according to the file system's locking strategy when its methods are called.)
• Child entity bookkeeping (for directory entities).
• Access right control
• Keeping track of if the file system is read only. (No read / write delegate methods will ever be called for a read only file system.)
• Events
• Views

A delegate implementation is responsible for:

• Calling the backend implementation's EntityAdapter.

A delegate proxy is responsible for:

• Intercept calls to delegate methods to introduce capability behavior. It can use it's proxied delegate, delegates of other capabilities that it requires and, if if makes assumptions about the backend implementation, the entity's EntityAdapter to perform its work.

Since:

1.0

Author:

Karl Gustafsson

See Also:

FileSystemDelegate

In_jar:

entityfs-core

Method Summary

boolean	canRead() Check with the backend to see if this entity can be read.
boolean	canWrite() Check with the backend to see if this entity can be written to.
Set<EntityView>	copy(DirectoryImplementation targetDir, String targetName, boolean preserveAttrs, List<EntityAttributeSetter> asl, EntityLock[] setupLocks) Copy the entity.
void	copyAttributes(DirectoryImplementation targetParent, EntityImplementation target) Copy entity attributes from this entity to the target.
boolean	exists() Does the entity really exist in the backend? This is used by some EntityValidityControlStrategy:s.
EntityDelegate	getDelegateOfTypeOrNull(Class<? extends EntityDelegate> c) Get an instance of a specific delegate type from the chain of delegates.
EntityAdapter	getEntityAdapter() Get the underlying EntityAdapter.
FileSystemImplementation	getFileSystem() Get the file system that owns this delegate's entity.
long	getLastModified() Get the last time that the entity was modified.
String	getName() Get the entity's name.
EntityImplementation	getOwner() Get the owner of this delegate.
void	init() This method is called after the entire entity object has been fully created, but before it is published.
boolean	isReadOnly() Does the delegate or a delegate proxy make this entity read only?
void	rename(String oldName, DirectoryImplementation targetDir, String newName) Rename and/or move the entity.
void	setLastModified(long t) Set the time of last modification for the entity.
void	setOwner(EntityImplementation owner) This is set when the entity object is created.

Method Detail

getDelegateOfTypeOrNull

EntityDelegate getDelegateOfTypeOrNull(Class<? extends EntityDelegate> c)

Get an instance of a specific delegate type from the chain of delegates.

Parameters:

c - The delegate type.

Returns:

The delegate instance, or null if no such delegate can be found.

setOwner

void setOwner(EntityImplementation owner)

This is set when the entity object is created.

Parameters:

owner - The owning entity object.

See Also:

init()

getOwner

EntityImplementation getOwner()

Get the owner of this delegate.

Returns:

The delegate's owner.

getFileSystem

FileSystemImplementation getFileSystem()

Get the file system that owns this delegate's entity.

Returns:

The parent file system.

getEntityAdapter

EntityAdapter getEntityAdapter()

Get the underlying EntityAdapter. This should only be called by delegate proxies that introduce entirely new entity types.

Returns:

The adapter to the backend.

exists

boolean exists()

Does the entity really exist in the backend? This is used by some EntityValidityControlStrategy:s.

Returns:

true if the entity exists in the backend.

canRead

boolean canRead()

Check with the backend to see if this entity can be read.

Returns:

true if the backend can be read.

canWrite

boolean canWrite()

Check with the backend to see if this entity can be written to.

If isReadOnly() returns true, this method should always return false. (The opposite is not true, however.)

Returns:

true if the backend can be written to.

isReadOnly

boolean isReadOnly()

Does the delegate or a delegate proxy make this entity read only?

This method is invoked frequently and should execute fast. It is only invoked for read/write file systems.

Returns:

true if the delegate has made the entity read only.

getLastModified

long getLastModified()

Get the last time that the entity was modified.

Returns:

The last modification time.

setLastModified

void setLastModified(long t)

Set the time of last modification for the entity.

Parameters:

t - A time stamp.

rename

void rename(String oldName,
            DirectoryImplementation targetDir,
            String newName)
            throws FileSystemException

Rename and/or move the entity.

Parameters:

oldName - The old name,

targetDir - The new parent directory.

newName - The new name.

Throws:

FileSystemException - On errors.

copy

Set<EntityView> copy(DirectoryImplementation targetDir,
                     String targetName,
                     boolean preserveAttrs,
                     List<EntityAttributeSetter> asl,
                     EntityLock[] setupLocks)

Copy the entity. It is not verified that there does not already exist an entity at the target location.

Parameters:

targetDir - The target directory of the new entity. This directory may be in another file system.

targetName - The name of the new entity.

preserveAttrs - Should entity attributes be copied to the target entity?

asl - A list of EntityAttributeSetter:s that are run just after the target entity has been created, before the setupLocks are released. This may be null. This may only be non-null if preserveAttrs is true.

setupLocks - Exception to the rule that the delegate should not bother with locking. This is here so that the delegate can release locks used to set up the target entity before data is copied to it. This method is responsible for unlocking this lock regardless of whether it is successful or fails.

Returns:

All new entities that were created. (This may be more than one if, for instance, copying a file from a metadata-enabled file system to a metadata-unaware file system.) It is safe to assume that the objects in the returned Set are real entities, not views.

copyAttributes

void copyAttributes(DirectoryImplementation targetParent,
                    EntityImplementation target)

Copy entity attributes from this entity to the target.

Parameters:

targetParent - The parent directory of the target. This is null if target is a root directory of a file system. Otherwise it is locked for writing.

target - The target entity to copy attributes to. Locked for writing.

init

void init()

This method is called after the entire entity object has been fully created, but before it is published. It should contain initialization logic that requires a fully created entity object.

Implementations are required to call init on proxied delegates and on entity adapters.

getName

String getName()

Get the entity's name.

Returns:

The entity's name.