|
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Objectorg.restlet.representation.Variant
org.restlet.representation.RepresentationInfo
org.restlet.representation.Representation
public abstract class Representation
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
Field Summary | |
---|---|
static long |
UNKNOWN_SIZE
Indicates that the size of the representation can't be known in advance. |
Constructor Summary | |
---|---|
Representation()
Default constructor. |
|
Representation(MediaType mediaType)
Constructor. |
|
Representation(MediaType mediaType,
Date modificationDate)
Constructor. |
|
Representation(MediaType mediaType,
Date modificationDate,
Tag tag)
Constructor. |
|
Representation(MediaType mediaType,
Tag tag)
Constructor. |
|
Representation(Variant variant,
Date modificationDate)
Constructor from a variant. |
|
Representation(Variant variant,
Date modificationDate,
Tag tag)
Constructor from a variant. |
|
Representation(Variant variant,
Tag tag)
Constructor from a variant. |
Method Summary | |
---|---|
void |
append(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 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. |
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 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 InputStream |
getStream()
Returns a stream with the representation's content. |
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(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(OutputStream outputStream)
Writes the representation to a byte stream. |
abstract void |
write(WritableByteChannel writableChannel)
Writes the representation to a byte channel. |
abstract void |
write(Writer writer)
Writes the representation to a characters writer. |
Methods inherited from class org.restlet.representation.RepresentationInfo |
---|
getModificationDate, getTag, setModificationDate, setTag |
Methods inherited from class org.restlet.representation.Variant |
---|
createClientInfo, equals, getCharacterSet, getEncodings, getLanguages, getLocationRef, getMediaType, includes, isCompatible, setCharacterSet, setEncodings, setLanguages, setLocationRef, setLocationRef, setMediaType, toString |
Methods inherited from class java.lang.Object |
---|
clone, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait |
Field Detail |
---|
public static final long UNKNOWN_SIZE
Constructor Detail |
---|
public Representation()
public Representation(MediaType mediaType)
mediaType
- The media type.public Representation(MediaType mediaType, Date modificationDate)
mediaType
- The media type.modificationDate
- The modification date.public Representation(MediaType mediaType, Date modificationDate, Tag tag)
mediaType
- The media type.modificationDate
- The modification date.tag
- The tag.public Representation(MediaType mediaType, Tag tag)
mediaType
- The media type.tag
- The tag.public Representation(Variant variant, Date modificationDate)
variant
- The variant to copy.modificationDate
- The modification date.public Representation(Variant variant, Date modificationDate, Tag tag)
variant
- The variant to copy.modificationDate
- The modification date.tag
- The tag.public Representation(Variant variant, Tag tag)
variant
- The variant to copy.tag
- The tag.Method Detail |
---|
public void append(Appendable appendable) throws IOException
getText()
is used by the default implementation.
appendable
- The appendable sequence of characters.
IOException
public long exhaust() throws IOException
getStream()
and closes the retrieved stream in the end.
IOException
public long getAvailableSize()
getSize()
if no range is defined, otherwise it returns the size
of the range using Range.getSize()
.
public abstract ReadableByteChannel getChannel() throws IOException
IOException
public Digest getDigest()
public Disposition getDisposition()
public Date getExpirationDate()
public Range getRange()
public abstract Reader getReader() throws IOException
IOException
public SelectionRegistration getRegistration() throws IOException
IOException
isSelectable()
public long getSize()
getAvailableSize()
method.
isEmpty()
public abstract InputStream getStream() throws IOException
IOException
public String getText() throws IOException
IOException
public boolean hasKnownSize()
public boolean isAvailable()
public boolean isEmpty()
public boolean isSelectable()
org.restlet.engine.connector.ConnectionController#register(java.nio.channels.SelectableChannel, int, org.restlet.util.SelectionListener)
method can be called to be notified when new content is ready for
reading.
org.restlet.engine.connector.ConnectionController
public boolean isTransient()
public void release()
setAvailable(boolean)
method
with "false" as a value.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()
.
public void setAvailable(boolean available)
available
- True if some fresh content is available.public void setDigest(Digest digest)
digest
- The representation digest.public void setDisposition(Disposition disposition)
disposition
- The disposition characteristics of the representation.public void setExpirationDate(Date expirationDate)
expirationDate
- The expiration date.public void setListener(ReadingListener readingListener)
readingListener
- The listener for NIO read events.public void setRange(Range range)
range
- The content range.public void setSize(long expectedSize)
getAvailableSize()
method.
expectedSize
- The expected size in bytes if known, -1 otherwise.public void setTransient(boolean isTransient)
isTransient
- True if the representation's content is transient.public abstract void write(Writer writer) throws IOException
Writer
after writing to it as this will be handled
by the Restlet connectors automatically.
writer
- The characters writer.
IOException
public abstract void write(WritableByteChannel writableChannel) throws IOException
writableChannel
- A writable byte channel.
IOException
public abstract void write(OutputStream outputStream) throws IOException
OutputStream
after writing to it as this will be handled by
the Restlet connectors automatically.
outputStream
- The output stream.
IOException
|
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |