Handlers on Palmyra

QueryHandler

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

QueryHandler#

com.palmyralabs.palmyra.handlers.QueryHandler

Publishes paged, filtered reads.

Request — query parameters#

QueryHandler accepts the filter criteria as HTTP query parameters. Any parameter whose name matches a @PalmyraField.attribute is treated as an equality filter — ?status=ACTIVE&tenantId=3.

A handful of reserved parameters shape the page and the ordering:

Parameter	Type	Purpose
`_limit`	number (default 15)	Max number of rows returned
`_offset`	number (default 0)	Number of rows to skip — used for paging
`_orderBy`	comma-separated fields	Sort order — prefix a field with `-` for descending (e.g. `_orderBy=-createdAt,name`)
`_total`	`true` / `false`	When `true`, the framework runs an additional count query and populates `total` in the response

Response shape#

JSON envelope with the rows under result plus paging metadata:

ReadHandler

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

ReadHandler#

com.palmyralabs.palmyra.handlers.ReadHandler

Single-record read endpoint. Returns one object identified by the {id} path placeholder — the primary key of the table mapped through @CrudMapping.type.

Request / response shape#

HTTP: GET <secondaryMapping> — e.g. GET /api/masterdata/industrySector/42.
Request body: none.
Response body: a single JSON object carrying every attribute declared on the model class from @CrudMapping.type, minus any field flagged DropMode.OUTGOING. Not wrapped — just the object.

{
  "id": 42,
  "name": "Health Care",
  "code": "HC",
  "createdAt": "2026-04-01T09:12:00Z"
}

Internally the endpoint operates from a FilterCriteria / QueryFilter split (similar to QueryHandler but narrowed to a single-row lookup).

NativeQueryHandler

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

NativeQueryHandler#

com.palmyralabs.palmyra.handlers.NativeQueryHandler

Use when annotation-driven queries aren’t expressive enough. You supply the SQL; Palmyra still handles result streaming, filtering, and row mapping through onQueryResult.

Methods#

Method	Signature
`aclCheck`	`int aclCheck(FilterCriteria criteria, HandlerContext ctx)`
`getQuery` (abstract)	`NativeQuery getQuery(FilterCriteria criteria, HandlerContext ctx)`
`preProcess`	`void preProcess(FilterCriteria criteria, HandlerContext ctx)`
`onQueryResult`	`Tuple onQueryResult(Tuple tuple, Action action)`

NativeQuery#

Package: com.zitlab.palmyra.store. Implements QueryOptions, CountQuery.

Methods#

Method	Signature
`getQuery` / `setQuery`	`String getQuery()` · `void setQuery(String query)`
`getParams` / `setParams`	`List<Object> getParams()` · `void setParams(List<Object> params)`
`addParams`	`void addParams(Object param)` · `void addParams(Object... params)`
`clearParam`	`void clearParam()`
`hasParams`	`boolean hasParams()`
`getCountQuery` / `setCountQuery`	`String getCountQuery()` · `void setCountQuery(String countQuery)`
`getFetchSize` / `setFetchSize`	`int getFetchSize()` · `void setFetchSize(int fetchSize)` — default 100
`getLimit` / `setLimit`	`int getLimit()` · `void setLimit(int limit)`
`getOffset` / `setOffset`	`int getOffset()` · `void setOffset(int offset)`
`limitFirst`	`void limitFirst()`

params are positional ? placeholders (JDBC-style), not named parameters — bind them in order with addParams(...) or the vararg constructor. Set countQuery when you need an accurate total for pagination that differs from a naive COUNT(*) over the main query.

TypedQueryHandler

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

TypedQueryHandler<E>#

com.palmyralabs.palmyra.handlers.TypedQueryHandler

Standalone generic interface for type-safe row callbacks.

Methods#

Method	Signature
`onQueryResult`	`void onQueryResult(E e)`

Use it when you want strongly-typed access to mapped rows rather than working with Tuple.

Example#

@Component
public class UserAuditHandler implements TypedQueryHandler<User> {

    private final List<User> audit = new ArrayList<>();

    @Override
    public void onQueryResult(User user) {
        // collect active users for an out-of-band audit feed
        if ("ACTIVE".equals(user.getStatus())) {
            audit.add(user);
        }
    }
}

CreateHandler

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

CreateHandler#

com.palmyralabs.palmyra.handlers.CreateHandler

Insert lifecycle. Composes PreProcessor (validation + ACL) and a rollback failure hook.

Request / response — `User`#

Assuming the User model from QueryHandler → Worked example:

