Annotations on Palmyra

@PalmyraType

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

@PalmyraType#

com.palmyralabs.palmyra.base.annotations.PalmyraType

Maps a POJO to its primary database table. Target: TYPE. Retention: RUNTIME.

Attributes#

Attribute	Signature
`type`	`String type() default ""` — alias for `value`; logical type name
`value`	`String value() default ""` — alias for `type`
`table`	`String table() default ""` — DB table name
`schema`	`String schema() default ""` — DB schema name
`aclMask`	`Acl aclMask() default Acl.ALL` — access-control mask
`active`	`boolean active() default true` — whether the entity is active
`searchAll`	`boolean searchAll() default false` — all fields searchable
`sortAll`	`boolean sortAll() default false` — all fields sortable
`preferredKey`	`String preferredKey() default ""` — unique key to consult first during identity lookups (see preferredKey)
`drop`	`DropMode drop() default DropMode.NONE` — drop behavior

When the database uses snake_case, supply type in CamelCase.

@PalmyraField

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

@PalmyraField#

com.palmyralabs.palmyra.base.annotations.PalmyraField

Attaches metadata to an attribute — column mapping, sort/search flags, validation, ACL, and pre-save transforms. Target: FIELD. Retention: RUNTIME.

Attributes#

Attribute	Signature
`attribute`	`String attribute() default ""` — bean attribute name
`value`	`String value() default ""` — alias for `attribute`
`name`	`String name() default ""` — logical field name
`column`	`String column() default ""` — DB column
`title`	`String title() default ""` — display title
`displayOrder`	`int displayOrder() default 0`
`primaryKey`	`boolean primaryKey() default false`
`keyField`	`boolean keyField() default false` — logical key field
`primaryRef`	`String primaryRef() default ""`
`parentRef`	`String parentRef() default ""`
`search`	`boolean search() default false` — searchable
`sort`	`boolean sort() default false` — sortable
`quickSearch`	`boolean quickSearch() default false`
`pattern`	`String pattern() default ""` — validation regex
`notNull`	`boolean notNull() default false`
`mandatory`	`Mandatory mandatory() default Mandatory.NONE` — operation-scoped required check (see Mandatory)
`active`	`boolean active() default true`
`virtual`	`boolean virtual() default false` — non-persistent
`aclMask`	`Acl aclMask() default Acl.DEFAULT`
`drop`	`DropMode drop() default DropMode.NONE` — strip the attribute in a given direction (see DropMode)
`preProcessor`	`Class<? extends Function<Object,Object>> preProcessor() default processor.class` — pre-save transform
`childMode`	`ChildProcessMode childMode() default ChildProcessMode.MERGE`

Example#

public class User {

    @PalmyraField(attribute = "id", column = "user_id", primaryKey = true)
    private Long id;

    @PalmyraField(attribute = "email", sort = true, search = true, quickSearch = true)
    private String loginName;

    @PalmyraField(attribute = "displayName", pattern = "^[A-Za-z ]{1,64}$", notNull = true)
    private String name;
}

Flattening with `parentRef`#

parentRef lets a DTO expose a scalar that’s actually sourced from a joined table. The client sees a flat JSON shape; the backend still does the join. The dotted path can live on either parentRef or attribute.

@PalmyraIgnore

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

@PalmyraIgnore#

com.palmyralabs.palmyra.base.annotations.PalmyraIgnore

Marker annotation — excludes a field from Palmyra’s processing (no attribute). Target: FIELD. Retention: RUNTIME.

Attributes#

None.

Example#

public class User {
    private String loginName;

    @PalmyraIgnore
    private transient String oneTimeToken; // never mapped, never serialized
}

@CrudMapping

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

@CrudMapping#

com.palmyralabs.palmyra.base.annotations.CrudMapping

Binds a handler component to one or more URL paths and the entity type it operates on — Palmyra’s equivalent of Spring’s @RequestMapping for CRUD surfaces. Target: TYPE. Retention: RUNTIME.

Attributes#

Attribute	Signature
`mapping`	`String[] mapping()` — collection-level path; consumed by `QueryHandler`, `CreateHandler`, `SaveHandler`
`secondaryMapping`	`String secondaryMapping() default ""` — single-record path (usually `{id}`-templated); consumed by `UpdateHandler`, `DeleteHandler`
`type`	`Class<?> type()` — entity type handled
`queryType`	`Class<?> queryType() default Object.class` — type used for query projections

Which handler hits which URL#

Palmyra routes HTTP methods to handler interfaces based on which mapping the request matched:

@ActionMapping

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

@ActionMapping#

com.palmyralabs.palmyra.base.annotations.ActionMapping

Binds a handler component to one or more action names/URLs — used for non-CRUD RPC-style endpoints. Target: TYPE. Retention: RUNTIME.

Attributes#

Attribute	Signature
`value`	`String[] value()` — URL path(s); alias for `path`
`path`	`String[] path() default {}` — alias for `value`
`action`	`String[] action() default {}` — action name(s)

Example#

@Component
@ActionMapping(value = "/v1/admin/user", action = {"reset-password", "enable", "disable"})
public class UserAdminActions {
    // ...
}

@Permission

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

@Permission#

com.palmyralabs.palmyra.base.annotations.Permission

Declares the permission keys required to invoke a handler’s operations. Target: TYPE. Retention: RUNTIME.

Use cruds to assign a single permission across all CRUD operations, or set per-operation keys individually.

How these keys are evaluated#

Palmyra feeds each @Permission value through the standard Spring PermissionEvaluator registered in the application context — the same mechanism @PreAuthorize("hasPermission(...)") uses. This makes the authorization policy pluggable at the framework level:

