Advanced on Palmyra

Custom query filters

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

Custom query filters#

When your read endpoint needs to enforce implicit conditions — a tenant scope, a soft-delete flag, a visibility rule — don’t require clients to pass them. Override applyQueryFilter on the handler and append the conditions server-side.

The hook#

@Override
public QueryFilter applyQueryFilter(QueryFilter filter, HandlerContext ctx) {
    // conditions the caller cannot override
    filter.sqlExpression("status <> 'ARCHIVED'");
    filter.addCondition(new SimpleCondition("tenantId", userProvider.getTenantId()));

    // default ordering if the caller didn't ask
    if (!filter.hasOrderBy()) {
        filter.addOrderDesc("createdAt");
    }

    // hard cap on page size
    if (filter.getLimit() == 0 || filter.getLimit() > 500) {
        filter.setLimit(500);
    }
    return filter;
}

Patterns worth reusing#

Tenant scoping. Read the tenant from AuthProvider (or a custom UserProvider) and add it as a condition; never trust a tenant id from the request.
Soft delete. Use sqlExpression("status <> 'ARCHIVED'") on the default path; publish a sibling handler at /admin/... without the clause for operators who need to see archived rows.
Role-based projection. Call filter.setFields(...) from applyQueryFilter to strip columns a given role shouldn’t see (PII, financial totals).
Default ordering. Only apply a default when the caller didn’t supply one — filter.hasOrderBy() is the guard.

Filtering by a parent-table attribute#

addCondition accepts dotted attribute paths, so you can filter on a column that lives on a joined parent table. Palmyra auto-includes the JOIN — you never write it in Java.

Native SQL reports

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

Native SQL reports#

Annotation-driven queries compile great SELECTs for CRUD, but reporting is usually where hand-written SQL earns its keep — aggregates, window functions, complex joins. Publish those as first-class endpoints with NativeQueryHandler.

A reporting endpoint#

@Component
@CrudMapping("/v1/reports/user-sales")
public class UserSalesReportHandler implements NativeQueryHandler {

    @Autowired private AuthProvider auth;

    @Override
    public int aclCheck(FilterCriteria criteria, HandlerContext ctx) {
        return userProvider.hasRole("REPORT_VIEW") ? 0 : -1;
    }

    @Override
    public void preProcess(FilterCriteria criteria, HandlerContext ctx) {
        if (criteria.getSimpleCriteria().get("since") == null) {
            criteria.addCriteria("since", Instant.now().minus(30, ChronoUnit.DAYS).toString());
        }
    }

    @Override
    public NativeQuery getQuery(FilterCriteria criteria, HandlerContext ctx) {
        String sql = """
            SELECT u.id, u.name, SUM(o.amount) AS total
            FROM users u JOIN orders o ON o.user_id = u.id
            WHERE o.created_at >= ?
            GROUP BY u.id, u.name
        """;
        NativeQuery q = new NativeQuery(sql, criteria.getSimpleCriteria().get("since"));
        q.setCountQuery("""
            SELECT COUNT(DISTINCT u.id)
            FROM users u JOIN orders o ON o.user_id = u.id
            WHERE o.created_at >= ?
        """);
        q.setFetchSize(500);
        return q;
    }

    @Override
    public Tuple onQueryResult(Tuple tuple, Action action) {
        BigDecimal total = (BigDecimal) tuple.get("total");
        if (total != null) tuple.set("total", total.setScale(2, RoundingMode.HALF_UP));
        return tuple;
    }
}

Guidelines#

Use positional ? placeholders. Bind in order with the vararg constructor or addParams; Palmyra does not substitute named parameters.
Set countQuery when pagination matters. A naive COUNT(*) over a GROUP BY / DISTINCT query is usually wrong — supply the right count query explicitly.
Tune fetchSize for wide reports. The default is 100; bump it for reports that return hundreds of thousands of rows to reduce round trips.
Keep onQueryResult cheap. It runs per row inside the reactive stream — no database calls from here.

Bulk exports

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

Bulk exports#

When an export means “everything that matches this filter” — not the one page of 50 rows the user is looking at — run the export through a dedicated handler instead of building the file in the browser. CsvHandler and ExcelHandler stream reactively, so the response starts flowing before the full result is in memory.

CSV with a curated column set#

