This page provides guidelines for structuring a Seam module project. A Seam module is a multi-module Maven project capable of producing both Maven jar, javadoc and source artifacts as well as a packaged distribution.

Module archetype

When creating a new Seam module, you can use the module archetype described on the Check Out and Build Seam page.

Computer Repair Services

With your project seeded, we'll look at the project tree as a whole, then divide into the role of notable files and folders.

Project tree

Below is a dump of the project tree so that you can get a full view of where the files and directories fall.

|-- api (or spi)
|   |-- pom.xml
|   \-- src
|       |-- main
|       |   |-- java
|       |   |   \-- org
|       |   |       \-- jboss
|       |   |           \-- seam
|       |   |               \-- [module]
|       |   |                    \-- **/*.java
|       \-- test
|           |-- java
|               \-- org
|                   \-- jboss
|                       \-- seam
|                           \-- [module]
|                                \-- **/*.java
|-- apl.txt / lgpl.txt
|-- combined
|   \-- pom.xml
|-- dist
|   |-- pom.xml
|   \-- src
|       \-- main
|           \-- assembly
|               |-- assembly.xml
|               |-- lgpl.txt
|               \-- readme.txt
|-- docs
|   |-- pom.xml
|   \-- src
|       \-- main
|           \-- docbook
|               \-- en-US
|                   |-- author_group.xml
|                   |-- book_info.xml
|                   |-- master.xml
|                   |-- preface.xml
|                   \-- ...
|-- examples
|   |-- [exampleA]
|   |    \-- src
|   |        |-- main
|   |        |   |-- java
|   |        |   |   |-- org
|   |        |   |       \-- jboss
|   |        |   |           \-- seam
|   |        |   |               \-- [module]
|   |        |   \-- ...             \-- examples
|   |        |                           \-- [exampleA]
|   |        |                               \-- **/*.java
|   |        \-- test
|   |            |-- java
|   |            |   |-- org
|   |            |       \-- jboss
|   |            |           \-- seam
|   |            |               \-- [module]
|   |            \-- ...             \-- examples
|   |                                    \-- [exampleA]
|   |                                        \-- ftest
|   |                                            \-- **/*.java
|   |-- ...
|   \-- [exampleZ] 
|-- impl
|   |-- pom.xml
|   \-- src
|       |-- main
|       |   |-- java
|       |   |   \-- org
|       |   |       \-- jboss
|       |   |           \-- seam
|       |   |                \-- [module]
|       |   |                     \-- **/*.java
|       |   \-- resources
|       |       \-- META-INF
|       |           |-- beans.xml
|       |           |-- *.properties
|       |           |-- *.xml
|       |           \-- services
|       |               \-- javax.enterprise.inject.spi.Extension
|       \-- test
|           |-- java
|           |   \-- org
|           |       \-- jboss
|           |           \-- seam
|           |                \-- [module]
|           |                    \-- **/*.java
|           \-- resources
|-- pom.xml
\-- readme.txt

Project breakdown

The series of tables below describe the function of notable files and folders in the project. First, we'll start with the Maven POM structure.

POM hierarchy

Each module will have a parent pom.xml (POM) at the root of the module and a POM for each artifact in the subprojects listed below.

Here are the guidelines for the POMs:

• All projects should inherit from a org.jboss.seam:seam-parent release (e.g., 5, 6, 7, ...). The seam-parent POM defines versions for modules tests and examples WD10EADS.
• All projects should import a org.jboss.seam:seam-bom release (e.g. 3.0.0.b04, 3.0.0.M1, 3.0.0.Final). The Seam BOM/Stack POM defines versions for running Seam modules, and can be imported by a user.
• Dependency versions should only be defined in the modules parent POM dependencyManagement section if a temporary override is needed to either the parent POM or Stack POM. For a Final release, there must be no overrides.
• Java EE 6 API dependencies should use the groupId:artifactId from the JBoss Java EE 6 spec bom
• All dependencies must be in the JBoss Maven Repository

The following diagram displays Seam's Maven hierarchy. Only the Drools module is displayed (as an example) as all modules should roughly look the same.

See the Development Guidelines for additional details about project guidelines.

Subprojects

Each module will have at least three or four subprojects, described in the table below. A module may decide to break up the implementation (or even API) into multiple artifacts if there are a distinct optional features. Cheap Data Recovery

Folder	Artifact Id	Purpose
api (or spi)	seam-[module]-api (or -spi)	The public APIs (and SPIs) that are exposed by the module. This is a Java project that consists of classes, interfaces and annotations that the end developer will import into their project classes to use the module. The developer is only required to include this artifact on the classpath to compile a project that uses this module. Separating out these Java artifacts from the implementation also has the benefit of making it easy to create JavaDocs just for the public APIs. NOTE: If you module only has an SPI, rather than an API, you can rename this folder and project to spi. If you have neither, you can leave out this project folder.
combined	seam-[module]	The public APIs (and/or SPIs) and implementation(s) of the module shaded into a single JAR.
dist	seam-[module]-dist	We recommend using a distribution module in your project hierarchy, just another module in the project directory, which depends on everything you want to bundle together. Using <dependencySets/> in the assembly plugin is MUCH less quirky than using <moduleSets/> or <fileSets />. If you'd like an example, check out Seam Faces POM which creates a zip containing module sources and binaries, reference guide and javadoc, libraries needed at runtime, and examples.
docs	seam-[module]-reference-guide	The docbook source for generating HTML and PDF versions of the reference guide.
examples/[example]	seam-[module]-example-[example]	A Maven project for each example. These examples depend only on the current module and perhaps its dependent modules. The purpose of these examples is to demonstrate the features that this module alone provides.
impl	seam-[module]-impl	The implementation classes for this module. The end developer should not be exposed to these classes directly (except to enable interceptors and/or decorators). This project hosts the beans.xml marker file and the extensions service file.

Distribution files

A project should include a minimal set of distribution files that help the end developer find their way around the project the first time. These files are targeted at the zip distribution, but may also contain useful information for source checkouts.

File	Purpose
assembly.xml	The Maven assembly descriptor that identifies the files to be included in the zip distribution. The distribution should include: API JavaDoc API and impl sources Examples Pre-compiled JARs Dependent library JARs
license.txt	The license document for this module
readme.txt	An information document about the project. This file should include: Project name Project version Project mission statement Contents overview Project URLs Release notes (or link to release notes)

Example naming convention

A sample application should follow this convention in order to be consistent with other Seam 3 applications:

• containing folder name: examples
• folder name: {example}
• artifact id: seam-{module}-example-{example}
• context path: {module}-{example}
• package: org.jboss.seam.{module}.examples.{example}
• use dashes as delimiters
• if the example name uses dashes ( - ), these are removed in the package name