org.eclipse.aether.spi.connector.transport

## Class GetTask

- java.lang.Object
- - org.eclipse.aether.spi.connector.transport.TransportTask
  - - org.eclipse.aether.spi.connector.transport.GetTask

-     public final class GetTask
      extends TransportTask

  A task to download a resource from the remote repository.
  See Also:
    `Transporter.get(GetTask)`

- - ### Constructor Summary

    Constructors
    Constructor and Description
    `GetTask(URI location)` Creates a new task for the specified remote resource.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `Map<String,String>` | `getChecksums()` Gets the checksums which the remote repository advertises for the resource.
    `byte[]` | `getDataBytes()` Gets the data that was downloaded into memory.
    `File` | `getDataFile()` Gets the file (if any) where the downloaded data should be stored.
    `String` | `getDataString()` Gets the data that was downloaded into memory as a string.
    `long` | `getResumeOffset()` Gets the byte offset within the resource from which the download should resume if supported.
    `OutputStream` | `newOutputStream()` Opens an output stream to store the downloaded data.
    `OutputStream` | `newOutputStream(boolean resume)` Opens an output stream to store the downloaded data.
    `GetTask` | `setChecksum(String algorithm, String value)` Sets a checksum which the remote repository advertises for the resource.
    `GetTask` | `setDataFile(File dataFile)` Sets the file where the downloaded data should be stored.
    `GetTask` | `setDataFile(File dataFile, boolean resume)` Sets the file where the downloaded data should be stored.
    `GetTask` | `setListener(TransportListener listener)` Sets the listener that is to be notified during the transfer.
    `String` | `toString()`

    - ### Methods inherited from class org.eclipse.aether.spi.connector.transport.TransportTask

      `getListener, getLocation`

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

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

- - ### Constructor Detail

    - #### GetTask

          public GetTask(URI location)

      Creates a new task for the specified remote resource.
      Parameters:
        `location` - The relative location of the resource in the remote repository, must not be `null`.

  - ### Method Detail

    - #### newOutputStream

          public OutputStream newOutputStream()
                                       throws IOException

      Opens an output stream to store the downloaded data. Depending on `getDataFile()`, this stream writes either to a file on disk or a growable buffer in memory. It's the responsibility of the caller to close the provided stream.
      Returns:
        The output stream for the data, never `null`.
      Throws:
        `IOException` - If the stream could not be opened.

    - #### newOutputStream

          public OutputStream newOutputStream(boolean resume)
                                       throws IOException

      Opens an output stream to store the downloaded data. Depending on `getDataFile()`, this stream writes either to a file on disk or a growable buffer in memory. It's the responsibility of the caller to close the provided stream.
      Parameters:
        `resume` - `true` if the download resumes from the byte offset given by `getResumeOffset()`, `false` if the download starts at the first byte of the resource.
      Returns:
        The output stream for the data, never `null`.
      Throws:
        `IOException` - If the stream could not be opened.

    - #### getDataFile

          public File getDataFile()

      Gets the file (if any) where the downloaded data should be stored. If the specified file already exists, it will be overwritten.
      Returns:
        The data file or `null` if the data will be buffered in memory.

    - #### setDataFile

          public GetTask setDataFile(File dataFile)

      Sets the file where the downloaded data should be stored. If the specified file already exists, it will be overwritten. Unless the caller can reasonably expect the resource to be small, use of a data file is strongly recommended to avoid exhausting heap memory during the download.
      Parameters:
        `dataFile` - The file to store the downloaded data, may be `null` to store the data in memory.
      Returns:
        This task for chaining, never `null`.

    - #### setDataFile

          public GetTask setDataFile(File dataFile,
                            boolean resume)

      Sets the file where the downloaded data should be stored. If the specified file already exists, it will be overwritten or appended to, depending on the `resume` argument and the capabilities of the transporter. Unless the caller can reasonably expect the resource to be small, use of a data file is strongly recommended to avoid exhausting heap memory during the download.
      Parameters:
        `dataFile` - The file to store the downloaded data, may be `null` to store the data in memory.
        `resume` - `true` to request resuming a previous download attempt, starting from the current length of the data file, `false` to download the resource from its beginning.
      Returns:
        This task for chaining, never `null`.

    - #### getResumeOffset

          public long getResumeOffset()

      Gets the byte offset within the resource from which the download should resume if supported.
      Returns:
        The zero-based index of the first byte to download or `0` for a full download from the start of the resource, never negative.

    - #### getDataBytes

          public byte[] getDataBytes()

      Gets the data that was downloaded into memory. Note: This method may only be called if `getDataFile()` is `null` as otherwise the downloaded data has been written directly to disk.
      Returns:
        The possibly empty data bytes, never `null`.

    - #### getDataString

          public String getDataString()

      Gets the data that was downloaded into memory as a string. The downloaded data is assumed to be encoded using UTF-8. Note: This method may only be called if `getDataFile()` is `null` as otherwise the downloaded data has been written directly to disk.
      Returns:
        The possibly empty data string, never `null`.

    - #### setListener

          public GetTask setListener(TransportListener listener)

      Sets the listener that is to be notified during the transfer.
      Parameters:
        `listener` - The listener to notify of progress, may be `null`.
      Returns:
        This task for chaining, never `null`.

    - #### getChecksums

          public Map<String,String> getChecksums()

      Gets the checksums which the remote repository advertises for the resource. The map is keyed by algorithm name (cf. `MessageDigest.getInstance(String)`) and the values are hexadecimal representations of the corresponding value. Note: This is optional data that a transporter may return if the underlying transport protocol provides metadata (e.g. HTTP headers) along with the actual resource data.
      Returns:
        The (read-only) checksums advertised for the downloaded resource, possibly empty but never `null`.

    - #### setChecksum

          public GetTask setChecksum(String algorithm,
                            String value)

      Sets a checksum which the remote repository advertises for the resource. Note: Transporters should only use this method to record checksum information which is readily available while performing the actual download, they should not perform additional transfers to gather this data.
      Parameters:
        `algorithm` - The name of the checksum algorithm (e.g. `"SHA-1"`, cf. `MessageDigest.getInstance(String)` ), may be `null`.
        `value` - The hexadecimal representation of the checksum, may be `null`.
      Returns:
        This task for chaining, never `null`.

    - #### toString

          public String toString()

      Overrides:
        `toString` in class `Object`

Copyright © 2010-2013 The Eclipse Foundation. All Rights Reserved.