@Component
@CrudMapping(value = "/v1/admin/user/export.csv", type = User.class)
public class UserCsvHandler implements CsvHandler, QueryHandler {

    @Override
    public List<ColumnMeta> getHeaders() {
        return List.of(
            ColumnMeta.of("loginName", "Email"),
            ColumnMeta.of("firstName", "First Name"),
            ColumnMeta.of("lastName",  "Last Name"),
            ColumnMeta.of("createdAt", "Created On")
        );
    }

    @Override
    public QueryFilter applyQueryFilter(QueryFilter filter, HandlerContext ctx) {
        // honour whatever the request came with, but never export archived rows
        filter.sqlExpression("status <> 'ARCHIVED'");
        return filter;
    }
}

Excel with a read-side ACL#

@Component
@CrudMapping(value = "/v1/admin/user/export.xlsx", type = User.class)
public class UserExcelHandler implements ExcelHandler, QueryHandler {

    @Autowired private AuthProvider auth;

    @Override public String getReportName() { return "Users"; }

    @Override
    public int aclCheck(FilterCriteria criteria, HandlerContext ctx) {
        return userProvider.hasRole("USER_EXPORT") ? 0 : -1;
    }

    @Override
    public List<ColumnMeta> getHeaders() {
        return UserCsvHandler.STANDARD_HEADERS;   // share the header list
    }

    @Override
    public QueryFilter applyQueryFilter(QueryFilter filter, HandlerContext ctx) {
        filter.addCondition(new SimpleCondition("tenantId", userProvider.getTenantId()));
        return filter;
    }
}

Frontend hookup#

Export endpoints are normal URLs — just point the browser at them:

Cross-entity business validation

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

Cross-entity business validation#

When a handler needs to enforce rules that span multiple tables — “the invoice total must not exceed the contract award” or “the assigned contractor must belong to this project” — @PalmyraField annotations aren’t enough. The validation lives in the handler’s lifecycle hooks, backed by JPA repositories (or any injected service).

The pattern#

Override preCreate / preUpdate / preDelete and call your repositories from there. The tuple carries the incoming payload; the repositories carry the truth. Throw a domain exception to abort the operation.

Dynamic native queries with JSqlParser

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

Dynamic native queries with JSqlParser#

When a dashboard endpoint serves multiple chart widgets — each with its own combination of filters (department, stage, contractor, value range) — hard-coding a SQL variant per filter combination doesn’t scale. Instead, start with a base query and inject WHERE clauses programmatically using JSqlParser.

The architecture#

Request → Controller → QueryModifier.inject(baseSQL, filters) → JDBC → JSON

Base queries live as constants — one per report type, containing the JOINs and GROUP BYs that never change.
A QueryModifier parses the SQL at runtime, appends filter conditions to the WHERE clause, and returns the modified query string.
The controller (or NativeQueryHandler) executes the modified query and returns the results.

QueryModifier — safe WHERE injection#

import net.sf.jsqlparser.parser.CCJSqlParserUtil;
import net.sf.jsqlparser.statement.select.*;
import net.sf.jsqlparser.expression.operators.conditional.AndExpression;
import net.sf.jsqlparser.expression.StringValue;

public class QueryModifier {

    /**
     * Parse the base SQL, append one or more AND conditions, return the modified SQL.
     */
    public static String inject(String baseSql, Map<String, Object> filters) {
        try {
            Select select = (Select) CCJSqlParserUtil.parse(baseSql);
            PlainSelect plain = select.getPlainSelect();

            for (var entry : filters.entrySet()) {
                if (entry.getValue() == null) continue;

                var condition = CCJSqlParserUtil.parseCondExpression(
                    entry.getKey() + " = '" + entry.getValue() + "'"
                );

                if (plain.getWhere() == null) {
                    plain.setWhere(condition);
                } else {
                    plain.setWhere(new AndExpression(plain.getWhere(), condition));
                }
            }
            return select.toString();
        } catch (Exception e) {
            throw new RuntimeException("Failed to modify query", e);
        }
    }
}

Base queries as constants#

public class DashboardQueries {

    public static final String PROJECTS_BY_DEPARTMENT = """
        SELECT d.name AS department, COUNT(p.id) AS project_count,
               SUM(p.awarded_value) AS total_value
        FROM project p
        JOIN department d ON d.id = p.department_id
        GROUP BY d.name
        ORDER BY total_value DESC
    """;

