Project Goals

A "Secret Santa" exchange is a party where people get together to exchange surprise gifts. The gift assignments are secret, and the gifts are usually fairly small.

santa-exchange.appspot.com is a Google Web Toolkit (GWT) web site built on Google App Engine (GAE) using Java. The web site lets users manage a gift exchange and send invitations via email.

The code is intended to be a solid foundation for building other web sites in the future. Although the application is pretty small from an end-user perspective, all of the important underlying frameworks have been implemented and thoroughly tested. My goal was to demo all of the features needed in an enterprise-quality software project. I chose to implement Secret Santa functionality because I am comfortable with the problem domain, which is limited in scope. This allowed me to focus on the design patterns and frameworks rather than the problem domain.

System Architecture

The source code is divided into two projects: CedarCommon (hg, javadoc) provides common functionality that could be shared with other GWT web applications. SantaExchange (hg, javadoc) implements the actual GWT web site.

Both CedarCommon and SantaExchange are Eclipse projects, targeted at Eclipse 3.6 using the Google Plugin for Eclipse. Because the Google plugin does not support Eclipse project references as of this writing, CedarCommon code is pulled into SantaExchange in cedar-common.jar.

The GWT portion of the web site uses the Model-View-Presenter (Passive View) pattern, implemented by the Mvp4g framework. The back-end is designed around Spring 2.5.

GAE supports two standard roles: user and administrator. For SantaExchange, role-level authorization is implemented both at the UI layer and at the back-end.

At the UI layer, users log into the site using an OpenId login from either AOL, Google, MyOpenId, MySpace or Yahoo. Mvp4g modules and filters are configured to divide the site into 3 regions: external, internal, and administrative. The external region is visible to the public, the internal region is visible to any authenticated user, and the administrative region is visible only to authenticated administrators.

All GWT remote procedure calls (RPCs) are implemented as Spring services using GWT-SL. Spring security is integrated into the RPC layer. Service interfaces or method calls can be annotated with @Secured("ROLE_ADMIN") or @Secured("ROLE_USER"). The Spring security framework will make sure that only authenticated users of the proper type are allowed to invoke the RPCs.

The back-end DAO (data access object) layer is implemented using Objectify. CedarCommon provides an abstract DAO layer and includes an efficient, generalized pagination framework.

The back-end email implementation uses Velocity templates. Email is sent via the usual GAE infrastructure, but CedarCommon provides access to the infrastructure via a Spring service.

The user-visible portions of the implementation are fully localized, although I have not yet found time to have the site translated into any language other than English.

Test Coverage

There is a substantial unit test suite, with over 90% code coverage and nearly 1000 test cases implemented as of this writing. Many unit tests rely on StubbedTestRunner, a JUnit4 test runner that allows much (but not all) of the GWT client code to be tested using standard JUnit 4 unit tests and Mockito mocks. Presenters and certain portions of the view layer code can be tested with JUnit 4. Code that deals directly with user interface widgets must still be tested using the slower and less-flexible GWT client-side unit tests.

Besides the unit test suite, there is also a functional acceptance test suite implemented using Cucumber and Capybara. Cucumber tests are written in a business-readable domain-specific language. Test bindings are written in Ruby, and then Capybara drives a browser session using Selenium. Acceptance test coverage is not as complete as unit test coverage, but the acceptance test suite still provides a good smoke test to prove that the application is working normally.