org.restlet.resource
Class Representation

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

public abstract class Representation
extends Variant

Current or intended state of a resource. 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 (contact@noelios.com)
See Also:
Source dissertation

Field Summary
 
Fields inherited from class org.restlet.resource.Variant
UNKNOWN_SIZE
 
Constructor Summary
Representation()
          Default constructor.
Representation(MediaType mediaType)
          Constructor.
 
Method Summary
abstract  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.
abstract  InputStream getStream()
          Returns a stream with the representation's content.
 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 isTransient()
          Indicates if the representation's content is transient, which means that it can be obtained only once.
 void setAvailable(boolean available)
          Indicates if some fresh content is available.
 void setTransient(boolean isTransient)
          Indicates if the representation's content is transient.
abstract  void write(OutputStream outputStream)
          Writes the representation to a byte stream.
abstract  void write(WritableByteChannel writableChannel)
          Writes the representation to a byte channel.
 
Methods inherited from class org.restlet.resource.Variant
getCharacterSet, getEncodings, getExpirationDate, getIdentifier, getLanguages, getMediaType, getModificationDate, getSize, getTag, setCharacterSet, setExpirationDate, setIdentifier, setIdentifier, setMediaType, setModificationDate, setSize, setTag
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

Representation

public Representation()
Default constructor.


Representation

public Representation(MediaType mediaType)
Constructor.

Parameters:
mediaType - The media type.
Method Detail

getChannel

public abstract ReadableByteChannel getChannel()
                                        throws 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:
IOException

getStream

public abstract InputStream getStream()
                               throws 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:
IOException

getText

public String getText()
               throws 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:
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.

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.

setAvailable

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

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

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(OutputStream outputStream)
                    throws 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:
IOException

write

public abstract void write(WritableByteChannel writableChannel)
                    throws 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:
IOException


Copyright © 2005-2007 Noelios Consulting.