1.1. Project Structure

Project Directory Layout

The directory structure of a project can, specially at it's topmost level, follow an agreed upon functional division. This structure should be defined by the team responsible for the project's creation and, if any doubts arise, the 2-1B team should be consulted on the matter to make sure it conforms with the defined guidelines.

After the functional division, if any, is settled the modules of the project should respect the following structure:

• api: We should always have an api module separated from the implementation. Use the plural apis if there are multiple api modules. If there isn’t a clear separation between api and implementation, one may not exist and all the code should be placed under the impl folder.
• impl: Where the api implementation code should exist. Use the plural impls if there are multiple implementation modules.
• assembly: if the project does any composition of artifacts, then this should be in this module. Use the plural assemblies if there are multiple assembly modules.

One module should serve a singular purpose but may produce multiple related artifacts such as jar, source, client or configuration items. Formats such as zip, feature, kar and others that require composition of artifacts should be handled in it's own assembly module.

Bellow you can find some generic examples of multimodule project layouts. The directories represent the modules without any detail of what they contain.

Basic project example

project
├── api
├── impl
└── assemblies
    ├── assembly-module
    └── assembly-module

Multi module project example

project
├── apis
│   ├── module
│   └── module
├── impls
│   ├── module
│   └── module
└── assemblies
    ├── assembly-module
    └── assembly-module

Very basic project example

project
├── impl
└── assembly

Multi module complex project example

project
├── core
│   ├── api
│   ├── impl
│   └── assembly
├── functional-module
│   ├── apis
│   │   ├── module
│   │   └── module
│   ├── impls
│   │   ├── module
│   │   └── module
│   └── assemblies
│       ├── assembly-module
│       └── assembly-module
└── functional-module
    ├── apis
    │   ├── module
    │   └── module
    ├── impls
    │   ├── module
    │   └── module
    └── assemblies
        ├── assembly-module
        ├── assembly-module
        └── assembly-module

Module Directory Layout

Considering the previously defined project directory layout, the modules contained within the project should follow Maven's Standard Directory Layout. In addition to those, several others have been defined as standards and have added functionality provided by the parent poms configuration.

• Javascript (code, test, build configuration and test configuration)

  • src/main/javascript/
  • src/main/config/javascript/
  • src/test/javascript/
  • src/test/config/javascript/

• I18N

  • src/main/resources/i18n/

• Resources

  • src/main/resources-filtered/
  • src/main/resources/ (These resources are not filtered)

• OSGI related folders

  • src/main/resources/META-INF/js/
  • src/main/resources/OSGI-INF/blueprint/

• Assemblies

  • src/main/feature/feature.xml
  • src/assembly/assembly.xml

Archetypes

We have created several Maven Archetypes that take care of building the correct module structure for you, please make use of them whenever possible. Also feel free to create a new one or update an existing one by submitting a pull request, you can find the source here along with information about usage.