Homework 1: Start a Project with SVN and Eclipse

To Deliver: 

1. email with answers to Q1-4 (plus photo of yourself to help us learn who-is-who unless you have done that already), send email to the grader for your section: Section 1: Md Atiqur Rahman <mrahman@email.wm.edu>, Section 2: Jianhua Sun <jsun01@email.wm.edu>
2. svn repository in your home directory that contains a cs301 project with the updated Knightstour code.

To Download:

1. Either download tar file with input from here or directly copy files from /home/scratch/kemper/cs301codebase/KnightsTour

Due date for submission: Sep 4, at noon (12.00 PM)

Drop out date: Sep 6, at noon (12.00 PM)

Motivation

Many people contribute to a software product in a professional environment. Software development means team work.  If many people edit and change files with program code in a common code base, there is a need for a system that keeps track of changes and a mechanism that avoids that people destroy each others work. 

This is the job of  a versioning system. A versioning system is used to allow developers to perform changes to a shared code base in a concurrent manner. We will make use of subversion (SVN) in our CS 301 projects to get some practical experience in working with a versioning system. 

As each student will work on his/her own project, the sharing will take place only between student, grader and instructor. 

For professional software development, it is very common to use an integrated development environment that makes common task easy and automates certain procedures. We will also work with eclipse as our integrated development environment. Eclipse is a huge system with many features which is particularly strong in Java programming. The initial learning curve pays off if a project reaches a critical size and complexity. 

So this homework will get you started with subversion, eclipse and some prepared Java code that will be the topic of first project assignment.

To do list for beginners of Java and Eclipse:

• Please visit our CS 301 wiki for instructions and tutorials to quickly familiarize yourself with Java and Eclipse.
• The wiki also contains links to video tutorials. In particular the video tutorials by Mark Dexter are really good as they also cover unit testing and test driven design. Note that we do not check if you worked through those tutorials. It is really up to you to decide if you benefit from this or not.

To do list for all students:

