JoinedWorkz

Appearance

Facilities and platforms ​

Facilities are the way JoinedWorkz bundles everything that is needed to use one or more platforms in a project.

A platform defines what is generated: target architecture, conventions, mappings, project structure and any platform-specific helpers or libraries. A facility defines how this platform becomes available: profiles, cartridges, generators, CMN support, stereotypes and utilities.

A facility is a Maven module that contains:

  • one or more profiles (.profil) with stereotypes, properties, outlets, cartridges and platforms
  • shared CMN models (.cmn) such as base types or method types
  • generator and cartridge implementations
  • optional additional helpers (strategies, utilities, …)

Your application project only needs to add the facility as a Maven dependency. The JoinedWorkz generator plugin discovers the profiles, CMN models and implementations on the classpath and uses them during parsing, validation and generation.

For an overview of how DSLs and platforms fit together, see:

1. Stable facilities ​

The main facilities that are intended for regular use are:

  • common-base – provides the Base platform
    • basic simple types (String, Integer, Date, …)
    • resource method types (create, read, update, delete, query, …)
    • OpenAPI, schema and diagram cartridges
    • core strategies (naming, type mapping, …)
  • common-java – provides the Java platform (extends Base)
    • Java-specific properties and strategies (javaType, naming rules, …)
    • cartridges for Java-centric artefacts
  • spring-boot – provides the SpringBoot platform (extends Java)
    • Spring Boot specific mappings and conventions
    • cartridges for controllers, configuration, etc.

All of these facilities live in the GitLab repository:

  • https://gitlab.com/joinedworkz/joinedworkz-facilities

The corresponding artifacts are published to Maven Central and are free to use.

Other platforms in this repository are currently considered experimental and may move into a separate repository (for example joinedworkz-facilities-experimental) in the future.

2. Using a facility in your project ​

To use a facility, add it as a dependency to your model module. The Maven dependency brings the profile(s), CMN models and implementations onto the classpath.

A typical setup when you want to build Spring Boot services looks like this:

xml
<properties>
    <joinedworkz.version>1.3.74</joinedworkz.version>
</properties>

<dependencies>
    <!-- Spring Boot platform (includes Java and Base via transitive dependencies) -->
    <dependency>
        <groupId>org.joinedworkz.facilities</groupId>
        <artifactId>spring-boot</artifactId>
        <version>${joinedworkz.version}</version>
        <scope>provided</scope>
    </dependency>
</dependencies>

You do not need to add common-java and common-base explicitly in this case: the spring-boot facility depends on common-java, and common-java depends on common-base. Maven will put all three on the classpath.

If you only want to use the Java platform without Spring Boot, you can depend on common-java directly; if you only need the Base platform, you can depend on common-base:

xml
<!-- only Base platform -->
<dependency>
    <groupId>org.joinedworkz.facilities</groupId>
    <artifactId>common-base</artifactId>
    <version>${joinedworkz.version}</version>
    <scope>provided</scope>
</dependency>

<!-- Base + Java platform -->
<dependency>
    <groupId>org.joinedworkz.facilities</groupId>
    <artifactId>common-java</artifactId>
    <version>${joinedworkz.version}</version>
    <scope>provided</scope>
</dependency>

General rule:
If platform A in one facility depends on a platform or types from another facility B, then facility A declares a Maven dependency on B. You only need to add the top-level facility (the one you use directly) as a dependency in your project; Maven brings in the rest transitively.

The JoinedWorkz generator plugin is configured once in the build section (see the Quickstart and Create a project with Maven pages). It then automatically finds all profiles, platforms and cartridges provided by the facilities on the classpath.

In your CMN models you simply:

  1. import the CMN models from the facility, e.g.

    cmn
    import org.joinedworkz.facilities.common.base.types
import org.joinedworkz.facilities.common.base.api

  2. select a platform in the header:

    cmn
    platform Base

    or, with Java/Spring Boot enabled:

    cmn
    platform Java
    cmn
    platform SpringBoot

3. Relationship between facilities, profiles and platforms ​

The layering looks like this:

  • Facility – Maven module that packages everything together.
  • Profile(s) – describe stereotypes, properties, outlets, cartridges and strategies used by one or more platforms.
  • Platform(s) – select which cartridges run and which properties are available for a given target stack.
  • CMN models – use platform X in the header and import base models from the facility.

For example:

  • common-base contains the Base profile and platform, plus CMN models with base types and resource method types.
  • common-java extends the Base platform with Java-specific behaviour.
  • spring-boot extends the Java platform with Spring Boot specifics.

You can think of a facility as a plug-in bundle: once it is on the classpath, all its platforms become available to your models.

4. Package overrides for helper libraries ​

Some generators rely on small helper libraries that are shipped as normal JARs. In many organisations it is undesirable to keep a hard dependency on a library that is maintained by a single external author for production code.

To support “clone-and-own” of such helper libraries, JoinedWorkz provides a package override mechanism. It allows you to:

  • copy the helper classes into your own repository,
  • change their package names to match your organisation / product,
  • and tell JoinedWorkz to generate references to your packages instead of the original ones.

The generator still uses the original package names internally when deciding which class to reference, but applies your overrides when writing Java code.

Configuration ​

Package overrides are configured in joinedworkz.properties using the prefix override-package.

properties
override-package.<original-package>=<target-package>

# package overrides
override-package.org.iworkz.core.exception = com.example.exception
override-package.org.iworkz.core          = com.example.core
override-package.org.iworkz.spring.persistence = com.example.persistence

Meaning:

  • wherever a generator would normally emit a reference to org.iworkz.core.exception., it will instead use com.example.exception.
  • classes under org.iworkz.core.* are redirected to com.example.core.*
  • classes under org.iworkz.spring.persistence.* are redirected to com.example.persistence.*

You are expected to copy the corresponding classes into your own project and adjust the package declarations accordingly.

The feature is intentionally generic: any facility / generator that knows about helper classes in certain packages can respect these overrides when emitting Java code.

Typical workflow ​

  1. Identify the helper library For example a small “glue-code” library published under a generic groupId and package name (e.g. org.iworkz).
  2. Copy the classes into your own repository
  • Add them to a suitable module in your project.
  • Change the package declarations to match your organisation’s conventions (e.g. com.example.core, com.example.persistence).
  1. Configure override-package mappings In joinedworkz.properties, map the original packages to your new packages as shown above.
  2. Regenerate Run the JoinedWorkz generators (via Maven or Studio). The generated Java code will now reference your packages, not the original helper library packages.
  3. Drop the runtime dependency (optional, but usually the goal) Once all references are redirected, you can remove the dependency on the original helper library from your Maven POMs.

This keeps you fully in control:

  • You can customise the helper classes as needed.
  • You are not forced to depend on a third-party library at runtime.
  • Generated code stays aligned with your chosen package structure.

5. Experimental facilities ​

Some facilities or platforms in the joinedworkz-facilities repository are currently experimental. They are useful for trying out ideas or for very specific projects, but their API and behaviour may change without notice.

For the public documentation and for most users, the recommended set is:

  • Base (from common-base) – always present; used by almost all models.
  • Java (from common-java) – when you generate Java-based artefacts.
  • SpringBoot (from spring-boot) – when you build Spring Boot services. → Spring Boot facility

Other platforms may later move into a dedicated experimental repository to underline that they are not part of the stable surface of JoinedWorkz.

6. Where to go next ​

  • To see how platforms are defined:
    → Profile reference

  • To understand how CMN models bind to platforms:
    → Modeling overview

  • To try it out in a working project:
    → Quickstart and example projects (see the Examples section).