Note that these slides do not cover all the material presented in the screencast.
For this assignment, you will work in small groups to develop a command line interface program to understand various aspects of energy use in the Hale Aloha residence halls. In general, you will invoke the program as follows:
java -jar hale-aloha-cli-<team>.jar
Once invoked, the program will enter a loop in which you can enter commands for the program to execute. For example, here is a hypothetical session where user input is in bold face.
% java -jar hale-aloha-cli.jar
Connected successfully to the Hale Aloha WattDepot server.
> current-power Ilima-A
Ilima-A's power as of 2011-11-07 13:48:56 was 2.3 kW.
> daily-energy Mokihana 2011-11-05
Mokihana's energy consumption for 2011-11-05 was: 89 kWh.
> energy-since Lehua-E 2011-11-01
Total energy consumption by Lehua-E from 2011-11-01 00:00:00 to 2011-11-09 12:34:45 is: 345.2 kWh
> rank-towers 2011-11-01 2011-11-09
For the interval 2011-11-01 to 2011-11-09, energy consumption by tower was:
Mokihana 345 kWh
Ilima 389 kWh
Lehua 401 kWh
Lokelani 423 kWh
Here are the available commands for this system.
current-power [tower | lounge]
Returns the current power in kW for the associated tower or lounge.
daily-energy [tower | lounge] [date]
Returns the energy in kWh used by the tower or lounge for the specified date (yyyy-mm-dd).
energy-since [tower | lounge] [date]
Returns the energy used since the date (yyyy-mm-dd) to now.
rank-towers [start] [end]
Returns a list in sorted order from least to most energy consumed between the [start] and [end] date (yyyy-mm-dd)
Note: towers are: Mokihana, Ilima, Lehua, Lokelani
Lounges are the tower names followed by a "-" followed by one of A, B, C, D, E. For example, Mokihana-A.
One major part of this assignment involves checking the user input for correctness. You must check to make sure that the command is legal, and then if the command is legal, that the correct number of arguments for that command is passed and that the arguments are also legal. You must provide helpful feedback to the user when a problem occurs and allow the user to enter a new command. You should not print a stack trace and exit whenever a problem occurs.
A second major part of this assignment involves the development of an appropriate design for this system. You should assume that this system will be extended with additional commands in future, so you should create a modular system where a central command processor class parses the user input, figures out what the command is, and dispatches to an instance of another class that has the code to handle the command. These latter classes should all implement (for example) a Command interface, so that they can be viewed as instances of the same type of class by the command processor class. The development of an appropriate design means that new commands can be implemented with very few changes to existing classes.
Your package hierarchy might be something like this:
- where your Main class sits.
- where the class or classes associated with your command processor sit.
- where the classes implementing commands sit, as well as the Command interface class. This includes the Command interface class, as well as the class that implement Command (such as CurrentPower, DailyEnergy, etc.)
As said before, the processor class must somehow invoke methods from the appropriate command class implementation. The default approach is to hardwire references to the command classes in the processor class.
If you are feeling adventurous (and I would try this after successfully implementing the default approach), you can use reflection to decouple the processor class from the command class. Create a class (in the command package) called CommandManager. This class can be used by the processor class to obtain a list of instances of all the Command classes. Internally, this class can keep a list of all known Command classes and use reflection to create instances of them.
With this approach, no changes to the code in the processor class need occur when extending the system. To extend the system with a new class, you simply create the new Command class, and update the CommandManager class to return an instance of it as well. No changes to the processor class are needed. If you use this approach, you should discover the set of Command classes at the beginning of execution, and print some output indicating what commands were discovered.
A third major part of this assignment involves team work. Remember that this is a module on project management, and that effective project management means that all team members are efficiently and effectively engaged in the project at all times. A significant part of your grade will be based on how well your team process can be understood from the contents of the commit log and the Issues page, and whether the process shows that all members contributed approximately equally to the system.
A fourth major part of this assignment involves continuous integration. You should immediately create a google project called hale-aloha-cli-<team>, where <team> is the name of your team, and should be no more than 5 characters long. You must then use our class Jenkins server to put your project under continuous integration (i.e. it is built and tested each time a commit occurs). A significant part of your grade will be based upon how well you use continuous integration to develop your project.
A fifth major part of this assignment involves testing. If you design your system correctly, you should be able to test virtually all of the code and ensure that it provides the correct feedback to the user under a variety of input conditions. Note that you should create the tests for your system in parallel with the code. If you wait until the end to start testing, then it is likely that the design of your system will not support thorough testing.
A sixth major part of this assignment involves incremental development. By looking at the commit log and issue list, it is straightforward to see if your team began early and worked consistently on the project, or started late and did things at the last minute. A significant part of your grade will be based upon your team's ability to start early, work regularly on the project, and avoid last minute heroic development efforts.
Note: your team name, hale-aloha-cli-<team>, should be used as the google project hosting project name, the Eclipse project name, the Jenkins job name, the Ant system project name, and the jar file name.
Once you have created your google project, please email me the link.
Due by the end of class on the date noted on the schedule page. At the due date, each team member should send me a private email summarizing the quality of their team's interaction, and the percentage of effort on the project due to each team member. In addition, each team member should create a public blog entry summarizing their experiences with issue-based project management and what worked and what didn't. The blog entry should also detail your group's system, what functionality was implemented and what functionality was not implemented, and your perception of the overall quality of your software. Finally, the Downloads page of the google project should provide a zip file produced using "ant -f dist.build.xml" which Kendyll and I can download to evaluate whether or not your project builds, tests, and runs successfully.
Here are some criteria that will be used in evaluating your submission. Note that this list might be extended, so check back occasionally.
The goal of this assignment is for you to gain a better understanding of what an effectively managed software system using IDPM looks like through review of another system in the class. After completing this review of another project, you will hopefully understand how to better manage your own development project.
Here are the review assignments: Akina/backr, Antonio/pichu, Barbasa/jz, Beck/bking, Cam Liu/backr, Carillo/pichu, Cheng/tiger, Chida/bking, Chung/grads, Connell/chair, Decandia/kmj, Do/jcev, Elfalan/teams, Fang/hash, Foo/backr, Gamiao/cycuc, Hori/tiger, Hirano/hash, Hsu/pichu, Klemme/tnt, Kupfer/chair, Kwock/hash, Lim/tiger, Ly/grads, MacMillan/teams, Mizumoto/teams, Negrashov/tnt, Ogata/kmj, Shaw/jcev, Takabayashi/jz, Takayama/cycuc, Tomaszewski/jcev, Vea/chair, Visitacion/bking, Wilkie/teams, Wilson/backr, Wong/kmj, Yeo/tnt, Young/grads. (If you are not listed, or you are reviewing your own team, let me know as that indicates an error.)
To perform the review, carry out the following instructions, record the results in an email message, and send the results to me and to all members of the team whose project you are reviewing. You will have thirty minutes to complete this review, following which you will be able to meet with your team members. You will be graded on the quality and completeness of your review.
1. Assess quality of Issues page in Google Project Hosting.
In this section, you will assess the ability of the team to do basic project management by seeing if they have been able to decompose the project task into small chunks, document these chunks as issues, and delegate these issues to individual members. You will also assess if all team members have engaged in the project during the past five days.
Go to the Issues page of the team under review. Select "All Issues", then click "Search" to display all Issues recorded so far by the team. Now click the "Grid" button.
1a. Is the Grid displayed with rows=Owner and Columns=Status by default? (Answer Yes or No.)
If not, set rows=Owner and Columns=Status, then continue with the review.
1b. Are all group members represented with a row? (Answer Yes or else list the group members who do not have any issues assigned to them.)
1c. Does each member have at least one issue that they completed, one issue that they have started, and one issue that they have accepted? (Answer Yes or else document the lacking issues.)
2. Assess quality of commit log messages.
In this section, you will assess whether project members have effectively tied their work to individual issues and been able to document this connection through their commit messages.
Go to the Home page of the team under review. Click on "Updates" to see the listing of changes to the project so far. For each change related to an SVN commit (i.e. the rows starting with "r1", "r2", etc.), click the "+" sign to see the entire commit log entry.
2a. What percentage of the commit messages contain a link to an associated Issue? (State the results as a fraction. For example, if there are 10 commits and only 5 contain a link to an issue, then answer "5/10".)
2b. To see how each team member is doing with respect to commit log messages, now compute the fraction for each member. (For example, if Smith committed twice and one of those had a linked issue, and if the other team member Jones never committed, then report the results as: Smith: 1/2, Jones: 0/0.)
3. Assess quality of continuous integration.
In this section, you will assess whether the team has been making effective use of continuous integration practices.
3a. What percentage of the commits so far are under CI? (Use the "Updates" page in Google Project Hosting to determine the number of commits. Do to this, just find the current revision number: for example, if the current revision number is r12, then there have been 12 commits. Now check the Jenkins build history to see how many builds were triggered by a commit. To do this, click on each build number and see if it says "Started by an SCM change". Finally, report the results as a fraction. For example, if the project is on revision 15, and 10 of those commits triggered a CI build, then report the results as "10/15".
3b. What percentage of the project days have had an associated CI build? (To determine this percentage, just total up the number of days during which there has been at least one CI build for this project. Then report the results as a fraction with the denominator of "6", since there have been six days since the project began. So, if there have been CI builds for this project on three days so far, report the results as "3/6".
3c. What is the maximum latency between a failed build and a subsequent successful build? (If the project does not have any failed builds, answer "No failed builds." Otherwise, for each failed build, see how long it took until it was fixed. For example, if the build failed at 12:00, 12:05, 12:10, and then passed at 12:15, then it took 15 minutes to fix that failed build. Compute this latency for each failed build, then report the maximum number of minutes (or hours and minutes).
4. Assess quality of testing.
Check out the project from google project hosting. Read-only status is fine (i.e. use the http: as opposed to https: URL). You do not have to become a project member to do this part of the review.
Once you have checked out the source files for the project to your local workspace, invoke "ant -f jacoco.build.xml" to determine the coverage associated with the project test cases.
4a. Report the current coverage of testing. If there are no test cases, report that. If jacoco aborts with an error, report that. If Jacoco runs, then bring up the report (in build/jacoco) in a browser and report the total coverage associated with the project.
To submit your results, create an email message that you will send to me and to all of the team members on the project. Here is an example submission:
To: email@example.com, firstname.lastname@example.org, email@example.com, firstname.lastname@example.org
Subject: Review of hale-aloha-cli-foo
1b: No. Foo and Bar do not have rows.
1c: No. Foo and Bar have no issues, Baz has no accepted issues.
2a: 6/8 commits have a link to an associated issue.
2b: Baz: 6/8, Foo: 0/0, Bar: 0/0.
3a: 4/8 commits are under CI.
3b: 3/6 days have at least one CI build.
3c: Maximum latency for correcting a failed build was 32 minutes.
4a: Current coverage is 55%.
The purpose of this assignment is to further practice your technical review skills, and to better understand how a software system can satisfy the Three Prime Directives of ICS Software Engineering.
In general, pairs of teams will review each other's project. For best results, each member of the team should perform a complete review of the system, and then the team should meet to share results. Finally, each team member will write up their own analysis based upon all of the data available.
The team pairings are:
Since there are an odd number of teams, the last line indicates how the last three teams will review each other's projects: "pichu" will review "teams", "teams" will review "cycuc", and "cycuc" will review "pichu".
To answer this question, you must download, install, and run the system under review. You should exercise the system with a variety of values for each of its possible commands. You want to discover if there is any functionality that should be present that is not present. You must document what functionality is present in the system and then come to a conclusion regarding the usefulness of the system.
To answer this question, you should begin by carefully reviewing the project site associated the system. Does the home page provide a clear understanding of what the system is supposed to accomplished, perhaps accompanied by sample input and output? Is there a User Guide wiki page that provides details on how to download, install, and execute the system as a user? Is there a downloadable distribution that provides an executable jar file, so that users do not have to compile and build the system in order to use it? Does the distribution contain a version number so that users can easily keep track of what system they are using as it evolves over time? Document the extent to which these are satisfied.
Next, you will want to exercise the system under both valid and invalid inputs, and see if the system responds in a useful way under both conditions. You must document what inputs you provided to the system, how the system responded to the inputs you provided, and then come to a conclusion regarding the "usefulness" of the system.
To answer this question, you should first carefully review the Developer's Guide wiki page to see if it provides clear and comprehensive instructions on how to build the system from sources. The Developer's Guide wiki page should also indicate whatever quality assurance standards are being followed for this project (automated, or "manual" (testing)), and how a new developer can ensure that any code they might write adheres to these standards. If there are coding standards, are these documented? If there is a development process that is being followed, such as Issue Driven Project Management, does the Developer's Guide explain the way that the developers for this project have implemented this process? If the system is under Continuous Integration, does the Developer's Guide provide a link to the CI server associated with this project? Finally, does the developer's guide explain how to generate JavaDoc documentation?
Next, check out the sources from SVN (read only), and see if you can generate the JavaDoc documentation. If it can be generated, review all of the JavaDoc pages to see if they are well-written and informative. Do the JavaDocs provide a good understanding of the system's architecture and how individual components are structured? Do the names of components (packages, classes, methods, fields) clearly indicate their underlying purpose? Is the system designed to support information hiding?
Next, see if you can build the system from sources without errors. See if you can generate coverage information regarding the system. Next, review the test case source code to see how the current developers are assuring the correctness of the functionality of the system. By combining information from the coverage tool with review of the testing source code, you should come to a conclusion about how well the current set of test cases can prevent a new developer from making enhancements that break pre-existing code.
Now read through the source code, and check to see if coding standards are followed and if the code is commented appropriately. Is the code easy to understand, and is there neither too much nor too little commenting?
Next, check the Issues page associated with this project. Is it clear what parts of the system were worked on by each developer? If an external developer had a question regarding a certain part of the system or a certain aspect of its behavior, could the Issues page be used to determine which developer would be the best person to ask? Does the current system appear to result from approximately equal input from all of the developers, or did some developers appear to do much more than other developers?
Now check the CI server associated with this project. Apart from Nov 22-24 when there were known outages, did any build failures get corrected promptly? Was the system worked on in a consistent fashion? Were at least 9 out of 10 commits associated with an appropriate Issue?
Carefully document the results of your investigations into each of these issues, and use the results to come to a conclusion regarding the ease with which a new external developer could successfully understand the current system and successfully contribute with the current team to enhancing it in future.
You can begin working on this review as soon as the deadline for A24 has passed. You will have all of Tuesday's class period to get started and work with your team concurrently on the review. By the deadline, you must publish a technical article to your blog containing the results of this review. Note that this will be a rather lengthy blog posting if you do it correctly, since you cannot assume that the reader will be familiar with the software project assignment, the three prime directives, WattDepot, Continuous Integration, or Issue Driven Project Management. You must find a way to both introduce all of these concepts, as well as provide a thorough review of the system assigned to you. In many ways, this technical review and associated article has the potential to serve as a summation of the many of the most important concepts presented in class this semester. It can not only provide useful feedback to the team whose software you are reviewing, but also show future employers the depth of your insight into high quality software engineering principles and practices.
The goal of this assignment is for you to continue to practice Issue Driven Project Management practices in your group, and also to gain a more visceral sense for the Three Prime Directives of Software Engineering by having to work on a different code base.
The first step in this assignment is for you to provide "owner" privileges to the all members of the team who just reviewed your code in Assignment A26. Thus, for this assignment, you will no longer be working on your own code base. Instead, your task is to add new features to the code base that you have just finished reviewing.
Second, you will want to update the build task for the Jenkins CI server so that it emails the new project members when a build fails.
Third, update the build.xml file and change the major version number from "1" to "2".
While it might be tempting to "replace" your new code base with the one you have been previously working on, that is a violation of the assignment. Instead, you should figure out how to add the following new functionality to this code base while preserving its current design.
(1) set-baseline [tower | lounge] [date]
This command defines [date] as the "baseline" day for [tower | lounge]. [date] is an optional argument in YYYY-MM-DD format and defaults to yesterday. When this command is executed, the system should obtain and save the amount of energy used during each of the 24 hours of that day for the given tower or lounge. These 24 values define the baseline power for that tower or lounge for that one hour time interval. For example, if lounge Ilima-A used 100 kWh of energy during the hour 6am-7am, then the baseline power during the interval 6am - 7am for Ilima-A is 100 kW.
(2) monitor-power [tower | lounge] [interval]
This command prints out a timestamp and the current power for [tower | lounge] every [interval] seconds. [interval] is an optional integer greater than 0 and defaults to 10 seconds. Entering any character (such as a carriage return) stops this monitoring process and returns the user to the command loop.
To implement this, you should familiarize yourself with the Timer and TimerTask classes in Java. (You can also use the ExecutorService class if your prefer.)
Here is a snippet of code that shows how you can enter a loop waiting for a character to be pressed by the user.
(3) monitor-goal [tower | lounge] goal interval
This command prints out a timestamp, the current power being consumed by the [tower | lounge], and whether or not the lounge is meeting its power conservation goal. [goal] is an integer between 1 and 99. It defines the percentage reduction from the baseline for this [tower | lounge] at this point in time. [interval] is an integer greater than 0.
For example, assume the user has previously defined the baseline power for Ilima-A as 100 kW for the time interval between 6am and 7am, and the current time is 6:30am. If the goal is set as 5, then Ilima-A's current power must be 5% less than its baseline in order to make the goal. At the current time, that means that Ilima-A should be using less than 95 kW of power in order to make its goal.
It is an error if the monitor-goal command is invoked without a prior set-baseline command for that [tower | lounge].
Entering any character (such as a carriage return) stops this monitoring process and returns the user to the command loop.
Make sure to update all wiki pages and other associated documentation. Obviously, you should implement test cases for your new code.
Due by 8am on the date noted on the schedule page. At the due date, each team member should send me a private email summarizing the quality of their team's interaction, and the percentage of effort on the project due to each team member.
Second, each team member should create a public blog entry summarizing their experiences with issue-based project management and what worked and what didn't. The blog entry should also detail your group's enhancements, what functionality was implemented and what functionality was not implemented, and your perception of the overall quality of your software. You should also discuss the Three Prime Directives of Software Engineering and what you learned from taking over a different group's code base.
Finally, the Downloads page of the google project should provide a zip file produced using "ant -f dist.build.xml" which Kendyll and I can download to evaluate whether or not your project builds, tests, and runs successfully. Do not replace the download left by the previous team for Version 1 of Hale Aloha CLI, just add your new one to the downloads page.