Due date: Tuesday, January 27 (FIRM)
This is an individual project
Installation of required course software, through Android Studio, and creation of a Bitbucket account:
- Ensure you have a functioning Android Studio development environment.
- Ensure you can access the course examples from GitHub (found at https://github.com/LoyolaChicagoCode/ - for future projects, filter by android-java).
- Ensure you understand the basics of Java programs and Test-Driven Development (TDD)
An initial understanding of Bitbucket and Android Studio plus Test-Driven Development (TDD)
- Installing required course software
- Using course software
- Using Bitbucket to “import” (copy) an existing Java Git project from GitHub
- Sharing the imported Bitbucket project with the instructor and TA
- Cloning the imported Bitbucket project in Android Studio (Check out project from Version Control)
- Using Android Studio to update the cloned project
- Updating the cloned project by committing it in Bitbucket
- Using TDD
- Running the project tests in Android Studio and understanding the results
- Running on an emulated or real Android device
- Running in a Java SDK using "gradle unittest" (not for Project 1)
- Applying TDD by modifying the project source code so the tests pass
- Java coding
- Understanding why the project tests fail and how to modify the program to fix it
In this project, you will import an existing Java Git project from GitHub into Bitbucket, download it / clone it into Android Studio by "Checking it out" on your PC, run its single failing test, update the project source to fix the program, and commit your changes to your project Bitbucket. Your imported project will be shared with the instructor and TA for grading.
Importing the base version of Project 1 into Bitbucket
Start with this code skeleton: https://github.com/LoyolaChicagoCode/hello-java. See below for detailed instructions about how to import this into Bitbucket.Cloning the base version of Project 1 into Android Studio on your PC
To clone your hello-java project into Android Studio, open Android Studio and click Check out project from Version Control on the welcome page, select Git (not GitHub), then copy the https URL for your repository into the first field of the window that comes up. Select a parent directory or folder on your PC that will contain your course Projects, and change the name of the checked-out project to cs313sp15p1, then click Clone. You will probably have to enter your Bitbucket password to get the clone to complete. If you have any problems cloning your repo to your PC, use SourceTree instead.
Functional requirements for Project 1
The functional requirements for this Project are embodied in the JUnit tests in the test folder; instructions for running the test are detailed below. When your code passes all the tests, you will have fulfilled the functional requirements for grading purposes. If some of the tests do not pass, you will receive partial credit.
Specifically, fix the code in the Java source file within the src folder, using the test cases as your guide. Be sure to push your changes continually (under VCS in Android Studio, or by using SourceTree)!
Create a new doc folder within your local project root folder. Include your screenshot called project1.png inside the doc folder (see details below).
Notify the instructor and TA when the project is ready to be graded by Submitting a note on Sakai in the Project 1 Assignment.
- 1 point – submission via Bitbucket repo (should still show the history before clone)
- 1 point – fix the getYear method to make the tests pass
- 1 point – screenshot showing the fixed getYear method and the tests passing
3 points total
To do Project 1, follow these steps carefully; note that they may be updated as we get feedback about any problems that students encounter:
- Install the first 6 sets of "Required Software": http://laufer.cs.luc.edu/teaching/313/software, Java SDK through Android Studio. The current default for Java is Java 8.
Note: after you install Android Studio, check for updates and install any that are available. Also be sure to install Android SDKs (not needed for Project 1).
Now go to http://bitbucket.org and create an account using your Loyola email (if you already have such an account, just use it). Bitbucket is a cloud-based system that hosts so-called repositories in Version Control Systems (VCSs) Git and Mercurial. We'll be using Git in this class. Using your Loyola email allows you to create an unlimited number of Bitbucket repositories.
- On Windows you may need to modify System Environment variables PATH, CLASSPATH, and JAVA_HOME to include the path to the javac and java commands. Ask me or our TA on Piazza how to do that if you need to and can't get the instructions in the attached file to work.
- On Mac OS X or Linux you may have to modify just the PATH Environment Variable in your .profile or .bashrc file. Again, ask if you need to do that, and can't get it to work.
- Information about how to set these variables is in the text file attached to this webpage.
- And, of course, ask us if you need help with any installation.
Once you have installed everything and created a Bitbucket account, use Android Studio to download an Android Console project hosted in Bitbucket from a Git repository as described above in the Cloning section. To get the Project 1 tests to run in Android Studio, you will perform the following steps:
- You'll be asked if you want to create a repository or import one - choose import and then change Source to Git and Language to Java
- Set the URL field in the Import existing code window to: https://github.com/LoyolaChicagoCode/hello-java/
This is the GitHub location of the Android Studio repository for Project 1. Bitbucket will fill in the name hello-java in the Name field. Instead, change that name to cs313sp15p1 (this is the required name for the repository – the p1 part refers to Project 1).
- Next, click Import repository and open your cs313sp15p1 repository by clicking on that name if it is not already open. In the Overview section click in the field to the right of HTTPS and copy the URL there - that is the Bitbucket URL to your copy of the hello-java Android Studio project.
- Now click Share toward the top and share your repository with me at email@example.com and with our TA at firstname.lastname@example.org - share your repository with us with admin access.
To finish Project 1 you must change file HelloWorld.java in hello-java so that the tests all pass (there are two others in addition to the one that fails), then commit your changes in Git. You will also need to upload a screenshot of the successfully-run tests from the project into a new doc directory/folder that you create in your project on your PC, add that screenshot and directory to your local Git repository, commit that change as well, and finally push both changes to your Bitbucket repository in the cloud. If you have any problems doing those steps in Android Studio, use SourceTree instead. You can put the doc directory at either the cs313sp15p1 level or under src - in either case, right-click where you want to put it in the project window and select New then Directory and name it doc.
- Click on cs313sp15p1 on the Welcome page, and after Android Studio opens its project page, press Alt-1 to open the project window on the left, then select Project view rather than Android at the top left of that window - that shows the "directory" structure of the cs313sp15p1 project and all of its components (you should be able to open all the right-facing arrows under src to see files in the main and test directories).
- Now click Build at the top of the Android Studio window and select Rebuild Project - you will probably be asked to select an SDK (software development kit) for the Project, so select the version of Java that you installed earlier in the window that comes up. When you have done that, do the Rebuild Project again, and it should work now.
- Note: on Windows there seems to be a problem where two "modules" show up rather than just one - both the cs313sp15p1 project you imported into Bitbucket and some holdover from the original hello-world project. Follow these steps to fix that:
- Go to the File => Project Structure window, click Modules in the left column, select cs313sp15p1 in the second column, then click the minus sign above it and confirm the removal of that module - you should now be able to set the SDK to Java 8u25. (I did not have to do this on my Mac OS X Yosemite, the cloned Project did not have this error; however if your Mac experiences the error, follow the same process to fix it.)
- While you're jn the Project Structure window, click Paths toward the top right and click the button that says Use module compile output path, then click OK.
- Now under Build once again select Rebuild Project and tell Android Studio to remove the cs313sp15p1 project's "VCS root" (if you had the SDK problem and fixed it as above).
- Right-click (Windows) or CTRL-click (Mac) the Project name cs313sp15p1 on the left and select Create 'All Tests' about halfway down, then click OK - you may get an error message, this time saying that the output path(s) have not been specified.
- If so, in the Project Structure window that opens, click on Project under Project Settings and select the same Project SDK as you did in the previous step, and also fill in the directory/folder path where you stored cs313sp15p1 followed by "/classes" - it should look like this on Windows: C:\Users\yourUserID\cs313sp15p1\classes, or /Users/yourUserID/cs313sp15p1/classes on a Mac. Now the Create 'All Tests' should work - if not, see me or our TA.
- Finally, at the top of the Android Studio window click the run arrow to the right of All in cs313sp15p1 to run the tests - there should be one failure that you will have to fix. You can see the test that failed by double-clicking TestHelloWorld in the test section of the project window on the left; notice that this test "fixture" creates a HelloWorld object (from HelloWorld in the src section of the project window) and runs three tests using that object - only the third test fails, that's the one you have to fix.
Note: there are instructions for connecting to Git on Bitbucket using SSH so that you don’t have to enter your Bitbucket password every time you do a commit – follow this URL: https://confluence.atlassian.com/display/BITBUCKET/Set+up+SSH+for+Git for more information. Some students have had problems using those instructions in the past, so you may have to fall back on entering your password each time …
How to submit
To finish Project 1 you must change file HelloWorld.java in hello-java so that the tests all pass and then commit that change in Git. You will also need to upload a screenshot of the successfully-run tests from that project into the project’s new doc directory/folder on your PC, add it to your local Git repository, commit that change as well, and finally push both changes to your Bitbucket repository in the cloud.
As the first step in working on this project, you will import the code skeleton into a private Bitbucket repository shared with your instructor and the TA. The name of the repository is cs313sp15p1, where the p1 part refers to Project 1. When your work is ready to be graded, please notify your instructor and TA via both Piazza and by Submitting the assignment in Sakai, and add a completion note in the Sakai comments box.