Package 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:
BufferingRepresentation, DecodeRepresentation, DigesterRepresentation, EncodeRepresentation, RangeRepresentation
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:

  • Field Summary

    Fields inherited from class org.restlet.representation.Representation

    UNKNOWN_SIZE

  • Constructor Summary

    Constructors
    Constructor
    Description
    WrapperRepresentation(Representation wrappedRepresentation)
    Constructor.

  • Method Summary

    Modifier and Type
    Method
    Description
    long
    exhaust()
    Exhaust the content of the representation by reading it and silently discarding anything read.
    long
    getAvailableSize()
    Returns the size effectively available.
    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.
    List<Encoding>
    getEncodings()
    Returns the modifiable list of encodings applied to the entity-body.
    Date
    getExpirationDate()
    Returns the future date when this representation expire.
    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 character reader with the representation's content.
    long
    getSize()
    Returns the total size in bytes if known, UNKNOWN_SIZE (-1) otherwise.
    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
    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
    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
    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(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
    setLocationRef(Reference location)
    Sets the optional identifier.
    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.
    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(Writer writer)
    Writes the representation to a characters writer.

    Methods inherited from class org.restlet.representation.Representation

    append, hasKnownSize, isEmpty

    Methods inherited from class org.restlet.representation.Variant

    createClientInfo, equals, hashCode, includes, isCompatible, toString

    Methods inherited from class java.lang.Object

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

  • Constructor Details

    • WrapperRepresentation

      public WrapperRepresentation(Representation wrappedRepresentation)
      Constructor.
      Parameters:
      wrappedRepresentation - The wrapped representation.

  • Method Details

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

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

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

    • 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 character 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 total size in bytes if known, UNKNOWN_SIZE (-1) otherwise. When ranges are used, this might not be the actual size available. For this purpose, you can use the Representation.getAvailableSize() method.

      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.
      See Also:

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

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

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

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

    • 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. For this purpose, you can use the Representation.getAvailableSize() method.

      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