org.restlet.resource
Class Representation

java.lang.Object
  extended by org.restlet.resource.Variant
      extended by org.restlet.resource.Representation
Direct Known Subclasses:
ChannelRepresentation, CharacterRepresentation, FileRepresentation, StreamRepresentation, WrapperRepresentation

public abstract class Representation
extends Variant

Current or intended state of a resource. The content of a representation can be retrieved several times if there is a stable and accessible source, like a local file or a string. When the representation is obtained via a temporary source like a network socket, its content can only be retrieved once. The "transient" and "available" properties are available to help you figure out those aspects at runtime.

For performance purpose, it is essential that a minimal overhead occurs upon initialization. The main overhead must only occur during invocation of content processing methods (write, getStream, getChannel and toString).

"REST components perform actions on a resource by using a representation to capture the current or intended state of that resource and transferring that representation between components. A representation is a sequence of bytes, plus representation metadata to describe those bytes. Other commonly used but less precise names for a representation include: document, file, and HTTP message entity, instance, or variant." Roy T. Fielding

Author:
Jerome Louvel
See Also:
Source dissertation

Field Summary
static long UNKNOWN_SIZE
          Indicates that the size of the representation can't be known in advance.
 
Constructor Summary
Representation()
          Default constructor.
Representation(MediaType mediaType)
          Constructor.
 
Method Summary
 boolean checkDigest()
          Check that the digest computed from the representation content and the digest declared by the representation are the same.
Since this method relies on the computeDigest(String) method, and since this method reads entirely the representation's stream, user must take care of the content of the representation in case the latter is transient.
 boolean checkDigest(java.lang.String algorithm)
          Check that the digest computed from the representation content and the digest declared by the representation are the same.
 Digest computeDigest(java.lang.String algorithm)
          Compute the representation digest according to the given algorithm.
Since this method reads entirely the representation's stream, user must take care of the content of the representation in case the latter is transient.
static Representation createEmpty()
          Returns a new empty representation with no content.
 long exhaust()
          Exhauts the content of the representation by reading it and silently discarding anything read.
 long getAvailableSize()
          Returns the size effectively available.
abstract  java.nio.channels.ReadableByteChannel getChannel()
          Returns a channel with the representation's content.
If it is supported by a file, a read-only instance of FileChannel is returned.
This method is ensured to return a fresh channel for each invocation unless it is a transient representation, in which case null is returned.
 Digest getDigest()
          Returns the representation digest if any.
 java.lang.String getDownloadName()
          Returns the suggested download file name for this representation.
 java.util.Date getExpirationDate()
          Returns the future date when this representation expire.
 java.util.Date getModificationDate()
          Returns the last date when this representation was modified.
 Range getRange()
          Returns the range where in the full content the partial content available should be applied.
abstract  java.io.Reader getReader()
          Returns a characters reader with the representation's content.
 long getSize()
          Returns the size in bytes if known, UNKNOWN_SIZE (-1) otherwise.
abstract  java.io.InputStream getStream()
          Returns a stream with the representation's content.
 Tag getTag()
          Returns the tag.
 java.lang.String getText()
          Converts the representation to a string value.
 boolean isAvailable()
          Indicates if some fresh content is available, without having to actually call one of the content manipulation method like getStream() that would actually consume it.
 boolean isDownloadable()
          Indicates if the representation is downloadable which means that it can be obtained via a download dialog box.
 boolean isTransient()
          Indicates if the representation's content is transient, which means that it can be obtained only once.
 void release()
          Releases the representation's content and all associated objects like sockets, channels or files.
 void setAvailable(boolean available)
          Indicates if some fresh content is available.
 void setDigest(Digest digest)
          Sets the representation digest.
 void setDownloadable(boolean downloadable)
          Indicates if the representation is downloadable which means that it can be obtained via a download dialog box.
 void setDownloadName(java.lang.String fileName)
          Set the suggested download file name for this representation.
 void setExpirationDate(java.util.Date expirationDate)
          Sets the future date when this representation expire.
 void setModificationDate(java.util.Date modificationDate)
          Sets the last date when this representation was modified.
 void setRange(Range range)
          Sets the range where in the full content the partial content available should be applied.
 void setSize(long expectedSize)
          Sets the expected size in bytes if known, -1 otherwise.
 void setTag(Tag tag)
          Sets the tag.
 void setTransient(boolean isTransient)
          Indicates if the representation's content is transient.