Request#

POST /api/v1/admin/user
Content-Type: application/json

{
  "loginName": "ada@example.com",
  "firstName": "Ada",
  "lastName":  "Lovelace",
  "status":    "ACTIVE",
  "tenantId":  3
}

Fields flagged DropMode.INCOMING (createdAt, createdBy) are ignored if the client supplies them — the server is the authoritative writer.

Response#

The newly-inserted row, with server-populated fields filled in:

{
  "id": 102,
  "loginName": "ada@example.com",
  "firstName": "Ada",
  "lastName":  "Lovelace",
  "status":    "ACTIVE",
  "tenantId":  3,
  "createdAt": "2026-04-01T09:12:00Z",
  "createdBy": "admin@example.com"
}

Methods#

Method	Signature
`validate`	`void validate(Tuple tuple, HandlerContext ctx)`
`preProcessRaw`	`Tuple preProcessRaw(Tuple tuple, HandlerContext ctx)`
`preProcess`	`Tuple preProcess(Tuple tuple, HandlerContext ctx)`
`aclCheck`	`int aclCheck(Tuple tuple, HandlerContext ctx)`
`getAcl`	`int getAcl(Tuple tuple, HandlerContext ctx)`
`preCreate`	`Tuple preCreate(Tuple tuple, HandlerContext ctx)`
`onCreate`	`Tuple onCreate(Tuple tuple, HandlerContext ctx)`
`postCreate`	`Tuple postCreate(Tuple tuple, HandlerContext ctx)`
`rollback`	`default Tuple rollback(Tuple tuple, HandlerContext ctx)`

Example#

@Component
@CrudMapping(value = "/v1/admin/user", type = User.class)
public class UserCreateHandler implements CreateHandler {

    @Autowired
    private UserProvider userProvider;
    @Autowired
    private AuditService audit;
    @Autowired
    private OutboxService outbox;

    // PreProcessor hooks -----------------------------------------------------

    @Override
    public void validate(Tuple tuple, HandlerContext ctx) {
        if (tuple.get("loginName") == null) {
            throw new ValidationException("loginName is required");
        }
    }

    @Override
    public int aclCheck(Tuple tuple, HandlerContext ctx) {
        return userProvider.hasRole("USER_CREATE") ? 0 : -1;
    }

    @Override
    public Tuple preProcessRaw(Tuple tuple, HandlerContext ctx) {
        // normalize raw input before validation
        String login = (String) tuple.get("loginName");
        if (login != null) tuple.set("loginName", login.trim().toLowerCase());
        return tuple;
    }

    @Override
    public Tuple preProcess(Tuple tuple, HandlerContext ctx) {
        tuple.set("status", "PENDING");
        return tuple;
    }

    // Lifecycle hooks --------------------------------------------------------

    @Override
    public Tuple preCreate(Tuple tuple, HandlerContext ctx) {
        tuple.set("createdBy", userProvider.getUserId());
        tuple.set("createdAt", Instant.now());
        return tuple;
    }

    @Override
    public Tuple onCreate(Tuple tuple, HandlerContext ctx) {
        // hash password in-band with the insert
        String raw = (String) tuple.get("password");
        if (raw != null) tuple.set("passwordHash", BCrypt.hash(raw));
        tuple.remove("password");
        return tuple;
    }

    @Override
    public Tuple postCreate(Tuple tuple, HandlerContext ctx) {
        outbox.publish("user.created", tuple);
        audit.record(ctx, "USER_CREATE", tuple.get("id"));
        return tuple;
    }

    @Override
    public Tuple rollback(Tuple tuple, HandlerContext ctx) {
        // undo any out-of-transaction side effects
        outbox.discardPending(tuple.get("id"));
        return tuple;
    }
}

UpdateHandler

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

UpdateHandler#

com.palmyralabs.palmyra.handlers.UpdateHandler

Update lifecycle. Composes PreProcessor and a rollback failure hook. Each hook additionally receives the pre-image dbTuple so you can diff new vs. stored values.

Request / response — `User`#

Assuming the User model from QueryHandler → Worked example:

Request#

The URL carries the primary key (see @CrudMapping → {id}); the body carries the new values.

POST /api/v1/admin/user/102
Content-Type: application/json

{
  "firstName": "Ada",
  "lastName":  "Lovelace-Byron",
  "status":    "ACTIVE"
}

Partial payloads are fine — Palmyra merges supplied fields onto the row identified by {id}. Omitted attributes are left untouched.

SaveHandler

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

