org.eclipse.ecf.filetransfer

Interface IRetrieveFileTransferContainerAdapter

All Superinterfaces:

org.eclipse.core.runtime.IAdaptable

All Known Subinterfaces:

IRetrieveFileTransfer

All Known Implementing Classes:

AbstractRetrieveFileTransfer, 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 and Description
Namespace	getRetrieveNamespace() Get namespace to be used for creation of remoteFileID for retrieve request.
void	sendRetrieveRequest(IFileID remoteFileID, IFileRangeSpecification rangeSpecification, IFileTransferListener transferListener, java.util.Map options) Send request for transfer of a remote file to local file storage.
void	sendRetrieveRequest(IFileID remoteFileID, IFileTransferListener transferListener, java.util.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 Detail

sendRetrieveRequest

void sendRetrieveRequest(IFileID remoteFileID,
                         IFileTransferListener transferListener,
                         java.util.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,
                         java.util.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.