abstract  void write(java.io.OutputStream outputStream)
          Writes the representation to a byte stream.
abstract  void write(java.nio.channels.WritableByteChannel writableChannel)
          Writes the representation to a byte channel.
abstract  void write(java.io.Writer writer)
          Writes the representation to a characters writer.
 
Methods inherited from class org.restlet.resource.Variant
getCharacterSet, getEncodings, getIdentifier, getLanguages, getMediaType, setCharacterSet, setEncodings, setIdentifier, setIdentifier, setLanguages, setMediaType
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

UNKNOWN_SIZE

public static final long UNKNOWN_SIZE
Indicates that the size of the representation can't be known in advance.

See Also:
Constant Field Values
Constructor Detail

Representation

public Representation()
Default constructor.


Representation

public Representation(MediaType mediaType)
Constructor.

Parameters:
mediaType - The media type.
Method Detail

createEmpty

public static Representation createEmpty()
Returns a new empty representation with no content.

Returns:
A new empty representation.

checkDigest

public boolean checkDigest()
Check that the digest computed from the representation content and the digest declared by the representation are the same.
Since this method relies on the computeDigest(String) method, and since this method reads entirely the representation's stream, user must take care of the content of the representation in case the latter is transient. isTransient

Returns:
True if both digests are not null and equals.

checkDigest

public boolean checkDigest(java.lang.String algorithm)
Check that the digest computed from the representation content and the digest declared by the representation are the same. It also first checks that the algorithms are the same.
Since this method relies on the computeDigest(String) method, and since this method reads entirely the representation's stream, user must take care of the content of the representation in case the latter is transient. isTransient

Parameters:
algorithm - The algorithm used to compute the digest to compare with. See constant values in Digest.
Returns:
True if both digests are not null and equals.

computeDigest

public Digest computeDigest(java.lang.String algorithm)
Compute the representation digest according to the given algorithm.
Since this method reads entirely the representation's stream, user must take care of the content of the representation in case the latter is transient. isTransient

Parameters:
algorithm - The algorithm used to compute the digest. See constant values in Digest.
Returns:
The computed digest or null if the digest cannot be computed.

exhaust

public long exhaust()
             throws java.io.IOException
Exhauts the content of the representation by reading it and silently discarding anything read.

Returns:
The number of bytes consumed or -1 if unknown.
Throws:
java.io.IOException

getAvailableSize

public long getAvailableSize()
Returns the size effectively available. This returns the same value as getSize() if no range is defined, otherwise it returns the size of the range using Range.getSize().

Returns:
The available size.

getChannel

public abstract java.nio.channels.ReadableByteChannel getChannel()
                                                          throws java.io.IOException
Returns a channel with the representation's content.
If it is supported by a file, a read-only instance of FileChannel is returned.
This method is ensured to return a fresh channel for each invocation unless it is a transient representation, in which case null is returned.

Returns:
A channel with the representation's content.
Throws:
java.io.IOException

getDigest

public Digest getDigest()
Returns the representation digest if any.

Returns:
The representation digest or null.

getDownloadName

public java.lang.String getDownloadName()
Returns the suggested download file name for this representation. This is mainly used to suggest to the client a local name for a downloaded representation.

Returns:
The suggested file name for this representation.

getExpirationDate

public java.util.Date getExpirationDate()
Returns the future date when this representation expire. If this information is not known, returns null.

Overrides:
getExpirationDate in class Variant
Returns:
The expiration date.

getModificationDate

public java.util.Date getModificationDate()
Returns the last date when this representation was modified. If this information is not known, returns null.

Overrides:
getModificationDate in class Variant
Returns:
The modification date.

getRange

public Range getRange()
Returns the range where in the full content the partial content available should be applied.

Returns:
The content range or null if the full content is available.

getReader

public abstract java.io.Reader getReader()
                                  throws java.io.IOException
Returns a characters reader with the representation's content. This method is ensured to return a fresh reader for each invocation unless it is a transient representation, in which case null is returned. If the representation has no character set defined, the system's default one will be used.

Returns:
A reader with the representation's content.
Throws:
java.io.IOException

getSize

public long getSize()
Returns the size in bytes if known, UNKNOWN_SIZE (-1) otherwise.

Overrides:
getSize in class Variant
Returns:
The size in bytes if known, UNKNOWN_SIZE (-1) otherwise.

