org.entityfs.impl.impl
Class FileImpl

java.lang.Object
  org.entityfs.lock.AbstractLockable
      org.entityfs.impl.impl.AbstractEntityImpl
          org.entityfs.impl.impl.FileImpl

All Implemented Interfaces:

Comparable<EntityView>, Deletable, EFile, Entity, EntityView, Observable, EFileImplementation, EntityImplementation, EntityViewImplementation, Lockable, ReadLockable, ReadWriteLockable, WriteLockable, Named, NamedReadableFile, RandomAccessCloseObserver, RandomlyAccessibleFile, ReadableFile, ReadWritableFile, WritableFile

public class FileImpl
extends AbstractEntityImpl
implements EFileImplementation, RandomAccessCloseObserver

Constructor Summary

FileImpl(FileSystemImplementation fs, DirectoryImplementation parent, FileDelegate fd)

Method Summary

void	assertCanBeDeleted() Perform entity type-specific checks in addition to the checks in the delete method.
Set<EntityView>	copy(DirectoryView d, String targetName, boolean preserveAttrs, EntityLock... setupLocks) Copy the viewed entity to a new directory and possibly give the target another name.
long	copy(OutputStream os) Dump the file contents to the stream.
long	copy(WritableByteChannel c) Copy the file's contents to the WritableByteChannel.
void	copyFrom(ReadableByteChannel c)
protected void	deleteInternal() This method is called by AbstractEntityImpl.delete() after it has performed all validity, access control and lock checks.
long	getDataSize() Get the size of the data in the file.
long	getSize() Get the size of the file (in bytes).
long	getSizeNoLocking() Get an approximate size of the file without having to lock it.
EntityType	getType() Get the entity's EntityType.
void	notifyClosed(RandomAccess ra) Notify the observer that the supplied RandomAccess has been closed.
WritableByteChannel	openChannelForAppend() Open a WritableByteChannel for appending to the file.
ReadableByteChannel	openChannelForRead() Open a ReadableByteChannel for reading from the file.
WritableByteChannel	openChannelForWrite() Open a WritableByteChannel for writing on the file.
OutputStream	openForAppend() Open the file for appending.
RandomAccess	openForRandomAccess(RandomAccessMode mode) Open the file for random access in the specified mode.
InputStream	openForRead() Opens the file for reading.
OutputStream	openForWrite() Opens the file for writing.
void	replaceContents(ReadWritableFile f) Replace the contents of this file with the contents of the supplied file and then delete the supplied file.
String	toString() Subclasses should override this to return something more pretty.

Methods inherited from class org.entityfs.impl.impl.AbstractEntityImpl

addObserver, assertNotReadOnly, assertOk, assertParentIsReadLocked, assertParentIsWriteLocked, assertThisOrParentIsReadLocked, canRead, canWrite, compareTo, copy, copyAttributes, countObservers, createLock, createLockInternal, delete, deleteObserver, deleteObservers, disconnect, doDelete, equals, fireEvent, getAbsoluteLocationNoLocking, getCapability, getDelegate, getDelegateOfType, getDelegateOfTypeOrNull, getEntityAdapter, getFileSystem, getFileSystemImplementation, getLastModified, getLogAdapter, getName, getNameNoLocking, getObserverList, getParent, getParentInternal, getViewed, getViewedEntity, handleDisappeared, hasExecuteAccess, hashCode, hasReadAccess, hasWriteAccess, init, isConnected, isDeleted, isRootDirectory, isValid, rename, setLastModified, supportsCapability, touch, verifyHasExecuteAccess, verifyHasExecuteAccessToParent, verifyHasReadAccess, verifyHasReadAccessToParent, verifyHasWriteAccess, verifyHasWriteAccessToParent

Methods inherited from class org.entityfs.lock.AbstractLockable

assertIsReadLocked, assertIsWriteLocked, getLockAcquiringStrategy, getLockAdapter, getLocked, getReadLock, getWriteLock, isReadLockedByCurrentThread, isWriteLockedByCurrentThread, lock, lockForReading, lockForWriting, logLockStack

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Methods inherited from interface org.entityfs.impl.EntityImplementation

assertIsReadLocked, assertIsWriteLocked, assertNotReadOnly, assertOk, assertParentIsReadLocked, assertParentIsWriteLocked, createLockInternal, fireEvent, getDelegate, getDelegateOfType, getDelegateOfTypeOrNull, getEntityAdapter, init, verifyHasExecuteAccess, verifyHasExecuteAccessToParent, verifyHasReadAccess, verifyHasReadAccessToParent, verifyHasWriteAccess, verifyHasWriteAccessToParent

