pCDN:develop

Developing new features for the pCDN client

This document describes the software tools used in accessing pCDN source code and building pCDN client binary. This document also provides step-by-step instructions for testing the pCDN client using basic test cases.

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 repository. 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 all examples given in this document, you should substitute your account name for mine (cha16).

Checking out the project using command-line subversion tool requires the following steps:

1. mkdir pCDN (or any other directory name)
2. cd pCDN
3. svn co https://cha16@cs-svn.cs.surrey.sfu.ca/svn/nsl/pCDN .

Note that the svn utility will prompt for your unix password. Send an email to Cheng if you encounter any problems while checking out the files. 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. fig_1 Last, 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 GUI on MS windows. We have setup TortoiseSVN on all Windows machines. Checking out the project using TortoiseSVN requires the following steps:

1. right click on the desktop (or within the explore)
2. select "SVN Checkout" as showed in the next figure

fig_2

1. fill out the project URI and the destination directory as showed in the next figure, and click OK

fig_3 TortoiseSVN will prompt for your account and password. The following figure shows the expected output of a successful checkout. fig_4

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 different folder. To address this potential complication, we use a simple make file system called "Apache ant", which is very similar to the traditional UNIX make system. Installing ant is straightforward in 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 build 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 jar file). I recommend the first approach because you will lose all stdout and stderr messages if you launch pCDN client by double-clicking. 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.

You may decide to use IDE to develop, build, and debug your code. However, before checking in your code, please make sure that others can build the binary using ant system.

Play with pCDN binary =

The pCDN client loads a configuration file, called conf.xml, at bootup time. This file contains several critical setting that will be used in bootstrapping the pCDN client. 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 txt 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 This file contains a list of available trackers. 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 peerid based on the 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). For now, just remove the whole line. Save the file, 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. fig_5

Next, we want to download something through the pCDN client. Notice that every media file is given a unique object ID in pCDN system. The content distributors must provide the object ID to the users through some out-of-band channel such as using an XML podcast feed or a web page. Here, we use a simple web page to deliver the object ID 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 an object in the pCDN network. Please only use the first two URLs, and ignore the other two for now. 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 second, you should see the file has been downloaded, similar to the following figure. fig_6

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 fig_7

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. fig_8 Logging system is important in multi-threading systems like the pCDN. 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 at all, to fix such problem. This will get much worse if the bug is discovered in the field. So, please plan ahead, and put detailed logs in your subsystem. This will make our life easier.

Commit code changes

Check the manual of your choice of subversion client 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 a new file 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 case, the files/directories are not sent to the repository until you commit the code.

Please skim through a subversion tutorial, and send Cheng an email if you have any doubt.

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.

Before committing the code, make sure it compiles and runs. You have to carefully go through the list of files you have changed.

Importing pCDN project into Netbean and Eclipse

IDEs such as Netbean and Eclipse also use the ant build system. Hence, they provide the mechanism for importing ant-based projects. To be completed.