Package org.restlet.representation

Class 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 
      Modifier and Type Field Description
      static long UNKNOWN_SIZE
      Indicates that the size of the representation can't be known in advance.

    • Method Summary

      All Methods Instance Methods Abstract Methods Concrete Methods 
      Modifier and Type Method Description
      void append​(java.lang.Appendable appendable)
      Appends the representation to an appendable sequence of characters.
      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.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.
      SelectionRegistration getRegistration()
      Returns the NIO registration of the related channel with its selector.
      long getSize()
      Returns the total size in bytes if known, UNKNOWN_SIZE (-1) otherwise.
      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 hasKnownSize()
      Indicates if the size of representation is known.
      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 isEmpty()
      Indicates if the representation is empty.
      boolean isSelectable()
      Indicates if the representation content supports NIO selection.
      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 setExpirationDate​(java.util.Date expirationDate)
      Sets the future date when this representation expire.
      void setListener​(ReadingListener readingListener)
      Sets a listener for NIO read events.
      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 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.io.Writer writer)
      Writes the representation to a characters writer.
      abstract void write​(java.nio.channels.WritableByteChannel writableChannel)
      Writes the representation to a byte channel.

      • Methods inherited from class java.lang.Object

        clone, finalize, getClass, 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

      • append

        public void append​(java.lang.Appendable appendable)
            throws java.io.IOException
        Appends the representation to an appendable sequence of characters. 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 getText() is used by the default implementation.
        Parameters:
        appendable - The appendable sequence of characters.
        Throws:
        java.io.IOException

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

      • 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

      • getRegistration

        public SelectionRegistration getRegistration()
                                      throws java.io.IOException
        Returns the NIO registration of the related channel with its selector. You can modify this registration to be called back when some readable content is available. Note that the listener will keep being called back until you suspend or cancel the registration returned by this method.
        Returns:
        The NIO registration.
        Throws:
        java.io.IOException
        See Also:
        isSelectable()

      • getSize

        public long getSize()
        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 getAvailableSize() method.

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

      • 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

      • hasKnownSize

        public boolean hasKnownSize()
        Indicates if the size of representation is known. It basically means that its size 0 or superior.
        Returns:
        True if the representation has content.

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

      • isEmpty

        public boolean isEmpty()
        Indicates if the representation is empty. It basically means that its size is 0.
        Returns:
        True if the representation has no content.

      • isSelectable

        public boolean isSelectable()
        Indicates if the representation content supports NIO selection. In this case, the getRegistration() method can be called to be notified when new content is ready for reading.
        Returns:
        True if the representation content supports NIO selection.

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

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

      • setListener

        public void setListener​(ReadingListener readingListener)
        Sets a listener for NIO read events. If the listener is null, it clear any existing listener.
        Parameters:
        readingListener - The listener for NIO read events.

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

        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