org.restlet.client.representation
Class Representation

java.lang.Object
  extended by org.restlet.client.representation.Variant
      extended by org.restlet.client.representation.RepresentationInfo
          extended by org.restlet.client.representation.Representation
Direct Known Subclasses:
CharacterRepresentation, EmptyRepresentation, StreamRepresentation, WrapperRepresentation

public abstract class Representation
extends RepresentationInfo

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.
Representation(MediaType mediaType, Date modificationDate)
          Constructor.
Representation(MediaType mediaType, Date modificationDate, Tag tag)
          Constructor.
Representation(MediaType mediaType, Tag tag)
          Constructor.
Representation(Variant variant, Date modificationDate)
          Constructor from a variant.
Representation(Variant variant, Date modificationDate, Tag tag)
          Constructor from a variant.
Representation(Variant variant, Tag tag)
          Constructor from a variant.
 
Method Summary
static Representation createEmpty()
          Deprecated. Use EmptyRepresentation instead.
 long exhaust()
          Exhaust the content of the representation by reading it and silently discarding anything read.
 long getAvailableSize()
          Returns the size effectively available.
 Disposition getDisposition()
          Returns the disposition characteristics of the representation.
 String getDownloadName()
          Deprecated. Use the "disposition" attribute instead.
 Date getExpirationDate()
          Returns the future date when this representation expire.
 Range getRange()
          Returns the range where in the full content the partial content available should be applied.

Note that when used with HTTP connectors, this property maps to the "Content-Range" header.
abstract  Reader getReader()
          Returns a characters reader with the representation's content.
 long getSize()
          Returns the size in bytes if known, UNKNOWN_SIZE (-1) otherwise.

Note that when used with HTTP connectors, this property maps to the "Content-Length" header.
abstract  InputStream getStream()
          Returns a stream with the representation's content.
abstract  String getText()
          Converts the representation to a string value.
 boolean isAvailable()
          Indicates if some fresh content is potentially available, without having to actually call one of the content manipulation method like getStream() that would actually consume it.
 boolean isDownloadable()
          Deprecated. Use the "disposition" attribute instead.
 boolean isTransient()
          Indicates if the representation's content is transient, which means that it can be obtained only once.
 void release()
          Releases the representation and all associated objects like streams, channels or files which are used to produce its content, transient or not.
 void setAvailable(boolean available)
          Indicates if some fresh content is available.
 void setDisposition(Disposition disposition)
          Sets the disposition characteristics of the representation.
 void setDownloadable(boolean downloadable)
          Deprecated. Use the "disposition" attribute instead.
 void setDownloadName(String fileName)
          Deprecated. Use the "disposition" attribute instead.
 void setExpirationDate(Date expirationDate)
          Sets the future date when this representation expire.
 void setRange(Range range)
          Sets the range where in the full content the partial content available should be applied.

Note that when used with HTTP connectors, this property maps to the "Content-Range" header.
 void setSize(long expectedSize)
          Sets the expected size in bytes if known, -1 otherwise.

Note that when used with HTTP connectors, this property maps to the "Content-Length" header.
 void setTransient(boolean isTransient)
          Indicates if the representation's content is transient.
 
Methods inherited from class org.restlet.client.representation.RepresentationInfo
getModificationDate, getTag, setModificationDate, setTag
 
Methods inherited from class org.restlet.client.representation.Variant
createClientInfo, equals, getCharacterSet, getEncodings, getIdentifier, getLanguages, getLocationRef, getMediaType, includes, isCompatible, setCharacterSet, setEncodings, setIdentifier, setIdentifier, setLanguages, setLocationRef, setLocationRef, setMediaType, toString
 
Methods inherited from class java.lang.Object
clone, finalize, getClass, hashCode, notify, notifyAll, 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.

Representation

public Representation(MediaType mediaType,
                      Date modificationDate)
Constructor.

Parameters:
mediaType - The media type.
modificationDate - The modification date.

Representation

public Representation(MediaType mediaType,
                      Date modificationDate,
                      Tag tag)
Constructor.

Parameters:
mediaType - The media type.
modificationDate - The modification date.
tag - The tag.

Representation

public Representation(MediaType mediaType,
                      Tag tag)
Constructor.

