aTrack

Project Purpose

Our goal is to build a small, but useful and real application. We have chosen a bug tracking application.

How to Build

Requirements

Use cases

• report bug: search for existing bugs that match this one, then create a new bug report, and get confirmation. Alternate flow: reopen bug.
• analyze bugs: report on bugs based on various characteristics, and drill into the details
• resolve bug: the life cycle after a bug is reported, to include bug triage (prioritization and assignment), to ultimate resolution (closure).
• review bugs: reports on outstanding bugs
• register user
• login

Follow on features

• bug dependencies
• issue tracking
• release planning
• project management integration
• reporting

Design

Data Model

• bugs - captures core information about bugs reported
• users - captures information about registered users
• products (versions, platforms, milestones) - we want to have a flexible model for associated information about products, unlike most bug trackers
• roles - used to define valid operations (based on products)
• comments - collects multiple long comments about bugs
• attachments - stores attachments related to bugs
• roleMembers - maps principals (users or roles) to roles
• observers - tracks principals watching products or milestones or bugs

Technology Architecture

• aTrack is designed to be deployed in any Web container that supports J2EE^? 1.3 (i.e., Servlet 2.3, JSP 1.2, JavaMail 1.2, JAAS 1.0, JDBC 2.0 extension).
• The design should not preclude clustering for high availablility and performance, but this is not currently a priority.
• The software has four tiers:
  1. Browser Client: supporting HTML 4.0; this will use CSS to display pages and JavaScript for client-side validation but will use the minimum amount of JavaScript possible.
  2. User Interface: Using the Model-View-Controller design patterns, by extending the Struts 1.1 framework with minimal logical in JSPs. All validation will be performed on the server (we don't trust the client). Some validation will be done in the model. The application is designed to minimize the storage of information in the http session and to maxmize REST usage (e.g., adding parameters to the URL rather than POSTing hidden form fields).
  3. Model: We define interfaces to our business objects, and map them to implementation objects. They will be POJO's.
  4. Technology: We use Hibernate to provide O/R mapping for persistence of our model objects. We use JAAS interfaces to allow pluggable authentication and authorization.

Subsystems

• Bugs - the bug class and related domain objects form the core business objects.
• Query - specialized processing of queries for our needs. Saved queries will be tackled later.
• Users - handling user profiles and groups
• Reference Data - handling relatively static information like platforms, projects, releases, etc.
• UI control - the app is small enough that we don't need to break out subsystems in the UI beyond the model/view/controller. Control is through Struts action classes and mapping.
• UI model - provided by Struts forms objects (simple Java beans)
• UI view - JSPs are to be a very thin view that renders information passed in via form beans. We will minimize the use of JavaScript.
• Security - forced authentication will be handled by the SecuredFunction aspect, which will check if the given action is protected, and if so redirect requests where a Subject is not stored in the Session. The SecuredFunction aspect will also set up a JAAS login context for authorization, using Subject.doAs(...) (I don't think we need this to be doAsPrivileged). Authentication will be handled by a form that posts to an AuthenticationAction, which will then use a JAAS LoginContext. Role-based security checks will be defined for access to actions and business objects/methods using appropriate aspects. Fine-grained (data-driven) security will be handled by aspects that enforce specific relationships (e.g., reporters being allowed to withdraw bugs, and product owners being allowed to reassign them).
• Persistence - to be provided by Hibernate. There are also likely to be some adapter classes because Hibernate requires 1-1 mappings from tables to classes.
  Persistence control is handled by aspects: this is responsible for starting, disconnecting, reconnecting, and stopping sessions across Web requests (though it also needs to support batch mode and testin harnesses).
  Transaction control will be handled by aspects. We will control transactions within the execution methods of Save*Action classes (controller code). Other persistent modification code will behave as REQUIRES transaction in EJB. It should be possible to combine transactions from multiple transaction "roots".
• Error Handling - generally exceptions are converted to unchecked layer-specific ones, and are handled as appropriate at layer boundaries. Ultimate resolution is provided in Action classes for displaying errors to the user. The error handling system, including conversions, capturing additional context, and associated logging will be handled by an abstract ErrorHandling policy aspect which will be extended to define error handling for each tier.
• Logging - using Jakarta commons logging (with Log4j underneath). An aspect makes all the classes loggable (i.e., have access to a logger and associated logging methods). There is configurable method execution tracing support.
• Event handling - we will track modifications of business objects immediately before and immediately after commit, to publish a changed event. This will trigger audit trail entry updates (immediately before) and email notification (immediately after).
• Testing - we will use virtual mock objects to unit test all Java components. We will also provide regression tests that test end-to-end functionality simulating user input. The integration tests will be run in-container, either using a simple virtual mocks approach, or using Cactus.
• Temporal Objects - tracking versions including making deep copies and triggering based on changes.

Pages

• The link for the mockups appears to be broken; I checked out the source code and a search for "prototype" didn't turn up anything. -- KyleAdams - 23 Jan 2004

1. Add/edit/view bug
2. Confirm bug submission
3. Home page
4. Query for bug
5. Query bug results

Parts (JSPs, Classes, Aspects)

Our initial focus is to create a working slice that allows creating, submitting, finding, and editing bugs end-to-end (from the browser to the database). -- RonBodkin - 19 Nov 2003

Issues

• How to package platform dependencies? E.g., some database driver is needed. We don't want to require MySql (also for licensing reasons). We plan to use environment variables to point to the driver (for test code) and to ask users to configure their Web container with the driver appropriately.
• Ensure no GPL code is included in cvs. E.g., the MySql JDBC driver.
• How to best support ajdoc for Javadoc? I'd like to see a hacked up AJDOC 1.0.6

Action Plan

1. site prototype including look and feel. (Dion)
2. extend database data model (Ron)
3. write architecture description (Ron)
4. add unit test cases - in progress (Ron)
5. add integration test cases (Ron)
6. reference data for bug entry (storing in data model, adding business objects, and updating report use) - in progress
7. refactor and comment the core code. (Ron)
8. site header/footer with SiteMesh. (Dion)
9. query processing - basic structured queries with joins. (Dion)
10. query processing - using Lucene to connect with full text search. (Dion)
11. attachments (Ron)

After this, major tasks to be completed are:

• User registration
• Security - authentication with JAAS - use of aspects vs. servlet filters
• Security - authorization with JAAS
• Logging for events
• Event handling
• Reports
• Reference Data UI
• User administration (hopefully we can do this through a 3rd party product)
• Flexible product/component/version data model
• Refactor build.xml to support ajdoc generation - issue how to handle AspectJ 1.1 code differences (Dion)

-- RonBodkin - 16 Nov 2003

Completed

1. get the end-to-end slice up and running. I am currently implementing persistence using Hibernate, and a simple bug database definition. After this, we will add in transaction control aspects. (Ron) - done
2. refactor build.xml to build test and non-test code separately and to support hibernate and test - done (Dion)
3. Tracing with configuration - done (Ron)