Package org.eclipse.ecf.filetransfer

# Interface IRetrieveFileTransferContainerAdapter

All Superinterfaces:
  `org.eclipse.core.runtime.IAdaptable`

All Known Subinterfaces:
  `IRetrieveFileTransfer`

All Known Implementing Classes:
  `AbstractRetrieveFileTransfer`, `HttpClientRetrieveFileTransfer`, `HttpClientRetrieveFileTransfer`, `HttpClientRetrieveFileTransfer`, `MultiProtocolRetrieveAdapter`, `UrlConnectionRetrieveFileTransfer`

public interface IRetrieveFileTransferContainerAdapter extends org.eclipse.core.runtime.IAdaptable
Entry point retrieval file transfer adapter. This adapter interface allows providers to expose file retrieval semantics to clients in a transport independent manner. To be used, a non-null adapter reference must be returned from a call to `IContainer.getAdapter(Class)`. Once a non-null reference is retrieved, then it may be used to send a retrieve request. Events will then be asynchronously delivered to the provided listener to complete file transfer.

For example, to retrieve a remote file and store it in a local file:

     // Get IRetrieveFileTransferContainerAdapter adapter
     IRetrieveFileTransferContainerAdapter ftc = (IRetrieveFileTransferContainerAdapter) container
                    .getAdapter(IRetrieveFileTransferContainerAdapter.class);
     if (ftc != null) {
            // Create listener for receiving/responding to asynchronous file transfer events
            IFileTransferListener listener = new IFileTransferListener() {
                    public void handleTransferEvent(IFileTransferEvent event) {
                            // If incoming receive start event, respond by specifying local file to save to
                            if (event instanceof IIncomingFileTransferReceiveStartEvent) {
                                    IIncomingFileTransferReceiveStartEvent rse = (IIncomingFileTransferReceiveStartEvent) event;
                                    try {
                                            rse.receive(new File("composent.main.page.html"));
                                    } catch (IOException e) {
                                            // Handle exception appropriately
                                    }
                            }
                    }
            };
            // Identify file to retrieve and create ID
            IFileID remoteFileID = FileIDFactory.getDefault().createID(
                            ftc.getRetrieveNamespace(), "http://www.composent.com/index.html");
            // Actually make request to start retrieval.  The listener provided will then be notified asynchronously
            // as file transfer events occur
            ftc.sendRetrieveRequest(remoteFileID, listener, null);
     }

Where the IFileTransferEvent subtypes for the receiver will be:

- `IIncomingFileTransferReceiveStartEvent`
- `IIncomingFileTransferReceiveDataEvent`
- `IIncomingFileTransferReceiveDoneEvent`

## Method Summary

Modifier and Type
Method
Description
`Namespace`
`getRetrieveNamespace()`
Get namespace to be used for creation of remoteFileID for retrieve request.
`void`
`sendRetrieveRequest(IFileID remoteFileID, IFileRangeSpecification rangeSpecification, IFileTransferListener transferListener, Map options)`
Send request for transfer of a remote file to local file storage.
`void`
`sendRetrieveRequest(IFileID remoteFileID, IFileTransferListener transferListener, Map options)`
Send request for transfer of a remote file to local file storage.
`void`
`setConnectContextForAuthentication(IConnectContext connectContext)`
Set connect context for authentication upon subsequent `sendRetrieveRequest(IFileID, IFileTransferListener, Map)`.
`void`
`setProxy(Proxy proxy)`
Set proxy for use upon subsequent `sendRetrieveRequest(IFileID, IFileTransferListener, Map)`.

### Methods inherited from interface org.eclipse.core.runtime.IAdaptable

`getAdapter`

## Method Details

### sendRetrieveRequest

void sendRetrieveRequest(IFileID remoteFileID, IFileTransferListener transferListener, Map options) throws IncomingFileTransferException
Send request for transfer of a remote file to local file storage. This method is used to initiate a file retrieve for a remoteFileID (first parameter). File transfer events are asynchronously delivered a file transfer listener (second parameter). The given remoteFileID and transferListener must not be null.

NOTE: if this method completes successfully, the given transferListener will be asynchronously notified via an IIncomingFileTransferReceiveDoneEvent (along with other possible events). All implementations are required to issue this event whether successful or failed. Listeners can consult `IIncomingFileTransferReceiveDoneEvent.getException()` to determine whether the transfer operation completed successfully.

