org.jicengine.io
Interface Resource

All Known Implementing Classes:
AbstractResource

public interface Resource

Provides a common interface for reading resources and resolving relative path-references.

A resource is typically a file that contains data to be used by an application. Java provides various ways for reading resources: java.io.File, java.net.URL, java.lang.Class.getResourceAsStream(), java.lang.ClassLoader.getResourceAsStream(), etc.

This class encapsulates all these under a common interface.

Version:
1.0
Author:
.timo

Method Summary
 java.lang.String getIdentifier()
          Returns the identifier of this resource.
 java.io.InputStream getInputStream()
          A primary way reading the resource.
 java.lang.String getMimeType()
           Returns the http mime-type of this Resource, if this Resource has one.
 java.io.Reader getReader()
          Alternative way for reading text-based resources.
 Resource getResource(java.lang.String relativePath)
           Locates another Resource whose path is defined relative to this Resource.
 boolean isAvailable()
           Tests whether the resource is available i.e. can be read.
 void writeTo(java.io.OutputStream out)
          Writes the content of this resource into an OutputStream.
 void writeTo(java.io.Writer writer)
           Writes the content of this resource into a Writer.
 

Method Detail

getInputStream

public java.io.InputStream getInputStream()
                                   throws java.io.IOException
A primary way reading the resource.

Returns:
InputStream
Throws:
java.io.IOException - if the reading fails - if the resource doesn't exist, for example.

getReader

public java.io.Reader getReader()
                         throws java.io.IOException
Alternative way for reading text-based resources.

Returns:
A Reader that returns data from this Resource.
Throws:
java.io.IOException - if the reading fails - if the resource doesn't exist, for example.

writeTo

public void writeTo(java.io.OutputStream out)
             throws java.io.IOException
Writes the content of this resource into an OutputStream. This is an alternative way for obtaining the data of this Resource.

Throws:
java.io.IOException - if the content of this Resource isn't available - if the resource doesn't exist, for example.

writeTo

public void writeTo(java.io.Writer writer)
             throws java.io.IOException

Writes the content of this resource into a Writer. This is an alternative way for obtaining the data of this Resource.

Throws:
java.io.IOException - if the content of this Resource isn't available - if the resource doesn't exist, for example.

isAvailable

public boolean isAvailable()

Tests whether the resource is available i.e. can be read.

If this method returns true, the attempt to read this Resource (with getInputStream() or other methods) is not likely to fail. Unless the resource is somehow removed between the two method calls.

If a false is return, the resource is not available.

NOTE: testing whether a resource is available can be as resource-intensive as actually reading the resource.


getIdentifier

public java.lang.String getIdentifier()
Returns the identifier of this resource. Depending on the kind of resource, the identifier could be a file-path, url, etc. The identifier is descriptive - it will help a human to find out what kind of resource is in question, but don't rely in the format and try to create a resource based on the identifier. the format varies and may be changed in the future.


getMimeType

public java.lang.String getMimeType()

Returns the http mime-type of this Resource, if this Resource has one.

Mime-type information is an easy way to find out something about the type of content in a Resource. it also makes it easier to write Resource data into http-responses.

Returns:
NOTE: this property is optional! null is returned if the mime-type information is not available. and most in cases it probably isn't.

getResource

public Resource getResource(java.lang.String relativePath)
                     throws java.io.IOException

Locates another Resource whose path is defined relative to this Resource.

the path scheme used with files and urls is used for specifying relative paths.

the method generally returns instances of the same Resource-subclass than the current instance, but this is not obligatory.

NOTE:

NOTE: there is no support for absolute paths. yet.

Parameters:
relativePath - name of the neighbouring resource. only relative paths are allowed, don't put the root mark '/' in the beginning. notations like '../' can be used (in most of the cases, at least) Windows-like paths '\joku\jotain.txt' won't work.
Returns:
a new Resource. The returned Resource is most likely of the same type as this resource (although there's no guarantee). In other words, if this Resource is a FileResource, the returned Resource will also be a FileResource. NOTE: this method doesn't necessary check the availability of the relative resource, because that may be too slow. if you want to make sure that the returned resource is available, you must examine the availability of the returned resource by your self.
Throws:
java.io.IOException - if a reference to the neighbouring resource couldn't be created.