Make it "clearer" that the target file might "not be there"

.gitignore

@@ -3,9 +3,12 @@
 
 # Ignore build output
 /build/*
+/target/*
+/release.properties
 
 # Ignore Javadoc output
-/doc/*
+cli/doc/*
+core/doc/*
 
 # Ignore any eventual Eclipse project files, these don't belong in the
 # repository.
@@ -17,4 +20,4 @@
 *.swp
 *.bak
 *~
-*~
+pom.xml.releaseBackup

.travis.yml

@@ -0,0 +1 @@
+language: java

INSTALL

@@ -1,20 +1,21 @@
-Howto build and use the BitTorrent library
+Howto build and use the ttorrent library
 ==========================================
 
 Dependencies
 ------------
 
 This Java implementation of the BitTorrent protocol implements a BitTorrent
-tracker (an HTTP service), and a BitTorrent client. The only dependencies of
-the BitTorrent library are:
+tracker (an HTTP service), and a BitTorrent client. All dependencies are managed
+by maven. The only dependencies of ttorrent-core are:
 
-* the log4j library
 * the slf4j logging library
 * the SimpleHTTPFramework
+* the Apache Commons (Codec and IO)
 
-These libraries are provided in the lib/ directory, and are automatically
-included in the JAR file created by the build process.
+The CLI module also depends on:
 
+* the log4j library
+* the jargs library
 
 Building the distribution JAR
 -----------------------------
@@ -23,6 +24,14 @@ Simply execute the following command:
 
   $ mvn package
 
-To build the library's JAR file (in the target/ directory). You can then import
+To build the library's JAR file (in the core/target/ directory). You can then import
 this JAR file into your Java project and start using the Java BitTorrent
 library.
+
+This will also create a shaded JAR (in the cli/target/ directory). You can then use
+this JAR file in conjunction with the three scripts in the bin/ folder. Each script
+allows execution of one of the following entry points:
+
+* ClientMain - for running a torrent client
+* TorrentMain - for creating .torrent files
+* TrackerMain - for running a tracking server

README.md

@@ -1,6 +1,8 @@
 Ttorrent, a Java implementation of the BitTorrent protocol
 ==========================================================
 
+[![Build Status](https://travis-ci.org/mpetazzoni/ttorrent.png)](https://travis-ci.org/mpetazzoni/ttorrent)
+
 Description
 -----------
 
@@ -65,6 +67,22 @@ usage message on the console when invoked with the ``-h`` command-line flag.
 
 ### As a library
 
+To use ``ttorrent`` is a library in your project, all you need is to
+declare the dependency on the latest version of ``ttorrent``. For
+example, if you use Maven, add the following in your POM's dependencies
+section:
+
+```xml
+  <dependencies>
+    ...
+    <dependency>
+      <groupId>com.turn</groupId>
+      <artifactId>ttorrent-core</artifactId>
+      <version>1.5</version>
+    </dependency>
+  </dependencies>
+```
+
 *Thanks to Anatoli Vladev for the code examples in #16.*
 
 #### Client code
@@ -82,6 +100,12 @@ Client client = new Client(
     new File("/path/to/your.torrent"),
     new File("/path/to/output/directory")));
 
+// You can optionally set download/upload rate limits
+// in kB/second. Setting a limit to 0.0 disables rate
+// limits.
+client.setMaxDownloadRate(50.0);
+client.setMaxUploadRate(50.0);
+
 // At this point, can you either call download() to download the torrent and
 // stop immediately after...
 client.download();
@@ -95,6 +119,9 @@ client.download();
 client.waitForCompletion();
 
 // At any time you can call client.stop() to interrupt the download.
+
+// If you plan on using the downloaded file(s) right away uncomment the line below
+//client.getTorrent().finish();
 ```
 
 #### Tracker code
@@ -124,6 +151,23 @@ tracker.start();
 tracker.stop();
 ```
 
+### Track download progress
+
+You can track the progress of the download and the state of the torrent
+by registering an `Observer` on your `Client` instance. The observer is
+updated every time a piece of the download completes:
+
+```java
+client.addObserver(new Observer() {
+  @Override
+  public void update(Observable observable, Object data) {
+    Client client = (Client) observable;
+    float progress = client.getTorrent().getCompletion();
+    // Do something with progress.
+  }
+});
+```
+
 License
 -------
 
@@ -134,21 +178,22 @@ License version 2.0. See COPYING file for more details.
 Authors and contributors
 ------------------------
 
-* Maxime Petazzoni <<[email protected]>> (Platform Engineer at Turn, Inc)  
+* Maxime Petazzoni <<[email protected]>> (Software Engineer at SignalFuse, Inc)  
   Original author, main developer and maintainer
 * David Giffin <<[email protected]>>  
   Contributed parallel hashing and multi-file torrent support.
 * Thomas Zink <<[email protected]>>  
   Fixed a piece length computation issue when the total torrent size is an
   exact multiple of the piece size.
-* Johan Parent <<parent_johan@yahoo.com>>  
+* Johan Parent <<parent\_johan@yahoo.com>>  
   Fixed a bug in unfresh peer collection and issues on download completion on
   Windows platforms.
 * Dmitriy Dumanskiy  
   Contributed the switch from Ant to Maven.
 * Alexey Ptashniy  
   Fixed an integer overflow in the calculation of a torrent's full size.
 
+And many other helpful contributors on GitHub! Thanks to all of you.
 
 Caveats
 -------

bin/ttorrent

@@ -0,0 +1,73 @@
+#!/bin/sh
+
+# Copyright (C) 2012 Turn, Inc.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+EXECJAR="ttorrent-*-shaded.jar"
+
+real_path() {
+    case $1 in
+        /*)
+            SCRIPT="$1"
+            ;;
+        *)
+            PWD=`pwd`
+            SCRIPT="$PWD/$1"
+            ;;
+    esac
+    CHANGED=true
+    while [ "X$CHANGED" != "X" ] ; do
+        # Change spaces to ":" so the tokens can be parsed.
+        SAFESCRIPT=`echo $SCRIPT | sed -e 's; ;:;g'`
+        # Get the real path to this script, resolving any symbolic links
+        TOKENS=`echo $SAFESCRIPT | sed -e 's;/; ;g'`
+        REALPATH=
+        for C in $TOKENS; do
+            # Change any ":" in the token back to a space.
+            C=`echo $C | sed -e 's;:; ;g'`
+            REALPATH="$REALPATH/$C"
+            # If REALPATH is a sym link, resolve it.  Loop for nested links.
+            while [ -h "$REALPATH" ] ; do
+                LS="`ls -ld "$REALPATH"`"
+                LINK="`expr "$LS" : '.*-> \(.*\)$'`"
+                if expr "$LINK" : '/.*' > /dev/null; then
+                    # LINK is absolute.
+                    REALPATH="$LINK"
+                else
+                    # LINK is relative.
+                    REALPATH="`dirname "$REALPATH"`""/$LINK"
+                fi
+            done
+        done
+        if [ "$REALPATH" = "$SCRIPT" ] ; then
+            CHANGED=""
+        else
+            SCRIPT="$REALPATH"
+        fi
+    done
+    echo "$REALPATH"
+}
+
+base=$(dirname $(real_path $0))
+CPARG=$(find ${base}/../build -name "$EXECJAR" | tail -n 1)
+if [ -z "$CPARG" ] ; then
+    echo "Unable to find $EXECJAR"
+    exit 1
+fi
+if [ -z "$MAINCLASS" ] ; then
+    CPARG="-jar $CPARG"
+else
+    CPARG="-cp $CPARG $MAINCLASS"
+fi
+exec java $CPARG "$@"

bin/client → bin/ttorrent-torrent

@@ -1,4 +1,4 @@
-#!/bin/bash
+#!/bin/sh
 
 # Copyright (C) 2012 Turn, Inc.
 #
@@ -14,5 +14,5 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-base=$(dirname $(readlink -f $0))
-exec java -jar $(find ${base}/../build -name "ttorrent-*.jar" | tail -n 1) $*
+EXEFILE="${0%-torrent}"
+MAINCLASS="com.turn.ttorrent.cli.TorrentMain" "${EXEFILE}" "$@"

bin/torrent → bin/ttorrent-tracker

@@ -1,4 +1,4 @@
-#!/bin/bash
+#!/bin/sh
 
 # Copyright (C) 2012 Turn, Inc.
 #
@@ -14,5 +14,5 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-base=$(dirname $(readlink -f $0))
-exec java -cp $(find ${base}/../build -name "ttorrent-*.jar" | tail -n 1) com.turn.ttorrent.common.Torrent $*
+EXEFILE="${0%-tracker}"
+MAINCLASS="com.turn.ttorrent.cli.TrackerMain" "${EXEFILE}" "$@"

cli/.gitignore

@@ -0,0 +1,5 @@
+/target/
+
+/.classpath
+/.project
+/.settings

cli/pom.xml

@@ -0,0 +1,77 @@
+<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">
+	<modelVersion>4.0.0</modelVersion>
+
+	<parent>
+		<groupId>com.turn</groupId>
+		<artifactId>ttorrent</artifactId>
+		<version>1.6-SNAPSHOT</version>
+	</parent>
+
+	<name>Java BitTorrent library CLI</name>
+	<artifactId>ttorrent-cli</artifactId>
+	<packaging>jar</packaging>
+
+	<dependencies>
+		<dependency>
+			<groupId>com.turn</groupId>
+			<artifactId>ttorrent-core</artifactId>
+			<version>1.6-SNAPSHOT</version>
+		</dependency>
+
+		<dependency>
+			<groupId>org.slf4j</groupId>
+			<artifactId>slf4j-log4j12</artifactId>
+			<version>1.6.4</version>
+		</dependency>
+		<dependency>
+			<groupId>net.sf</groupId>
+			<artifactId>jargs</artifactId>
+			<version>1.0</version>
+		</dependency>
+	</dependencies>
+
+	<build>
+		<defaultGoal>package</defaultGoal>
+
+		<plugins>
+			<plugin>
+				<groupId>org.apache.maven.plugins</groupId>
+				<artifactId>maven-jar-plugin</artifactId>
+				<version>2.4</version>
+				<configuration>
+					<archive>
+						<manifest>
+							<addDefaultImplementationEntries>true</addDefaultImplementationEntries>
+						</manifest>
+					</archive>
+					<includes>
+						<include>**</include>
+					</includes>
+				</configuration>
+			</plugin>
+
+			<plugin>
+				<artifactId>maven-shade-plugin</artifactId>
+				<version>2.1</version>
+				<executions>
+					<execution>
+						<phase>package</phase>
+						<goals>
+							<goal>shade</goal>
+						</goals>
+						<configuration>
+							<outputFile>${project.build.directory}/${project.artifactId}-${project.version}-shaded.jar</outputFile>
+							<transformers>
+								<transformer implementation="org.apache.maven.plugins.shade.resource.ManifestResourceTransformer">
+									<manifestEntries>
+										<Main-Class>com.turn.ttorrent.cli.ClientMain</Main-Class>
+									</manifestEntries>
+								</transformer>
+							</transformers>
+						</configuration>
+					</execution>
+				</executions>
+			</plugin>
+		</plugins>
+	</build>
+</project>