getStream

public abstract java.io.InputStream getStream()
                                       throws java.io.IOException
Returns a stream with the representation's content. This method is ensured to return a fresh stream for each invocation unless it is a transient representation, in which case null is returned.

Returns:
A stream with the representation's content.
Throws:
java.io.IOException

getTag

public Tag getTag()
Returns the tag.

Overrides:
getTag in class Variant
Returns:
The tag.

getText

public java.lang.String getText()
                         throws java.io.IOException
Converts the representation to a string value. Be careful when using this method as the conversion of large content to a string fully stored in memory can result in OutOfMemoryErrors being thrown.

Returns:
The representation as a string value.
Throws:
java.io.IOException

isAvailable

public boolean isAvailable()
Indicates if some fresh content is available, without having to actually call one of the content manipulation method like getStream() that would actually consume it. This is especially useful for transient representation whose content can only be accessed once and also when the size of the representation is not known in advance.

Returns:
True if some fresh content is available.

isDownloadable

public boolean isDownloadable()
Indicates if the representation is downloadable which means that it can be obtained via a download dialog box.

Returns:
True if the representation's content is downloadable.

isTransient

public boolean isTransient()
Indicates if the representation's content is transient, which means that it can be obtained only once. This is often the case with representations transmitted via network sockets for example. In such case, if you need to read the content several times, you need to cache it first, for example into memory or into a file.

Returns:
True if the representation's content is transient.

release

public void release()
Releases the representation's content and all associated objects like sockets, channels or files. If the representation is transient and hasn't been read yet, all the remaining content will be discarded, any open socket, channel, file or similar source of content will be immediately closed. The representation is also no more available.


setAvailable

public void setAvailable(boolean available)
Indicates if some fresh content is available.

Parameters:
available - True if some fresh content is available.

setDigest

public void setDigest(Digest digest)
Sets the representation digest.

Parameters:
digest - The representation digest.

setDownloadable

public void setDownloadable(boolean downloadable)
Indicates if the representation is downloadable which means that it can be obtained via a download dialog box.

Parameters:
downloadable - True if the representation's content is downloadable.

setDownloadName

public void setDownloadName(java.lang.String fileName)
Set the suggested download file name for this representation.

Parameters:
fileName - The suggested file name.

setExpirationDate

public void setExpirationDate(java.util.Date expirationDate)
Sets the future date when this representation expire. If this information is not known, pass null.

Overrides:
setExpirationDate in class Variant
Parameters:
expirationDate - The expiration date.

setModificationDate

public void setModificationDate(java.util.Date modificationDate)
Sets the last date when this representation was modified. If this information is not known, pass null.

Overrides:
setModificationDate in class Variant
Parameters:
modificationDate - The modification date.

setRange

public void setRange(Range range)
Sets the range where in the full content the partial content available should be applied.

Parameters:
range - The content range.

setSize

public void setSize(long expectedSize)
Sets the expected size in bytes if known, -1 otherwise.

Overrides:
setSize in class Variant
Parameters:
expectedSize - The expected size in bytes if known, -1 otherwise.

setTag

public void setTag(Tag tag)
Sets the tag.

Overrides:
setTag in class Variant
Parameters:
tag - The tag.

setTransient

public void setTransient(boolean isTransient)
Indicates if the representation's content is transient.

Parameters:
isTransient - True if the representation's content is transient.

write

public abstract void write(java.io.OutputStream outputStream)
                    throws java.io.IOException
Writes the representation to a byte stream. This method is ensured to write the full content for each invocation unless it is a transient representation, in which case an exception is thrown.

Parameters:
outputStream - The output stream.
Throws:
java.io.IOException

write

public abstract void write(java.nio.channels.WritableByteChannel writableChannel)
                    throws java.io.IOException
Writes the representation to a byte channel. This method is ensured to write the full content for each invocation unless it is a transient representation, in which case an exception is thrown.

Parameters:
writableChannel - A writable byte channel.
Throws:
java.io.IOException

write

public abstract void write(java.io.Writer writer)
                    throws java.io.IOException
Writes the representation to a characters writer. This method is ensured to write the full content for each invocation unless it is a transient representation, in which case an exception is thrown.

Parameters:
writer - The characters writer.
Throws:
java.io.IOException


Copyright © 2005-2008 Noelios Technologies.