Parameters:
  `remoteFileID` - reference to the remote target file (e.g. http://www.eclipse.org/index.html) or a reference to a resource that specifies the location of a target file. Implementing providers will determine what protocol schemes are supported (e.g. ftp, http, torrent, file, etc) and the required format of the scheme-specific information. If a protocol is specified that is not supported, or the scheme-specific information is not well-formed, then an IncomingFileTransferException will be thrown. Typically, callers will create IFileID instances via calls such as:

       IFileID remoteFileID = FileIDFactory.getDefault().createID(
                      ftc.getRetrieveNamespace(), "http://www.composent.com/index.html");

  Must not be `null`.
  `transferListener` - a listener for file transfer events. Must not be null. Must not be null. See Note above.
  `options` - a Map of options associated with sendRetrieveRequest. The particular name/value pairs will be unique to the individual providers. May be `null`.
Throws:
  `IncomingFileTransferException` - if the provider is not connected or is not in the correct state for initiating file transfer

### sendRetrieveRequest

void sendRetrieveRequest(IFileID remoteFileID, IFileRangeSpecification rangeSpecification, IFileTransferListener transferListener, Map options) throws IncomingFileTransferException
Send request for transfer of a remote file to local file storage. This method is used to initiate a file retrieve for a remoteFileID (first parameter). File transfer events are asynchronously delivered a file transfer listener (third parameter). The given remoteFileID and transferListener must not be null.

NOTE: if this method completes successfully, the given transferListener will be asynchronously notified via an IIncomingFileTransferReceiveDoneEvent (along with other possible events). All implementations are required to issue this event whether successful or failed. Listeners can consult `IIncomingFileTransferReceiveDoneEvent.getException()` to determine whether the transfer operation completed successfully.

Parameters:
  `remoteFileID` - reference to the remote target file (e.g. http://www.eclipse.org/index.html) or a reference to a resource that specifies the location of a target file. Implementing providers will determine what protocol schemes are supported (e.g. ftp, http, torrent, file, etc) and the required format of the scheme-specific information. If a protocol is specified that is not supported, or the scheme-specific information is not well-formed, then an IncomingFileTransferException will be thrown. Typically, callers will create IFileID instances via calls such as:

       IFileID remoteFileID = FileIDFactory.getDefault().createID(
                      ftc.getRetrieveNamespace(), "http://www.composent.com/index.html");

  Must not be `null`.
  `rangeSpecification` - a range specification for retrieving a portion of the given remote file. If `null` the entire file will be retrieved (as per `sendRetrieveRequest(IFileID, IFileTransferListener, Map)`. If non-`null` the given file range will be used to retrieve the given file. For example, if the rangeSpecification has a start value of 1 and end value of 3, and the total length of the file is 5 bytes with content [a, b, c, d, e], a successful retrieve request would transfer bytes 'b', 'c', and 'd', but not 'a', and 'e'.
  `transferListener` - a listener for file transfer events. Must not be null. See Note above.
  `options` - a Map of options associated with sendRetrieveRequest. The particular name/value pairs will be unique to the individual providers. May be `null`.
Throws:
  `IncomingFileTransferException` - if the provider is not connected or is not in the correct state for initiating file transfer

### getRetrieveNamespace

Namespace getRetrieveNamespace()
Get namespace to be used for creation of remoteFileID for retrieve request. Result typically used as first parameter for `IDFactory.createID(Namespace, String)` to be used as first in `sendRetrieveRequest(IFileID, IFileTransferListener, Map)`

Returns:
  Namespace to use for ID creation via `IDFactory.createID(Namespace, String)`. Will not be `null`.

### setConnectContextForAuthentication

void setConnectContextForAuthentication(IConnectContext connectContext)
Set connect context for authentication upon subsequent `sendRetrieveRequest(IFileID, IFileTransferListener, Map)`. This method should be called with a non-null connectContext in order to allow authentication to occur during call to `sendRetrieveRequest(IFileID, IFileTransferListener, Map)`.

Parameters:
  `connectContext` - the connect context to use for authenticating during subsequent call to `sendRetrieveRequest(IFileID, IFileTransferListener, Map)`. If `null`, then no authentication will be attempted.

### setProxy

void setProxy(Proxy proxy)
Set proxy for use upon subsequent `sendRetrieveRequest(IFileID, IFileTransferListener, Map)`. This method should be called with proxy to allow the given proxy to be used in subsequent calls to `sendRetrieveRequest(IFileID, IFileTransferListener, Map)`.

When proxy is `null` or has not been called providers must use the `org.eclipse.core.net` proxy API to obtain proxy information and proxy credentials if they support proxies of the type(s) supported by that API. The API is provided by an OSGi service of type `org.eclipse.core.net.proxy.IProxyService`.

If no information is available via `IProxyService` providers may use other defaults.

Parameters:
  `proxy` - the proxy to use for subsequent calls to `sendRetrieveRequest(IFileID, IFileTransferListener, Map)`. If `null`, then proxy information is obtained from `IProxyService` if available. Otherwise provider defined defaults may be used.