Skip to main content

Extension API

The API version equals the release version: the contract is 0.1.0, the version the first release will carry, and every type and member says since: '0.1.0'. The plugin ships its exact type and member list at META-INF/jcm/extension-api.yml, with the candidate baseline at META-INF/jcm/api-baselines/0.1.0.yml. The candidate holds 97 types and 595 declarations, notifications, deadline operations, appointments, availability, delivery evidence and print batches included. It is not evidence of an earlier released API: nothing is released until history.properties says 0.1.0=released:<sha>. A change to the manifest re-freezes the candidate in the same reviewed change (copy it byte for byte to the baseline and put its SHA-256 in history.properties); checks never rewrite either file. The runtime core JAR also carries the manifest and history. check runs checkJcmApi alongside checkJmixLayer.

Choosing an application extension​

NeedSupported routeFramework/legacy facility outside the manifest
Persisted derivation or save validationRecordLifecycle, RecordValidator, secured RecordOperationsCaseFieldHook, Jmix managers
A condition a file cannot sayRecordFact<E> with FactContext, named as {fact: x} in a conditionA ConditionKind bean, which is for JCM modules
Case UI customizationCase-type configuration or CaseScreenSection with exported context and listed Vaadin typesOwn Jmix detail views, internal JCM controls, ComboEnter
React to a configured workflow moveTask templates or WorkflowEffectGeneral WorkflowTransitionedEvent listeners
Move or start a record from codeRecordMoves; a file's on-enter for a record's relativesWorkflowService, moveRelated
Open or make a record beside a child, under its parentA declared or transition create with under: parent (and draft: true to open it unsaved), RecordActions.draft from codeGenerated or Jmix views edited, an empty record saved first
Choose one child of a parent as its primary onesingle: on the child type and a declared action with choose, run from code by RecordActionsA query before a save, a unique key, locking through internals
Hold a child record by one account of named roles, apart from its caseassignee: {field, roles} on the child type; offer and check with ChildAssigneeChoicesA plain user field with its own checks, UsersByRole, jcm_Assignment rows for a child
Record historyBuilt-in timeline and notes UICustom TimelineSource; no exported replacement
ConfigurationExisting shipped file kinds and studio settingsConfigCheck, ConfigReloadable, ConfigGeneration; no exported registry SPI

A validator remains read-only. Use reason-bearing SystemWork only when its check needs privileged data; ordinary reads stay secured. Public implementation descriptions in the component contract do not extend exports.

Exact supported declarations​

@JcmApi(since = "0.1.0") is runtime metadata on hand-written types, members and packages. A package marker identifies where entry points live. A type marker identifies a supported type. Neither exports other public members, constructors, inherited methods or neighboring types. The shipped manifest is authoritative; adding an annotation in application code cannot export an implementation class.

