Package nz.org.riskscape.engine.resource

Interface Resource

All Known Implementing Classes:

BaseResource, Resource.PseudoResource

public interface Resource

Represents a file type resource in a way that allows where the resource is from to be decoupled from how it is accessed.

For example implementations may fetch remote resources and make the local copy available.

# TODO - add some metadata methods, like size, checksum, cache metadata, anything else? - make it clearer whether the resource is open at this point or not, and whether streams need to be closed

Nested Class Summary

Nested Classes

Modifier and Type	Interface	Description
static class	Resource.Options
static class	Resource.PseudoResource	A resource that can not be opened but is still useful for identifying some content.

Field Summary

Fields

Modifier and Type	Field	Description
static final InputStream	NO_BYTES	An empty input stream for use with UNKNOWN
static final Resource.Options	SECURE_OPTIONS	Options that will only allow a remote file to be fetched if it can be done over a secure connection.
static final Resource	UNKNOWN	Null alternative for a Resource - use this in place of null where there is no obvious resource to provide as metadata.
static final URI	UNKNOWN_URI	A URI for use with UNKNOWN

Method Summary

Modifier and Type	Method	Description
default ResultOrProblems<Path>	ensureLocal(Resource.Options options)	Returns a Path to a local representation of the resource if the resource loader supports this and is allowable given the options.
default ResultOrProblems<Path>	ensureLocal(Resource.Options secureOptions, String fileExtension)
default String	getContentAsString()
default Reader	getContentReader()	Return a Reader for the underlying resource.
InputStream	getContentStream()	Return an InputStream to the underlying resource.
default Optional<Path>	getLocal()	Alternative to ensureLocal(nz.org.riskscape.engine.resource.Resource.Options, java.lang.String) that will only return the local path if the resource already exists there.
URI	getLocation()
default Optional<String>	getMediaType()

Field Details

SECURE_OPTIONS

static final Resource.Options SECURE_OPTIONS

Options that will only allow a remote file to be fetched if it can be done over a secure connection.

UNKNOWN_URI

static final URI UNKNOWN_URI

A URI for use with UNKNOWN

NO_BYTES

static final InputStream NO_BYTES

An empty input stream for use with UNKNOWN

UNKNOWN

static final Resource UNKNOWN

Null alternative for a Resource - use this in place of null where there is no obvious resource to provide as metadata. Obviously this is not useful if the Resource is going to be open, it's meant as metadata for assisting with messaging etc and clarity in places where no Resource exists.

Method Details

getLocation

URI getLocation()

Returns:

a URI identifying where this resource is located

getContentStream

InputStream getContentStream()
                      throws RiskscapeIOException

Return an InputStream to the underlying resource.

Each call should return a freshly created input stream.

Returns:

the input stream for the underlying resource.

Throws:

RiskscapeIOException

getContentReader

default Reader getContentReader()
                         throws RiskscapeIOException

Return a Reader for the underlying resource.

A convenience that wraps the result of #getResourceStream() in a InputStreamReader.

Returns:

reader for the underlying resource

Throws:

RiskscapeIOException

getContentAsString

default String getContentAsString()
                           throws RiskscapeIOException

Returns:

a String that is the resource's data read completely in to a string - don't use this on potentially large resources, or you're going to run out of heap

Throws:

RiskscapeIOException

ensureLocal

default ResultOrProblems<Path> ensureLocal(Resource.Options secureOptions,
 String fileExtension)

ensureLocal

default ResultOrProblems<Path> ensureLocal(Resource.Options options)

Returns a Path to a local representation of the resource if the resource loader supports this and is allowable given the options. Otherwise problems preventing this operation from succeeding.

Throws:

RiskscapeIOException - if IO errors occur whilst fetching resource

getLocal

default Optional<Path> getLocal()

Alternative to ensureLocal(nz.org.riskscape.engine.resource.Resource.Options, java.lang.String) that will only return the local path if the resource already exists there.

Returns:

the path to the resource on the local path or empty if the resource does not exist locally already

getMediaType

default Optional<String> getMediaType()

Returns:

a media type that represents this resource