JoinedWorkz
Docs1.3.81

Appearance

Java facility examples ​

Support status

Stable · Java 21 · Maven 3.9+

The public Java examples separate two learning goals that are often needed independently:

  1. generate Java data types from a domain model;
  2. generate Java data types and an OpenAPI contract from a REST API model.

Both use the stable Java facility and are standalone Maven modules. They do not depend on one another.

1. Get the release examples ​

Clone the release branch once:

sh
git clone --branch release/1.3.81 --single-branch \
    https://gitlab.com/joinedworkz/joinedworkz-examples.git
cd joinedworkz-examples

The two modules are available directly at:

2. Domain types: example-java-domain ​

Use this example when you want to learn how CMN types become Java DTOs and enums without introducing an HTTP or application framework.

The authoritative model is:

text
example-java-domain/model/customer-domain.cmn

It declares the package org.joinedworkz.examples.java.domain, the complex types Customer and Address, and the enum CustomerStatus.

From the repository root, build and verify the module:

sh
cd example-java-domain
mvn clean verify
cd ..

The build generates and compiles these replaceable Java sources:

text
src/generated/java/org/joinedworkz/examples/java/domain/dto/Address.java
src/generated/java/org/joinedworkz/examples/java/domain/dto/Customer.java
src/generated/java/org/joinedworkz/examples/java/domain/type/CustomerStatus.java

CustomerDomainModelTest uses the generated types and checks the customer DTO contract, including the modeled address and status types. The example does not define a REST resource, so OpenAPI output is not its learning goal.

3. REST contract: example-java-rest-api ​

Use this example when you want to see how the Java facility combines generated Java data types with the OpenAPI output inherited from Base. The module owns its model and types; it does not import the domain example.

Its authoritative model is:

text
example-java-rest-api/model/customer-api.cmn

The model declares the package org.joinedworkz.examples.java.rest, the Customer and CustomerSummary types, a CustomerFilter fieldset and the resource /customers. The resource uses the Base create(), read() and query() methods; the query returns CustomerSummary and exposes the modeled filter.

From the repository root, build and verify the module independently:

sh
cd example-java-rest-api
mvn clean verify
cd ..

The core replaceable outputs are:

text
src/generated/java/org/joinedworkz/examples/java/rest/dto/Customer.java
src/generated/java/org/joinedworkz/examples/java/rest/dto/CustomerSummary.java
src/generated/resources/openapi/org.joinedworkz.examples.java.rest.yaml
diagram/api/org.joinedworkz.examples.java.rest.html

CustomerOpenApiTest checks OpenAPI 3.0.3, the collection and instance paths, the create/read/query operation IDs, the query filter parameter and the generated response schema. It also checks modeled operation summaries and descriptions, named request/primary-result/status-response examples, type/field descriptions and field-, source-field- and simple-type examples taking precedence over generated fallback values. The JSON request and error examples are asserted as structured OpenAPI values rather than escaped JSON strings.

The model is a compact executable reference for the documentation syntax:

The request example uses the usual multiline form and places its JSON value directly below example standard:. The explicit boundary shown for the created scalar is also accepted, but it is optional; example created: with the value on the same or following line is simpler. In the complete model, the notFound example uses value: for its intended purpose: separating its own description from the JSON value. See Multiline and structured values.

cmn
package org.joinedworkz.examples.java.rest

import org.joinedworkz.facilities.common.profiles.java
import org.joinedworkz.facilities.common.base.api

platform Java

type Customer {
    id: Id
    displayName: String
    emailAddress: String
}

resource /customers as Customer[] by id {
'''
Creates a customer.
@summary Create a customer
@request Customer representation supplied by the caller.
    example standard:
        {
          "id": "00000000-0000-4000-8000-000000000001",
          "displayName": "Sample Customer",
          "emailAddress": "contact@example.invalid"
        }
@response Identifier assigned to the created customer.
    example created:
        value: 00000000-0000-4000-8000-000000000001
'''
    create()
}

The authoritative complete model remains model/customer-api.cmn; the generated contract is src/generated/resources/openapi/org.joinedworkz.examples.java.rest.yaml. See Common CMN syntax for all canonical forms and Base OpenAPI metadata for output placement and precedence.

The generated OpenAPI document is an API contract, not a running endpoint. The Java facility does not generate a controller, server bootstrap, persistence layer or deployable application.

4. Ownership and regeneration ​

In both modules:

  • pom.xml, model/**/*.cmn, README.md and src/test/** are authoritative or manually maintained project sources;
  • src/generated/java/**, src/generated/resources/** and diagram/** are replaceable generator output;
  • target/** is disposable Maven build output;
  • generated files must not be edited to change the example;
  • changes start in the model or Maven configuration and are followed by mvn clean verify;
  • handwritten files must not be placed in a directory cleaned as replaceable output.

Each POM limits Maven Clean to its dedicated replaceable output directories. The tests assert observable generated types or contract content. A successful build therefore checks clean generation and compilation; it does not turn either module into a runtime application.

For the general cleanup and commit-policy rules, see Generated output, ownership and regeneration.

5. Choose the next example ​