ECF BitTorrent Provider

Project Lead: Remy Chi Jian Suen

Mentor(s): Wayne Beaton, Scott Lewis, and Chris Aniszczyk

The goal if this project is to create an implementation of the file sharing API provided by the Eclipse Communication Framework using the BitTorrent protocol. The BitTorrent protocol will be implemented in 100% Java in a clean room environment. It is currently under active development and is licensed under both the MIT License and the Eclipse Public License.

Getting the Code

The code is currently hosted on Sourceforge until the Summer of Code proposal has been approved by the Eclipse Foundation.

Host: eclipse-incub.cvs.sourceforge.net
Repository Path: /cvsroot/eclipse-incub
User name: anonymous
Connection type: pserver

BitTorrent Plug-in Data Model

The package name org.eclipse.bittorrent may be altered when the plug-in is released. All internal packages are not intended to be used by developers and the implementation will change even after the API has reached a 1.0 release.

Text in red denotes that the code for that specified class or interface has not been written yet.

org.eclipse.bittorrent

Torrent- reads in a TorrentFile and connects to peers to begin seeding or downloading

TorrentFile - a representation of the metainfo stored within a .torrent file

TorrentFactory - creates Torrents

TorrentConfiguration - configures debugging output and state location storage paths

TorrentServer - listens for incoming connections from other peers and hooks them onto the appropriate Host

ITorrentErrorListener - watches for errors caused by trackers or failed hash checks

ITorrentStateListener - reports what state the download is in right now, such as whether it has been 'stopped' or whether the download has 'completed'

ITorrentProgressListener - monitors how far the download has gone

IPieceProgressListener - monitors the download progress of a particular piece

org.eclipse.bittorrent.internal.torrent

DataFile - a representation of a file on the user's system for read/write operations

• contains one or more Pieces

Piece - a piece of data that is needed to complete a download

• contains one or more DataFiles

org.eclipse.bittorrent.internal.net

ConnectionPool - a thread pool that manages ConnectionThreads

• contains exactly one Host
• contains one or more ConnectionThreads

ConnectionThread - creates a PeerConnection to talk to a peer

• contains exactly one PeerConnection

PeerConnection - connects to a peer and exchanges information

• exactly one Host

TorrentManager - reads and writes to files and performs message processing with PeerConnections

• contains exactly one ConnectionPool

org.eclipse.bittorrent.internal.encode

BEncodedDictionary - holds the key-value pairs stored within a bencoded string.

Decode - decodes information such as the contents of a torrent file

Encode - converts or alters information for use

Plug-in Usage

This section will describe how a developer would create a client using the BitTorrent plug-in.

Use Cases

1. - downloads a single file from a torrent until completion
2. - begin downloading a single file from a torrent and pause the download after a period of time
   1. - resume the download
3. - start two downloads from two torrents until completion
4. - begin two downloads from two torrent and then pause the second one after a period of time
5. - begin downloading from a torrent and monitor its progress with a listener
6. - LATER start downloading multiple files from a torrent and select which files should be downloaded
7. - LATER begin downloading a file from a torrent and cap the download/upload speeds
8. - LATER start a download from a torrent and alter the number of connections that can be made

The use cases listed below makes use of an implementation of the ITorrentStateListener interface. All references to stateListener can be referred back to the implementation provided below.

ITorrentStateListener stateListener = new ITorrentStateListener() {
    public void stateChanged(int state) {
        switch (state) {
        case ITorrentStateListener.STARTED:
            System.out.println("The torrent set-up is starting...");
            break;
        case ITorrentStateListener.EXCHANGING:
            System.out.println("Exchanging pieces with peers...");
            break;
        case ITorrentStateListener.STOPPED:
            System.out.println("The exchanging has stopped...");
            break;
        case ITorrentStateListener.FINISHED:
            System.out.println("The download is now complete...");
            break;
        }
    }
};

It is also assumed that a path has been set for the library to save configuration and state information to properly support the resuming of torrents without having to perform a hash check when the client has started.

TorrentConfiguration.setConfigurationPath(new File(System.getProperty("user.home"), ".hilberteffect"));

Use Case 1 - download a torrent's contents to completion

Torrent torrent = TorrentFactory.createTorrent(new TorrentFile(new File("eclipse-sdk.torrent")));
torrent.addTorrentStateListener(stateListener);
torrent.start();

Use Case 2 - stop the download after a period of time

Torrent torrent = TorrentFactory.createTorrent(new TorrentFile(new File("eclipse-sdk.torrent")));
torrent.addTorrentStateListener(stateListener);
torrent.start();
// after some amount of time has passed
torrent.stop();

Use Case 2.1 - resume downloading a torrent after pausing it for a period of time

Torrent torrent = new Torrent(new File("eclipse-sdk.torrent"));
torrent.addTorrentStateListener(stateListener);
torrent.start(stateListener);
// after some amount of time has passed
torrent.stop();
// more time passes
torrent.start();

Use Case 3 - begin downloading from two different torrents until completion

Torrent torrent01 = TorrentFactory.createTorrent(new TorrentFile(new File("eclipse-sdk.torrent")));
torrent01.addTorrentStateListener(stateListener);
torrent01.start(stateListener);
Torrent torrent02 = TorrentFactory.createTorrent(new TorrentFile(new File("eclipse-ecf.torrent")));
torrent02.addTorrentStateListener(stateListener);
torrent02.start();

Use Case 4 - start downloading two different torrents and stop the second one after a period of time

Torrent torrent01 = TorrentFactory.createTorrent(new TorrentFile(new File("eclipse-sdk.torrent")));
torrent01.addTorrentStateListener(stateListener);
torrent01.start();
Torrent torrent02 = TorrentFactory.createTorrent(new TorrentFile(new File("eclipse-ecf.torrent")));
torrent02.addTorrentStateListener(stateListener);
torrent02.start();
// some time passes
torrent02.stop();

Use Case 5 - begin downloading from a torrent and monitor its progress with a listener

Torrent torrent = TorrentFactory.createTorrent(new TorrentFile(new File("eclipse-sdk.torrent")));
torrent.addTorrentProgressListener(new ITorrentProgressListener() {
    public void pieceCompleted(int completed) {
        System.out.println("Pieces completed thus far: " + completed);
    }
});

External Links

Eclipse Communication Framework Website

BitTorrent Specification