Prime Directives Redux

Today's assignment is PrimeDirectivesRedux, where we reexamine some of our past assignments in terms of the Three Prime Directives.

---

The Three Prime Directives

1. The system accomplishes a useful task.
2. An external user can successfully install and use the system.
3. An external developer can successfully understand and enhance the system.

One thing that's not included in the prime directives, but which several of the tools help support, is the ability of an external developer to join the project and become an internal developer.

Interactive Development Environments (Eclipse, VisualStudio, etc.)

An IDE is mostly focused on helping you create any system at all. Since the system needs to exist before it can satisfy any of the directives, it helps in that sense.

More directly, it can help satisfy Prime Directive Three by encouraging consistent structure and idioms. IDEs automate a lot of common tasks, and the results are usually very consistent, making the code easier for an outside developer to understand and extend.

Coding Standards and Coding Standards Compliance Tools (Checkstyle, etc.)

Coding standards and compliance tools also provide consistency, though of a different type. Again, consistent style helps external developers understand the code.

There's no direct effect on the first two Prime Directives, because the coding standards aren't going to directly make the system easy to install or change what it does.

Build Systems (Ant, Make, etc.)

A build system can output a single file for external users to download and install from, so that's quite helpful for Prime Directive Two.

By automating some important development tasks (building, of course, but also testing) a build system makes the development environment easier to learn and use, which helps with Prime Directive Three.

A build system also makes it easier to run tests on the system. That's helpful for Prime Directive One because it helps check that the task is being successfully accomplished.

Automated Quality Assurance Tools (PMD and FindBugs, etc.)

These tools help ensure that the system successfully accomplishes whatever task it is designed to accomplish, which can help with Prime Directive One.

They also help with Prime Directive Three by making it easier for external developers to successfully integrate their changes into the system. A system that passes quality assurance tests is also usually easier to understand.

There's no direct effect on installation, but preventing bugs with quality assurance can make the system easier to use.

Black and White Box Testing

Testing supports Prime Directive One by helping ensure that the system successfully accomplishes whatever task it's designed to accomplish.

It also helps with Prime Directive Three by giving external developers a "safety net" when making changes. They can see right away whether their change broke something.

Again, there's an effect on Prime Directive Two, in the sense that a system with fewer bugs tends to be easier to use.

Automated Testing Tools (JUnit, HttpUnit, etc.)

Automated testing tools make black and white box testing easier, so all the same effects apply. The tools are especially helpful for Prime Directive Three because they simplify an development task (running the tests) that could otherwise be much harder to learn.

Configuration Management (CVS, SVN, etc.)

Configuration management is focused on how the internal developers store and track the code, so here's no direct effect on the Prime Directives, except maybe Prime Directive Three if you make your commit logs available to external developers.

There is a strong, indirect effect on all three Prime Directives because configuration management makes it much easier for internal developers to work together and get things done.

Issue Driven Project Management

Like configuration management, issue driven project management is mostly about how internal developers run the project. If the issues are made public, they can sometimes be helpful to external developers and users, but mainly it helps the internal developers work more effectively, which might mean they do a better job of satisfying all three Prime Directives.

Use Cases

Use cases help define the tasks that the system is supposed to accomplish, which helps with Prime Directive One.

They can also make the system easier to use by getting the developers to think about what the experience of using the system is supposed to be like. Things like the number of mouse clicks needed for a common task can show up in the use cases.

It can also be helpful for an external developer to read the use cases. Understanding what a system is supposed to do is an important part of understanding it in general.

Software Review

Software review is particularly important because the Three Prime Directives are defined in terms of other people. In a software review, some external person can check that the system is useful, installable, usable, understandable, and enhanceable.

When they find places that it isn't, the internal developers can work on fixing the system to better satisfy the Prime Directives.

Agile Methods (XP, Scrum, etc.)

Agile methods emphasize communication with users, which helps with Prime Directives One and Two. Users can tell the internal developers what's needed to satisfy the Prime Directives, and the developers can make adjustments.

The effect on Prime Directive Three probably depends a lot on which particular method you are using and the particular developer. The agile method itself won't include external developers, but it can lead to things that are helpful to them, like good unit tests or simple implementations.

Open Source Licenses (GPL, CPL, etc.)

An open license has no real direct effect on Prime Directives One and Two because it doesn't directly affect the behavior of the program.

It will make a big difference for Prime Directive Three. If an external developer is not allowed to read the source code and modify it, then Prime Directive Three is clearly not being met.

Online Hosting Services (Google Project Hosting, SourceForge, etc.)

An online hosting service helps with Prime Directives Two and Three by giving external users and developers a place to get the system and information about it.