Methods inherited from interface org.entityfs.impl.EntityViewImplementation

getAbsoluteLocationNoLocking, getFileSystemImplementation, getNameNoLocking, getObserverList

Methods inherited from interface org.entityfs.Entity

hasExecuteAccess, hasReadAccess, hasWriteAccess

Methods inherited from interface org.entityfs.EntityView

canRead, canWrite, copy, copyAttributes, createLock, disconnect, getCapability, getFileSystem, getLastModified, getParent, getViewed, getViewedEntity, isConnected, isRootDirectory, isValid, lock, rename, setLastModified, supportsCapability, touch

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.Deletable

delete, isDeleted

Constructor Detail

FileImpl

public FileImpl(FileSystemImplementation fs,
                DirectoryImplementation parent,
                FileDelegate fd)

Method Detail

getType

public EntityType getType()

Description copied from interface: EntityView

Get the entity's EntityType.

Specified by:

getType in interface EntityView

Returns:

ETFile.TYPE, always.

openForWrite

public OutputStream openForWrite()

Description copied from interface: WritableFile

Opens the file for writing. This deletes all previous contents of the file. Use WritableFile.openForAppend() to append to the file.

The caller is responsible for closing the stream.

When two output streams, one writing and one appending are open on the same file, the stream opened for write will ignore the contents written by the other stream and the content written by the other stream will be overwritten. When two or more appending streams are opened on a file, a stream will not overwrite the content written by the other streams.

Although a write lock on the file is required for the execution thread opening the stream, the stream itself is not protected from access by other threads. It can be protected by wrapping it in a LockAwareOutputStream.

Specified by:

openForWrite in interface WritableFile

Returns:

An OutputStream to write to. The stream must be closed by the caller.

See Also:

WritableFile.openForAppend(), WritableFile.openChannelForWrite()

openForAppend

public OutputStream openForAppend()

Description copied from interface: WritableFile