SaveHandler#

com.palmyralabs.palmyra.handlers.SaveHandler

Upsert semantics — insert when the key is absent, update when present. Composes PreProcessor.

Each hook receives the incoming Tuple, the pre-image dbTuple (null on insert), the HandlerContext, and a MutableAction indicating whether the framework will insert or update.

Request / response — `User`#

Assuming the User model from QueryHandler → Worked example.

Save lookups honour @PalmyraType.preferredKey — in the example model that’s loginName, so clients can upsert by natural key without supplying id.

DeleteHandler

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

DeleteHandler#

com.palmyralabs.palmyra.handlers.DeleteHandler

Delete lifecycle. Composes PreProcessor and a rollback failure hook.

The default preProcess(Tuple, HandlerContext) copies ctx.getParams() into the tuple attributes before the ACL check fires.

Methods#

Method	Signature
`validate`	`void validate(Tuple tuple, HandlerContext ctx)`
`preProcessRaw`	`Tuple preProcessRaw(Tuple tuple, HandlerContext ctx)`
`preProcess`	`void preProcess(Tuple tuple, HandlerContext ctx)` — default copies `ctx.getParams()` into the tuple
`aclCheck`	`int aclCheck(Tuple tuple, HandlerContext ctx)`
`getAcl`	`int getAcl(Tuple tuple, HandlerContext ctx)`
`preDelete`	`Tuple preDelete(Tuple tuple, HandlerContext ctx)`
`onDelete`	`Tuple onDelete(Tuple tuple, HandlerContext ctx)`
`postDelete`	`Tuple postDelete(Tuple tuple, HandlerContext ctx)`
`rollback`	`default Tuple rollback(Tuple tuple, HandlerContext ctx)`

Use preDelete / filter patterns to implement soft-delete; use onDelete for hard-delete side effects.

CsvHandler

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

CsvHandler#

com.palmyralabs.palmyra.handlers.CsvHandler

Streams query results as CSV. Streaming is reactive, so exports scale without loading the full result set into memory.

Methods#

Method	Signature
`getHeaders`	`default List<ColumnMeta> getHeaders()`

Override getHeaders() to control the exported columns, their labels, and their order. Return null or an empty list to fall back to the schema’s declared fields.

Example#

@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")
        );
    }
}

ExcelHandler

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

ExcelHandler#

com.palmyralabs.palmyra.handlers.ExcelHandler

Streams query results as an Excel workbook, combining the tabular export surface with the read-side lifecycle.

Methods#

Method	Signature
`getReportName`	`default String getReportName()` — returns `"Report"` by default
`getHeaders`	`List<ColumnMeta> getHeaders()`
`aclCheck`	`int aclCheck(FilterCriteria criteria, HandlerContext ctx)`
`applyQueryFilter`	`QueryFilter applyQueryFilter(QueryFilter filter, HandlerContext ctx)`
`preProcess`	`void preProcess(FilterCriteria criteria, HandlerContext ctx)` — default copies `ctx.getParams()` into the criteria

Example#

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

    @Autowired
    private UserProvider userProvider;

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

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

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

    @Override
    public void preProcess(FilterCriteria criteria, HandlerContext ctx) {
        ExcelHandler.super.preProcess(criteria, ctx);
        criteria.addAttribute("requestedBy", userProvider.getUserId());
    }

    @Override
    public QueryFilter applyQueryFilter(QueryFilter filter, HandlerContext ctx) {
        // restrict export to active users in the caller's tenant
        filter.addCondition("tenantId", userProvider.getTenantId());
        filter.addCondition("status", "ACTIVE");
        return filter;
    }
}

CustomFormatHandler

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

CustomFormatHandler#

com.palmyralabs.palmyra.handlers.CustomFormatHandler

Escape hatch for bespoke output formats (PDF, JSON-lines, fixed-width, etc.).

Methods#

Method	Signature
`getWriter`	`CustomResultSetWriter getWriter(String format)`

Return a writer keyed on the requested format; Palmyra’s query pipeline pushes rows through it.

Example#

@Component
@CrudMapping(value = "/v1/admin/user/export", type = User.class)
public class UserCustomFormatHandler implements CustomFormatHandler {

    @Override
    public CustomResultSetWriter getWriter(String format) {
        return switch (format.toLowerCase()) {
            case "jsonl" -> new JsonLinesWriter();
            case "pdf"   -> new PdfReportWriter("Users");
            case "tsv"   -> new DelimitedWriter('\t');
            default      -> throw new UnsupportedFormatException(format);
        };
    }
}