    public static final String MONTHLY_PROGRESS = """
        WITH months AS (
            SELECT generate_series(
                date_trunc('year', CURRENT_DATE),
                CURRENT_DATE, '1 month'
            )::date AS month
        )
        SELECT m.month, COUNT(p.id) AS started, SUM(p.budget) AS committed
        FROM months m
        LEFT JOIN project p ON date_trunc('month', p.start_date) = m.month
        GROUP BY m.month
        ORDER BY m.month
    """;

    public static final String TOP_VENDORS = """
        SELECT v.name AS vendor, COUNT(c.id) AS contracts, SUM(c.value) AS total
        FROM vendor v
        JOIN contract c ON c.vendor_id = v.id
        GROUP BY v.name
        ORDER BY total DESC
        LIMIT 10
    """;
}

Controller that uses it#

@RestController
@RequestMapping("/dashboard")
public class DashboardChartController {

    @Autowired private JdbcTemplate jdbc;

    @GetMapping("/projects-by-department")
    public List<Map<String, Object>> projectsByDepartment(
            @RequestParam(required = false) String stage,
            @RequestParam(required = false) Long departmentId,
            @RequestParam(required = false) Long contractorId) {

        Map<String, Object> filters = new LinkedHashMap<>();
        if (stage != null)        filters.put("p.stage", stage);
        if (departmentId != null) filters.put("p.department_id", departmentId);
        if (contractorId != null) filters.put("c.contractor_id", contractorId);

        String sql = QueryModifier.inject(DashboardQueries.PROJECTS_BY_DEPARTMENT, filters);
        return jdbc.queryForList(sql);
    }

    @GetMapping("/top-vendors")
    public List<Map<String, Object>> topVendors(
            @RequestParam(required = false) String stage) {

        Map<String, Object> filters = new LinkedHashMap<>();
        if (stage != null) filters.put("c.stage", stage);

        String sql = QueryModifier.inject(DashboardQueries.TOP_VENDORS, filters);
        return jdbc.queryForList(sql);
    }
}

Using JSqlParser inside a NativeQueryHandler#

JSqlParser works just as well inside a Palmyra NativeQueryHandler — you get the framework’s pagination, onQueryResult, and aclCheck for free while still composing the SQL dynamically.

Custom controllers with Palmyra ACL

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

Custom controllers with Palmyra ACL#

Palmyra handlers cover the CRUD surface. Non-CRUD actions — multi-record payments, approve/reject workflows, custom aggregation endpoints — belong in plain Spring @RestControllers. The two patterns coexist: handlers own the data, controllers own the actions.

The boundary#

Use a handler when…	Use a custom controller when…
The operation maps to a single entity’s CRUD lifecycle	The operation spans multiple entities in one call
Pagination, sort, search, export are needed	The request shape doesn’t fit the standard query-param contract
`@CrudMapping` + handler interfaces cover the surface	The endpoint needs a custom URL, custom request body, or a non-JSON response

Securing custom controllers with Palmyra’s ACL#

@PreAuthorize("hasPermission(...)") flows through the same PalmyraPermissionEvaluator that resolves @Permission on handlers. The ACL tables are the single source of truth for both surfaces.

Approval workflow with audit trail

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

Approval workflow with audit trail#

A multi-step approval flow: DRAFT → SUBMITTED → IN_PROGRESS → APPROVED (or REJECTED), with a field-level audit trail that records who changed what at each step.

Data model#

Three tables power the flow:

-- The entity being approved (e.g., an invoice)
ALTER TABLE invoice ADD COLUMN status VARCHAR(16) NOT NULL DEFAULT 'DRAFT';

-- Each step in the approval chain
CREATE TABLE workflow_step (
  id            BIGINT AUTO_INCREMENT PRIMARY KEY,
  invoice_id    BIGINT NOT NULL,
  step_order    INT    NOT NULL,          -- 1, 2, 3, ...
  group_name    VARCHAR(64),              -- "Finance", "Director", "Secretary"
  status        VARCHAR(16) NOT NULL DEFAULT 'PENDING',
  acted_by      VARCHAR(128),
  acted_at      TIMESTAMP,
  remarks       TEXT,
  CONSTRAINT fk_ws_invoice FOREIGN KEY (invoice_id) REFERENCES invoice(id)
);

