org.entityfs
Interface WritableFile

All Superinterfaces:

Lockable, WriteLockable

All Known Subinterfaces:

ECMetadata, EFile, EFileImplementation, ReadWritableFile

All Known Implementing Classes:

AbstractReadWritableFile, AbstractWritableFile, ByteArrayWritableFile, ECMetadataImpl, FileDelegateReadWritableFileAdapter, FileImpl, FileWritableFile, GZipWritableFile, MetadataFileAdapter, ReadWritableFileAdapter

public interface WritableFile
extends WriteLockable

This interface is implemented by objects that behave as writable files, EFile:s for instance.

Note that files are writable even if the are in a read only file system. If the methods defined in this interface are called on a file in a read only file system, they throw an ReadOnlyException.

Use this interface instead of EFile wherever possible to make mocking and testing easier.

Since:

1.0

Author:

Karl Gustafsson

See Also:

ReadableFile, RandomlyAccessibleFile

In_jar:

entityfs-core

Method Summary

WritableByteChannel	openChannelForAppend() Open a WritableByteChannel for appending to the file.
WritableByteChannel	openChannelForWrite() Open a WritableByteChannel for writing on the file.
OutputStream	openForAppend() Open the file for appending.
OutputStream	openForWrite() Opens the file for writing.

Methods inherited from interface org.entityfs.lock.WriteLockable

getWriteLock, isWriteLockedByCurrentThread, lockForWriting

Method Detail

openForWrite

OutputStream openForWrite()
                          throws WriteLockRequiredException,
                                 AccessDeniedException,
                                 ReadOnlyException

Opens the file for writing. This deletes all previous contents of the file. Use 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.

Returns:

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

Throws:

WriteLockRequiredException - If the client does not have a write lock for the file.

AccessDeniedException - If the client does not have write access to the file.

ReadOnlyException - If the file system is read-only.

See Also:

openForAppend(), openChannelForWrite()

Locks_required:

A write lock on the file.

Permissions_required:

Write access.

Generates_events:

EntityModifiedEvent for this when the stream is closed, if it has been written to., ChildEntityModifiedEvent for this's parent when the stream is closed, if it has been written to.

openForAppend

OutputStream openForAppend()
                           throws ReadOnlyException,
                                  WriteLockRequiredException,
                                  AccessDeniedException

Open the file for appending. This preserves all previous contents of the file. Use 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.

Returns:

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

Throws:

ReadOnlyException - If the file system is read-only.

WriteLockRequiredException - If the client does not have a write lock for the file.

AccessDeniedException - If the client does not have write access to the file.

See Also:

openForWrite(), openChannelForAppend()

Locks_required:

A write lock on the file.

Permissions_required:

Write access.

Generates_events:

EntityModifiedEvent for this when the stream is closed, if it has been written to., ChildEntityModifiedEvent for this's parent when the stream is closed, if it has been written to.

openChannelForWrite

WritableByteChannel openChannelForWrite()
                                        throws WriteLockRequiredException,
                                               AccessDeniedException,
                                               ReadOnlyException

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

Returns:

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

Throws:

ReadOnlyException - If the file system is read-only.

WriteLockRequiredException - If the client does not have a write lock for the file.

AccessDeniedException - If the client does not have write access to the file.

See Also:

openForWrite(), openChannelForAppend()

Locks_required:

A write lock on the file.

Permissions_required:

Write access.

Generates_events:

EntityModifiedEvent for this when the stream is closed, if it has been written to., ChildEntityModifiedEvent for this's parent when the stream is closed, if it has been written to.

openChannelForAppend

WritableByteChannel openChannelForAppend()
                                         throws WriteLockRequiredException,
                                                AccessDeniedException,
                                                ReadOnlyException

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

Returns:

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

Throws:

ReadOnlyException - If the file system is read-only.

WriteLockRequiredException - If the client does not have a write lock for the file.

AccessDeniedException - If the client does not have write access to the file.

Locks_required:

A write lock on the file.

Permissions_required:

Write access.

Generates_events:

EntityModifiedEvent for this when the stream is closed, if it has been written to., ChildEntityModifiedEvent for this's parent when the stream is closed, if it has been written to.