How to Download

There are several ways to download data from the ProteomeCommons.org Tranche network: through the Java GUI as described in the user's guide, through the command-line tool, or through the Java API.

Command line tool

The Java GUI is layered on top of a set of scriptable command-line tools. Here is a link to a ZIP file that contains exactly what you need to use the command-line tool that downloads data. It is assumed that you have a current version of Java installed on your computer. Unzip the ZIP file and you are set. The command to run this tool is the following.

java -jar Tranche-Downloader.jar

The tool will automatically give you a list of options that you can use, including specific server(s) to download from, if digital signatures should be checked, where to save data to, and how to specify the hash of the file(s) to download. Alternatively, you can add the hash you want to download to the end of the line and the tool will get that file. For example:

java -jar Tranche-Downloader.jar {Tranche hash}

Replace the {Tranche hash} in the above example with the Tranche hash you want to download. Once the download starts you will get a listing of the download's progress. Note, if you don't specify any servers the tool will automatically attempt to find the servers that contain the data. The tool will also skip the downloading of any file that is already present, i.e. you can easily resume downloads or check that you have all the files by simply starting the download again.

For the following options, you are required to place them before the Tranche hash, as shown in the following example:

java -jar Tranche-Downloader.jar {options} {Tranche hash}

Any combination of options may be used in a command.

-cert option

After setting the -cert option, specify the file location of a X.509 Certificate to use as a trusted authority. A project or file will only be downloaded if the project, or file, has been signed by the trusted authority.

java -jar Tranche-Downloader.jar -cert {file location} {Tranche hash}

Multiple '-cert' commands may be used. Only content signed by one of the given certificates will be downloaded.

java -jar Tranche-Downloader.jar -cert {file location 1} -cert {file location 2} {Tranche hash}

-file option

After setting the -file option, specify the file or directory that the Tranche code should save the data to, as shown here:

java -jar Tranche-Downloader.jar -file {location} {Tranche hash}

-regex option

After setting the -regex option, specify a regular expression that will limit the files that are downloaded. Only files with names that match the regular expression will be downloaded. A great use for this is to download only files of a certain extension. The following is an example of how to use the option:

java -jar Tranche-Downloader.jar -regex {regex} {Tranche hash}

To use the regular expression to download only ".pkl" files, use the following:

java -jar Tranche-Downloader.jar -regex \.pkl {Tranche hash}

Notice that the period character was preceded with a backslash. If you would like to download more than one type of file, like either ".pkl" or ".t2d" files, use the "|" character betewen the two:

java -jar Tranche-Downloader.jar -regex \.pkl|\.t2d {Tranche hash}

There are many regular expression tutorials available online. We recommend using O'Reilly's Regular Expression Pocket Reference.

-server option

After setting the -server option, specify a server to download from, as shown in the following example. If the file you are trying to download is not found on that server, the download will fail.

java -jar Tranche-Downloader.jar -server {server} {Tranche hash}

For indicating multiple servers to download from, you can simply add-server {server} more times, as shown here:

java -jar Tranche-Downloader.jar -server {server 1} -server {server 2} {Tranche hash}

If the file you are trying to download is not found on any of the given servers you specified, the download will fail.

-tempDir option

After setting the -tempDir option, specify the temporary directory to use while downloading the data. When the download is complete, the data will be moved to its final destination.

java -jar Tranche-Downloader.jar -tempDir {location} {Tranche hash}

-validate option

After setting the -validate option, specify a boolean value that denotes whether or not the data should be validated once downloaded. If the Boolean value is true, then the GetFileTool will check whether the data that was downloaded matches the Tranche hash. Note that the Tranche hash was created using the data that was uploaded. With validation, you can ensure that the data you have downloaded matches the data that was originally uploaded.

java -jar Tranche-Downloader.jar -validate {true/false} {Tranche hash}

Multiple download shell script

You will need the GetFileTool command-line client and the shell script to perform the tasks in this brief section. Unzip the command-line tool in the same directory as the script.

You may wish to download a list of projects. This is particularly convenient if you have a list of projects you wish to download; using the shell script, each project will download sequentially.

There are two ways to use the tool. If you wish to simply provide the hashes as arguments, you can execute the shell script along with the hashes:

