Backend on Palmyra

1. Project setup

Mon, 01 Jan 0001 00:00:00 +0000

1. Project setup#

The thinxar/clinic reference service uses plain Groovy Gradle with dependency versions hoisted into a sibling deps.gradle. This keeps version bumps to one file and avoids drift between the Palmyra core artifact and its extensions.

Prerequisites#

Java 21+
Gradle 8.x
MariaDB / MySQL / PostgreSQL / Oracle / DB2

Layout#

service/
  build.gradle
  deps.gradle        ← versions + dependency bundles
  settings.gradle
  src/main/java/...  com.your.app.AppMain, controller/, entity/, model/, pojo/, handler/, ...
  src/main/resources/application.yaml

`deps.gradle`#

Centralise versions and pre-compose reusable dependency bundles:

2. Entities, models, POJOs

Mon, 01 Jan 0001 00:00:00 +0000

2. Entities, models, POJOs#

The clinic sample uses a three-file separation — and the split is load-bearing:

Kind	Package	Role
JPA entity	`entity/`	Persistence shape — JPA annotations, relationships, audit fields
Palmyra model	`model/`	Public API shape — `@PalmyraType` + `@PalmyraField`, what clients see
Plain POJO	`pojo/`	Value objects for custom JPQL / native queries — no annotations

Keeping the Palmyra model separate from the JPA entity lets you flatten joined attributes, hide internal columns, and evolve the API contract without reshaping the database.

3. Publish handlers

Mon, 01 Jan 0001 00:00:00 +0000

3. Publish handlers#

The clinic sample does not use the composite CrudHandler — every handler explicitly composes the granular interfaces it needs. The common pattern is QueryHandler + ReadHandler + SaveHandler, extending a project-local AbstractHandler that owns the shared concerns.

The `AbstractHandler` base#

A local base class keeps ACL, audit, and shared dependencies out of every handler:

// handler/AbstractHandler.java
public abstract class AbstractHandler implements PreProcessor {

    @Autowired
    protected AuthProvider authProvider;

    @Override
    public int aclCheck(Tuple tuple, HandlerContext ctx) {
        // Fine-grained ACL is enforced by palmyra-dbacl-mgmt at the filter
        // level; handlers get full rights once authentication has passed.
        return AclRights.ALL;
    }

    protected String currentUser() {
        return authProvider.getUser();
    }
}

Minimal handler — master data#

The simplest handler is just a composition declaration:

4. ACL and extensions

Mon, 01 Jan 0001 00:00:00 +0000

4. ACL and extensions#

The clinic sample deliberately does not use @Permission — authorization is split between Spring Security (who is authenticated) and the palmyra-dbacl-mgmt extension (what each user is allowed to see and change). Password lifecycle is delegated to palmyra-dbpwd-mgmt. Exports are handled client-side, not by server handlers.

Wire Spring Security#

Permit the auth endpoints, authenticate everything else, and return 401 on auth failure so the frontend’s axios interceptor can redirect to login.

Backend on Palmyra

1. Project setup

1. Project setup#

Prerequisites#

Layout#

deps.gradle#

2. Entities, models, POJOs

2. Entities, models, POJOs#

3. Publish handlers

3. Publish handlers#

The AbstractHandler base#

Minimal handler — master data#

4. ACL and extensions

4. ACL and extensions#

Wire Spring Security#

`deps.gradle`#

The `AbstractHandler` base#