Base Classes on Palmyra

Tuple

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

Tuple#

com.zitlab.palmyra.store.Tuple

Overview#

Tuple is the base data carrier for every Palmyra operation. It holds the incoming JSON as a flat attribute map plus explicit parent and children maps for related records, and it travels unchanged from the request parser all the way to the database layer. Tuple extends RecordImpl and is Serializable.

Typical lifecycle: the framework hydrates a Tuple from the request, your handler mutates it in preXxx / onXxx, the SQL layer writes it, and postXxx sees the post-write state. On updates the original DB snapshot is available via getDbTuple().

HandlerContext

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

HandlerContext#

com.palmyralabs.palmyra.handlers.HandlerContext

Overview#

Request-scope context passed to every handler hook. Exposes the mapped type, URL path, action, query/path parameters, the client info, and the raw HttpServletResponse. It also doubles as a typed scratchpad via put / get(String, Class<T>), scoped to the current request.

Methods#

Method	Signature
`getType`	`String getType()` — entity type being handled
`getPathMapping`	`String getPathMapping()` — matched CRUD/action path
`getAction`	`MutableAction getAction()` — current CRUD action
`getParams`	`Map<String, String> getParams()` — query + path params
`getClientInfo`	`ClientInfo getClientInfo()` — calling client metadata
`getResponse`	`HttpServletResponse getResponse()` — raw servlet response
`getReturnMode`	`String getReturnMode()`
`put`	`void put(String key, Object value)` — scratchpad write
`get`	`Object get(String key)` · `default <T> T get(String key, Class<T> clazz)` — typed read

Example#

@Override
public Tuple preCreate(Tuple tuple, HandlerContext ctx) {
    // pull a tenant hint from the URL
    String tenant = ctx.getParams().get("tenantId");
    tuple.setAttribute("tenantId", tenant);

    // cache something for postCreate to read
    ctx.put("correlationId", UUID.randomUUID().toString());

    // set a custom response header
    ctx.getResponse().setHeader("X-Palmyra-Action", ctx.getAction().name());
    return tuple;
}

@Override
public Tuple postCreate(Tuple tuple, HandlerContext ctx) {
    String correlationId = ctx.get("correlationId", String.class);
    outbox.publish("user.created", Map.of("id", tuple.get("id"), "corr", correlationId));
    return tuple;
}

FilterCriteria

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

FilterCriteria#

com.palmyralabs.palmyra.base.FilterCriteria

Overview#

Interface representing client-supplied criteria for a read — underlying SimpleCriteria plus order-by list, pagination, and an “include parents” toggle. This is what handlers receive in aclCheck, applyQueryFilter, preProcess, and friends — before the framework compiles it into a QueryFilter.

The constant FilterCriteria.EMPTY is a shared no-op instance.

Methods#

Method	Signature
`getSimpleCriteria`	`SimpleCriteria getSimpleCriteria()`
`addCriteria`	`default void addCriteria(String key, String value)`
`addRefCriteria`	`default void addRefCriteria(String key, String value)`
`removeCriteria`	`default void removeCriteria(String key)`
`addOrderBy`	`void addOrderBy(String field, boolean asc)`
`removeOrderBy`	`boolean removeOrderBy(String field)`
`getPagination` / `setPagination`	`Pagination getPagination()` · `void setPagination(Pagination page)`
`isIncludeParents` / `setIncludeParents`	`boolean isIncludeParents()` · `void setIncludeParents(boolean include)`

Example#

@Override
public void preProcess(FilterCriteria criteria, HandlerContext ctx) {
    // inject a default tenant scope into every request
    criteria.addCriteria("tenantId", userProvider.getTenantId());

    // if the client didn't ask for sorting, pick a default
    if (!criteria.removeOrderBy("createdAt")) {
        criteria.addOrderBy("createdAt", false); // DESC
    }

    // always hydrate parent records for this endpoint
    criteria.setIncludeParents(true);
}

QueryFilter

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

QueryFilter#

com.zitlab.palmyra.store.QueryFilter

Overview#

The compiled filter the framework hands to the SQL layer — implements Filter. Handlers receive it in applyQueryFilter (or applyFilter) to inject additional conditions, fields, joins, ordering, or pagination before the SELECT is built.

