Due date: Monday, June 5 (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 in a Java SDK by right-clicking and choosing Run => All Tests
- Running in a Java SDK using "gradle unittest" or "gradle testDebug" (not for Project 1)
- Running on an emulated or real Android device (not for Project 1)
- Applying TDD by modifying the project source code so the tests pass and fixing any bad tests
- Java coding
- Understanding why the project tests fail and how to modify the program and the tests to fix that
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 from your Bitbucket repository 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 cs313su17p1 or cs413su17p1 (depending on your class number), 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. In addition, there might be one of the test cases that is not correct, and that also needs to be fixed. Be sure to push your changes continually (use push under VCS in Android Studio, or do a push 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 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 and one of the tests to make the tests pass
- 1 point – screenshot showing the fixed getYear method and all 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": https://sites.google.com/a/cs.luc.edu/laufer/teaching/313/software, Java SDK through Android Studio. Note that the only required software for this course is Java and Android Studio; the other software may be helpful, and so might the seventh software, GenyMotion, which provides a much faster Android emulator than Android Studio.
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 using your Loyola email, just use it). Bitbucket is a cloud-based system that hosts so-called repositories or repos 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 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 at the bottom of this webpage.
- And, of course, ask 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:
- Click on Create at the top of the Bitbucket web page.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 may fill in the name hello-java in the Name field. Instead, change that name to cs313su17p1 or cs413su17p1 depending on your class (this is the required name for the repository – the p1 part refers to Project 1).
- Next, click Import repository and open your cs313su17p1 or cs413su17p1 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 with admin access. Note that this is not my standard Loyola email address, it is a special Bitbucket account I use only for COMP 313 and 413 repository grading.
To finish Project 1 you must change file HelloWorld.java and the one incorrect test in the project so that the tests all pass (there are three tests in total), then commit your changes in Git using the Android Studio VCS menu. 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 (right click the screen shot file, and use the Git => Add menu item), commit that change as well, and finally push both changes to your Bitbucket repository in the cloud. You should be able to find push in Android Studio by doing a VCS => Open VCS Popup (it was choice 8 in the version on my PC). If you have any problems doing those steps in Android Studio, use SourceTree instead. You can put the doc directory at either the cs313su17p1 or cs413su17p1 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, then right-click its name, choose Open in Explorer, and copy the screenshot there before you do the Add and push.
- Click on cs313su17p1 or cs413su17p1 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 the Project view rather than Android at the top left of that window - that will show the "directory" structure of the cs313su17p1 or cs413su17p1 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).
- Right-click (Windows) or CTRL-click (Mac) the Project name cs313su17p1 or cs413su17p1 on the left and select Run => 'All Tests' from the menu to run the project tests - there should be two failures that you will have to fix, one a source code failure, and the other a problem in one of the tests. You can see the test(s) that failed by double-clicking their names in the test section of the project window on the left; notice that the TestHelloWorld test "fixture" creates a HelloWorld object (from HelloWorld in the src section of the project window) and runs three tests using that object - the third test fails, that's the one where you have to fix the source code; one of the other tests also fails, and you will need to fix the test itself, because it's incorrect.
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. The name of the repository is cs313su17p1 or cs413su17p1, where the p1 part refers to Project 1. When your work is ready to be graded, please notify your instructor via both Piazza and by Submitting the assignment in Sakai, and add a completion note in the Sakai comments box.