CLRA files and directories

$Revision: 1.1 $
$Date: 2002/02/22 19:49:08 $

Contents
  1. Overview

    2. Source-controlled

  2. Bin directory
  3. Etc directory
  4. Src directory
  5. Web directory

    6. Constructed

  6. Dist directory
  7. Tmp directory

Overview

The clra-java project should be buildable on any machine. The steps for doing a build on a new machine are discussed elsewhere. In order to have machine-independent and reproducible builds, the project has the directory structure described here.

At the top-level of the project tree are two build files: build.bat (for builds on a Windows machine) and build.sh (for builds on a Unix machine). These should be the only files at the top level.

There a set of directories that are maintained under source code control. These directories contain ancillary script files; documentation files (such as this note); configuration data; source code; and HTML, JSP and image files.

There are two directories that are constructed as the part of a build. These directories hold temporary, working copies of output files and (separately) the final products of various build targets.

Back to top

Source-controlled

 The following directories are maintained under source-code control. There may need to be an additional directory to contain the results of milestone and release builds.

Bin directory

 This directory contains various command-line scripts. For example: to set up a build environment; re-initialize a database to a known state for unit testing; and to kick off recursive unit, functional and load testing.

Back to top

Etc directory

This directory contains configuration data, in the form of xml and sql scripts. Sql scripts are divided between two subdirectories, sql-mysql and sql-oracle, for MySQL and Oracle scripts respectively. As discussed in the document on database setup, most MySQL scripts are not source-controlled, but rather generated from Oracle scripts by the oracle-to-mysql.sh shell script contained in the bin directory.

Back to top

Src directory

 This directory contains java source code. There are two main branches:

The com/clra branch is main source code branch. The test/clra branch is a set of recursive JUnit tests that cover the com/clra code branches.

Currently, the com/clra contains four subdirectories:

  1. util
    2. This util directory contains database and error handling routines common across other CLRA packages

  2. member
    3. The member directory contains classes related to member information. In general, classes in this directory reference the Member and MemberRole tables in the CLRA database. The member directory contains one subdirectory called remote. Classes at the main level of the member directory are read-only; they do not write to the CLRA database. Classes of the member/remote subdirectory are read-write; they are implementation classes for EJB's.

  3. rowing
    4. The rowing directory contains classes related to rowing sessions and participation in rowing sessions. In general, classes in this directory reference the RowingSession and Participant tables of the CLRA database. The rowing directory contains one subdirectory called remote. Classes at the main level of the rowing directory are read-only; they do not write to the CLRA database. Classes of the rowing/remote subdirectory are read-write; they are implementation classes for EJB's.

  4. web
    5. The web directory contains classes related to workflow and presentation. Classes in the web directory should not directly reference database tables.

The directories above are listed in order of dependency. The util directory has no dependencies on other CLRA classes. The member directory has dependencies on classes in the util directory. The rowing directory has dependencies on classes in the util and member directories. The web directory depends on all the other directories.

Note: new dependencies should not be introduced between the directories listed above.

It is important that dependencies be minimized if code is to be testable. With the above structure, testing can occcur in layers. First, utility classes can be tested without regard to classes in any other package. Second, member classes can be tested. Because member classes depend only on utility classes, and because utility classes are tested first, testing can focus only on functionality defined in the member package. Similarly, layering permits testing of the rowing and web packages can focus strictly on the functionality of the rowing and web packages. With layering, the complexity of testing grows just linearly with the number of classes. Without layering, when couplings are allowed to multiply without constraint among packages, testing grows exponentially complex with the number of classes.

Back to top

Web directory

 This directory contains any JSP and HTML files used by the project. At the top level, it contains files that do not require security, such as the logon.jsp screen. It also contains three subdirectories:

The admin directory contains screens restricted to club administrators. The help directory contains help screens. The restricted directory contains screens restricted to club members

Back to top

Constructed

 These directories are created and populated during a build. They should not be maintained under source control. They should be removed before the start of a milestone or release build or any build in which source files have been removed or renamed. See the build target "clean".

Dist directory

 This directory contains the output of builds. There are three main subdirectories:

The classes directory contains the complete Java class hierarchy generated by a build: servlet-related classes and properties, test harnesses and properties, and any other code, such as EJB's and client-side code. In general, it is not a good practice to use this directory tree in a classpath, because of the way that servlet, test, ejb and client classes are jumbled together. Testing against such a jumble will mask configuration issues.

The doc diretory contains generated Javadoc HTML files, plus any other files copied over from the doc directory.

The lib diretory contains deployable jar files for servlets, EJB's, client-side test harnesses, and documentation.

Back to top

Tmp directory

 This directory contains temporary working files and directories.

Back to top