org.restlet.representation

## Class FileRepresentation

- java.lang.Object
- - org.restlet.representation.Variant
  - - org.restlet.representation.RepresentationInfo
    - - org.restlet.representation.Representation
      - - org.restlet.representation.FileRepresentation

    public class FileRepresentation
    extends Representation

Representation based on a static file. Note that in order for Web clients to display a download box upon reception of a file representation, it needs an additional call to `Disposition.setType(String)` with a `Disposition.TYPE_ATTACHMENT` value.

Author:
  Jerome Louvel

### Field Summary

### Fields inherited from class org.restlet.representation.Representation

`UNKNOWN_SIZE`

### Constructor Summary

Constructors
Constructor and Description
`FileRepresentation(java.io.File file, MediaType mediaType)` Constructor that does not set an expiration date for `file`
`FileRepresentation(java.io.File file, MediaType mediaType, int timeToLive)` Constructor.
`FileRepresentation(java.lang.String path, MediaType mediaType)` Constructor that does not set an expiration date for `path`
`FileRepresentation(java.lang.String path, MediaType mediaType, int timeToLive)` Constructor.

### Method Summary

Methods
`java.nio.channels.FileChannel` `getChannel()` Returns a readable byte channel.
`java.io.File` `getFile()` Returns the file handle.
`java.io.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.
`java.io.FileInputStream` `getStream()` Returns a stream with the representation's content.
`java.lang.String` `getText()` Note that this method relies on `getStream()`.
`boolean` `isAutoDelete()` Deprecated. Use `isAutoDeleting()` instead.
`boolean` `isAutoDeleting()` Indicates if this file should be automatically deleted on release of the representation.
`void` `release()` Releases the file handle.
`void` `setAutoDelete(boolean autoDeleting)` Deprecated. Use `setAutoDeleting(boolean)` instead.
`void` `setAutoDeleting(boolean autoDeleting)` Indicates if this file should be automatically deleted on release of the representation.
`void` `setFile(java.io.File file)` Sets the file handle.
`void` `write(java.io.OutputStream outputStream)` Writes the representation to a byte stream.
`void` `write(java.nio.channels.WritableByteChannel writableChannel)` Writes the representation to a byte channel.
`void` `write(java.io.Writer writer)` Writes the representation to a characters writer.

### Methods inherited from class org.restlet.representation.Representation

`checkDigest, checkDigest, computeDigest, createEmpty, exhaust, getAvailableSize, getDigest, getDisposition, getDownloadName, getExpirationDate, getRange, isAvailable, isDownloadable, isTransient, setAvailable, setDigest, setDisposition, setDownloadable, setDownloadName, setExpirationDate, setRange, setSize, setTransient`

### Methods inherited from class org.restlet.representation.RepresentationInfo

`getModificationDate, getTag, setModificationDate, setTag`

### Methods inherited from class org.restlet.representation.Variant

`createClientInfo, equals, getCharacterSet, getEncodings, getIdentifier, getLanguages, getLocationRef, getMediaType, includes, isCompatible, setCharacterSet, setEncodings, setIdentifier, setIdentifier, setLanguages, setLocationRef, setLocationRef, setMediaType, toString`

### Methods inherited from class java.lang.Object

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

### Constructor Detail

#### FileRepresentation

    public FileRepresentation(java.io.File file,
                      MediaType mediaType)

Constructor that does not set an expiration date for `file`

Parameters:
  `file` - The represented file.
  `mediaType` - The representation's media type.
See Also:
  `FileRepresentation(File, MediaType, int)`

#### FileRepresentation

    public FileRepresentation(java.io.File file,
                      MediaType mediaType,
                      int timeToLive)

Constructor. If a positive "timeToLive" parameter is given, then the expiration date is set accordingly. If "timeToLive" is equal to zero, then the expiration date is set to the current date, meaning that it will immediately expire on the client. If -1 is given, then no expiration date is set.

Parameters:
  `file` - The represented file.
  `mediaType` - The representation's media type.
  `timeToLive` - The time to live before it expires (in seconds).

#### FileRepresentation

    public FileRepresentation(java.lang.String path,
                      MediaType mediaType)

Constructor that does not set an expiration date for `path`

Parameters:
  `path` - The path name or file URI of the represented file (either in system format or in 'file:///' format).
  `mediaType` - The representation's media type.
See Also:
  `FileRepresentation(String, MediaType, int)`

#### FileRepresentation

    public FileRepresentation(java.lang.String path,
                      MediaType mediaType,
                      int timeToLive)

Constructor.

Parameters:
  `path` - The path name or file URI of the represented file (either in system format or in 'file:///' format).
  `mediaType` - The representation's media type.
  `timeToLive` - The time to live before it expires (in seconds).
See Also:
  `File.File(String)`

### Method Detail

#### getChannel

    public java.nio.channels.FileChannel getChannel()
                                             throws java.io.IOException

Returns a readable byte channel. If it is supported by a file a read-only instance of FileChannel is returned.

Specified by:
  `getChannel` in class `Representation`
Returns:
  A readable byte channel.
Throws:
  `java.io.IOException`

#### getFile

    public java.io.File getFile()

Returns the file handle.

Returns:
  the file handle.

#### 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 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 java.io.FileInputStream 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`

#### getText

    public java.lang.String getText()
                             throws java.io.IOException

Note that this method relies on `getStream()`. This stream is closed once fully read.

Overrides:
  `getText` in class `Representation`
Returns:
  The representation as a string value.
Throws:
  `java.io.IOException`

#### isAutoDelete

    @Deprecated
    public boolean isAutoDelete()

Deprecated. Use `isAutoDeleting()` instead.
Indicates if this file should be automatically deleted on release of the representation.

Returns:
  True if this file should be automatically deleted on release of the representation.

#### isAutoDeleting

    public boolean isAutoDeleting()

Indicates if this file should be automatically deleted on release of the representation.

Returns:
  True if this file should be automatically deleted on release of the representation.

#### release

    public void release()

Releases the file handle.

Overrides:
  `release` in class `Representation`

#### setAutoDelete

    @Deprecated
    public void setAutoDelete(boolean autoDeleting)

Deprecated. Use `setAutoDeleting(boolean)` instead.
Indicates if this file should be automatically deleted on release of the representation.

Parameters:
  `autoDeleting` - True if this file should be automatically deleted on release of the representation.

#### setAutoDeleting

    public void setAutoDeleting(boolean autoDeleting)

Indicates if this file should be automatically deleted on release of the representation.

Parameters:
  `autoDeleting` - True if this file should be automatically deleted on release of the representation.

#### setFile

    public void setFile(java.io.File file)

Sets the file handle.

Parameters:
  `file` - The file handle.

#### write

    public void write(java.io.OutputStream outputStream)
               throws java.io.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:
  `java.io.IOException`

#### write

    public void write(java.nio.channels.WritableByteChannel writableChannel)
               throws java.io.IOException

Writes the representation to a byte channel. Optimizes using the file channel transferTo method.

Specified by:
  `write` in class `Representation`
Parameters:
  `writableChannel` - A writable byte channel.
Throws:
  `java.io.IOException`

#### write

    public void write(java.io.Writer writer)
               throws java.io.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:
  `java.io.IOException`