Backed internally by ComboCondition for WHERE clauses, FieldList for projected fields, OrderList for ORDER BY, and a map of JoinClause entries for joins.

Methods#

Fields / projection

Method	Signature
`getFields` / `setFields`	`FieldList getFields()` · `void setFields(FieldList)` · `void setFields(String... values)`
`addFields`	`void addFields(String... values)`
`addParentFields`	`void addParentFields(String... values)`
`setDistinctFields`	`void setDistinctFields(String... fields)`
`setFieldsAsString`	`void setFieldsAsString(List<String> fieldList)`
`isDistinct` / `setDistinct`	`boolean isDistinct()` · `void setDistinct(boolean)`
`getCustFields` / `setCustomFields`	`Map<AggregationClause, String> getCustFields()` · `void setCustomFields(AggregationClause, String)`

Conditions

NativeQuery

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

NativeQuery#

com.zitlab.palmyra.store.NativeQuery

Overview#

Value object that carries a hand-written SQL statement plus its positional parameters, optional count query, and paging controls. Implements QueryOptions and CountQuery. Built and returned from NativeQueryHandler.getQuery(...).

params are positional ? placeholders (JDBC-style) — bind them in order. Set countQuery when pagination needs a distinct count different from a naive COUNT(*) over the main query.

Methods#

Method	Signature
`NativeQuery`	`NativeQuery()` · `NativeQuery(String query)` · `NativeQuery(String query, List<Object> params)` · `NativeQuery(String query, Object... params)`
`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()`

Example#

@Override
public NativeQuery getQuery(FilterCriteria criteria, HandlerContext ctx) {
    String sql = """
        SELECT u.id, u.name, SUM(o.amount) 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;
}

ColumnMeta

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

ColumnMeta#

com.palmyralabs.palmyra.handlers.ColumnMeta

Overview#

Describes a single exported column for CsvHandler / ExcelHandler: the display name, the bean attribute to read from the row, and an optional FieldConverter for formatting values on the way out (dates, enums, currency, etc.).

Methods#

Method	Signature
`getName`	`String getName()`
`getAttribute`	`String getAttribute()`
`getConverter`	`FieldConverter getConverter()`

Example#

@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", new LocalDateConverter("yyyy-MM-dd"))
    );
}

PalmyraResponse

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

PalmyraResponse#

com.palmyralabs.palmyra.base.PalmyraResponse<T>

Overview#

Thin generic wrapper around a handler result. Holds the result value and derives the HTTP status — 200 when a result is present, 404 when it is null. Lombok-generated getters and an all-args constructor.

Methods#

Method	Signature
`PalmyraResponse`	`PalmyraResponse(T result)` (generated)
`getResult`	`T getResult()` (Lombok-generated)
`getStatus`	`int getStatus()` — `200` when result is non-null, `404` otherwise

Example#

@RestController
@RequestMapping("/v1/admin/user")
public class UserLookupController {

    private final UserService service;

    @GetMapping("/{id}")
    public PalmyraResponse<User> byId(@PathVariable String id) {
        return new PalmyraResponse<>(service.findById(id)); // status auto: 200 or 404
    }
}

AuthProvider

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

AuthProvider#

com.zitlab.palmyra.store.base.security.AuthProvider

Overview#

Tiny SPI for resolving the currently authenticated user. Provide an implementation (typically wired against your auth stack — Spring Security, an OAuth filter, a JWT resolver) and the storage layer will call getUser() to stamp audit columns, scope ACLs, and so on. A lightweight SimpleUserProvider is available for tests and fixtures via the of(String) factory.

Methods#

Method	Signature
`getUser`	`String getUser()`
`of`	`static AuthProvider of(String user)` — returns a `SimpleUserProvider`

Example#

@Component
public class SecurityContextAuthProvider implements AuthProvider {

    @Override
    public String getUser() {
        var auth = SecurityContextHolder.getContext().getAuthentication();
        return (auth != null && auth.isAuthenticated()) ? auth.getName() : "anonymous";
    }
}

// Unit / integration tests — fixed user:
AuthProvider fixture = AuthProvider.of("test-user");