-- Field-level change log per step
CREATE TABLE workflow_context (
  id            BIGINT AUTO_INCREMENT PRIMARY KEY,
  step_id       BIGINT NOT NULL,
  field_name    VARCHAR(64),
  old_value     VARCHAR(512),
  new_value     VARCHAR(512),
  CONSTRAINT fk_wc_step FOREIGN KEY (step_id) REFERENCES workflow_step(id)
);

Workflow service#

@Service
@RequiredArgsConstructor
public class InvoiceWorkflowService {

    private final WorkflowStepRepo   stepRepo;
    private final WorkflowContextRepo contextRepo;
    private final InvoiceRepo         invoiceRepo;

    @Transactional
    public void submit(Long invoiceId, String submittedBy) {
        var invoice = invoiceRepo.findById(invoiceId).orElseThrow();
        assertStatus(invoice, "DRAFT", "REJECTED");

        invoice.setStatus("SUBMITTED");
        invoiceRepo.save(invoice);

        stepRepo.save(WorkflowStepEntity.builder()
            .invoiceId(invoiceId)
            .stepOrder(nextStep(invoiceId))
            .groupName("Submitter")
            .status("COMPLETED")
            .actedBy(submittedBy)
            .actedAt(Instant.now())
            .build());
    }

    @Transactional
    public void approve(Long invoiceId, String approvedBy, Map<String, String> amendments) {
        var invoice = invoiceRepo.findById(invoiceId).orElseThrow();
        assertStatus(invoice, "SUBMITTED", "IN_PROGRESS");

        int order = nextStep(invoiceId);
        var step = stepRepo.save(WorkflowStepEntity.builder()
            .invoiceId(invoiceId)
            .stepOrder(order)
            .groupName(resolveGroup(approvedBy))
            .status("APPROVED")
            .actedBy(approvedBy)
            .actedAt(Instant.now())
            .build());

        // Audit every field the approver amended
        amendments.forEach((field, newValue) -> {
            String oldValue = getFieldValue(invoice, field);
            if (!Objects.equals(oldValue, newValue)) {
                contextRepo.save(WorkflowContextEntity.builder()
                    .stepId(step.getId())
                    .fieldName(field)
                    .oldValue(oldValue)
                    .newValue(newValue)
                    .build());
                setFieldValue(invoice, field, newValue);
            }
        });

        invoice.setStatus(isLastApprover(order) ? "APPROVED" : "IN_PROGRESS");
        invoiceRepo.save(invoice);
    }

    @Transactional
    public void reject(Long invoiceId, String rejectedBy, String remarks) {
        var invoice = invoiceRepo.findById(invoiceId).orElseThrow();
        assertStatus(invoice, "SUBMITTED", "IN_PROGRESS");

        invoice.setStatus("REJECTED");
        invoiceRepo.save(invoice);

        stepRepo.save(WorkflowStepEntity.builder()
            .invoiceId(invoiceId)
            .stepOrder(nextStep(invoiceId))
            .groupName(resolveGroup(rejectedBy))
            .status("REJECTED")
            .actedBy(rejectedBy)
            .actedAt(Instant.now())
            .remarks(remarks)
            .build());
    }

    private void assertStatus(InvoiceEntity invoice, String... allowed) {
        if (!Set.of(allowed).contains(invoice.getStatus())) {
            throw new BusinessException("Invoice is in status " + invoice.getStatus()
                + "; expected one of " + Arrays.toString(allowed));
        }
    }

    private int nextStep(Long invoiceId) {
        return stepRepo.countByInvoiceId(invoiceId) + 1;
    }
}

Wiring to a Palmyra handler#

The handler gates the status transitions; the workflow service owns the logic.

Row-level data scoping

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

Row-level data scoping#

Palmyra’s @Permission and the ACL extension control what operations a user can perform — feature-level security. Which rows the user can see or edit is a different concern — data-level security. This page shows how to implement row-level scoping through applyQueryFilter and a shared access-manager class.

The scenario#

Users belong to departments. A regular user should see only records in their own department. Specific senior roles (director, secretary) see everything. The scoping applies to every list endpoint, every export, and every dashboard query.

Child entity handlers with nested URLs

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

Child entity handlers with nested URLs#

