org.apache.commons.transaction.resource
Interface StreamableResource

All Known Implementing Classes:

FileResourceManager.FileResource, TxFileResourceManager.FileTxContext.TxFileResource

public interface StreamableResource

Interface for a resource that has a stream and properties. The resource is organized in a hierarchy.

This can be a direct match for File.

Method Summary

void	copy(StreamableResource destination) Copies this resource to a new one.
void	createAsDirectory() Creates this resource or a physical directory.
void	createAsFile() Creates this resource or a physical file.
void	delete() Physically deletes this resource.
boolean	exists() Checks if this resource physically exists.
StreamableResource	getChild(String name) Gets a specific child of this resource.
List<? extends StreamableResource>	getChildren() Gets the children of the resource.
String	getName() Gets the name, i.e. the last segment of the path.
StreamableResource	getParent() Gets the parent of this resource, i.e. the directory this resource resides in or null if this is the root folder.
String	getPath() Gets the full path of this resource
Object	getProperty(String name) Retrieves a specific property.
boolean	isDirectory() Checks whether this resource is a directory, i.e. whether it can have children.
boolean	isFile() Checks whether this resource is a file, i.e. whether it contains a content stream.
void	move(StreamableResource destination) Moves (or renames) this resource to a new one.
void	readLock() Explicitly sets a read lock on this resource.
InputStream	readStream() Gets the input stream associated to this resource.
void	removeProperty(String name) Removes a specific property.
void	setProperty(String name, Object newValue) Sets a specific property.
void	writeLock() Explicitly sets a write lock on this resource.
OutputStream	writeStream(boolean append) Gets the output stream associated to this resource.

Method Detail

getPath

String getPath()

Gets the full path of this resource

Returns:

the full path

getName

String getName()

Gets the name, i.e. the last segment of the path.

Returns:

the name

isDirectory

boolean isDirectory()

Checks whether this resource is a directory, i.e. whether it can have children. Note that a resource can be both a directory and a file.

Returns:

true if this resource can have children

isFile

boolean isFile()

Checks whether this resource is a file, i.e. whether it contains a content stream. Note that a resource can be both a directory and a file.

Returns:

true if this resource contains a content stream

getChildren

List<? extends StreamableResource> getChildren()
                                               throws ResourceException

Gets the children of the resource.

Returns:

a list of children (empty if this is a file), never null

Throws:

ResourceException - in case anything goes fatally wrong

getParent

StreamableResource getParent()
                             throws ResourceException

Gets the parent of this resource, i.e. the directory this resource resides in or null if this is the root folder.

Returns:

the parent directory or null if there is none

Throws:

ResourceException - in case anything goes fatally wrong

getChild

StreamableResource getChild(String name)
                            throws ResourceException

Gets a specific child of this resource. This method returns a resource even if it does not exist.

Parameters:

name - the name of the child resource

Returns:

the resource object - even if it does not exist

Throws:

ResourceException - in case anything goes fatally wrong

readStream

InputStream readStream()
                       throws ResourceException

Gets the input stream associated to this resource. You are responsible for closing the stream after using it.

Returns:

the input stream for reading

Throws:

ResourceException - in case anything goes fatally wrong

writeStream

OutputStream writeStream(boolean append)
                         throws ResourceException

Gets the output stream associated to this resource. You are responsible for closing the stream after using it.

Parameters:

append - determines whether you append to the existing content

Returns:

the output stream for writing

Throws:

ResourceException - in case anything goes fatally wrong

delete

void delete()
            throws ResourceException

Physically deletes this resource.

Throws:

ResourceException - in case anything goes fatally wrong or you have not been able to delete the resource

move

void move(StreamableResource destination)
          throws ResourceException

Moves (or renames) this resource to a new one. If nothing goes wrong this resource will be deleted afterwards.

Parameters:

destination - the new resource

Throws:

ResourceException - in case anything goes fatally wrong or you have not been able to move this resource

copy

void copy(StreamableResource destination)
          throws ResourceException

Copies this resource to a new one. If nothing goes wrong there will be two existing resources afterwards.

Parameters:

destination - the new resource

Throws:

ResourceException - in case anything goes fatally wrong or you have not been able to copy this resource

exists

boolean exists()

Checks if this resource physically exists.

Returns:

true if it exists

createAsDirectory

void createAsDirectory()
                       throws ResourceException

Creates this resource or a physical directory. In case there already is a physical resource having the same name, this request will fail and throw an exception.

Throws:

ResourceException - in case anything goes fatally wrong or you have not been able to create this resource as a directory

createAsFile

void createAsFile()
                  throws ResourceException

Creates this resource or a physical file. In case there already is a physical resource having the same name, this request will fail and throw an exception.

Throws:

ResourceException - in case anything goes fatally wrong or you have not been able to create this resource as a file

getProperty

Object getProperty(String name)

Retrieves a specific property. Which properties there are and whether you can create new ones depends on the specific implementation.

Parameters:

name - the name of the property

Returns:

the value of the property or null if there is no such property

setProperty

void setProperty(String name,
                 Object newValue)
                 throws UnsupportedOperationException

Sets a specific property. Not all implementations support his operation. If unsupported an exception in thrown.

Parameters:

name - the name of the property

newValue - the new value

Throws:

UnsupportedOperationException - if this operation is not supported by the specific implementation

removeProperty

void removeProperty(String name)
                    throws UnsupportedOperationException

Removes a specific property. Not all implementations support his operation. If unsupported an exception in thrown.

Parameters:

name - the name of the property

Throws:

UnsupportedOperationException - if this operation is not supported by the specific implementation

readLock

void readLock()

Explicitly sets a read lock on this resource. This means no other thread can write to this resource while this read lock is held. Other threads are allowed to set further read locks, though.

Not all implementations support his operation as it only makes sense in a transactional environment. There is no unlock operation as the release of all locks has to be controlled by the transaction manager.

If unsupported nothing will happen.

writeLock

void writeLock()

Explicitly sets a write lock on this resource. This means no other thread can neither write nor read to this resource while this write lock is held.

Not all implementations support his operation as it only makes sense in a transactional environment. There is no unlock operation as the release of all locks has to be controlled by the transaction manager.

If unsupported nothing will happen.