The initial entries cover:

  • RecordLifecycle, LifecycleContext, Change and Change.Kind for hooks, immutable changes and save work.
  • RecordFact and FactContext: a named fact a condition asks, typed by the record's class as RecordLifecycle is.
  • Conditions: holds(binding, record, text), a job asking the text a file would write of a stored record, read as system. So the text is the author's and never a person's: a text a person types, answered from what they may not see, is an oracle that finds a hidden value character by character. IllegalArgumentException says what cannot be read; assignee = current-user in a job, with nobody asking, throws IllegalStateException.
  • Documents and DocumentInfo (call), and DocumentScanner (implement) with ScanContext and ScanResult, whose constructor is contracted because a scanner makes one. A read through Documents is for the person the work is for. choices gives what a model field of type: document can be set to now, and revisions the documents of one file name on a record, oldest first; a record sets such a field through RecordOperations, and the save is held to the same rule (contract, Document revision fields).
  • Deliveries, DeliveryRequest, DeliveryPiece, DeliveryEntry and DeliveryRefusedException (call): delivery evidence recorded and read back. PrintBatches, PrintBatchInfo, PrintBatchFile and PrintBatchRefusedException (call), and PrintConnector (implement) with PrintPackage (call), PrintReceipt, PrintNotTakenException and PrintSendUnknownException, whose constructors are contracted because a connector makes them. The constructors of the records JCM alone makes (DeliveryPiece, DeliveryEntry, PrintBatchInfo, PrintBatchFile) are excluded.
  • RecordValidator, ValidationContext, RecordIssue, RecordRefused and the PlainMessage marker, and RecordInvalidException (catch it and read issues(); only JCM throws it, so its constructor is internal).
  • RecordSavedOutOfReach (com.jcm.core): thrown by RecordOperations.save after a change to a stored record that is stored and leaves the record outside what its saver may read under row rules of role files. Not a refusal. A workflow move catches it from an effect and goes on; elsewhere catch it around the save, or the change around it rolls back and the screens say that nothing was saved. Its public surface is the type, entityName(), id() and its message; it has no public constants.
  • SystemWork's run, runInNewTransaction, quietly, current, isQuiet and actor, and SystemWork.Scope's accessors and actorText. Its infrastructure constructor, onBehalfOf (the framework's own starters: jobs and sign-in) and Scope's canonical constructor (only JCM creates a scope) are excluded.
  • RecordActions, with Verdict (allowed, reasons, warnings, asks) and Outcome (message, record, tab), which only JCM makes: may and run of a declared action, with or without its binding, run taking an idempotency key; draft(binding, record, action) and its SiblingDraft (binding, record; only JCM makes one), the unsaved record a create: ..., draft: true action opens for its generated form.
  • ChildAssigneeChoices (field, roles, eligible, choices, refusal by binding) and AssigneeChoice (username, name; only JCM makes one, read as the system so the picker needs no access to accounts): who may hold a child record whose type declares assignee: in the case-type file, an active account holding one of the roles now, and the words a save refuses anyone else with. For an application's own picker or a check before it saves; the platform judges every save whatever is asked here. See the contract, A role-scoped assignee on a child type.
  • RecordMoves, its MoveResult (state, stateName, related; only JCM makes one) and WorkflowException, which applications catch and only JCM throws, so its constructors are not exported. Its subclasses for a refused role and a lost race are caught as it.
  • RecordMoves.adopt(record, workflow, version, state, reason) and its AdoptResult (started, workflow, version, state, stateName, related; only JCM makes one): starts the workflow on a record stored before its type had one, or answers started = false with what the record follows, whatever the call asks, and writes nothing. A person needs a role of the workflow file's adopt: roles and read permission on the entity; system work, a job's included, does not. See the contract, Adopting stored records, for what the start runs and for the bulk recipe.
  • JobContext.summary(text): the one line a run's history shows beside its counts, in fixed wording with counts ("Adopted 8, already started 2"). It has a body that keeps nothing, so a JobContext written by hand for a job's own test still compiles; the context a run is given keeps the line.
  • JcmJob, JobContext, WorkflowEffect, WorkflowContext, QueueGroupResolver and QueueGroupMembers (the reverse of the resolver: a group's usernames in pages, so group notifications reach members without visiting every user).
  • AudienceProvider, which answers {code: <code>} in a to: with usernames, party keys or addresses, and the AudienceAsked it is told (binding, actor; only JCM makes one, and it may grow).
  • Json, JsonValue and JsonValue.Kind (call only), with JsonValue's toString, equals and hashCode listed explicitly; JsonValue.ofPlain is the implementation's factory and is not exported.
  • CaseScreenSection constants and methods; CaseScreenContext's binding, record, refresh, addMenu, transitions, isSaved, hasChanges, onRecordChange and onSaved. Its constructors, layout, container and dataContext remain internal.
  • RefItem's getId, getCode, getName, getSortOrder, getValidFrom, getValidTo, getParent and isActiveOn. Its constructor, mutators, version, list metadata and seed hash are excluded.

Generated record accessors, canonical constructors (except SystemWork.Scope's), equality/hash/text methods and enum constants/lookup methods are listed explicitly. They do not need boilerplate overrides solely to carry an annotation. Ordinary Java Object and Throwable operations remain Java operations; they do not expose JCM implementation members. The pure values in these signatures need no additional JCM closure types in this task.

A hook still runs with the existing ordering, save transaction and after-flush/after-commit semantics. System work still requires a reason and retains the actor. The contract adds no new runtime privilege.

@Component
public class DecisionCheck implements RecordValidator<Decision> {
@Override
public void validate(Decision record, ValidationContext context) {
if (record.getDecisionDate() == null) {
context.error("decisionDate", "Enter the decision date");
}
}
}

The example uses an application record and Spring's component annotation; the complete approved dependency and source namespace policy is delivered with enforcement. Signature closure currently accepts Java platform module types and exactly Vaadin Component, Registration and Anchor (what ScreenLinks returns) alongside explicitly exported JCM types. It does not approve arbitrary Vaadin, Spring, Jmix or other library implementation types.