JoinedWorkz

Appearance

Examples ​

This section collects runnable example projects that you can clone, build and explore alongside the documentation.

The focus is on small, focused examples that demonstrate specific JoinedWorkz concepts:

  • how to structure CMN and profile models
  • how to wire the Maven plugin and facilities
  • how generation and outlet overrides work in real projects

More examples will be added over time.

1. JoinedWorkz quickstart ​

The main example project is hosted in a public GitLab repository:

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

It contains a minimal Maven setup and CMN models that match the Quickstart and Model a REST API step by step guides in this documentation.

You can use it as:

  • a reference when following the guides
  • a starting point for your own experiments
  • a template for new projects

1.1 Clone and build ​

Requirements:

  • Java 17
  • Maven

Clone and build:

bash
git clone https://gitlab.com/joinedworkz/joinedworkz-quickstart.git
cd joinedworkz-quickstart
mvn clean package

If everything is set up correctly, the build will:

  • parse and validate the CMN models
  • run the JoinedWorkz generators via the Maven plugin
  • place generated artefacts (OpenAPI, diagrams, Java sources, …) in the configured output directories

You can then open the project in JoinedWorkz Studio or your preferred IDE to inspect the models and generated code.

Tip: keep the quickstart project untouched in one clone and create a second copy for experiments. That way you always have a clean reference.

2. How the quickstart maps to the documentation ​

The quickstart repository is designed to mirror the structure of this documentation:

  • Get Started / Quickstart
    shows how to set up the Maven build and run the generator once.

  • Guides / Model a REST API step by step
    is reflected by the customer-related CMN models (domain, API and backend component/application).

  • Reference sections
    (CMN reference, profile reference, Maven plugin reference) explain the syntax and configuration that you can see in the example project.

Whenever a guide mentions a CMN fragment or a Maven snippet, you should be able to find a corresponding real file or configuration in the quickstart repository.

3. Planned example categories ​

Over time, more example projects are planned, for example:

  • REST backend with persistence
    combining API modelling with entities mapped to a database.

  • Multi-module setup with outlet overrides
    model in one module, generate OpenAPI, DTOs and backend code into separate sibling modules.

  • Custom generator and platform extensions
    small facility that adds a profile, cartridges and strategies on top of the existing platforms.

  • Integration into an existing Java project
    use JoinedWorkz models to generate only selected artefacts (e.g. OpenAPI or DTOs) and wire them into an existing codebase.

These categories are a roadmap rather than a fixed list. The exact projects may evolve over time as JoinedWorkz and its usage patterns develop.

If you have a concrete scenario that would be useful as an example, you can use the contact information on the JoinedWorkz website to propose it.

4. Spring Boot CRUD example ​

In addition to the joinedworkz-quickstart project there is a Spring Boot example that demonstrates how the SpringBoot facility, the entity CRUD helpers and the handler pattern work together:

  • Repository:
    https://gitlab.com/joinedworkz/joinedworkz-examples/-/tree/main
    Module: example-spring-boot

The example contains:

  • a customer entity model,
  • an API model that uses the createEntity, readEntity, updateEntity, queryEntities and deleteEntity method types,
  • generated Spring Boot controllers,
  • generated DataAccessService classes for persistence,
  • generated mapper interfaces between DES and entities.

The API model for the customer CSRUD endpoints looks roughly like this:

cnm
api package org.joinedworkz.examples.customer.api

import org.joinedworkz.examples.customer

import org.joinedworkz.facilities.profiles.springboot
import org.joinedworkz.facilities.springboot.api

platform SpringBoot

resource /customers as Customer[] by id {

    queryEntities()
    createEntity()
    readEntity()
    updateEntity()
    deleteEntity()  
}

abstract resource /address as Address { }

From this model the Spring Boot facility generates:

  • a controller class for /customers,
  • a CustomerDataAccessService (or equivalent) with CRUD operations,
  • a mapper interface between API DTOs and the entity type,
  • wiring between controller and data access service, including mapping.

You can clone the example, run it as a Spring Boot application and call the generated endpoints immediately. This is a good way to explore how the SpringBoot platform interprets entity models, resources, method types and handler properties in a real project.