Project Modules

Modules

Module Name	Description
we99-parent	Parent module that aggregates all of its children. This is a good place to define properties or common dependencies for use in multiple child modules in order to avoid repeating yourself.
we99-test	Contains some helper classes useful for unit and integration testing.
we99-util	General utility classes for use in other modules
we99-domain	Core domain and service interfaces reside in this module. The domain classes are plain Java with Jackson/JAXB annotations to assist with their marshaling/unmarshaling. There are also service interfaces for interacting with the entities and storage interfaces for persisting them.
we99-jpa	Implementation of the storage interfaces that uses JPA. It also includes a separate set of JPA entities and code to map between the JPA entities and domain classes.
we99-domain-impl	Service implementations and supporting implementation classes live here.
we99-ddl	Module for the dynamic generation of the DDL file for our H2 database.
we99-web	he web app module. There won't be any Java source in this module's main class path. Instead, it'll contain Integration Tests for our web services. The assets for the front end (JS and HTML files) have been combined into this module in order to simplify the workflow for the front end devlopers.

The we99-domain-impl module has a direct dependency on the we99-jpa module but that's largely for some existing tests and default deployment option. This dependency could be refactored out to inject the storage implementation another way. This type of flexibility isn't required for 1.0, but it should provide some confidences that we could swap out the storage layer for something like MongoDB if the db proved to be a bottleneck.

Folder Structure

Maven provides a default layout for the directories in modules. All of the modules in WE99 adhere to this layout and therefore don't require any special configuration. The one exception are for cases where there are generated files from plugins that don't place the files in the expected output directories.

Standard JAR Module Layout

Resource	Description
src	parent folder for source code and resources
src/main	source and other files needed by the application at runtime
src/main/java	root folder for your java source files
src/main/resources	root folder for any non-source files like config files. This folder is included in your class path and may contain nested folders
src/test	source and other files needed by the application during its test phase
src/test/java	root folder for your java source files
src/test/resources	root folder for any non-source files like config files. This folder is included in your class path during the test phase of the build. Note that resources in this folder are loaded a ahead of resources in the main class path.

Standard WAR Module Layout

Same as the JAR Layout above except that you typically don't see any source code in src/main/java. The reason for this is that while classes placed in this path are available at runtime, they are not easily available to other applications that need to access them. Best practice in Maven is to put your Java source into a JAR module so it's possible to add that JAR to another module as a dependency and reuse the code. WAR's can be added as a dependency as well but that works differently as noted below.

Resource	Description
src/main/resources	Files in here wind up in the WAR's WEB-INF/classes folder. The Servlet Spec mandates that containers load resources from this path ahead of any JAR's in WEB-INF/lib
src/main/webapp	Becomes the root of the webapp

---

Note: The information here is out of date. The HTML/JS WAR and Servlet WAR have been combined. Stay tuned for updates.

WE99 Specific Layout

For the most part, WE99 follows the Maven Conventions. However, there are a few details worth highlighting to understand how the app comes together during the build.

First, we're using the Maven WAR Plugin's Overlay feature. This behavior is configured automatically when a WAR module has a dependency on another WAR module. So far, we have not needed to change the default behavior of the overlay feature.

Second, we're using the Jetty in order to provide a local web container that we can use for our integration tests and also for standard alone testing from our dev boxes. The integration test application of Jetty creates an embedded instance as part of the WebAppIT test class. This instance only supports testing of the JAXRS services since it does not apply the UI files into its web path. Testing of the full application locally can be done with the Maven Jetty Plugin from the command line of the we99-web module. This plugin will analyze the dependencies for the WAR and create a special resource path such that source files from the current module are served directly from their source directory and any resources applied from an overlay are staged in a tmp directory and served from there. This is illustrated in the table below:

Resource	Description
src/test/resources/jetty/jetty-context.xml	This contains a config to limit the scanning of dependencies at start time in order to have Jetty come up faster. The details are in a JIRA issue that's referenced in the source file
src/test/resources/jetty/jetty-env.xml	Provides a config point for JNDI resources. This is where we configure the database.
target/tmp	tmp directory created by the plugin
target/tmp/*_war[n]	full contents of the dependent WAR's contribution.

The pattern for dependent WAR tmp directories is based on the dependency's Maven Coordinate + counter. Thus, given a single dependency like so:

    <dependency>
        <groupId>edu.harvard.we99</groupId>
        <artifactId>we99-web-ui</artifactId>
        <version>0.1-SNAPSHOT</version>
        <type>war</type>
    </dependency>

You'll get a tmp directory named:

we99-web-ui-0_1-SNAPSHOT_war1

Since the HTML/JS files are served from this tmp directory, changes made to the original source files will not be seen by Jetty until a clean restart. However, it's possible to script an update that could be run manually much in the same way that a UI developer might push their changes to an external container. Given that you know the source and destination folders, perhaps a special grunt task could assemble and push the files.