Skip to main content

Notice: this Wiki will be going read only early in 2024 and edits will no longer be possible. Please see: https://gitlab.eclipse.org/eclipsefdn/helpdesk/-/wikis/Wiki-shutdown-plan for the plan.

Jump to: navigation, search

Difference between revisions of "ECF BitTorrent Provider"

(org.eclipse.bittorrent: Removing the red colouring on IPieceProgressListener)
 
(34 intermediate revisions by one other user not shown)
Line 1: Line 1:
'''Project Lead''':  Remy Chi Jian Suen
+
'''Project Lead''':  Remy Chi Jian Suen (IRC: rcjsuen)
  
'''Mentor(s)''':  Wayne Beaton, Scott Lewis, and Chris Aniszczyk
+
'''Mentor(s)''':  Wayne Beaton (IRC: WTB), Scott Lewis (IRC: slewis2), and Chris Aniszczyk (IRC: zx)
  
The goal if this project is to create an implementation of the file sharing API provided by the [[Eclipse Communication Framework Project|Eclipse Communication Framework]] using the [http://www.bittorrent.org BitTorrent] protocol.
+
The goal of this project is to create an implementation of the file sharing API provided by the [[Eclipse Communication Framework Project|Eclipse Communication Framework]] using the [http://www.bittorrent.org 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.
  
==BitTorrent Plug-in Data Model==
+
Bug [https://bugs.eclipse.org/bugs/show_bug.cgi?id=144133 144133] will monitor the progress of this project.
  
The package name ''org.eclipse.bittorrent'' may be altered when the plug-in is released.
+
==Getting the code==
 +
The 'Summer of Code' project component has been approved by Eclipse but the code has not yet been committed into CVS yet as it is currently questionable whether the base library itself will be hosted by Eclipse.org or not.
  
Text in <font color="red">red</font> denotes that the code has not been written yet.
+
'''Host:''' eclipse-incub.cvs.sourceforge.net<br>
 +
'''Repository Path:''' /cvsroot/eclipse-incub<br>
 +
'''User name:''' anonymous<br>
 +
'''Connection type:''' pserver
 +
 
 +
==Features==
 +
*start and stop torrents, resuming supported
 +
*select which files to try to download first and which files to not download at all
 +
*set up and down speeds
 +
 
 +
==Examples==
 +
Currently, there are three example projects committed into CVS.
 +
*org.eclipse.bittorrent.example
 +
*org.eclipse.bittorrent.example.plugin
 +
*org.eclipse.ecf.example.rcpbittorrent
 +
 
 +
===org.eclipse.bittorrent.example===
 +
This project contains two different classes each with a main method. The command line client's main class is org.eclipse.bittorrent.example.cli.CLI. The other client within this project is the SWT graphical client, its main class is org.eclipse.bittorrent.example.swt.SWTClient.
 +
 
 +
===org.eclipse.bittorrent.example.plugin===
 +
This plug-in adds a "Torrents" view to the workbench to allow the user to download torrents whilst using Eclipse. A console is embedded within the view to allow debugging messages to be displayed.
 +
 
 +
===org.eclipse.ecf.example.rcpbittorrent===
 +
This RCP application allows the user to download files through the BitTorrent protocol using ECF's file sharing APIs.
 +
 
 +
==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 <font color="red">red</font> denotes that the code for that specified class or interface has not been written yet.
  
 
===org.eclipse.bittorrent===
 
===org.eclipse.bittorrent===
Host - reads in a Torrent and connects to peers to begin seeding or downloading
+
Torrent - reads in a TorrentFile and connects to peers to begin seeding or downloading
*contains exactly one Torrent
+
 
*contains one or more DataFiles
+
TorrentFile - a representation of the metainfo stored within a ''.torrent'' file
*contains one or more Pieces
+
 
 +
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
  
Torrent - a representation of the metainfo stored within a ''.torrent'' file
+
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 is 'downloading' or 'completed'
+
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
 
ITorrentProgressListener - monitors how far the download has gone
Line 31: Line 66:
 
Piece - a piece of data that is needed to complete a download
 
Piece - a piece of data that is needed to complete a download
 
*contains one or more DataFiles
 
*contains one or more DataFiles
 
  
 
===org.eclipse.bittorrent.internal.net===
 
===org.eclipse.bittorrent.internal.net===
 
ConnectionPool - a thread pool that manages ConnectionThreads
 
ConnectionPool - a thread pool that manages ConnectionThreads
*contains exactly one Host
+
*contains exactly one TorrentManager
*contains one or more ConnectionThreads
+
*contains one or more PeerConnections
 
+
ConnectionThread - creates a PeerConnection to talk to a peer
+
*contains exactly one PeerConnection
+
  
 
PeerConnection - connects to a peer and exchanges information
 
PeerConnection - connects to a peer and exchanges information
 
*exactly one Host
 
*exactly one Host
  
 +
TorrentManager - reads and writes to files and performs message processing with PeerConnections
 +
*contains exactly one ConnectionPool
  
 
===org.eclipse.bittorrent.internal.encode===
 
===org.eclipse.bittorrent.internal.encode===
Line 59: Line 92:
 
# - begin downloading a single file from a torrent and pause the download after a period of time
 
# - begin downloading a single file from a torrent and pause the download after a period of time
 
## - resume the download
 
## - resume the download
## - cancel the download and delete the downloaded files
 
 
# - start two downloads from two torrents until completion
 
# - start two downloads from two torrents until completion
 
# - begin two downloads from two torrent and then pause the second one after a period of time
 
# - begin two downloads from two torrent and then pause the second one after a period of time
## - resume the second download after the first has completed
 
## - cancel the first download and start the second download
 
 
# - begin downloading from a torrent and monitor its progress with a listener
 
# - begin downloading from a torrent and monitor its progress with a listener
# - '''LATER''' start downloading multiple files from a torrent and select which files should be downloaded
+
# - start downloading multiple files from a torrent and select which files should be downloaded
# - '''LATER''' begin downloading a file from a torrent and cap the download/upload speeds
+
# - begin downloading a file from a torrent and cap the download/upload speeds
# - '''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.
 
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() {
+
<source lang="java">
    public void stateChanged(int state) {
+
ITorrentStateListener stateListener = new ITorrentStateListener() {
        switch (state) {
+
    public void stateChanged(int state) {
        case ITorrentStateListener.STARTED:
+
        switch (state) {
            System.out.println("The torrent set-up is starting...");
+
        case ITorrentStateListener.STARTED:
            break;
+
            System.out.println("The torrent set-up is starting...");
        case ITorrentStateListener.DOWNLOADING:
+
            break;
            System.out.println("The downloading has begun...");
+
        case ITorrentStateListener.EXCHANGING:
            break;
+
            System.out.println("Exchanging pieces with peers...");
        case ITorrentStateListener.PAUSED:
+
            break;
            System.out.println("The downloading has been paused...");
+
        case ITorrentStateListener.STOPPED:
            break;
+
            System.out.println("The exchanging has stopped...");
        case ITorrentStateListener.FINISHED:
+
            break;
            System.out.println("The download is now complete...");
+
        case ITorrentStateListener.FINISHED:
            break;
+
            System.out.println("The download is now complete...");
        }
+
            break;
    }
+
        }
};
+
    }
 +
};
 +
</source>
 +
 
 +
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.
 +
 
 +
<source lang="java">
 +
TorrentConfiguration.setConfigurationPath(new File(System.getProperty("user.home"), ".hilberteffect"));
 +
</source>
  
 
'''Use Case 1''' - download a torrent's contents to completion
 
'''Use Case 1''' - download a torrent's contents to completion
  
Torrent torrent = new Torrent(new FileInputStream("eclipse-sdk.torrent"));
+
<source lang="java">
Host host = new Host(torrent);
+
Torrent torrent = TorrentFactory.createTorrent(new TorrentFile(new File("eclipse-sdk.torrent")));
host.start(stateListener);
+
torrent.addTorrentStateListener(stateListener);
 +
torrent.start();
 +
</source>
  
 
'''Use Case 2''' - stop the download after a period of time
 
'''Use Case 2''' - stop the download after a period of time
  
Torrent torrent = new Torrent(new FileInputStream("eclipse-sdk.torrent"));
+
<source lang="java">
Host host = new Host(torrent);
+
Torrent torrent = TorrentFactory.createTorrent(new TorrentFile(new File("eclipse-sdk.torrent")));
host.start(stateListener);
+
torrent.addTorrentStateListener(stateListener);
// after some amount of time has passed
+
torrent.start();
host.stop();
+
// after some amount of time has passed
 +
torrent.stop();
 +
</source>
  
 
'''Use Case 2.1''' - resume downloading a torrent after pausing it for a period of time
 
'''Use Case 2.1''' - resume downloading a torrent after pausing it for a period of time
  
Torrent torrent = new Torrent(new FileInputStream("eclipse-sdk.torrent"));
+
<source lang="java">
Host host = new Host(torrent);
+
Torrent torrent = new Torrent(new File("eclipse-sdk.torrent"));
host.start(stateListener);
+
torrent.addTorrentStateListener(stateListener);
// after some amount of time has passed
+
torrent.start();
host.pause();
+
// after some amount of time has passed
// more time passes
+
torrent.stop();
host.resume();
+
// more time passes
 
+
torrent.start();
'''Use Case 2.2''' - start a download and then stop it and remove all downloaded files
+
</source>
 
+
Torrent torrent = new Torrent(new FileInputStream("eclipse-sdk.torrent"));
+
Host host = new Host(torrent);
+
host.start(stateListener);
+
// after some amount of time has passed
+
host.stop();
+
host.remove();
+
  
 
'''Use Case 3''' - begin downloading from two different torrents until completion
 
'''Use Case 3''' - begin downloading from two different torrents until completion
  
Torrent torrent01 = new Torrent(new FileInputStream("eclipse-sdk.torrent");
+
<source lang="java">
Host host01 = new Host(torrent01);
+
Torrent torrent01 = TorrentFactory.createTorrent(new TorrentFile(new File("eclipse-sdk.torrent")));
host.start(stateListener);
+
torrent01.addTorrentStateListener(stateListener);
Torrent torrent02 = new Torrent(new FileInputStream("eclipse-ecf.torrent"));
+
torrent01.start();
Host host02 = new Host(torrent02);
+
Torrent torrent02 = TorrentFactory.createTorrent(new TorrentFile(new File("eclipse-ecf.torrent")));
host.start(stateListener);
+
torrent02.addTorrentStateListener(stateListener);
 +
torrent02.start();
 +
</source>
  
'''Use Case 4''' - start downloading two different torrents and pause one of them after a period of time
+
'''Use Case 4''' - start downloading two different torrents and stop the second one after a period of time
  
Torrent torrent01 = new Torrent(new FileInputStream("eclipse-sdk.torrent"));
+
<source lang="java">
Host host01 = new Host(torrent01);
+
Torrent torrent01 = TorrentFactory.createTorrent(new TorrentFile(new File("eclipse-sdk.torrent")));
host01.start(stateListener);
+
torrent01.addTorrentStateListener(stateListener);
Torrent torrent02 = new Torrent(new FileInputStream("eclipse-ecf.torrent"));
+
torrent01.start();
Host host02 = new Host(torrent02);
+
Torrent torrent02 = TorrentFactory.createTorrent(new TorrentFile(new File("eclipse-ecf.torrent")));
host02.start(stateListener);
+
torrent02.addTorrentStateListener(stateListener);
// some time passes
+
orrent02.start();
host02.pause();
+
// some time passes
 +
torrent02.stop();
 +
</source>
  
'''Use Case 4.1''' - resume downloading the second torrent after the first has finished
+
'''Use Case 5''' - begin downloading from a torrent and monitor its progress with a listener
  
Torrent torrent01 = new Torrent(new FileInputStream("eclipse-sdk.torrent"));
+
<source lang="java">
Host host01 = new Host(torrent01);
+
Torrent torrent = TorrentFactory.createTorrent(new TorrentFile(new File("eclipse-sdk.torrent")));
host01.start(stateListener);
+
torrent.addTorrentProgressListener(new ITorrentProgressListener() {
Torrent torrent02 = new Torrent(new FileInputStream("eclipse-ecf.torrent"));
+
    public void pieceCompleted(int completed) {
Host host02 = new Host(torrent02);
+
        System.out.println("Pieces completed thus far: " + completed);
host02.start(stateListener);
+
    }
// some time passes
+
});
host02.pause();
+
torrent.start();
while (!host01.isCompleted());
+
</source>
host02.resume();
+
  
'''Use Case 4.2''' - cancel the first download and resume the second download
+
'''Use Case 6''' - start downloading multiple files from a torrent and select which files should be downloaded
  
Torrent torrent01 = new Torrent(new FileInputStream("eclipse-sdk.torrent"));
+
<source lang="java">
Host host01 = new Host(torrent01);
+
Torrent torrent = TorrentFactory.createTorrent(new TorrentFile(new File("eclipse-all-in-one.torrent")));
host01.start(stateListener);
+
// assuming that this torrent has three files and the user only wants the first one
Torrent torrent02 = new Torrent(new FileInputStream("eclipse-sdk.torrent"));
+
torrent.setFilesToDownload(new int[] { 0, -1, -1 });
Host host02 = new Host(torrent02);
+
torrent.start();
host02.start(stateListener);
+
</source>
// some time passes
+
host02.pause();
+
// more time passes
+
host01.stop();
+
host02.resume();
+
  
'''Use Case 5''' - begin downloading from a torrent and monitor its progress with a listener
+
'''Use Case 7''' - begin downloading a file from a torrent and cap the download/upload speeds
  
Torrent torrent = new Torrent(new FileInputStream("eclipse-sdk.torrent"));
+
<source lang="java">
Host host = new Host(torrent);
+
Torrent torrent = TorrentFactory.createTorrent(new TorrentFile(new File("eclipse-sdk.torrent")));
host.addProgressListener(new ProgressListener() {
+
torrent.setMaxDownloadSpeed(5 * 1024);
    public void progressEvent(ProgressEvent event) {
+
torrent.setMaxUploadSpeed(5 * 1024);
        System.out.println(event.getRemaining());
+
torrent.start();
    }
+
</source>
});
+
  
==External Links==
+
==External links==
 
[http://www.eclipse.org/ecf Eclipse Communication Framework Website]
 
[http://www.eclipse.org/ecf Eclipse Communication Framework Website]
  
 
[http://wiki.theory.org/BitTorrentSpecification BitTorrent Specification]
 
[http://wiki.theory.org/BitTorrentSpecification BitTorrent Specification]
 +
 +
[[Category: Eclipse Communication Framework|BitTorrent Provider]]
 +
[[Category:SOC]]

Latest revision as of 23:33, 5 April 2013

Project Lead: Remy Chi Jian Suen (IRC: rcjsuen)

Mentor(s): Wayne Beaton (IRC: WTB), Scott Lewis (IRC: slewis2), and Chris Aniszczyk (IRC: zx)

The goal of 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.

Bug 144133 will monitor the progress of this project.

Getting the code

The 'Summer of Code' project component has been approved by Eclipse but the code has not yet been committed into CVS yet as it is currently questionable whether the base library itself will be hosted by Eclipse.org or not.

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

Features

  • start and stop torrents, resuming supported
  • select which files to try to download first and which files to not download at all
  • set up and down speeds

Examples

Currently, there are three example projects committed into CVS.

  • org.eclipse.bittorrent.example
  • org.eclipse.bittorrent.example.plugin
  • org.eclipse.ecf.example.rcpbittorrent

org.eclipse.bittorrent.example

This project contains two different classes each with a main method. The command line client's main class is org.eclipse.bittorrent.example.cli.CLI. The other client within this project is the SWT graphical client, its main class is org.eclipse.bittorrent.example.swt.SWTClient.

org.eclipse.bittorrent.example.plugin

This plug-in adds a "Torrents" view to the workbench to allow the user to download torrents whilst using Eclipse. A console is embedded within the view to allow debugging messages to be displayed.

org.eclipse.ecf.example.rcpbittorrent

This RCP application allows the user to download files through the BitTorrent protocol using ECF's file sharing APIs.

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 TorrentManager
  • contains one or more PeerConnections

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. - start downloading multiple files from a torrent and select which files should be downloaded
  7. - begin downloading a file from a torrent and cap the download/upload speeds

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();
// 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();
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);
orrent02.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);
    }
});
torrent.start();

Use Case 6 - start downloading multiple files from a torrent and select which files should be downloaded

Torrent torrent = TorrentFactory.createTorrent(new TorrentFile(new File("eclipse-all-in-one.torrent")));
// assuming that this torrent has three files and the user only wants the first one
torrent.setFilesToDownload(new int[] { 0, -1, -1 });
torrent.start();

Use Case 7 - begin downloading a file from a torrent and cap the download/upload speeds

Torrent torrent = TorrentFactory.createTorrent(new TorrentFile(new File("eclipse-sdk.torrent")));
torrent.setMaxDownloadSpeed(5 * 1024);
torrent.setMaxUploadSpeed(5 * 1024);
torrent.start();

External links

Eclipse Communication Framework Website

BitTorrent Specification

Back to the top