./tranche-downloads.sh hash1 hash2 [...]

However, since the hashes are long, this method will cause problems if the list of arguments are not passed due to their length; your shell may restrict the total size of your arguments. It may be more convenient to place the hashes in a text file, one per line. Say we have a text file called hashes.txt (the name is arbitrary; you can call it anything). You can simply pipe the contents to the shell script, which will download the projects in order:

cat hashes.txt | ./tranche-downloads.sh

However, if you use the second method, you must place each hash on a separate line. (As opposed to first method, where the hashes are used as arguments to the script and are separated by spaces.)

Note: remember to make sure the script is executable. If you get a 'permission denied' error while executing:

chmod 755 tranche-downloads.sh

Java API

Remember that Tranche is completely open-source. You are welcome to use, for free, any of the source code in the Tranche project. The following will show you how to set up and use the Java API. Also provided is an overview of the DownloadProject code snippet, provided in the code snippets documentation.

Setting up development environment

To start using the Tranche Java API, you will first need to download the Tranche source code. Clean and Build the project. For further information on how to set up your Tranche source code, you can consult the beginning developer's tutorial.

Next, use Netbeans to link to the project by opening the project's properties and selecting Libraries, as shown here:

Click the Add Project... button on the right side of the window and locate the folder your Tranche source code is in and select it. Click the Add Project JAR Files button, as shown here:

You now have full access to the Tranche Java API. Read the next section, an overview of using the DownloadProject code snippet, to get an idea of how to use the Java API. For more information on how to use the API, consult the JavaDocs.

Sample code snippet

We have written some of the most commonly requested code snippets, one of which downloads a project. You are free to use and modify these code snippets for your needs. The following is a walk-through of the DownloadProject code.

Open DownloadProject.java to see the full code that will be reviewed here.

package org.tranche.example;

The package the code is contained in may be changed. You are not required to keep this.

import java.io.File; import org.tranche.hash.BigHash; import org.tranche.get.CommandLineGetFileToolListener; import org.tranche.get.GetFileTool;

You are required to import the classes that are to be used in the code. Keep these lines.

public class DownloadProject { public static void main(String[] args) throws Exception {

The code snippet is runnable because it contains a main method. Keep this to allow the snippet to be runnable.

// the hash to download BigHash hash = BigHash.createHashFromString("mGNNW+dCIIk0hEqUFOgM4QBi15TYjGX3I1I6V7uo9JDKHJu8Ks8kx+hwKhumqFu6XXjCy1D7IqP3/hZjLnqW0MbR2YsAAAAAABdZew==");

This line of code creates a BigHash object out of the string within the createHashFromString method. Replace this string with any Tranche hash you want to download. Of course it is not required that you explicitly name the Tranche hash -- you could replace the given Tranche hash with a String object.

// use the GetFileTool to download the project file GetFileTool gft = new GetFileTool();

Keep this line as it is. The GetFileTool object is the workhorse for downloading from the Tranche network.

gft.setHash(hash);

It is required to tell the GetFileTool object the hash of the project you want to download, so keep this line.

// don't bother double-checking digital signatures gft.setValidate(false);

You may, or may not, want to include the setValidate method with the value of either true or false. If the Boolean value is true, then the GetFileTool will check whether the data downloaded matches the Tranche hash. Note, the Tranche hash was created using the data uploaded. With validation, you can ensure the data you have downloaded matches the data originally uploaded.

// save the contents to a directory -- a file would download just the project file itself File dir = new File("download"); dir.mkdirs();

A File object is used to represent the directory to be downloaded to. In this case, we are going to download the project into a folder named "download" in the same directory as the script. If the directory does not exist, the dir.mkdirs(); line will create the directory.

// before downloading register a command-line display gft.getListeners().add(new CommandLineGetFileToolListener(System.out));

This line will set the local System.out as the standard output of status information. It is not required to keep this line of code.

// get the project using the specified base directory gft.getDirectory(dir);

Executes the download. The Tranche hash used in this example was for a fairly large project, or a set or files, which is why the getDirectory method is used.



Home   •   FAQ   •   Contact Us   •   Join email list   •   Collaborations   •   Credits