org.entityfs.cap.metadata.impl
Class ECMetadataImpl

java.lang.Object
  org.entityfs.cap.metadata.impl.AbstractECMetadata
      org.entityfs.cap.metadata.impl.ECMetadataImpl

All Implemented Interfaces:

EntityCapability, ECMetadata, Deletable, Lockable, ReadLockable, ReadWriteLockable, WriteLockable, RandomlyAccessibleFile, ReadableFile, ReadWritableFile, WritableFile

public class ECMetadataImpl
extends AbstractECMetadata
implements ECMetadata

Field Summary

Fields inherited from interface org.entityfs.cap.metadata.entity.ECMetadata

METADATA_FILE_NAME

Constructor Summary

ECMetadataImpl(EntityImplementation parent, MetadataEnablingEntityDelegate delegate)

Method Summary

long	copy(OutputStream os) Dump the file contents to the stream.
long	copy(WritableByteChannel c) Copy the file's contents to the WritableByteChannel.
void	delete() Delete the entity from the file system.
long	getDataSize() Get the size of the data in the file.
EntityLock	getReadLock() Get the read lock without locking it.
long	getSize() Get the size of the file (in bytes).
long	getSizeNoLocking() Get an approximate size of the file without having to lock it.
EntityLock	getWriteLock() Get the write lock without locking it.
boolean	isDeleted() Check if the entity has been deleted.
boolean	isReadLockedByCurrentThread() Does the calling thread hold a read lock for this object? A write lock also qualifies as a read lock.
boolean	isWriteLockedByCurrentThread() Does the calling thread hold a write lock for the lockable object (this)?
EntityLock	lockForReading() Lock object for reading and return the lock.
EntityLock	lockForWriting() Lock the object for writing and return the lock.
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 m) 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.

Methods inherited from class org.entityfs.cap.metadata.impl.AbstractECMetadata

getEntity, getParentEntity, isValid, prepareForRead, prepareForWrite

Methods inherited from class java.lang.Object

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

Methods inherited from interface org.entityfs.cap.EntityCapability

getEntity, isValid

Constructor Detail

ECMetadataImpl

public ECMetadataImpl(EntityImplementation parent,
                      MetadataEnablingEntityDelegate delegate)

Method Detail

isReadLockedByCurrentThread

public boolean isReadLockedByCurrentThread()

Description copied from interface: ReadLockable

Does the calling thread hold a read lock for this object? A write lock also qualifies as a read lock.

Specified by:

isReadLockedByCurrentThread in interface ReadLockable

Returns:

true if the lockable object is read or write locked by the current thread.

isWriteLockedByCurrentThread

public boolean isWriteLockedByCurrentThread()

Description copied from interface: WriteLockable

Does the calling thread hold a write lock for the lockable object (this)?

Specified by:

isWriteLockedByCurrentThread in interface WriteLockable

Returns:

true if the lockable object is write locked by the current thread.

lockForReading

public EntityLock lockForReading()

Description copied from interface: ReadLockable

Lock object for reading and return the lock. How the lock is acquired is determined by the EntityLockAdapterFactory and LockAcquiringStrategy used. If this is called on an object that somehow is connected to an entity object, that entity's file system's entity lock adapter factory and lock acquiring strategy is used.

A read lock cannot be upgraded to a write lock (just like how Java's ReadWriteLock works).

For more discussions on locks and locking, see Entity and FileSystem.

This method always returns a lock, even if the object's file system is not locking or if the object is read only.

Specified by:

lockForReading in interface ReadLockable

Returns:

A locked read lock.

lockForWriting

public EntityLock lockForWriting()

Description copied from interface: WriteLockable

Lock the object for writing and return the lock. How the lock is acquired is determined by the EntityLockAdapterFactory and LockAcquiringStrategy used. If this is called on an object that is somehow connected to an Entity object, that entity's file systems' lock adapter factory and lock acquiring strategy is used. A write lock can be downgraded to a read lock (by calling ReadLockable.lockForReading() and then releasing the write lock).

An entity in a locking read only file system may still be locked for writing.

For more discussions on locks and locking, see Entity and FileSystem.

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

Specified by:

lockForWriting in interface WriteLockable

Returns:

A locked write lock.

getReadLock

public EntityLock getReadLock()

Description copied from interface: ReadLockable

Get the read lock without locking it.

This method always returns a lock, even if the object's file system is not locking or if the object is read only.

Specified by:

getReadLock in interface ReadLockable

Returns:

The lockable's read lock. This might be unlocked or locked by someone else.

getWriteLock

public EntityLock getWriteLock()

Description copied from interface: WriteLockable

Get the write lock without locking it.

This method always returns a lock, even if the object's file system is not locking or if the object is read only.

Specified by:

getWriteLock in interface WriteLockable

Returns:

The lockable's write lock. This might be unlocked or locked by someone else.

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.

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()

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()

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.

openForRandomAccess

public RandomAccess openForRandomAccess(RandomAccessMode m)

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:

m - The mode to open the file in.

Returns:

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

delete

public void delete()

Description copied from interface: Deletable

Delete the entity from the file system. If it is a directory, it has to be empty before it can be deleted. When the entity is deleted, the entity object is invalidated (EntityView.isValid() will return false from now on).

Specified by:

delete in interface Deletable

isDeleted

public boolean isDeleted()

Description copied from interface: Deletable

Check if the entity has been deleted. Unlike EntityView.isValid() , this method does not do any backend validation, so if the entity has been deleted in the backend storage without going through the EntityFS API, use that method instead.

Specified by:

isDeleted in interface Deletable

Returns:

true if the entity object has been deleted.

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()

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()

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.

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.