org.restlet.util
Class WrapperRepresentation

java.lang.Object
  org.restlet.representation.Variant
      org.restlet.representation.RepresentationInfo
          org.restlet.representation.Representation
              org.restlet.util.WrapperRepresentation

Direct Known Subclasses:

DigesterRepresentation, DigestRepresentation

public class WrapperRepresentation
extends Representation

Representation wrapper. Useful for application developer who need to enrich the representation with application related properties and behavior.

Author:

Jerome Louvel

See Also:

The decorator (aka wrapper) pattern

Field Summary

Fields inherited from class org.restlet.representation.Representation

UNKNOWN_SIZE

Constructor Summary

WrapperRepresentation(Representation wrappedRepresentation)
Constructor.

Method Summary

boolean	checkDigest() Deprecated.
boolean	checkDigest(String algorithm) Deprecated.
Digest	computeDigest(String algorithm) Deprecated.
long	exhaust() Exhaust the content of the representation by reading it and silently discarding anything read.
long	getAvailableSize() Returns the size effectively available.
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.
CharacterSet	getCharacterSet() Returns the character set or null if not applicable.
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.
String	getDownloadName() Deprecated.
List<Encoding>	getEncodings() Returns the modifiable list of encodings applied to the entity-body.
Date	getExpirationDate() Returns the future date when this representation expire.
Reference	getIdentifier() Returns an optional identifier.
List<Language>	getLanguages() Returns the modifiable list of languages.
Reference	getLocationRef() Returns an optional location reference.
MediaType	getMediaType() Returns the media type. Note that when used with HTTP connectors, this property maps to the "Content-Type" header.
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. Note that when used with HTTP connectors, this property maps to the "Content-Range" header.
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.
InputStream	getStream() Returns a stream with the representation's content.
Tag	getTag() Returns the tag. Note that when used with HTTP connectors, this property maps to the "ETag" header.
String	getText() Converts the representation to a string value.
Representation	getWrappedRepresentation() Returns the wrapped representation.
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.
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 isAvailable) Indicates if some fresh content is available.
void	setCharacterSet(CharacterSet characterSet) Sets the character set or null if not applicable. Note that when used with HTTP connectors, this property maps to the "Content-Type" header.
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.
void	setDownloadName(String fileName) Deprecated.
void	setEncodings(List<Encoding> encodings) Sets the list of encodings applied to the entity-body. Note that when used with HTTP connectors, this property maps to the "Content-Encoding" header.
void	setExpirationDate(Date expirationDate) Sets the future date when this representation expire.
void	setIdentifier(Reference identifier) Sets the optional identifier.
void	setIdentifier(String identifierUri) Sets the identifier from a URI string. Note that when used with HTTP connectors, this property maps to the "Content-Location" header.
void	setLanguages(List<Language> languages) Sets the list of languages. Note that when used with HTTP connectors, this property maps to the "Content-Language" header.
void	setLocationRef(Reference location) Sets the optional identifier.
void	setLocationRef(String locationUri) Sets the identifier from a URI string. Note that when used with HTTP connectors, this property maps to the "Content-Location" header.
void	setMediaType(MediaType mediaType) Sets the media type. Note that when used with HTTP connectors, this property maps to the "Content-Type" header.
void	setModificationDate(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. 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	setTag(Tag tag) Sets the tag. Note that when used with HTTP connectors, this property maps to the "ETag" header.
void	setTransient(boolean isTransient) Indicates if the representation's content is transient.
void	write(OutputStream outputStream) Writes the representation to a byte stream.
void	write(WritableByteChannel writableChannel) Writes the representation to a byte channel.
void	write(Writer writer) Writes the representation to a characters writer.

Methods inherited from class org.restlet.representation.Representation

createEmpty

Methods inherited from class org.restlet.representation.Variant

createClientInfo, equals, includes, isCompatible, toString

Methods inherited from class java.lang.Object

clone, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

WrapperRepresentation

public WrapperRepresentation(Representation wrappedRepresentation)

Constructor.

Parameters:

wrappedRepresentation - The wrapped representation.

Method Detail

checkDigest

@Deprecated
public boolean checkDigest()

Deprecated.

Description copied from class: Representation

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

Overrides:

checkDigest in class Representation

Returns:

True if both digests are not null and equals.

checkDigest

@Deprecated
public boolean checkDigest(String algorithm)

Deprecated.

Description copied from class: Representation

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

Overrides:

checkDigest in class Representation

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(String algorithm)

Deprecated.

Description copied from class: Representation

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

Overrides:

computeDigest in class Representation

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 IOException

Description copied from class: Representation

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

Overrides:

exhaust in class Representation

Returns:

The number of bytes consumed or -1 if unknown.

Throws:

IOException

getAvailableSize

public long getAvailableSize()

Description copied from class: Representation

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

Overrides:

getAvailableSize in class Representation

Returns:

The available size.

getChannel

public ReadableByteChannel getChannel()
                               throws IOException

Description copied from class: Representation

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.

Specified by:

getChannel in class Representation

Returns:

A channel with the representation's content.

Throws:

IOException

getCharacterSet

public CharacterSet getCharacterSet()

Description copied from class: Variant

Returns the character set or null if not applicable. Note that when used with HTTP connectors, this property maps to the "Content-Type" header.

Overrides:

getCharacterSet in class Variant

Returns:

The character set or null if not applicable.

getDigest

public Digest getDigest()

Description copied from class: Representation

Returns the representation digest if any.

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

Overrides:

getDigest in class Representation

Returns:

The representation digest or null.

getDisposition

public Disposition getDisposition()

Description copied from class: Representation

Returns the disposition characteristics of the representation.

Overrides:

getDisposition in class Representation

Returns:

The disposition characteristics of the representation.

getDownloadName

@Deprecated
public String getDownloadName()

Deprecated.

Description copied from class: Representation

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

Overrides:

getDownloadName in class Representation

Returns:

The suggested file name for this representation.

getEncodings

public List<Encoding> getEncodings()

Description copied from class: Variant

Returns the modifiable list of encodings applied to the entity-body. Creates a new instance if no one has been set. An "IllegalArgumentException" exception is thrown when adding a null encoding to this list.

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

Overrides:

getEncodings in class Variant

Returns:

The list of encodings applied to the entity-body.

getExpirationDate

public Date getExpirationDate()

Description copied from class: Representation

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.

Overrides:

getExpirationDate in class Representation

Returns:

The expiration date.

getIdentifier

public Reference getIdentifier()

Description copied from class: Variant

Returns an optional identifier. This is useful when the representation is accessible from a location separate from the representation's resource URI, for example when content negotiation occurs.

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

Overrides:

getIdentifier in class Variant

Returns:

The identifier.

getLanguages

public List<Language> getLanguages()

Description copied from class: Variant

Returns the modifiable list of languages. Creates a new instance if no one has been set. An "IllegalArgumentException" exception is thrown when adding a null language to this list.

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

Overrides:

getLanguages in class Variant

Returns:

The list of languages.

getLocationRef

public Reference getLocationRef()

Description copied from class: Variant

Returns an optional location reference. This is useful when the representation is accessible from a location separate from the representation's resource URI, for example when content negotiation occurs.

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

Overrides:

getLocationRef in class Variant

Returns:

The identifier.

getMediaType

public MediaType getMediaType()

Description copied from class: Variant

Returns the media type.

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

Overrides:

getMediaType in class Variant

Returns:

The media type.

getModificationDate

public Date getModificationDate()

Description copied from class: RepresentationInfo

Returns the last date when this representation was modified. If this information is not known, returns null.

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

Overrides:

getModificationDate in class RepresentationInfo

Returns:

The modification date.

getRange

public Range getRange()

Description copied from class: Representation

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.

Overrides:

getRange in class Representation

Returns:

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

getReader

public Reader getReader()
                 throws IOException

Description copied from class: Representation

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.

Specified by:

getReader in class Representation

Returns:

A reader with the representation's content.

Throws:

IOException

getSize

public long getSize()

Description copied from class: Representation

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.

Overrides:

getSize in class Representation

Returns:

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

getStream

public InputStream getStream()
                      throws IOException

Description copied from class: Representation

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.

Specified by:

getStream in class Representation

Returns:

A stream with the representation's content.

Throws:

IOException

getTag

public Tag getTag()

Description copied from class: RepresentationInfo

Returns the tag.

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

Overrides:

getTag in class RepresentationInfo

Returns:

The tag.

getText

public String getText()
               throws IOException

Description copied from class: Representation

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.

Overrides:

getText in class Representation

Returns:

The representation as a string value.

Throws:

IOException

getWrappedRepresentation

public Representation getWrappedRepresentation()

Returns the wrapped representation.

Returns:

The wrapped representation.

isAvailable

public boolean isAvailable()

Description copied from class: Representation

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.

Overrides:

isAvailable in class Representation

Returns:

True if some fresh content is available.

isDownloadable

@Deprecated
public boolean isDownloadable()

Deprecated.

Description copied from class: Representation

Indicates if the representation is downloadable which means that it can be obtained via a download dialog box.

Overrides:

isDownloadable in class Representation

Returns:

True if the representation's content is downloadable.

isTransient

public boolean isTransient()

Description copied from class: Representation

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.

Overrides:

isTransient in class Representation

Returns:

True if the representation's content is transient.

release

public void release()

Description copied from class: Representation

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 Representation.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 Representation.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().

Overrides:

release in class Representation

setAvailable

public void setAvailable(boolean isAvailable)

Description copied from class: Representation

Indicates if some fresh content is available.

Overrides:

setAvailable in class Representation

Parameters:

isAvailable - True if some fresh content is available.

setCharacterSet

public void setCharacterSet(CharacterSet characterSet)

Description copied from class: Variant

Sets the character set or null if not applicable.

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

Overrides:

setCharacterSet in class Variant

Parameters:

characterSet - The character set or null if not applicable.

setDigest

public void setDigest(Digest digest)

Description copied from class: Representation

Sets the representation digest.

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

Overrides:

setDigest in class Representation

Parameters:

digest - The representation digest.

setDisposition

public void setDisposition(Disposition disposition)

Description copied from class: Representation

Sets the disposition characteristics of the representation.

Overrides:

setDisposition in class Representation

Parameters:

disposition - The disposition characteristics of the representation.

setDownloadable

@Deprecated
public void setDownloadable(boolean downloadable)

Deprecated.

Description copied from class: Representation

Indicates if the representation is downloadable which means that it can be obtained via a download dialog box.

Overrides:

setDownloadable in class Representation

Parameters:

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

setDownloadName

@Deprecated
public void setDownloadName(String fileName)

Deprecated.

Description copied from class: Representation

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

Overrides:

setDownloadName in class Representation

Parameters:

fileName - The suggested file name.

setEncodings

public void setEncodings(List<Encoding> encodings)

Description copied from class: Variant

Sets the list of encodings applied to the entity-body.

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

Overrides:

setEncodings in class Variant

Parameters:

encodings - The list of encodings applied to the entity-body.

setExpirationDate

public void setExpirationDate(Date expirationDate)

Description copied from class: Representation

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.

Overrides:

setExpirationDate in class Representation

Parameters:

expirationDate - The expiration date.

setIdentifier

public void setIdentifier(Reference identifier)

Description copied from class: Variant

Sets the optional identifier. This is useful when the representation is accessible from a location separate from the representation's resource URI, for example when content negotiation occurs.

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

Overrides:

setIdentifier in class Variant

Parameters:

identifier - The identifier.

setIdentifier

public void setIdentifier(String identifierUri)

Description copied from class: Variant

Sets the identifier from a URI string.

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

Overrides:

setIdentifier in class Variant

Parameters:

identifierUri - The identifier to parse.

See Also:

Variant.setIdentifier(Reference)

setLanguages

public void setLanguages(List<Language> languages)

Description copied from class: Variant

Sets the list of languages.

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

Overrides:

setLanguages in class Variant

Parameters:

languages - The list of languages.

setLocationRef

public void setLocationRef(Reference location)

Description copied from class: Variant

Sets the optional identifier. This is useful when the representation is accessible from a location separate from the representation's resource URI, for example when content negotiation occurs.

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

Overrides:

setLocationRef in class Variant

Parameters:

location - The location reference.

setLocationRef

public void setLocationRef(String locationUri)

Description copied from class: Variant

Sets the identifier from a URI string.

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

Overrides:

setLocationRef in class Variant

Parameters:

locationUri - The location URI to parse.

See Also:

Variant.setIdentifier(Reference)

setMediaType

public void setMediaType(MediaType mediaType)

Description copied from class: Variant

Sets the media type.

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

Overrides:

setMediaType in class Variant

Parameters:

mediaType - The media type.

setModificationDate

public void setModificationDate(Date modificationDate)

Description copied from class: RepresentationInfo

Sets the last date when this representation was modified. If this information is not known, pass null.

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

Overrides:

setModificationDate in class RepresentationInfo

Parameters:

modificationDate - The modification date.

setRange

public void setRange(Range range)

Description copied from class: Representation

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.

Overrides:

setRange in class Representation

Parameters:

range - The content range.

setSize

public void setSize(long expectedSize)

Description copied from class: Representation

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.

Overrides:

setSize in class Representation

Parameters:

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

setTag

public void setTag(Tag tag)

Description copied from class: RepresentationInfo

Sets the tag.

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

Overrides:

setTag in class RepresentationInfo

Parameters:

tag - The tag.

setTransient

public void setTransient(boolean isTransient)

Description copied from class: Representation

Indicates if the representation's content is transient.

Overrides:

setTransient in class Representation

Parameters:

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

write

public void write(OutputStream outputStream)
           throws IOException

Description copied from class: Representation

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.

Specified by:

write in class Representation

Parameters:

outputStream - The output stream.

Throws:

IOException

write

public void write(Writer writer)
           throws IOException

Description copied from class: Representation

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.

Specified by:

write in class Representation

Parameters:

writer - The characters writer.

Throws:

IOException

write

public void write(WritableByteChannel writableChannel)
           throws IOException

Description copied from class: Representation

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.

Specified by:

write in class Representation

Parameters:

writableChannel - A writable byte channel.

Throws:

IOException