This document describes the software tools used in accessing pCDN source code and building pCDN client binary. This document also provides instructions for testing the pCDN client using a simple pCDN setup in NSL.
Check Out the pCDN Project
We use subversion to manage the source code. In subversion, the source code of each project is organized as a directory within the global repository on a subversion server. Each project is identified using a unique URI. The URI for the pCDN project is: https://cha16@cs-svn.cs.surrey.sfu.ca/svn/nsl/pCDN Notice that, throughout examples given in this document, you should substitute your account name for mine (cha16).
Checking out the project using command-line subversion client requires the following steps:
- mkdir pCDN (or any other directory name)
- cd pCDN
- svn co https://cha16@cs-svn.cs.surrey.sfu.ca/svn/nsl/pCDN .
Note that the svn utility will prompt for your unix password. The following figure illustrates the expected output of a successful checkout. The first field "A" means svn has added a new file/directory into your working directory. Run "svn --help" for detailed explanations on the output.
The svn tools comes with all Linux distributions, cygwin/X, and MacOS X Xcode environment as well as fink.
Alternatively, you may check out the project using the GUI on MS windows. We have setup TortoiseSVN on all Windows machines. Checking out the project using TortoiseSVN requires the following steps:
- right click on the desktop (or within the explore)
- select "SVN Checkout" as showed in the next figure
- fill out the project URI and the destination directory as showed in the next figure, and click OK
TortoiseSVN will prompt for your account and password. The following figure shows the expected output of a successful checkout.
Build pCDN Binary in Command Line
As a convention, we do not check in project files generated by IDEs such as Eclipse and Netbean. This is because many of the project files rely on absolute path settings that are not portable once being checked out on another computer under a different folder. To address this potential complication, we use a simple makefile system called "Apache ant", which is very similar to the traditional UNIX make system. Installing ant is straightforward on both Unix and Windows: (1) download and unzip the apache-ant binary package, and (2) set the ANT_HOME environment variable to the ant directory.
Ant employs makefiles in XML format. The project contains three makefiles: monitor.xml, move.xml, and peer.xml. You may ignore the other two and concentrate on peer.xml for now. To tell ant to compile peer.xml, issue the following command: ant -f peer.xml The option -f points to the specific makefile. This command tells ant to perform the default action, which is building a jar file that contains all Java class and external resource. The ant system would compile all Java files under src/ directory. It then zips these class files with some pre-compiled library files (under lib/ directory) and external resource files (under src/resource/) into a peer.jar file. It places the peer.jar file under release/ directory.
There are two ways to execute this peer.jar file. First, you can cd into release/ directory. Then run launch.bat (on Windows) or launch.linux.sh (on Linux). Read the launch scripts if you are using a different OS. Second, you may double click the launch scripts (or the jar file). The first approach in recommended because doing so allows you to see the stdout/stderr outputs. Finally, there is a short cut for executing peer.jar in command line. Just issue the following command: java -f peer.xml run and the ant system will cd into the release/ directory and run the peer.jar.
Run the pCDN Client
The pCDN client loads a configuration file, called conf.xml, at bootup time. This file contains several critical settings used for bootstrapping. The pCDN client provides a GUI to users for modifying the some settings in conf.xml. However, certain fields are not exposed to users, and you will need a text editor to edit the file. Notice that the filename suffix is misleading: conf.xml is just a text file.
Before launching the pCDN client, please go over your conf.xml file. First, make sure the trackerlist_url is pointing to http\://nsl-win.cs.surrey.sfu.ca/trackerlist.txt The above URL points to the testing tracker(s) in NSL. Second, please remove the line of peerid=<some leftover peerid> The pCDN client generates a peerid based on the computer's hardware signature. However, there is no mechanism to detect a pCDN client directory has been manually copied to another machine (thus the peerid should be reset). Therefore, remove the line containing peerid. Save conf.xml, and you are ready to go.
Now launch your pCDN client by, e.g., running ant -f peer.xml run You will see a pizza trayicon (at lower-right corner on Windows and at upper-right corner on Linux/Mac). Click on it and open the session info windows, which is illustrated in the following figure.
Next, we want to download files through the pCDN client. Every media file is given a unique object ID in the pCDN network. The content distributors must provide the object ID to the users through an out-of-band channel, e.g., using an XML podcast feed or a web page. Here, we use a web page to deliver the object IDs to users. Launch the firefox browser and open the following URL http://nsl-win.cs.surrey.sfu.ca/content.html This page contains URLs pointing to objects in the pCDN network. Please only use the first two URLs for now. Cut and paste the first URL into another firefox tab. Upon being prompted, save the media file somewhere on your computer. In a few seconds, you should see the file has been downloaded, as showed in the following figure.
Finally, repeat the same procedure on another computer. You should see the file has been downloaded from the first peer (rather than from the multimedia server). This is showed in the following figure.
Last, notice that the pCDN client heavily uses the Java logger system. The logging messages are written to a file called log.xml. The following figure shows a sample log.xml file.
Logging system is important in multi-threading systems like the pCDN client. This is because many bugs are indeterministic: meaning they don't happen all the time. Without a detailed logging system, there is little chance, if any, to fix such problems. This will get much worse if the bug is discovered in the field, where setting breakpoints is simply impossible. So, please plan ahead, and put detailed logs in your implementation. This will make our life easier.
Commit Code Changes
Check the manual of your choice of subversion clients regarding how to commit code change. In command-line, you usually do svn -m "your comments on the code change" commit . which means check in all changes under the current directory and all subdirectories within it. In Windows GUI, you right-click on the directory and select commit.
Note that you need to explicitly instructs subversion to include new directories/files into the project. In command-line, you usually do svn add directory-/file-list In Windows GUI, you right click on the new file/directory, and select add. In both cases, the files/directories are not sent to the repository until you commit the code.
Last, before checking in the code, make sure it compiles and runs. We often overlook new files/directories, so please carefully go through the list of files you are checking in. You may decide to use IDE to develop, build, and debug your code. However, make sure the binary can be built using ant before checking in your code changes.
Importing pCDN Project to IDEs
IDEs such as Netbean and Eclipse also use the ant build system. Hence, they often provide the mechanism for importing ant-based projects.
To be completed.
