Package org.restlet.client.util

Class WrapperRepresentation

  • 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

    • Method Summary

      All Methods Instance Methods Concrete Methods 
      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.
      Disposition getDisposition()
      Returns the disposition characteristics of the representation.
      java.util.List<Encoding> getEncodings()
      Returns the modifiable list of encodings applied to the entity-body.
      java.util.Date getExpirationDate()
      Returns the future date when this representation expire.
      java.util.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.
      java.util.Date getModificationDate()
      Returns the last date when this representation was modified.
      java.io.Reader getReader()
      Returns a characters reader with the representation's content.
      long getSize()
      Returns the total size in bytes if known, UNKNOWN_SIZE (-1) otherwise.
      java.io.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.
      java.lang.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 setDisposition​(Disposition disposition)
      Sets the disposition characteristics of the representation.
      void setEncodings​(java.util.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​(java.util.Date expirationDate)
      Sets the future date when this representation expire.
      void setLanguages​(java.util.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​(java.lang.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​(java.util.Date modificationDate)
      Sets the last date when this representation was modified.
      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.

      • Methods inherited from class java.lang.Object

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

    • Constructor Detail

      • WrapperRepresentation

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

    • Method Detail

      • exhaust

        public long exhaust()
             throws java.io.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:
        java.io.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.

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

      • getReader

        public java.io.Reader getReader()
                         throws java.io.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:
        java.io.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:
        Representation.isEmpty()

      • getStream

        public java.io.InputStream getStream()
                              throws java.io.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:
        java.io.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 java.lang.String getText()
                         throws java.io.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.
        Specified by:
        getText in class Representation
        Returns:
        The representation as a string value.
        Throws:
        java.io.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 org.restlet.client.resource.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.

      • 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​(java.util.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​(java.util.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​(java.util.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​(java.lang.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​(java.util.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.

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