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

  • 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

    • CLI_ARG_SCHEME

      static final String CLI_ARG_SCHEME

      A pseudo scheme for having URIs that refer to command line arguments

      See Also:

    • 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

    • isUnknownUri

      static boolean isUnknownUri(URI uri)

      Test whether the given uri is the magic UNKNOWN_URI, taking in to account that it might have an anchor fragment attached to it

    • cliArgUri

      static URI cliArgUri(String argName)

      Generate a URI for a command line argument

      Parameters:
      argName -
      Returns:

    • isCliArg

      static boolean isCliArg(URI uri)
      Returns:
      true if the given argument looks like a command line argument

    • 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