Parameters:
mediaType - The media type.
tag - The tag.

Representation

public Representation(Variant variant,
                      Date modificationDate)
Constructor from a variant.

Parameters:
variant - The variant to copy.
modificationDate - The modification date.

Representation

public Representation(Variant variant,
                      Date modificationDate,
                      Tag tag)
Constructor from a variant.

Parameters:
variant - The variant to copy.
modificationDate - The modification date.
tag - The tag.

Representation

public Representation(Variant variant,
                      Tag tag)
Constructor from a variant.

Parameters:
variant - The variant to copy.
tag - The tag.
Method Detail

createEmpty

@Deprecated
public static Representation createEmpty()
Deprecated. Use EmptyRepresentation instead.

Returns a new empty representation with no content.

Returns:
A new empty representation.

exhaust

public long exhaust()
             throws IOException
Exhaust the content of the representation by reading it and silently discarding anything read. By default, it relies on getStream() and closes the retrieved stream in the end.

Returns:
The number of bytes consumed or -1 if unknown.
Throws:
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.

getDisposition

public Disposition getDisposition()
Returns the disposition characteristics of the representation.

Returns:
The disposition characteristics of the representation.

getDownloadName

@Deprecated
public String getDownloadName()
Deprecated. Use the "disposition" attribute instead.

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.

Note that when used with HTTP connectors, this property maps to the "Content-Disposition" header with this value: "inline; filename=".

Returns:
The suggested file name for this representation.

getExpirationDate

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

Note that when used with HTTP connectors, this property maps to the "Expires" header.

Returns:
The expiration date.

getRange

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

Note that when used with HTTP connectors, this property maps to the "Content-Range" header.

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

getReader

public abstract Reader getReader()
                          throws 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:
IOException

getSize

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

Note that when used with HTTP connectors, this property maps to the "Content-Length" header.

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

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

isAvailable

public boolean isAvailable()
Indicates if some fresh content is potentially available, without having to actually call one of the content manipulation method like getStream() that would actually consume it. Note that when the size of a representation is 0 is a not considered available. However, sometimes the size isn't known until a read attempt is made, so availability doesn't guarantee a non empty content.

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.

getText

public abstract 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

isDownloadable

@Deprecated
public boolean isDownloadable()
Deprecated. Use the "disposition" attribute instead.

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 and all associated objects like streams, channels or files which are used to produce its content, transient or not. This method must be systematically called when the representation is no longer intended to be used. The framework automatically calls back this method via its connectors on the server-side when sending responses with an entity and on the client-side when sending a request with an entity. By default, it calls the setAvailable(boolean) method with "false" as a value.

Note that for transient socket-bound representations, calling this method after consuming the whole content shouldn't prevent the reuse of underlying socket via persistent connections for example. However, if the content hasn't been read, or has been partially read, the impact should be to discard the remaining content and to close the underlying connections.

Therefore, if you are not interested in the content, or in the remaining content, you should first call the exhaust() method or if this could be too costly, you should instead explicitly abort the parent request and the underlying connections using the Request#abort() method or a shortcut one like ServerResource#abort() or Response#abort().


setAvailable

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

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

setDisposition

public void setDisposition(Disposition disposition)
Sets the disposition characteristics of the representation.

Parameters:
disposition - The disposition characteristics of the representation.

setDownloadable

@Deprecated
public void setDownloadable(boolean downloadable)
Deprecated. Use the "disposition" attribute instead.

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

@Deprecated
public void setDownloadName(String fileName)
Deprecated. Use the "disposition" attribute instead.

Set the suggested download file name for this representation.

Note that when used with HTTP connectors, this property maps to the "Content-Disposition" header with this value: "inline; filename=".

Parameters:
fileName - The suggested file name.

setExpirationDate

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

Note that when used with HTTP connectors, this property maps to the "Expires" header.

Parameters:
expirationDate - The expiration date.

setRange

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

Note that when used with HTTP connectors, this property maps to the "Content-Range" header.

Parameters:
range - The content range.

setSize

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

Note that when used with HTTP connectors, this property maps to the "Content-Length" header.

Parameters:
expectedSize - The expected size in bytes if known, -1 otherwise.

setTransient

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

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


Copyright © 2005-2011 Noelios Technologies.