Introduction

Cartridge projects should have a homogeneous structure. Structure means the structure of directories, the storage location of templates, check-files, profiles, metamodels and so on. Otherwise it would be more difficult to develop tools working with cartridges properly, because the tools do not know anything about the structure. This page specifies the structure of cartridge projects.

The inner structure of a cartridge

A cartridge based on the openArchitectureWare framework contains different artifacts:

• Metamodels, Profiles
• Templates
• Extensions
• Files for validation, eg. formerly known as oAW-Checks
• Helper classes

All these artifacts are necesarry, of course. The goal for this inititive is to describe a standardized directory structure. Now let us start.

 The standardized directory structure for cartridges

The specification is divided into 2 parts. The first part discusses the project structure of a cartridge. The 2nd part takes a deeper look into the cartridge itself.

Part1: The project structure

If you want to develop a cartridge with the Fornax-Platform you need at least 3 seperate projects:

• The cartridge project itself
• A reference project to verify the cartridge
• The parent project containing common resources like documentation

Additionally to these 3 projects you can create more projects if you need more. An additionally project could be a platform project. Such a platform project contains resources you need for the generated code which isn't generated. This can be your application framework, helper classes or additionally resources like files.

All these projects use the default Maven directory layout. So there are directory-trees like src/main/java, src/main/resources and so on.

Part 2: A deeper look inside the cartridge-project 

As mentioned above a cartridge contains several artifacts. Such artifacts should be well organized. So everyone can navigate through this cartridge if he is searching for a special thing. A cartridge can contain source code, resources and model-specific artifacts. Commonly source code is Java source code. These are Helper classes to support extensions. Resources are the main artifacts. This could be templates, validation files, extensions. The 3rd type of artifacts are the model-specific ones. These are Metamodels, UML-Profiles, Models.

The cartridge's prefix

We recommend that every cartridge uses an unique prefix. This has the advantage that single files without package information are uniquely named. For instance if you develop a cartridge for wicket you should use the prefix wicket for your single files.

The directory layout

The cartridge project following the Maven directory layout, too. So we have at least two directories - called src/main/java and src/main/resources. The first directory contains only Java source code. The second one is the interesting one. Here are the important artifacts:

cartridge-project
|--src
    |--main
        |--java
            |--<packagename>
                |--*.java
        |--resources
            |--validation
            |--m2t
            |--m2m
            |--util

• validation - containing Model-checking files (formely known as oAW-Checks)
• m2t - Model-to-text files (the xPand-Templates)
• m2m - Model-to-model files (the xTend-Files you use for transforming one model into another one)
• util - Files that cannot be allocated to one of the other directories

But where are extensions for my templates?

If you need extensions for a special artifact (validation, m2t, m2m) you can store them into the respective directory. If the extension you write is used by different artifacts you should store it in the util-directory.

The default workflow definition

You should store the workflow for your cartridge in the package directory.
For the default workflow a name convention exists:

cartridge.oaw

cartridge-project
|--src
    |--main
        |--java
            |--<packagename>
                |--*.java
        |--resources
            |--<packagename>           
                |--validation
                |--m2t
                |--m2m
                |--util
                |--cartridge.oaw   <-- Place 'cartridge.oaw' here!

If you want to provide more than one workflow definition you can name them like you want. For additional workflow definitions no name conventions exists.

Metamodels and profiles

Of course you need metamodel(s) and/or UML profile(s) in your cartridge. This artifacts can be stored in the metamodel directory.

cartridge-project
|--src
    |--main
        |--java
            |--<packagename>
                |--*.java
        |--resources
            |--<packagename>           
                |--validation
                |--m2t
                |--m2m
                |--util
                |--cartridge.oaw
            |--metamodel          <-- Place metamodels here!
                |--[prefix].ecore
                |--[prefix].profile

The naming convention is quite simple. The filename should start with the prefix.

Example:
[prefix].ecore
[prefix]_myname.ecore
[prefix].profile

For information take a look to the prefix section of this document.

The  default properties?

Additionally to the default workflow you commonly provide a property file with default properties. This file the user can include in his workflow. The location you store such a file is the resources directory. Because this file isn't in a package you must name this file

[prefix]_cartridge_default.properties

For information take a look to the prefix section of this document.

cartridge-project
|--src
    |--main
        |--java
            |--<packagename>
                |--*.java
        |--resources
            |--<packagename>           
                |--validation
                |--m2t
                |--m2m
                |--util
                |--cartridge.oaw
            |--metamodels
                |--[prefix].ecore
                |--[prefix].profile
            |--[prefix]_cartridge_default.properties     <-- place here default workflow properties!

If you want to provide one or more another Property-files you can choose a name. But we recommend that you always use the prefix for files without a package information.

The feature configuration

If your cartridge provides several features that can be activated/deactivated you must provide a feature configuration. This is done similar to the default properties. The naming convention for this file is

[prefix]_cartridge.featurecfg

For information take a look to the prefix section of this document.

cartridge-project
|--src
    |--main
        |--java
            |--<packagename>
                |--*.java
        |--resources
            |--<packagename>           
                |--validation
                |--m2t
                |--m2m
                |--util
                |--cartridge.oaw
            |--metamodels
                |--[prefix].ecore
                |--[prefix].profile
            |--[prefix]_cartridge_default.properties
            |--[prefix]_cartridge.featurecfg              <-- this is the feature configuration file!

If you want to provide one or more another feature configurations you can choose a name. But we recommend that you always use the prefix for files without a package information.