Maven plugin reference

The JoinedWorkz Maven plugin integrates model parsing, validation and generation into the Maven build.

• It parses all CMN (.cmn) models on the project classpath.
• It applies model transformations.
• It runs all generators configured via platforms, cartridges and outlets.
• It writes generated artefacts to the directories defined by the active outlets (which can be overridden in joinedworkz.properties).

The plugin itself is intentionally generic: it does not know anything about specific platforms or technologies. Its behaviour is entirely driven by

• the platforms defined in facilities,
• the outlets in the active profiles, and
• project-level overrides in joinedworkz.properties.

For an introduction and an end-to-end example see:

• Quickstart
• Create a project with Maven
• Facilities & platforms

---

1. Plugin declaration

The plugin is added to the <build><plugins> section of your model module (or the module into which you generate). A minimal configuration looks like this:

<build>
    <plugins>
        <!-- joinedworkz generator plugin -->
        <plugin>
            <groupId>org.joinedworkz.cmn</groupId>
            <artifactId>cmn-maven-plugin</artifactId>
            <version>${joinedworkz.version}</version>
            <executions>
                <execution>
                    <?m2e ignore?><!-- ignore this execution in Eclipse -->
                    <goals>
                        <goal>generate</goal>
                    </goals>
                </execution>
            </executions>
        </plugin>
    </plugins>
</build>

Key points:

• cmn-maven-plugin has a single important goal for normal use: generate.
• No additional configuration is required for generators or platforms – those are controlled by facilities and profiles.
• The execution is typically wired so that generate runs as part of the normal build (mvn clean package, mvn verify, …).

The plugin will pick up all CMN models and facilities on the classpath of this module (and its test scope, if applicable).

---

2. Preventing m2e / Eclipse from executing the plugin

Eclipse (m2e) and also JoinedWorkz Studio may try to execute Maven plugin goals during incremental builds. For the JoinedWorkz generator this is usually not desired inside the IDE, because JoinedWorkz Studio already handles interactive validation and generation.

To prevent m2e from running the plugin execution, the standard pattern is:

<execution>
    <?m2e ignore?><!-- ignore this execution in Eclipse -->
    <goals>
        <goal>generate</goal>
    </goals>
</execution>

The <?m2e ignore?> processing instruction tells m2e to skip this execution, while Maven on the command line will still run it normally.

---

3. Registering generated resources

When generators write files into custom directories (for example OpenAPI YAML files), those directories must be added as resource folders in the module that consumes them.

Typical example: OpenAPI YAML into src/generated/resources/openapi.

If the OpenAPI outlet is configured to point into src/generated/resources, add that folder to <build><resources>:

<build>
    <resources>
        <resource>
            <directory>model</directory>
        </resource>
        <resource>
            <directory>src/main/resources</directory>
        </resource>
        <resource>
            <directory>src/generated/resources</directory>
        </resource>
    </resources>

    <plugins>
        <!-- cmn-maven-plugin ... -->
    </plugins>
</build>

Important:

• This configuration belongs in the module into which the outlet writes. That may be the same module that contains the model, or a different one if you route outlets to another module via joinedworkz.properties.
• If you use a module purely as a model-only module, and route all outputs into sibling modules, you only need to configure the resource directories in those target modules.

---

4. Registering generated Java sources

Similarly, generated Java sources must be added as source folders so that they are compiled as part of the build. A common pattern is to use src/generated/java and register it via the build-helper-maven-plugin:

<build>
    <plugins>
        <!-- JoinedWorkz generator -->
        <plugin>
            <groupId>org.joinedworkz.cmn</groupId>
            <artifactId>cmn-maven-plugin</artifactId>
            <version>${joinedworkz.version}</version>
            <executions>
                <execution>
                    <?m2e ignore?><!-- ignore this execution in Eclipse -->
                    <goals>
                        <goal>generate</goal>
                    </goals>
                </execution>
            </executions>
        </plugin>

        <!-- register generated sources -->
        <plugin>
            <groupId>org.codehaus.mojo</groupId>
            <artifactId>build-helper-maven-plugin</artifactId>
            <version>3.6.0</version>
            <executions>
                <execution>
                    <id>add-generated-source</id>
                    <phase>generate-sources</phase>
                    <goals>
                        <goal>add-source</goal>
                    </goals>
                    <configuration>
                        <sources>
                            <source>${basedir}/src/generated/java</source>
                        </sources>
                    </configuration>
                </execution>
            </executions>
        </plugin>
    </plugins>
</build>

Again, the important points are:

• Configure this in the module that contains the generated Java sources.
• Make sure the outlet for generated Java (generatedJavaSource or your own outlet) points to the same directory (src/generated/java in this example), either via the platform default or via joinedworkz.properties.

---

5. Configuration via joinedworkz.properties and outlets

The Maven plugin itself has almost no project-specific configuration. Instead, behaviour is controlled by:

• Platforms and outlets – defined in profiles inside facilities.
• joinedworkz.properties – project-level overrides for outlet directories and other settings (optionally per layer).

Example overrides (from joinedworkz.properties in the project root):

# global outlet override for generated Java sources
outlet.generatedJavaSource.directory=../my-service-module/src/generated/java

# layer-specific overrides
outlet.generatedJavaSource.commons.directory=../my-commons-module/src/generated/java
outlet.generatedJavaSource.webapp.directory=../my-webapp-module/src/generated/java

The plugin loads joinedworkz.properties from the project classpath and passes the resolved outlet configuration and properties into the cartridges and generators.

This separation keeps the Maven configuration simple:

• Maven knows where generated files live (resources / sources).
• Facilities and profiles know what to generate and how to interpret the model.
• joinedworkz.properties decides into which module / folder individual outlets write in a given project.

---

6. Summary

To integrate JoinedWorkz into your Maven build, you typically need:

1. Dependencies to the facilities you want to use
   (Base, Java, SpringBoot, …).

2. The cmn-maven-plugin with goal generate in your build section, including <?m2e ignore?> in the execution to avoid m2e triggering it inside Eclipse / JoinedWorkz Studio.

3. Resource folder registration for generated resources (OpenAPI, schemas, diagrams, …) in the target modules.

4. Source folder registration for generated Java (or other source) directories, usually via build-helper-maven-plugin.

The rest is driven by facilities (platforms, profiles, cartridges) and by your CMN models.