It also helps in a general way by making it easier for internal developers to get things done, which hopefully brings them closer to satisfying all three Prime Directives.

MyISERN 1.3 review

Today's assignment is MyIsern-1.3-review. I'm reviewing the team orange code, which is here.

---

Installation

The package I downloaded was myisern-orange-1.3-1.0.1114.zip. There was no installation guide, but it installed fine using the installation process we're all using. I had to look up a few things that would have been in the installation guide, but the installation worked.

JUnit, Checkstyle, PMD, and FindBugs tasks all ran cleanly.

Code Format and Conventions

Nothing really leapt out at me as far as coding conventions, except that some of the comments are out of date.

I would recommend that they split things up into multiple ActionBeans rather than just expanding the ActionBean from StackStripes to do everything, but that's not really a coding convention.

Test Cases

Emma Coverage summary

class:	14%	(3/22)
method:	1%	(3/215)
block:	1%	(16/3032)
line:	1%	(7/773)

White Box & Black Box

There are two tests: a test that the welcome page can be retrieved and a test that is turned off and prints out the number of records loaded from XML.

From both a white box and a black box perspective, this is rather limited testing.

Breaking

• Trying to list or edit anything causes a null pointer exception
• Trying to add a record causes a file not found exception. I think this one is caused by looking for the files in the wrong place. The directory is supposed to named .myisern, not myisern. (It's supposed to have a period at the beginning.)

User Interface

I was able to use the interface.

It uses very little screen space and works fine with only a quarter of my (small) screen.

The one thing I would improve is the labeling of the links on the main page. The links should probably contain the name of what they do ("edit" or "add"), so you don't have to look up at the table headers to figure it out. It seems like a small thing, but it threw me off at first.

Summary and Lessons Learned

This version of MyISERN doesn't do any of the things it's supposed to, but it's a pleasant improvement over the last piece of software I reviewed.

It compiles, installs, and runs. It doesn't run correctly, but that didn't get in the way of writing a review.

It will, however, need to run correctly by Monday.

MyIsern 1-3

Today's assignment is MyISERN-1.3.

• project distribution.
• project page
• InstallationGuide

---

This assignment doesn't actually say that we're supposed to do a log entry, but I thought I'd give the reviewers an easy place to download it from.

Unfortunately, not all tasks were fully completed.

The New Group

My new partner is Randy Cox.

I was the member who had been working on the same codebase from before, and I had been working on the model (which was the part we were keeping as we switched to a Stripes webapp) so I again worked on the model in this increment and Randy handled the view and controller.

The Work

The model changes were more extensive than I had originally hoped, mostly because of the concurrency issues. In the single user version, the model was just returning a reference to an object that it continued to hold onto and give out to. Even if the methods returning the references were synchronized, the lock would be released by the time the caller started actually using the object, which could then change out from under it.

I suppose I made that part of it harder than it should have been by trying to have a solution that I liked rather than one that just did the job. I ended up with something that worked and only sort of pleased me.

I also did the installation guide and the"sanity check" report, which technically means that I did a little of the view and controller, but not really. That part was just a thin wrapper around a report generated in the model. Randy did all the username/password, ActionBeans, etc.

The Result

There are still two unfinished parts of the program:

1. Test coverage is poor
2. There's some kind of problem with displaying list values

The poor test coverage is largely from try-catch blocks that never catch and a large method we're not calling because we're not sure if we want to keep it or not.

The list problem has something to do with list data (years, affiliatedResearchers, and other things where you can have more than one) not showing up on the page.

Randy mentioned it while I was finishing up the "sanity check" report, and I ran a few tests. The data was getting from the model into the ActionBean but not from there to the page. At the time, the problem looked (to me) like the JSP code wasn't making any calls to retrieve the data. I'm not sure where he went from there, but I think it was left unresolved. It's definitely something we should talk about in person and try to sort out by Monday.

Web App Questions

1. Explain in your own words the meaning of the web "request-response cycle".

   The client sends a request to the server, the server processes the request, the server sends a response, the client figures out what it wants next and sends another request, and the cycle repeats.

2. Explain how servlets facilitate processing of the request-response cycle.

   Servlets to the server-side processing of the cycle. There's a framework that handles receiving the request and sending the response, so you can complete the server side by creating servlets.

3. How do you login to the Tomcat Manager?

   Go to the top level page on the server and click the link.

4. What is the Tomcat Manager used for in the StackStripes application?

   It's not really used inside the application, but the build system uses it to deploy and undeploy the application (and check that it has access to deploy and undeploy).

5. What is the directory and file layout of an installed web application like StackStripes? (This is NOT the same as the directory and file layout of the StackStripes distribution!)

   At the top level, there are JSP pages and the WEB-INF directory. WEB-INF contains web.xml and the directories classes and lib.

6. How do you build a war directory structure in Ant? Where is this accomplished in the StackStripes application?

   The directory structure is built by creating a WEB-INF sub-directory and putting web.xml, classes, and lib. In StackStripes, there's a web directory that already contains the complete structure and the build system copies it to create the directory used to make the war file.

7. How do you install a war directory in a running Tomcat server? What information does the Ant task need to accomplish this?

   GET http://server:port/manager/deploy?path=servpath&war=fullpath where servpath is the path of the installed application within the server (e.g. /stackstripes) and fullpath is the full path of the war directory to install.

8. What is the "Model2" architecture? What are its advantages?

   The design is split into a model, view, and controller. The view is what the user directly interacts with, the model stores the data, and the controller responds to what what the user does to the view by doing things to the model and view.

   The advantages are that it's fairly easy to understand and it separates three types of things that are different, allowing you to do things with just one of them at a time. For example, you can create the view using JSTL, and the controller by writing Java.

9. What are JSP pages? How are they related to servlets?

   JSP pages are web page servlets (or parts of servlets) written in a way that directly includes the static parts of the page.

10. Why is there a delay when retrieving a JSP page for the first time? Where is the Java code for that page stored?

    It has to be converted to Java and compiled. The Java code is stored under a long, complicated path inside the directory where Tomcat is installed.

11. What are JSTL tags? Why are they useful? What is an example JSTL tag from the StackStripes system?

    JSTL is an extension to JSP that adds a lot of tags to take the place of inline Java, making it more of a templating system. For example, the forEach tag is used to iterate through the stack.

12. What are Stripes tags? Why are they useful? What is an example Stripes tag from the StackStripes system?

    Additional tags defined by Stripes. They're useful because they hook in to Stripes. For example the stripes form tag sets up a form that is also connected to an "action bean" by Stripes.

13. What is HttpUnit? How is it different from JUnit? Why is it useful? What is an example use of HttpUnit from the StackStripes system?

    HttpUnit is a library for doing HTTP requests and responses. JUnit is a unit testing framework. HttpUnit is useful because it lets you do HTTP requests and responses from inside the JUnit tests, so that that the tests pass or fail based on the HTTP results. For example, some of our JUnit tests use HttpUnit to retrieve pages and check the contents of the table which displays the stack.

14. What needed to be changed in order to implement the Double It button? What didn't need to be changed? What did you learn about the MVC design pattern from this exercise?

    Added doubleIt to the model, doubleIt to the controller (action bean), and added DoubleItForm to the view (JSP). If your framework isn't very smart, you can find yourself doing everything three times.

15. What are the equivalence classes that need to be tested for the Double It button?

    Empty stack and non-empty stack. You might also divide non-empty stack into one element and many elements.

16. Provide two screen images of your new StackStripes application with the Double It button, one showing the page before and one showing the page after hitting the "Double It" button.

17. What is the singleton design pattern? What is an example of its use in StackStripes? Why is it needed?

    Only one instance of a class can ever be created. The StackStripes model is a singleton because we want all users to share one stack.

18. Some of the StackStripes tests exercise code on the "server side", while others exercise code on the "client" side. Which test classes exercise code on the "server", and which exercise code on the "client"? How does Emma deal with this to create appropriate coverage data?

    TestStackActionBean tests code while it is deployed, and TestStackModel tests code while it is not deployed. Emma records the results in two files and then combines them.

19. Running 'ant -f junit.build.xml' results in the following target invocations: tomcat.check, tomcat.undeploy, compile, war, tomcat.deploy, junit.tool, junit.report, junit. Explain what each of these targets do.

    • tomcat.check checks that the server is up and we can log in
    • tomcat.undeploy undeploys the application
    • compile runs javac
    • war creates a war file
    • tomcat.deploy deploys the application to the server
    • junit.tool runs the JUnit tests
    • junit.report generates a report on the JUnit tests
    • junit depends on junit.tool and junit.report (rather pointless if you ask me -- junit.report could, and probably should, depend on junit.tool and be the default)

Stack Stripes Extension

Today's assignment is StackStripesExtension. My extended stack is here.

---

All tasks completed.

Difficulties

Nothing was particularly difficult. I ran into the problem that John Hauge brought up, but I had already seen Shaoxuan Zhang's reply, so I just started tomcat from the project directory.

I also had to add $CATALINA_HOME/bin to my PATH so that emma.build.xml could find it.

Coverage

Emma Coverage summary
class:   100% (2/2)
method:  100% (18/18)
block:   97%  (142/146)
line:    94%  (39.6/42)

When I did Task 4, adding an HTTPUnit test, I noticed that the isEmpty model method wasn't being called anywhere in the controller. That pretty much ruled out 100% method coverage via HTTPUnit, so I settled for ninety-something.

In Task 5, I added tests of isEmpty to the non-HTTPUnit tests at the same time that I added tests for my new doubleIt method, so method coverage did end up at 100%.

Lessons Learned

Being told to shoot for 100% method coverage kills any desire to do black box testing. The tests we did for MyISERN-1.2 were much better, even though Emma reported less coverage.

MyIsern-1.2

Today's assignment is MyISERN-1.2.

• project distribution.
• project page

---

All tasks completed.

Group Process

My partner Kevin English really got into the text interface on this assignment. We had already divided it up on a previous assignment so that he was doing the interface, but on this one he really seemed to have a vision of how it should work. He volunteered to do all the data inputting, so he was writing code for himself to use.

I tried it out a little, and it is a nice interface. It's actually menu-driven rather than command-driven and pretty intuitive¹.

As far as working together, we mostly did what we've done on past assignments: meet as often as we can, kick some ideas around, and then decide what we'll do until the next meeting. Since I'm writing the model, a lot of the group interaction has been about what methods my partner needed me to implement.

Difficulties

The main difficulty we had was with JAXB and Java. Every time we've used it, we've thought about wrapping JAXB somehow, but we never did. The problem is that we couldn't find a way of wrapping it that would solve the problems we were having without being more work than the problems themselves.

For me, working on the model, the problem manifests as doing things three times. For Kevin, it was probably different.

When we first started using JAXB, I thought maybe we could just wrap or convert the three JAXB objects into things that formed an inheritance tree. But there was really only one method they had in common. The problem was that they had many repeated methods which were analogous but not identical in type or number.

Kevin has his own take on the problem, but I look at it this way:

Java doesn't let you merge, or even blur the line between, object structure and metadata. Objects can't easily inspect each other's structure and interact based on what they discover. It's also very rigid about types. JAXB, on the other hand, converts XML entities with children to classes with fields. The sum is that you lose the ability to treat the structure of the data as data that can direct the code. Instead, it's an invisible (to the objects) structure that you must hard-code the objects to synchronize with.

To really get around that, as far as I can see, the wrapper would have to be a sort of reverse-JAXB that turns the JAXB objects back into some type of self-describing data structure like a DOM tree or nested maps of strings.

That never seemed worth the effort, so we would always sort of daydream about having a solution and then keep going without it².

I'm interested to see what other groups have to say about JAXB. I keep going back and forth between thinking there must be wonderful way around it that I just haven't figured out yet and thinking that Java and JAXB are just hopeless.

Another minor thing is that our code coverage suddenly dropped right near the end. From the reports, it looks like everything has pretty good coverage except for some enums and our old command-line interface, which is coming in at under 60%. I knew that my partner was still using parts of the command-line interface to work with the new interface, so I figured he had merged or moved the test code in some way that caused it to only test the things we're actually still using.

In any case, the sudden drop didn't seem to be caused by a whole bunch of new, untested code. I also didn't notice it till my parter was asleep, so I didn't hold up the release for it.

Next Time

Next time, we might want to do a little more of the "skeleton" of the project earlier: things like issues, unit test, and wiki pages. We sort of lost track of where we were and what was left to do, and I think that would've helped.

---

1. It has a little bit of old code that I wrote in the first iteration for displaying tables. Right at the last minute, that old code started choking on nulls.↩

2. We didn't realize it until the very tail end of this assignment, but there's also a problem with JAXB and null. JAXB uses null in a lot of places where an empty collection would make more sense. If I'd known how pervasive that was, I might have gone ahead and written a wrapper even if that was the only thing it fixed.↩

Use Case Specification

Today's assignment is UseCaseSpecification. Our use cases are here.

---

Our team drew up a list of the use cases we wanted, then divided them up to work on them. I expected that would lead to two different styles of use case at the end, but I was surprised at how different they turned out to be. My partner, Kevin English, took a much more formal approach. For example, his alternates always go back to the beginning and start from scratch, while mine often fork off in the middle of the typical case. Also, my mock-ups look like napkin doodles.

We actually cut out a lot of use cases because there were so many. Finding, adding, and editing each of the three types of things (collaboration, organization, and researcher) would already be nine and our target was six to twelve. We ended up not having separate use cases for finding things, and just including that as a step in editing. We also combined all the analysis into one use case.

We mostly followed the tips on how to write good use cases, but I think mine might have been a little on the terse side. It's very easy to come up with use cases, but it's hard to remember all the rules and it's easy to do too many.