net.sf.mmm.util.resource.api

Interface DataResource

All Known Subinterfaces:

BrowsableResource

All Known Implementing Classes:

AbstractBrowsableResource, AbstractDataResource, ClasspathResource, ClasspathScannerImpl.AbstractBrowsableClasspathResource, ClasspathScannerImpl.ClasspathFile, ClasspathScannerImpl.ClasspathFolder, FileResource, UrlResource

public interface DataResource

This is the interface for a resource potentially containing data. You can think of a DataResource as a file but it may come from other sources than the filesystem.
The major reason for naming it DataResource is that Resource is a very general name already occupied by Resource.

Since:

1.0.2

Author:

Joerg Hohwiller (hohwille at users.sourceforge.net)

Method Summary

Modifier and Type	Method and Description
Date	getLastModificationDate() This method gets the last modification date of the DataResource if available and supported.
String	getName() This method gets the name of the resource.
String	getPath() This method gets the path of this resource.
long	getSize() This method gets the size (content-length) of this resource.
String	getUri() This method gets a string identifying this DataResource.
URL	getUrl() This method gets this resource as URL.
boolean	isAvailable() This method determines if this resource is available.
boolean	isData() This method determines if this resource has potentially data available.
Boolean	isModifiedSince(Date date) This method determines if this resource has been been modified since the given data.
DataResource	navigate(String resourcePath) This method retrieves a DataResource pointing to the given resourcePath based on this resource. E.g.
OutputStream	openOutputStream() This method opens an output-stream in order to write data to the resource.
InputStream	openStream() This method opens this resource for reading.

Method Detail

isAvailable

boolean isAvailable()

This method determines if this resource is available. Available simply means that it exists and data can be read.
ATTENTION:
Depending on the underlying implementation this can be a relatively expensive operation. E.g. if this resource points to a remote URL this method has to open a network connection in order to verify if the resource is available. Use isData() to prevent such expensive operaitons.

Returns:

true if this resource is available, false otherwise.

isData

boolean isData()

This method determines if this resource has potentially data available. Unlike isAvailable() this method will not invoke expensive operations like connecting to remote URLs. If this method will return false, then isAvailable() would also have returned false. However in case of true only isAvailable() can guarantee if a resource really exists and contains data. E.g. if the resource points to a File then this method can check if it is a data-file. So in case it points to a directory or does not exist at all in the filesystem, this method will return false. Please also note that this may invoke expensive operations if the according directory path points to something like a network share. You should also be aware that the state of isData() and isAvailable() can change at any time so you never have a full guarantee if some data exists or NOT. However in most cases it is very improbable that this status changes when you read the resource immediately after the check.

Returns:

true if this resource points to potential data, false otherwise.

Since:

2.0.0

getPath

String getPath()

This method gets the path of this resource. Please note that the path is including the name of the resource.
ATTENTION:
The result of this method may differ to the path used in the URL when this resource has been created.

Returns:

the path that was used to identify this resource when creating.

getName

String getName()

This method gets the name of the resource. It is analog to a filename.

Returns:

the name of the resource.

Since:

2.0.0

getSize

long getSize()
      throws ResourceNotAvailableException

This method gets the size (content-length) of this resource.

Returns:

the size of this resource.

Throws:

ResourceNotAvailableException - if this resource is NOT available.

getUrl

URL getUrl()
    throws ResourceNotAvailableException

This method gets this resource as URL.

Returns:

the URL that represents this resource.

Throws:

ResourceNotAvailableException - if an URL can NOT be created because the represented resource does not exist.

getUri

String getUri()

This method gets a string identifying this DataResource. In most cases this will be the same as string-representation of the URL. However this method will not throw an exception.

Returns:

the URI as string.

openStream

InputStream openStream()
                throws ResourceNotAvailableException,
                       RuntimeIoException

This method opens this resource for reading.

Returns:

the input stream where to read from.

Throws:

ResourceNotAvailableException - if this resource is NOT available.

RuntimeIoException - if an input/output error occurred.

See Also:

URL.openStream()

openOutputStream

OutputStream openOutputStream()
                       throws ResourceNotAvailableException,
                              ResourceNotWritableException,
                              RuntimeIoException

This method opens an output-stream in order to write data to the resource.

Returns:

the OutputStream to write to the resource.

Throws:

ResourceNotAvailableException - if this resource is NOT available.

ResourceNotWritableException - if the resource is NOT writable (e.g. read-only).

RuntimeIoException - if an input/output error occurred.

Since:

2.0.0

navigate

DataResource navigate(String resourcePath)
               throws ResourceUriUndefinedException

This method retrieves a DataResource pointing to the given resourcePath based on this resource.
E.g. if this resource points to the file "/etc/init.d/rc" and resourcePath would be "../apt/sources.list" the resulting resource would point to "/etc/apt/sources.list".
ATTENTION:
As you can see by the example above this method always navigates relative to the parent folder of this resource. This will also be the case if this resource itself is a folder. Due to this generic API this is the only consistent way as there are implementations that can not easily know if they represent a folder or a file or maybe even both at the same time. However, please be aware of this and do not get confused as you might expect this to be a cd command if invoked on a folder what is not exactly not the case (instead it is a cd on the parent folder).

Parameters:

resourcePath - is the absolute or relative path pointing to a new resource. If it is a relative path, it is interpreted relative to the parent URI (directory) of this resource.

Returns:

is the resource pointing to the given path (relative to this resource).

Throws:

ResourceUriUndefinedException - if the given resourcePath leads to an undefined or illegal URI.

getLastModificationDate

Date getLastModificationDate()

This method gets the last modification date of the DataResource if available and supported.

Returns:

the last modification Date or null if not available or supported.

Since:

2.0.0

isModifiedSince

Boolean isModifiedSince(Date date)

This method determines if this resource has been been modified since the given data.

Parameters:

date - is the Date to check for.

Returns:

true if the resource has been modified after the given date, false if it has NOT been modified after the given date and null if this can NOT be determined (resource not available or operation NOT supported by this resource).

Since:

2.0.0