When an entity only makes sense in the context of a parent — line items under a purchase, comments under a ticket, attachments under a document — scope the URL under the parent and use the path variable to filter queries and inject the FK on writes.

The pattern#

A purchase has many line items. The line-item handler mounts under /purchase/{purchaseId}/purchaseLineItem, reads purchaseId from the URL on every request, and:

Email notifications with outbox pattern

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

Email notifications with outbox pattern#

Never send email inline from a handler hook — it blocks the HTTP response, fails silently on SMTP errors, and can’t retry. Instead, write a log row with status PENDING and let a @Scheduled background job process the queue.

This page covers the full pattern: the log entity, writing from handler hooks, the email service, the scheduled processor, and other useful scheduled jobs that follow the same shape.

Automatic JPA audit fields

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

Automatic JPA audit fields with EntityListeners#

When every table needs created_by, created_on, last_upd_by, last_upd_on — and you want them populated from Spring Security without repeating the logic per entity — use a JPA @EntityListeners approach alongside your Palmyra handlers.

Reusable audit base#

// Embeddable timestamps
@Embeddable
@Getter @Setter
public class Timestamps {
    @Column(name = "created_on", updatable = false) private Instant createdOn;
    @Column(name = "created_by", updatable = false, length = 128) private String createdBy;
    @Column(name = "last_upd_on") private Instant lastUpdOn;
    @Column(name = "last_upd_by", length = 128) private String lastUpdBy;
}

// Marker interface
public interface Auditable {
    Timestamps getTimestamps();
    void setTimestamps(Timestamps ts);
}

The listener#

public class AuditListener {

    @PrePersist
    public void prePersist(Object entity) {
        if (entity instanceof Auditable a) {
            Timestamps ts = a.getTimestamps();
            if (ts == null) { ts = new Timestamps(); a.setTimestamps(ts); }
            String user = currentUser();
            Instant now = Instant.now();
            ts.setCreatedOn(now);
            ts.setCreatedBy(user);
            ts.setLastUpdOn(now);
            ts.setLastUpdBy(user);
        }
    }

    @PreUpdate
    public void preUpdate(Object entity) {
        if (entity instanceof Auditable a) {
            Timestamps ts = a.getTimestamps();
            if (ts == null) { ts = new Timestamps(); a.setTimestamps(ts); }
            ts.setLastUpdOn(Instant.now());
            ts.setLastUpdBy(currentUser());
        }
    }

    private String currentUser() {
        var auth = SecurityContextHolder.getContext().getAuthentication();
        return (auth != null && auth.isAuthenticated()) ? auth.getName() : "system";
    }
}

Applying to an entity#

@Entity
@Table(name = "project")
@EntityListeners(AuditListener.class)
@Getter @Setter
public class ProjectEntity implements Auditable {

    @Id @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long id;

    @Column(nullable = false) private String name;
    @Column(nullable = false) private String status;

    @Embedded
    private Timestamps timestamps = new Timestamps();
}

Every entityManager.persist(project) and entityManager.merge(project) now stamps the four audit columns — no handler code needed for JPA-managed saves.

Advanced on Palmyra

Custom query filters

Custom query filters#

The hook#

Patterns worth reusing#

Filtering by a parent-table attribute#

Native SQL reports

Native SQL reports#

A reporting endpoint#

Guidelines#

See also#

Bulk exports

Bulk exports#

CSV with a curated column set#

Excel with a read-side ACL#

Frontend hookup#

Cross-entity business validation

Cross-entity business validation#

The pattern#

Dynamic native queries with JSqlParser

Dynamic native queries with JSqlParser#

The architecture#

QueryModifier — safe WHERE injection#

Base queries as constants#

Controller that uses it#

Using JSqlParser inside a NativeQueryHandler#

Custom controllers with Palmyra ACL

Custom controllers with Palmyra ACL#

The boundary#

Securing custom controllers with Palmyra’s ACL#

Approval workflow with audit trail

Approval workflow with audit trail#

Data model#

Workflow service#

Wiring to a Palmyra handler#

Row-level data scoping

Row-level data scoping#

The scenario#

Child entity handlers with nested URLs

Child entity handlers with nested URLs#

The pattern#

Email notifications with outbox pattern

Email notifications with outbox pattern#

Automatic JPA audit fields

Automatic JPA audit fields with EntityListeners#

Reusable audit base#

The listener#

Applying to an entity#