With the default PalmyraPermissionEvaluator (shipped by palmyra-dbacl-mgmt), the keys resolve against the ACL tables.
Register your own PermissionEvaluator bean — Keycloak/OPA bridge, in-house RBAC, remote SaaS — and the same @Permission keys resolve through your policy engine without touching handler code.

Attributes#

Attribute	Signature
`value`	`String value()` — permission name/key
`cruds`	`String cruds() default ""` — combined CRUD permission
`read`	`String read() default ""`
`query`	`String query() default ""`
`create`	`String create() default ""`
`update`	`String update() default ""`
`delete`	`String delete() default ""`
`export`	`String[] export() default {}` — export permission(s)

Example#

@Component
@CrudMapping(value = "/v1/admin/user", type = User.class)
@Permission(
    value  = "USER",
    query  = "USER_READ",
    create = "USER_CREATE",
    update = "USER_UPDATE",
    delete = "USER_DELETE",
    export = {"USER_EXPORT"}
)
public class UserCrudHandler implements CrudHandler {
}

@PalmyraMappingConfig

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

@PalmyraMappingConfig#

com.palmyralabs.palmyra.base.annotations.PalmyraMappingConfig

Declares application-managed unique-key and foreign-key constraints for a type. Target: TYPE. Retention: RUNTIME.

When you need it#

By default Palmyra discovers table relationships from JDBC metadata (or a custom schema-introspection query) — it reads primary keys, unique constraints and foreign keys straight off the database. You don’t write this annotation for normally-constrained schemas.

Reach for @PalmyraMappingConfig when those constraints are managed in the application, not the database:

A shared/read-only schema where you can’t add FK or unique constraints.
Legacy tables where the data modelling is enforced by application code only.
Views or staging tables that deliberately omit physical constraints for performance or flexibility reasons.

Declaring the constraints here tells Palmyra to treat them as real — identity lookups (pre-insert existence check, SaveHandler upsert, unique-violation detection) honour the declared unique keys, and joined-attribute resolution (see @PalmyraField.parentRef) follows the declared foreign keys.

@PalmyraUniqueKey

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

@PalmyraUniqueKey#

com.palmyralabs.palmyra.base.annotations.PalmyraUniqueKey

Declares a (composite) unique key over one or more fields. Target: TYPE. Retention: CLASS — consumed only through @PalmyraMappingConfig.uniqueKeys.

Attributes#

Attribute	Signature
`fields`	`String[] fields() default {}` — fields composing the unique key

Example#

@PalmyraMappingConfig(
    type = "User",
    uniqueKeys = {
        @PalmyraUniqueKey(fields = {"tenantId", "loginName"})
    }
)
public class User { }

@PalmyraForeignKey

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

@PalmyraForeignKey#

com.palmyralabs.palmyra.base.annotations.PalmyraForeignKey

Declares a foreign-key relationship to another Palmyra type. Target: TYPE. Retention: CLASS — consumed only through @PalmyraMappingConfig.foreignKeys.

Attributes#

Attribute	Signature
`name`	`String name()` — FK name
`targetType`	`String targetType() default ""` — referenced entity type
`targetReference`	`String targetReference()` — reference identifier on the target
`sourceFields`	`String[] sourceFields() default {}`
`targetFields`	`String[] targetFields() default {}`

Example#

@PalmyraMappingConfig(
    type = "Order",
    foreignKeys = {
        @PalmyraForeignKey(
            name = "fk_order_user",
            targetType = "User",
            targetReference = "user",
            sourceFields = {"userId"},
            targetFields = {"id"}
        )
    }
)
public class Order { }

@FetchConfig

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

@FetchConfig#

com.palmyralabs.palmyra.base.annotations.FetchConfig

Controls how much of a parent (referenced) object is fetched when its owning row is read. Target: FIELD. Retention: RUNTIME.

Applies to parent references only. @FetchConfig has no effect on child collections — child attributes are always fetched under the current framework behaviour. Apply the annotation to the field that holds the parent/FK reference.

Attributes#

Attribute	Signature
`fetchMode`	`FetchMode fetchMode() default FetchMode.ALL`

`FetchMode`#

com.palmyralabs.palmyra.base.format.FetchMode

Constant	Wire value	What comes back from the parent
`ALL`	`"all"`	Every attribute of the parent (default)
`PRIMITIVE_FIELDS`	`"primitive"`	Scalar / primitive columns only — no nested references
`KEY_FIELDS`	`"keyfield"`	Just the fields flagged as key (`@PalmyraField(keyField = true)` / primary key)
`PRIMITIVE_OR_KEY_FIELDS`	`"primitive_key"`	Union of the two — primitives plus key fields

Use PRIMITIVE_OR_KEY_FIELDS when the UI needs a display label (a primitive name/code) plus an id (a key field), but no further joins. Use KEY_FIELDS when only the id is needed — useful for light-weight list payloads.

Annotations on Palmyra

@PalmyraType

@PalmyraType#

Attributes#

@PalmyraField

@PalmyraField#

Attributes#

Example#

Flattening with parentRef#

@PalmyraIgnore

@PalmyraIgnore#

Attributes#

Example#

@CrudMapping

@CrudMapping#

Attributes#

Which handler hits which URL#

@ActionMapping

@ActionMapping#

Attributes#

Example#

@Permission

@Permission#

How these keys are evaluated#

Attributes#

Example#

@PalmyraMappingConfig

@PalmyraMappingConfig#

When you need it#

@PalmyraUniqueKey

@PalmyraUniqueKey#

Attributes#

Example#

@PalmyraForeignKey

@PalmyraForeignKey#

Attributes#

Example#

@FetchConfig

@FetchConfig#

Attributes#

FetchMode#

Flattening with `parentRef`#

`FetchMode`#