org.restlet.representation

## Class Representation

- java.lang.Object
- - org.restlet.representation.Variant
  - - org.restlet.representation.RepresentationInfo
    - - org.restlet.representation.Representation

Direct Known Subclasses:
  ChannelRepresentation, CharacterRepresentation, EmptyRepresentation, FileRepresentation, 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

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

### Constructor Summary

Constructors
Constructor and Description
`Representation()` Default constructor.
`Representation(MediaType mediaType)` Constructor.
`Representation(MediaType mediaType, java.util.Date modificationDate)` Constructor.
`Representation(MediaType mediaType, java.util.Date modificationDate, Tag tag)` Constructor.
`Representation(MediaType mediaType, Tag tag)` Constructor.
`Representation(Variant variant, java.util.Date modificationDate)` Constructor from a variant.
`Representation(Variant variant, java.util.Date modificationDate, Tag tag)` Constructor from a variant.
`Representation(Variant variant, Tag tag)` Constructor from a variant.

### Method Summary

Methods
`boolean` `checkDigest()` Deprecated. Use a `DigesterRepresentation` instead.
`boolean` `checkDigest(java.lang.String algorithm)` Deprecated. Use a `DigesterRepresentation` instead.
`Digest` `computeDigest(java.lang.String algorithm)` Deprecated. Use a `DigesterRepresentation` instead.
`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.
`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. Note that when used with HTTP connectors, this property maps to the "Content-MD5" header.
`Disposition` `getDisposition()` Returns the disposition characteristics of the representation.
`java.lang.String` `getDownloadName()` Deprecated. Use the "disposition" attribute instead.
`java.util.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 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. Note that when used with HTTP connectors, this property maps to the "Content-Length" header.
`abstract java.io.InputStream` `getStream()` Returns a stream with the representation's content.
`java.lang.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` `setDigest(Digest digest)` Sets the representation digest. Note that when used with HTTP connectors, this property maps to the "Content-MD5" header.
`void` `setDisposition(Disposition disposition)` Sets the disposition characteristics of the representation.
`void` `setDownloadable(boolean downloadable)` Deprecated. Use the "disposition" attribute instead.
`void` `setDownloadName(java.lang.String fileName)` Deprecated. Use the "disposition" attribute instead.
`void` `setExpirationDate(java.util.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.
`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.representation.RepresentationInfo

`getModificationDate, getTag, setModificationDate, setTag`

### Methods inherited from class org.restlet.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,
                  java.util.Date modificationDate)

Constructor.

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

#### Representation

    public Representation(MediaType mediaType,
                  java.util.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,
                  java.util.Date modificationDate)

Constructor from a variant.

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

#### Representation

    public Representation(Variant variant,
                  java.util.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.

#### checkDigest

    @Deprecated
    public boolean checkDigest()

Deprecated. Use a `DigesterRepresentation` instead.
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

    @Deprecated
    public boolean checkDigest(java.lang.String algorithm)

Deprecated. Use a `DigesterRepresentation` instead.
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

    @Deprecated
    public Digest computeDigest(java.lang.String algorithm)

Deprecated. Use a `DigesterRepresentation` instead.
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

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:
  `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.
Note that when used with HTTP connectors, this property maps to the "Content-MD5" header.

Returns:
  The representation digest or null.

#### getDisposition

    public Disposition getDisposition()

Returns the disposition characteristics of the representation.

Returns:
  The disposition characteristics of the representation.

#### getDownloadName

    @Deprecated
    public java.lang.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=<downloadName>".

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.
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 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.
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 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`

#### 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 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.

#### 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.

#### setDigest

    public void setDigest(Digest digest)

Sets the representation digest.
Note that when used with HTTP connectors, this property maps to the "Content-MD5" header.

Parameters:
  `digest` - The representation digest.

#### 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(java.lang.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=<downloadName>".

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.
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.

#### 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.
Note that the class implementing this method shouldn't flush or close the given `Writer` after writing to it as this will be handled by the Restlet connectors automatically.

Parameters:
  `writer` - The characters writer.
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.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.
Note that the class implementing this method shouldn't flush or close the given `OutputStream` after writing to it as this will be handled by the Restlet connectors automatically.

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