DataHandler

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

DataHandler#

com.palmyralabs.palmyra.handlers.DataHandler

Composite marker interface. Use when one component needs to serve the full read + write surface for a resource (without delete). Declares no methods of its own.

Composed Surface#

CrudHandler

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

CrudHandler#

com.palmyralabs.palmyra.handlers.CrudHandler

Composite marker interface. Implement for the full CRUD surface of a resource from a single component. Declares no methods of its own.

Composed Surface#

DataHandler (which itself composes QueryHandler, ReadHandler, CreateHandler, UpdateHandler)
DeleteHandler

PreProcessor

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

PreProcessor#

com.palmyralabs.palmyra.handlers.PreProcessor

Mixin shared by all mutating handlers (CreateHandler, UpdateHandler, SaveHandler, DeleteHandler). Centralizes validation and ACL.

Note: This interface should not be implemented by application developers. Implement one of the child interfaces (CreateHandler, UpdateHandler, SaveHandler, DeleteHandler) instead.

Methods#

Method	Signature
`validate`	`void validate(Tuple tuple, HandlerContext ctx)` — throw to reject
`preProcessRaw`	`Tuple preProcessRaw(Tuple tuple, HandlerContext ctx)` — runs before `preProcess`
`preProcess`	`Tuple preProcess(Tuple tuple, HandlerContext ctx)`
`aclCheck` (abstract)	`int aclCheck(Tuple tuple, HandlerContext ctx)` — return `-1` to forbid
`getAcl`	`int getAcl(Tuple tuple, HandlerContext ctx)` — throws `EndPointForbiddenException` when the mask is `-1`

Example#

@Component
@CrudMapping(value = "/v1/admin/user", type = User.class)
public class UserCreateHandler implements CreateHandler { // composes PreProcessor

    @Autowired
    private UserProvider userProvider;

    @Override
    public void validate(Tuple tuple, HandlerContext ctx) {
        if (tuple.get("loginName") == null) {
            throw new ValidationException("loginName is required");
        }
    }

    @Override
    public Tuple preProcessRaw(Tuple tuple, HandlerContext ctx) {
        // normalize raw input before validation / ACL
        String login = (String) tuple.get("loginName");
        if (login != null) tuple.set("loginName", login.trim().toLowerCase());
        return tuple;
    }

    @Override
    public Tuple preProcess(Tuple tuple, HandlerContext ctx) {
        tuple.set("status", "PENDING");
        return tuple;
    }

    @Override
    public int aclCheck(Tuple tuple, HandlerContext ctx) {
        return userProvider.hasRole("USER_CREATE") ? 0 : -1;
    }

    @Override
    public int getAcl(Tuple tuple, HandlerContext ctx) {
        // delegate to the default implementation, which throws when mask == -1
        return PreProcessor.super.getAcl(tuple, ctx);
    }
}

TusUploadHandler

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

TusUploadHandler#

com.palmyralabs.palmyra.handlers.TusUploadHandler

Marker interface — hook point for integrating a TUS resumable upload flow. Declares no methods of its own; implementations are wired by the TUS integration layer.

TusDownloadHandler

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

TusDownloadHandler#

com.palmyralabs.palmyra.handlers.TusDownloadHandler

Marker interface — hook point for TUS-style download flows (resumable, offset-based). Declares no methods of its own.

Handlers on Palmyra

QueryHandler

QueryHandler#

Request — query parameters#

Response shape#

ReadHandler

ReadHandler#

Request / response shape#

NativeQueryHandler

NativeQueryHandler#

Methods#

NativeQuery#

Methods#

TypedQueryHandler

TypedQueryHandler<E>#

Methods#

Example#

CreateHandler

CreateHandler#

Request / response — User#

Request#

Response#

Methods#

Example#

UpdateHandler

UpdateHandler#

Request / response — User#

Request#

SaveHandler

SaveHandler#

Request / response — User#

DeleteHandler

DeleteHandler#

Methods#

CsvHandler

CsvHandler#

Methods#

Example#

ExcelHandler

ExcelHandler#

Methods#

Example#

CustomFormatHandler

CustomFormatHandler#

Methods#

Example#

DataHandler

DataHandler#

Composed Surface#

CrudHandler

CrudHandler#

Composed Surface#

PreProcessor

PreProcessor#

Methods#

Example#

TusUploadHandler

TusUploadHandler#

TusDownloadHandler

TusDownloadHandler#

Request / response — `User`#

Request / response — `User`#

Request / response — `User`#