• Preliminary steps:
• You need a CS account which you can request online on any Linux box in the CS 121 lab by running the new user script.  
• In order to work on Linux boxes in the CS lab: eclipse and svn are already installed.
• (Optional, but recommended as space in CS 121 lab is insufficient.) In order to work on your own Linux/XP/Vista/MacOS PC: download and install eclipse (if not installed yet). You will make use of subversion on a lab machine, where it is already available, so it is important to pick the right combination of the subclipse plugin for eclipse to match with the subversion running on the department server. The CS 301 wiki page has some further information on installation issues with eclipse and subversion, in particular which versions are used in class and work together.
• Step 1: Set up a directory for subversion on a CS lab machine
• On a lab machine: use "svnadmin create ~/svncs301" to create a new svn repository at your home directory to hold your programming projects for cs301.  
• It is important that you do this step on a CS lab machine, because this way the SVN repository will be accessible (after adjusting some access rights) to the grader plus it will automatically been backed up within the departmental data storage system.
• So even if you work on your own laptop or PC, the SVN repository should reside on the departmental machine!
• For more information on subversion see http://svnbook.red-bean.com
• Step 2: Set up a new project cs301 in eclipse
• Start eclipse. 
• On a CS lab machine: we use /usr/remote/cs301/eclipse/eclipse and NOT the default /usr/bin/eclipse for CS 301. If you simply type "eclipse" in a terminal, it will start the default eclipse installation which will not work for you! You need to type  /usr/remote/cs301/eclipse/eclipse (setting an alias for your shell will save you the typing).
• Eclipse may ask for a workspace directory (which is where all your files with Java code and other project related files will reside). 
• On a CS lab machine, you may pick /home/f85/<yourname>/workspace for example. This will create a directory "workspace" in your home directory. Note that your home directory is subject to space limitations which you can check by typing "quota -v".
• Example: if your account name is "kemper", then you would pick  /home/f85/kemper/workspace.
• Eclipse may recognize that it does not have the location of the Android SDK. 
• On a CS lab machine, do not install yet another Android SDK, choose the option to use an existing one, it is located in "/usr/remote/cs301/android-sdk-linux_x86".
• On your private laptop or PC, you need to download and install the Android SDK (check the CS 301 wiki pages for instructions).
• Pick the resource view, create a new Java project (menu entry File->New-> Java Project) with name "cs301". The default settings in the window are ok.
• Create an additional source folder named test, such that you have 2 folders: "src" and "test" under your project directory. 
• Import the homework files
• On a CS lab machine, you can directly import files from /home/scratch/kemper/cs301codebase/KnightsTour into your new Java project (select project, right click->import->general->filesystem). The directory is accessible from cs lab machines. 
• On your private laptop or PC: Alternatively, all files are archived in a tar-file you can download from here. 
• Importing files into Eclipse is a bit tricky in the sense that you need to know what you are aiming for. 
• The resulting Eclipse project cs301 is supposed to have the following structure:
• source directory "src" with a package (directory) knightstour that contains files GUI.java and Tour.java
• source directory "test" with a package (directory) knightstour that contains a file TourTest.java
• files in directory data should not go into the eclipse project, those will be used separately in Step 5 below.
• Check the build path for your cs301 Eclipse project (select project, right click->properties->Java Build Path). It needs to be adjusted in the following way: 
• You need to add the "test" directory to the list of directories that contain source code (select project, right click->Build Path->Source->Add Folder, pick "test" directory)
• You need to add the JUnit 4 library (select project, right click->Build Path->Add Libraries, pick Junit and then Junit 4). 
• This will make at least some error flags disappear. 
• Eclipse will recognize lots of errors as the code base is incomplete. 
• Open file GUI.java and look for error markers (little red boxes with a white cross), you will find one for sure in method init() with a line "new KnightsTourSolver()", use the Eclipse quick-fix feature (click on the error marker and select the option to create a class KnightsTourSolver). This will result in a new file KnightsTourSolver in directory src that has an empty default implementation to satisfy the compiler requirements.
• Build project (Top menubar -> Project, where you can also select "Build automatically), which should work with no errors (don't worry too much about warnings, however, errors need to be taken seriously and resolved before you can run the code)
• Run project, (select project, right click->run as->java applet: to launch the applet). If it works, the applet will show an empty matrix of squared blocks with three buttons below.  You should press the red button. This will show you a particular number on the console output window.
• QUESTION 1: What is the value of this number? 
• QUESTION 2: What type of file is in directory test/knightstour? Hint: be as precise as possible, "a Java file" is not precise enough! Have a look inside, what kind of code is this?
• Step 3: Connect project with your svn repository (you can also check the CS 301 wiki pages for instructions)
• Eclipse by default uses a connector to svn that does not work well in the lab, so we need to adjust this. To switch from JavaHL to the SVNKit as a connector do the following:
• In eclipse check from pull down menu "Window->Preferences", pick "Team->SVN" on the left side of the window.
• You should see a screen with multiple tick boxes for "General SVN settings". 
• Go close to the bottom and SWITCH the Client under "SVN Interface" from JavaHL to SVNKit.
• Add your project to your svn repository 
• in Eclipse, select project, right click->Team->Share project, select the last entry that says SVN, select Create a new repository location, 
• use a url like svn+ssh://<labmachine>.cs.wm.edu/home/f85/<your-home-directory>/svncs301 where <labmachine> is the name of a machine in the CS lab and <your-home-directory> is the name of your home directory. 
• Example: for a machine named "al" (written on a sticker on the linux box) and a user named "kemper": the url string is svn+ssh://al.cs.wm.edu/home/f85/kemper/svncs301
• Perform an initial import into your svn repository.
• Step 4: Modify code and update svn repository 
• Modify the code for handling the red button in GUI.java to popup a window with each message instead of printing the message to the console terminal. The code distinguishes several cases, you may want to add the popup window to each case one by one. 
• Note: Search the Java documentation for existing functionality to do this. This is more a "find the right method" task and does not require much programming!
• Hint: check slides we discussed in class to introduce some Java basics
• QUESTION 3: which Java package provides you with methods to create such windows?
• Commit the modified code to the subversion repository.
• QUESTION 4: Do you happen to know the origin of this red button dialog? If not, try an internet search ... yes, it is from a book … or go through Steps 5 and 6.
• Step 5: Export the code and run it in a browser
• Export the code into a jar file 
• Right click on project in package explorer window -> export->Java->jar file. 
• Select only the source code folder src, not the test folder. 
• Pick "mytour" as the name of the jar file (if you pick a different one, you need to make further adjustments below).
• Sign the jar file:
• Brief but slightly outdated tutorial is here.
• As this is for the first time, you have to create a .keystore file in your home directory (documentation on keytool is here): 
• open a terminal window and type the following command: keytool - genkey
• Note: -genkeypair was previously named -genkey in older releases (still supported).
• Check if this worked
• type the following command into the terminal window: keytool - list. This should ask for a password and should then reveal what is in the file. The last line most likely says "mykey" plus a date and "PrivateKeyEntry".
• Sign the jar file by typing the following command into the terminal window: jarsigner mytour.jar mykey. 
• Note: you have to be in the same directory as your jar file or you would have to provide the path to the file as a parameter to jarsigner.
• A tutorial for jarsigner is here.
• Create a webpage that runs your applet
• For simplicity, you can copy 2 prepared files either from /home/scratch/kemper/cs301codebase/KnightsTour/data, namely KnightsTour.html and knightstour_applet.jnlp or from data directory in the tar file that you downloaded and imported into your cs301 project.
• Move all three files (the new jar file you created, the jnlp file and the html file) into the same directory. 
• Open the html file in a browser of your choice, for example, firefox.
• Clicking 4 times on the red button should help you find the answer to question 4 in step 4.
• For more information on deploying an applet check this page.
• Make the webpage accessible for the grader in your home directory of your CS account.
• Create our use an existing directory named "public" located in your CS home directory ("public_html" is an acceptable directory name as well).
• Move your solution to step 5 of this homework into this directory.
• Check the use of the "chmod" command with the linux manual (e.g. type "man chmod" in a terminal).
• Use the chmod command to set access rights wisely to make your KnightsTour webpage, applet and jar file accessible for external access (in this case mainly the grader). 
• Check that the grader (just like any other user) can open a webpage "KnightsTour.html" in your public_html directory to run your Knight's Tour code. 

Finally: send an email with your answers to Q1-4 plus a photo of yourself to the grader (see CS 301 syllabus for email address) before the dropout deadline. The photo will help us learn who-is-who in this class. We will also check out your code from your svn repository and see if you performed the required changes. Make sure you checked in your code with subversion!

Grading

• You will receive points for each answer to Q1-4.
• You will receive points for existence of a svn repository from which we can check out your code and the code contains your updated solution (solution to step 4).
• You will receive points for a webpage KnightsTour.html that is located in your public (public_html) directory that is accessible, runs your Knight's tour code (solution to step 5) and that pops up a window (solution to step 4).