Open the file for appending. This preserves all previous contents of the file. Use WritableFile.openForWrite() to delete the previous contents before writing. This requires that the file supports the FCAppendable capability (and/or that the file system supports the FSCAppendableFiles capability.

The caller is responsible for closing the stream.

When two appending output streams are open on the same file, one stream will not overwrite contents written by the other stream. Compare this with the behavior of one writing and one appending stream.

Although a write lock on the file is required for the execution thread opening the stream, the stream itself is not protected from access by other threads. It can be protected by wrapping it in a LockAwareWritableByteChannel.

Specified by:

openForAppend in interface WritableFile

Returns:

An OutputStream to write to. The stream must be closed by the caller.

See Also:

WritableFile.openForWrite(), WritableFile.openChannelForAppend()

openChannelForWrite

public WritableByteChannel openChannelForWrite()

Description copied from interface: WritableFile

Open a WritableByteChannel for writing on the file. The semantics of this method is the same as for WritableFile.openForWrite().

Specified by:

openChannelForWrite in interface WritableFile

Returns:

An open WritableByteChannel. The channel must be closed by the caller. The returned channel may be a GatheringByteChannel, but that is not required.

See Also:

WritableFile.openForWrite(), WritableFile.openChannelForAppend()

openChannelForAppend

public WritableByteChannel openChannelForAppend()

Description copied from interface: WritableFile

Open a WritableByteChannel for appending to the file. The semantics of this method is the same as for WritableFile.openForAppend().

Specified by:

openChannelForAppend in interface WritableFile

Returns:

An open WritableByteChannel. The channel must be closed by the caller. The returned channel may be a GatheringByteChannel, but that is not required.

openForRead

public InputStream openForRead()

Description copied from interface: ReadableFile

Opens the file for reading. The caller is responsible for closing the returned stream.

Although a read lock on the file is required for the execution thread opening the stream, the stream itself is not protected from access by other threads. It can be protected by wrapping it in a LockAwareInputStream.

Specified by:

openForRead in interface ReadableFile

Returns:

An InputStream on the file. The stream must be closed by the caller.

openChannelForRead

public ReadableByteChannel openChannelForRead()

Description copied from interface: ReadableFile

Open a ReadableByteChannel for reading from the file. The semantics of this method is the same as for ReadableFile.openForRead().

Although a read lock on the file is required for the execution thread opening the channel, the channel itself is not protected from access by other threads. It can be protected by wrapping it in a LockAwareReadableByteChannel.

Specified by:

openChannelForRead in interface ReadableFile

Returns:

An open ReadableByteChannel. The channel must be closed by the caller. The channel may be a ScatteringByteChannel, but that is not required.

See Also:

ReadableFile.openForRead()

openForRandomAccess

public RandomAccess openForRandomAccess(RandomAccessMode mode)

Description copied from interface: RandomlyAccessibleFile

Open the file for random access in the specified mode.

Although a read or write lock on the file is required for the execution thread opening the RandomAccess, the RandomAccess object itself is not protected from access by other threads. It can be protected by wrapping it in a LockAwareRandomAccess object.

Specified by:

openForRandomAccess in interface RandomlyAccessibleFile

Parameters:

mode - The mode to open the file in.

Returns:

An open RandomAccess object. It must be closed by the caller.

copy

public long copy(OutputStream os)

Description copied from interface: ReadWritableFile

Dump the file contents to the stream.

Specified by:

copy in interface ReadWritableFile

Parameters:

os - The stream the file contents are written to. The stream is not closed after writing, that must be done by the caller.

Returns:

The number of bytes written to the channel.

copy

public long copy(WritableByteChannel c)

Description copied from interface: ReadWritableFile

Copy the file's contents to the WritableByteChannel.

Specified by:

copy in interface ReadWritableFile

Parameters:

c - The WritableByteChannel. The channel is not closed by this method.

Returns:

The number of bytes written to the channel.

copyFrom

public void copyFrom(ReadableByteChannel c)

Specified by:

copyFrom in interface EFileImplementation

copy

public Set<EntityView> copy(DirectoryView d,
                            String targetName,
                            boolean preserveAttrs,
                            EntityLock... setupLocks)

Description copied from interface: EntityView

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.

Specified by:

copy in interface EntityView

Parameters:

d - A view of the target directory.

targetName - 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.

getSize

public long getSize()

Description copied from interface: ReadableFile

Get the size of the file (in bytes). This is the number of bytes that the file occupies where it is stored.

Note: Most, but not all, implementations know their sizes. If an implementation does not know its size beforehand, this method will be slow since it has to calculate the file size when it is called.

Implementation note: If the size of the backing file is not known, the StreamUtil.getSizeOfDataInStream(InputStream, int) method can be used to calculate it.

Specified by:

getSize in interface ReadableFile

Returns:

The size of the file, in bytes.

See Also:

ReadableFile.getDataSize()

getSizeNoLocking

public long getSizeNoLocking()

Description copied from interface: ReadWritableFile

Get an approximate size of the file without having to lock it.

Specified by:

getSizeNoLocking in interface ReadWritableFile

Returns:

The approximate size of the file, in bytes. If the file object is invalid, 0 is returned.

See Also:

ReadableFile.getSize()

getDataSize

public long getDataSize()

Description copied from interface: ReadableFile

Get the size of the data in the file. For compressed files, this is larger than the value returned by ReadableFile.getSize().

Warning: Calculating the data size of a file has the potential of being really slow, depending on the implementation used. The entire file may have to be read through in order to calculate the size of its data.

Implementation note: If the size of the backing file is not known, the StreamUtil.getSizeOfDataInStream(InputStream, int) method can be used to calculate it.

Specified by:

getDataSize in interface ReadableFile

Returns:

The size of data in the file.

See Also:

ReadableFile.getSize()

notifyClosed

public void notifyClosed(RandomAccess ra)

Description copied from interface: RandomAccessCloseObserver

Notify the observer that the supplied RandomAccess has been closed.

Specified by:

notifyClosed in interface RandomAccessCloseObserver

Parameters:

ra - The closed RandomAccess.

replaceContents

public void replaceContents(ReadWritableFile f)

Description copied from interface: ReadWritableFile

Replace the contents of this file with the contents of the supplied file and then delete the supplied file. If both files are in the same file system, an optimized implementation simply moves the contents of f over to this file, which makes the entire operation quick and not requiring any extra disk space.

If both files support metadata, this file's metadata is replaced with that of f.

Specified by:

replaceContents in interface ReadWritableFile

Parameters:

f - The file whose contents are to be moved to this file. f is deleted by this method.

assertCanBeDeleted

public void assertCanBeDeleted()

Description copied from class: AbstractEntityImpl

Perform entity type-specific checks in addition to the checks in the delete method.

Specified by:

assertCanBeDeleted in class AbstractEntityImpl

deleteInternal

protected void deleteInternal()

Description copied from class: AbstractEntityImpl

This method is called by AbstractEntityImpl.delete() after it has performed all validity, access control and lock checks. Subclasses implement this to call their delegate's delete method.

Specified by:

deleteInternal in class AbstractEntityImpl

toString

public String toString()

Description copied from class: AbstractEntityImpl

Subclasses should override this to return something more pretty.

Overrides:

toString in class AbstractEntityImpl