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
| Need | Supported route | Framework/legacy facility outside the manifest |
|---|---|---|
| Persisted derivation or save validation | RecordLifecycle, RecordValidator, secured RecordOperations | CaseFieldHook, Jmix managers |
| A condition a file cannot say | RecordFact<E> with FactContext, named as {fact: x} in a condition | A ConditionKind bean, which is for JCM modules |
| Case UI customization | Case-type configuration or CaseScreenSection with exported context and listed Vaadin types | Own Jmix detail views, internal JCM controls, ComboEnter |
| React to a configured workflow move | Task templates or WorkflowEffect | General WorkflowTransitionedEvent listeners |
| Move or start a record from code | RecordMoves; a file's on-enter for a record's relatives | WorkflowService, moveRelated |
| Open or make a record beside a child, under its parent | A declared or transition create with under: parent (and draft: true to open it unsaved), RecordActions.draft from code | Generated or Jmix views edited, an empty record saved first |
| Choose one child of a parent as its primary one | single: on the child type and a declared action with choose, run from code by RecordActions | A query before a save, a unique key, locking through internals |
| Hold a child record by one account of named roles, apart from its case | assignee: {field, roles} on the child type; offer and check with ChildAssigneeChoices | A plain user field with its own checks, UsersByRole, jcm_Assignment rows for a child |
| Record history | Built-in timeline and notes UI | Custom TimelineSource; no exported replacement |
| Configuration | Existing shipped file kinds and studio settings | ConfigCheck, 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,ChangeandChange.Kindfor hooks, immutable changes and save work.RecordFactandFactContext: a named fact a condition asks, typed by the record's class asRecordLifecycleis.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.IllegalArgumentExceptionsays what cannot be read;assignee = current-userin a job, with nobody asking, throwsIllegalStateException.DocumentsandDocumentInfo(call), andDocumentScanner(implement) withScanContextandScanResult, whose constructor is contracted because a scanner makes one. A read throughDocumentsis for the person the work is for.choicesgives what a model field oftype: documentcan be set to now, andrevisionsthe documents of one file name on a record, oldest first; a record sets such a field throughRecordOperations, and the save is held to the same rule (contract, Document revision fields).Deliveries,DeliveryRequest,DeliveryPiece,DeliveryEntryandDeliveryRefusedException(call): delivery evidence recorded and read back.PrintBatches,PrintBatchInfo,PrintBatchFileandPrintBatchRefusedException(call), andPrintConnector(implement) withPrintPackage(call),PrintReceipt,PrintNotTakenExceptionandPrintSendUnknownException, 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,RecordRefusedand thePlainMessagemarker, andRecordInvalidException(catch it and readissues(); only JCM throws it, so its constructor is internal).RecordSavedOutOfReach(com.jcm.core): thrown byRecordOperations.saveafter 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'srun,runInNewTransaction,quietly,current,isQuietandactor, andSystemWork.Scope's accessors andactorText. Its infrastructure constructor,onBehalfOf(the framework's own starters: jobs and sign-in) andScope's canonical constructor (only JCM creates a scope) are excluded.RecordActions, withVerdict(allowed,reasons,warnings,asks) andOutcome(message,record,tab), which only JCM makes:mayandrunof a declared action, with or without its binding,runtaking an idempotency key;draft(binding, record, action)and itsSiblingDraft(binding,record; only JCM makes one), the unsaved record acreate: ..., draft: trueaction opens for its generated form.ChildAssigneeChoices(field,roles,eligible,choices,refusalby binding) andAssigneeChoice(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 declaresassignee: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, itsMoveResult(state,stateName,related; only JCM makes one) andWorkflowException, 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 itsAdoptResult(started,workflow,version,state,stateName,related; only JCM makes one): starts the workflow on a record stored before its type had one, or answersstarted = falsewith what the record follows, whatever the call asks, and writes nothing. A person needs a role of the workflow file'sadopt: rolesand 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 aJobContextwritten by hand for a job's own test still compiles; the context a run is given keeps the line.JcmJob,JobContext,WorkflowEffect,WorkflowContext,QueueGroupResolverandQueueGroupMembers(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 ato:with usernames, party keys or addresses, and theAudienceAskedit is told (binding,actor; only JCM makes one, and it may grow).Json,JsonValueandJsonValue.Kind(call only), withJsonValue'stoString,equalsandhashCodelisted explicitly;JsonValue.ofPlainis the implementation's factory and is not exported.CaseScreenSectionconstants and methods;CaseScreenContext'sbinding,record,refresh,addMenu,transitions,isSaved,hasChanges,onRecordChangeandonSaved. Its constructors,layout,containeranddataContextremain internal.RefItem'sgetId,getCode,getName,getSortOrder,getValidFrom,getValidTo,getParentandisActiveOn. 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.