The studio and publishing
Configuration studio
jcm-studio with jcm-studio-starter (a Component; needs jcm-workflow, jcm-queues and jcm-roles) shows the
configuration as the app read it, for the people who shape the application, and, where an environment turns editing
on, changes it. The configuration is still the files: the studio writes the same YAML a developer edits, to a folder
on disk (jcm.studio.files) that is the loader's first override root, and nothing it writes lives only in the
database. Every change, from a form, the text editor, a matrix tick or an undo, goes through one pipeline: a draft of
the file, Check (every check the application runs at startup, against the configuration as it would be, nothing
written), Publish (the same checks again under a lock, the files written safely, the whole configuration swapped in
one step and applied at run time on this server without a restart), a History record with its diff, and Undo of the
newest publish. It shows names first, as users see them, with the code beside them, muted, for whoever edits the
files; every refusal it shows comes from the loader, a registry or the workflow's own reasons, never a check of its
own, with the file and line, put in plain words beside the field where a form has one.
How the parts fit (each is a section below):
- Generations (framework implementation of reload, not an application SPI).
ConfigGenerationholds the files and every kind's checked state as one generation; each registry reads from the current one per use. A publish prepares every kind against the candidate in startup order, verifies, swaps the whole generation in one write, then commits side effects (What a publish reloads; Configuration layout, "Configuration generations"). Every registry that reads files implementsConfigReloadable, so a new kind gets its editing setting, its place in the Files area and its reload by implementing it; a check lives in itsprepareorverify(or aConfigCheckbean), never incommitor a listener, so a publish refuses exactly what the next start refuses, with the same message (check parity). - Check and Publish.
StudioPublisher.check(change)andpublish(change)(Publish: the pipeline): areas and roles, stale forms, the candidate read by the loader and checked by every registry, the safe write, the swap and commits, the record. A failure after the write puts the files and the generation back;as.studio.last-publishsays so. - The version rule. A workflow version with records on it keeps its meaning: a change that could strand a
record (a state or transition taken away, a narrower
from, a changedtoorinitial) is written as a new version, and the publisher refuses any such change, from any route, made in place on a version records are on; records finish on the version they started on (Workflow editor). - History and Undo. One
jcm_StudioChangerow per file of each publish, with the text before and after and whether the folder held the file; the History area lists them with their diffs; Undo reverses the newest publish as a publish of its own (Undid: <summary>), checks and all, after a confirmation, taking out a copy the publish put where the folder held none; Download gives the folder, its diff against the deployed application and the log (History and undo, History area). - The notice. Open sessions on this server are told after a publish applied: the inbox and the case screen show "Configuration changed: <summary>. Reload to see it." and redraw only when the user reloads; studio areas redraw in place, keeping what the viewer chose, unless they hold a draft (What open sessions see).
- The editors. The workflow editor (states, transitions and stages on the diagram, renames carried to the files
that name the state), the queue editor (columns as two lists, filters, buttons, layout, its inbox tab, with a live
preview; new and removed queues; the inbox tabs), the job roles editor (add, edit, order and remove job roles; the
role matrix's ticks put a resource role into or out of a transition's, queue's or button's
roles), and the text editor (any file of an area that is on, new files, removals). Each holds a draft of one file (or the few files one change touches) and publishes it with a summary in words (Workflow editor, Queue editor, Inbox tabs, Job roles, Roles editor, The text editor). - Settings and the dev profile. Editing is off in every area unless that environment's own settings turn it on
(
jcm.studio.edit.<area>=trueand a writablejcm.studio.files); the dev profile does so for a developer's own machine, writing intosrc/main/resources/jcmsogit diffshows each publish (Editing settings, Where edits are written). The app never commits: outside development, edits reach source control by Download and a commit; a removal there is a.removedmarker (commit the deletion of the real file, then delete the marker); under the dev profile a removal deletes the source file alone, the built copy counting until the next build.
The areas:
- Overview: whether each area's editing is on here and why not, and where edits are written (Editing settings).
- Case types (
jcm_StudioCaseTypes, routejcm/studio/case-types,jcm/studio/case-types/<code>scrolling to one), read only: a card per case type, its label first with its code beside it, muted, and its layout file (case-types/<code>.yml, a link to Files). When its entity is in the data model, each entity of the case follows, the case entity and then its children depth first in the orderchildren:lists them: a grid of its fields (Field as the label with the attribute muted, Type, Required, Length, List), its parent, its children, and "Can read" and "Can change": every resource role (Java, file or database) holding an allowing entity policy on that entity, asName (code)by name, withread(or*) for reading andcreate,updateordelete(or*) for changing, child roles' policies counted; a policy on every entity (*, as full access holds) is not listed, which the area's intro says, and the empty case reads "No role besides full access". An entity withaudit: truesays "Records who created and last changed each record." "Belongs to" names the parent by its caption, with the entity name muted only when it differs. A case type whose entity is written in Java says so, by name, and shows no fields.CaseTypeSummaries(jcm_CaseTypeSummaries) builds it:all(), andbuild(Model, List<CaseBinding>, Function<String, Access>)withaccess(List<RoleGrants>)for tests. - Workflows: each version drawn in columns (its stages, or steps from the initial state), with records counted per version, and one record's path on it (Workflows, A record's path); where editing workflows is on, the diagram is the editor (Workflow editor).
- Queues: a gallery of cards by inbox tab, in plain words, each with a preview under the viewer's own rights in which nothing runs (Queues); where editing queues is on, Edit opens a queue as a form with a live preview, New queue starts one, Remove removes one (Queue editor), and "Inbox tabs" adds, renames, orders and removes the inbox's tabs and moves queues between them (Inbox tabs).
- Roles: a matrix of who may use each queue, make each transition, press each button and see each dashboard, as the app decides at run time, with the reason in each cell (Roles); a resource role's cell is a tick where editing its area is on (Roles editor). Under it, Job roles: each job role, what it is built from and its place in the job switcher, added, edited, ordered and removed where editing job roles is on (Job roles).
- Where used: every place a code is named, before removing it (Where used).
- Files: every file read, line by line, numbered as loader messages name them; any file of an area that is on edited as text, new files and removals (Files, The text editor).
- History: every publish newest first with its diffs, the confirmation and Undo of the newest, the files that differ here from the deployed application, and Download (History area).
Not applied at run time, but staged: case types and their form rules (case-types: read at startup only), the data
model, the data roles and access.yml (model, roles, access: fixed when the application is built). Each is an
area of its own, edited as text where its switch is on; a publish there is checked by the startup readers, written
where the build reads it, recorded, and counts after a restart, or a rebuild and a restart (Staged editing, below).
An area whose component is not installed is no area. jcm.yml cannot be removed. Areas without a form (tasks,
deadlines, rules, dashboards, letters, reference lists, jobs, questionnaires, duplicates, seed, and the staged kinds)
are edited as text where their setting is on.
Not here yet: reloading case types (DefaultCaseRegistry as a ConfigReloadable) and their form rules;
forms for rules, tasks, deadlines, dashboards, letters and reference lists (and jobs, questionnaires and
duplicates); propagation of a publish to other servers (today editing is refused above one server, and a server
behind the newest publish says so; another server reads a publish at its next start); a
condition builder for queues (the JPQL condition stays under Advanced); a Git publish target (a PublishTarget
writing a branch; the app names no git today); a check of another kind against a staged entity model (a case type
binding an entity only the staged model declares is refused until the rebuild).
Its overview is jcm_Studio (route jcm/studio), the item "Configuration studio" under the "Case administration"
menu. Every studio view has the studio header and a left navigation, "Studio areas": Overview, Case types
(jcm_StudioCaseTypes), Workflows (jcm_StudioWorkflows), Queues (jcm_StudioQueues), Roles (jcm_StudioRoles),
Job roles (jcm_StudioJobRoles, a flat item set in under Roles: a nested item's expand button fails the
accessibility scan), Where used (jcm_StudioWhereUsed), Files (jcm_StudioFiles) and
History (jcm_StudioHistory); the areas have no menu items of their own.
StudioViews.ALL lists the view ids. A studio view extends StudioAreaView, whose descriptor is one
<vbox id="studioBox" padding="false" width="100%"/>, and fills content(). StudioLinks makes the deep links:
workflow(code, version, transition) (jcm/studio/workflows/<code>?version=<n>&transition=<t>, each query value
when given), queue(code) (jcm/studio/queues/<code>), whereUsed(value) (jcm/studio/where-used?code=<v>) and
file(relativePath) (jcm/studio/files?file=<path>), history(publishId) (jcm/studio/history/<id>) and
historyDiff(relativePath) (jcm/studio/history?diff=<path>), queueEditor(code) (jcm/studio/queues/<code>/edit)
and newQueue() (jcm/studio/new-queue), jobRoles() (jcm/studio/job-roles), with the values URL-encoded; anchor(link, text)
makes a link to one that is followed in the page.
Two roles, held with the host's minimal UI role:
StudioViewerRole(jcm-studio-viewer) opens every studio view and its menu item, and nothing else; its@ViewPolicylists each view id, the queue editor's (jcm_StudioQueueEditor,jcm_StudioNewQueue) too, which are not inStudioViews.ALL(they are opened from a card, not the navigation) and show their form read only with the reason; the job roles' forms and the inbox tabs open for it read only, each button saying why. In History it sees every publish, its diffs and Download; Undo is disabled with the editor-role reason.StudioEditorRole(jcm-studio-editor) composes the viewer and grants no more rights; holding it is whatStudioEditing.of(area)asks of the signed-in user before a form, the text editor, a matrix tick or Undo may publish where the environment allows editing (no editor rolebelow). The publisher asks the same whatever calls it, and History records the user and the job role they worked as.
Neither grants entity rights or composes a role of another component: whatever a studio view shows of records (a
record's path, a queue preview's rows) runs with the user's other roles. Never give system-full-access to show
the studio.
A job role that holds a studio role beside a group's resource role, such as the hearings demo's Configuration
(job.studio: jcm-studio-editor and demo-manager), lets that user show a record's path and preview the group's
queues with rows; the demo's studio walk is in The hearings demo.
The Files area and where-used read what the loader read, never the files again: ConfigFiles.loaded() for each
file's text, root and what it replaces, and ConfigNode.scalars() for each value with its line and what it is
written under (see Where files are read from).
What a publish reloads
Every kind that loads from files is a ConfigReloadable (see Configuration layout, "Configuration generations"). A
publish prepares every one against the candidate in this order, each seeing the candidate's state of the kinds
before it, then verifies, swaps the generation, then commits; the next request reads the new generation.
| Order | Kind (folder) | Registry | Checked against on publish | Commit |
|---|---|---|---|---|
| 100 | Workflows (workflows) | WorkflowRegistry | bindings, roles, effects, related moves | nothing; a move running finishes on its definition, records keep their version |
| 110 | Duplicates rules (duplicates) | DuplicateRegistry | case types' attributes | nothing |
| 120 | Jobs (jobs) | JobRegistry | job beans | JobScheduleSync.sync(): group jcm matches the files; a run in progress finishes; other groups untouched |
| 200 | Job roles (job-roles) | JobRoleRegistry | resource and row-level roles | nothing; a removed job role drops to the default at the next request |
| 210 | Queues (queues) | QueueRegistry | the candidate's workflows; conditions in the database; set values in verify against the candidate's reference lists | nothing |
| 220 | Rules (rules) | RuleRegistry | the candidate's workflows and job roles | nothing |
| 230 | Task templates (tasks) | TaskTemplates | the candidate's workflows | nothing; tasks already made stay |
| 240 | Deadlines (deadlines) | DeadlinePolicies | the candidate's workflows | nothing |
| 250 | Seed (seed) | SeedRegistry | the candidate's workflows and job roles | nothing; seeding runs at startup only |
| 300 | Reference lists (refdata) | RefDataSeedLoader | stored parents | the changed lists and items, by hash, in one transaction |
| 310 | Letters (letters) | LetterSeedLoader | case types, placeholders | the changed templates, by hash, in one transaction |
| 320 | Dashboards (dashboards) | DashboardRegistry | the candidate's queues and deadline policies; roles | nothing |
| 330 | Questionnaires (questionnaires) | QuestionnaireRegistry | the candidate's reference lists, then the stored ones | nothing |
Case types (case-types) are read at startup only and are not reloaded: a publish there is staged (Staged editing,
below). Their form rules are still checked on every publish: FormRuleChecks is a ConfigCheck that parses the
candidate's layouts' rules against the candidate's workflows and job roles, so a publish that takes away a state,
transition or job role a rule names is refused with the layout's own <file>:<line> message (Configuration
generations).
Publish: the pipeline
Every save the studio makes goes through StudioPublisher (jcm_StudioPublisher): check(Change) runs
steps 1 to 3 and writes nothing; publish(Change) runs all six. Both run under one ReentrantLock per
application, so the candidate a publish checked is the one it swaps in, and two publishes never interleave. A
Change(files, summary, undoes) names one or more FileChange(relative, before, after, area): before the text
the form read (null: the file did not exist), after the new text (null: remove the file), area the editing
area the change belongs to. FileChange.of(relative, before, after) derives the area from the path (the first
segment; app for jcm.yml); a form that writes one kind's key of jcm.yml (inbox tabs, orders) builds
new FileChange("jcm.yml", before, after, "<kind folder>"), and such a change is accepted under that kind's
setting only when the two texts differ in no top-level key other than that kind's appWideKey (each key's value
compared as written, from where its node starts to where its last value ends: a change only to comments or to
whitespace outside the values counts as that kind's change); otherwise it needs app. For any other file the
area must be the path's own (its first segment), and a FileChange that says otherwise is refused with
IllegalArgumentException("<relative> is in the area <folder>, not <area>"), so no form can put a file past
another area's switch.
- Areas. No change may remove
jcm.yml, under any area:jcm.yml cannot be removed; edit it instead(an undo may still take away ajcm.ymlthe studio folder added where the application has none). Each file's area must be editable for the signed-in user (StudioEditing.of(area): the environment's reasons, then the role), its folder must have aConfigReloadableor be a staged area (StudioEditing.staging; elseEditing <label> is not possible at run time in this release: <label> are read at startup only. Edit the file and restart.), and there must be a publish target (Nothing can be published: jcm.studio.files is not set, so there is nowhere to write; set it to a writable folder.); a folder that cannot be read refusesNothing can be published: jcm.studio.files names <path>, which could not be read: <reason>. A folder no kind owns is not an area; it is left to the loader, which refuses it on the candidate with its own message (<file>: no installed component reads <root>nosuch/; ...). Ajcm.ymlchange labelled with an area no registry reloads (one the settings do not know, or a kind read at startup only) is put underappbefore anything else, since the loader readsjcm.ymlwhatever its label: the app-wide gate holds for it, and History and the notice readapp. - Stale forms. Each file's current text (the folder's copy, none when the folder holds its marker or when the
folder is the source (
jcm.studio.files-are-source) and lacks a file of its own, else what the application loaded) must equalbefore:<relative> changed since you opened it; reopen it and make the change again. - The candidate and the checks. The folder's contents (
target.contents()) with the change applied are read by the loader as the candidate,files.withRootBytes(target.root(), content), which runs every refusal the loader runs at startup; the files of a fixed kind the target stages (every fixed kind where the folder is the source, and a kind kept elsewhere,PublishTarget.elsewhere()) are taken out of that content and read first as the next build would copy them,files.asRebuilt(fixed)(Configuration layout), so a staged role or model file is checked, never refused as an override; thengeneration.prepareAll(candidate, every ConfigReloadable bean, every ConfigCheck bean)runs every registry's checks against it. AConfigException(every kind's exception is one) is the refusal as it is, with the file and line; any other exception isThe checks could not run: <message>, so a check that fails to run never lets a publish through. Once the candidate passes, everyConfigAdvicebean (jcm-core,notes(PreparedView candidate)) adds plain sentences to the result's notes: what publishing will do that the person should know, such as deadline actions a changed action definition cancels. Advice refuses nothing, and advice that cannot be given is left out. The version rule's refusal (WorkflowVersionRefusal) is worded for an undo when the change is one:Can't undo: removing Returned and Return from Appeal workflow version 1 would strand its 21 records; leave it, or remove it in a new version.(removing <state and transition names> from <workflow name> version <n>;changing ... (<reasons>) ... or make the change in a new version.when nothing is removed;removing <workflow name> version <n> would strand its <n> records; leave it.for a version dropped).checkreturnsChecked(notes)here. - Write.
target.write(writes): each changed file; a removal deletes the folder's own copy and, when a file of that path still counts in the candidate (the application's own), also writes the item's marker (<folder>/<code>.removed,<code>.v<n>.removedfor a version), read again by the loader before the checks so a marker's refusals are the loader's; a file written over its own marker takes the marker out. Two removals write no marker: one where the studio folder is the application's own source folder (jcm.studio.files-are-source, the dev profile), which deletes the file alone with the note<file> is deleted; the built copy counts until the next build; and aFileChange.dropCopy(relative, before, after, area)(dropsCopy), an undo taking out a copy the publish put where the folder held none, with the note<file>'s copy here is deleted; the application's own file counts again. A failure isNothing was published: <relative> could not be written: <reason>, with everything put back by the target. - Swap and commit.
generation.swap(candidate, states), then each kind'scommitin its reload order. When a commit throws, the files are put back from the contents read in step 3 (target.restore), the generation is swapped back (swapBack), and the previous state is committed again for the kinds the publish changed (a file's folder; for ajcm.ymlchange, the kinds whose key differs) that had committed: a kind the publish did not change committed the same entries by hash, so it is not committed again and an administrator's run-time edit to its rows stands. It is logged at ERROR,as.studio.last-publishfails, and the result isThe change was undone after a failure applying it: <message>. - Record. Every
PublishRecorderbean is told (record(publishId, change, generation, heldBefore), the last the paths the folder held before the write), inside the lock on the publishing thread, the required ones first (required(), true for History, below). When a required recorder throws, the publish is put back exactly as a step-5 commit failure is (files restored, generation swapped back, the changed kinds committed again),as.studio.last-publishfails, and the result isThe change was not published: History could not record it: <message>: a change History does not hold could not be audited or undone. Any other recorder that throws is logged at ERROR and the publish stands.ConfigGenerationChangedwas published by the swap.StudioReloadNotifieris the last recorder, not required: it tells open sessions (What open sessions see, below).
publish(change, guard) runs guard (a Supplier<Optional<String>>) first under the lock, before anything is
read or written, and refuses with its text when it gives one; undo passes History's refusals as the guard.
The result is a PublishResult: Published(publishId, generation, notes), Checked(notes) or
Refused(message, relative, line), where relative and line are read from a <file>:<line>: prefix when the
message names one of the change's files by its display under the folder (null otherwise), for the form to show the
refusal at the field. Notes say what a removal did: <file> is removed by the marker <marker>; the application's own copy remains or <file> is deleted. Every publish logs one INFO line naming the generation, the summary and
who published, as which job role. The console assertion as.studio.last-publish ("The last publish applied")
passes with No publish has failed while applying, or The last publish applied, and fails with The publish at <time> failed while applying: <message> from a step-5 failure until the next publish goes through.
What open sessions see
After a publish applied (committed and recorded; a refused or put-back publish tells no one),
StudioReloadNotifier (jcm_StudioReloadNotifier, a PublishRecorder) sends
ConfigurationChangedUiEvent(source, generation, folders, summary) (in jcm-core, com.jcm.core.config) through
UiEventPublisher.publishEventForUsers(event, null), which reaches every UI of every session on this server.
generation is the number the publish made current, folders the areas its files belong to, each once ("" for
jcm.yml as a whole), summary the publish's summary as History shows it. words() reads `Configuration changed:
- The inbox and the case screen show a notification (
ConfigurationChangedNotice, injcm-queues):NotificationidconfigurationChanged, bottom start (over the menu, clear of the header's controls and of a grid's pager), no auto-close (duration 0), theme variantinfo(one the Aura theme styles), the text (configurationChangedText), a "Reload" button (configurationChangedReload) and a "Dismiss" button (configurationChangedDismiss), both reached by Tab. Reload reloads the page at once, unless the screen shown holds unsaved changes (its view's data context has changes, as a case screen with edited fields does, or the viewHoldsUnsavedInputand says so, as a studio area with a draft does): then the dialogconfigurationChangedConfirmasks "You have unsaved changes on this screen. Reload anyway and lose them?" with "Keep editing" (configurationChangedKeep, focused; closes the dialog, keeps the input and the notice) and "Reload" (configurationChangedReloadAnyway). Nothing on the screen is drawn again: the inbox keeps its tabs, the queue it shows and its grid's columns, the case screen its record and any unsaved input, until the user reloads. There is one notice per browser tab (ConfigurationChangedNotice.of(UI)), whichever screen opened it: moving from the inbox to a case screen keeps it, and a further publish while it is open changes its text; it never stacks.InboxView.configurationNotice()andCaseScreenView.configurationNotice()return it while open. - Every studio area (
StudioAreaView) is drawn again in place, as the same view: the header's counts, then the area'srefresh()(abstract; each area implements it), which re-reads the current generation and keeps what the viewer chose. Workflows keeps the chosen workflow and version, the zoom, the marked transition, the record searched for and its path, and an open state's detail; Queues redraws its cards (an open preview stays open); Roles keeps the column group (by its name) and both checkboxes; Where used searches the new files for the code last searched, the field as typed; Files keeps the kind filter and the open file; History keeps the selected publish, or the file whose difference is shown, and an open Undo confirmation. When what was chosen is gone, the area says so instudioRefreshNote(role=status) as<name> was removed by a publish(Appeal workflow (wf.x) was removed by a publish,... version 2 ...,queues/q.a.yml ..., the group's name) and falls back to the first workflow or latest version, no open file, the first group. No route is navigated or refreshed. - An area holding a draft (an editor's unsaved input) returns true from
hasDraft(); it is then not drawn again, and the tab'sConfigurationChangedNoticeis shown instead, whose Reload asks first (StudioAreaViewimplementsHoldsUnsavedInputthroughhasDraft()). The editors hold one while their input is unpublished: the workflow editor's draft, the queue editor's (and a new queue's), an open job role or inbox tabs dialog with changes, and the text editor's changed text; once published, the form is drawn again from the new generation. The session that published receives the event too, after its own request. Nor is such an area left by the router without a question: a navigation item, the header's or where-used's links, a Diff link or the browser's Back stop atstudioDiscardConfirm(Discard your changes to <x>?,<x>the workflow, the queue by name and code, the file's path, the job role,the inbox tabs), wherestudioDiscardKeep(focused) cancels the navigation andstudioDiscardYesforgets the draft (discardDraft()) and lets it go on (Jmix'sBeforeCloseEventwith aNavigateCloseAction, theBeforeLeaveEventpostponed meanwhile); a second navigation while the question is open (Back, another click) asks nothing more: the one question stands and answers for the newest navigation (Vaadin keeps one postponed navigation per tab). - The studio's areas,
WhereUsedandRoleMatrixread the current generation's files (ConfigGeneration.files()) per use, never the startupConfigFilesbean, so none shows the files as they were before a publish; the case registry and layouts keep the startup bean (case types are read at startup only). - A publish whose every file is of a staged kind tells no session: nothing changed at run time. One that also
touches a kind applied at run time names those kinds alone (
StudioReloadNotifier). - Other screens are not told; they show the new configuration at their next navigation.
- A server push is needed for a session to be told without a click: the app class carries
@Push, as the scaffold writes it. Another server is not told; it reads the change at its next start.
How a form writes YAML
A form changes a file's text where the node it edits is written; the file is never written out again from what was
read, so every comment, the order of keys, blank lines and every line the change does not touch stay byte for byte,
with the file's line separator (\r\n or \n) and a leading byte order mark kept. YamlEdits (jcm-core, static)
does it from a node read from that same text (ConfigFile.ofText(...).root() and its find, sequence, items);
a node read from another text is refused, so read the text again after each change:
replaceItem(text, item, itemText): from where the item starts to where its last value ends; the dash before it and a comment after it stay.appendItem(text, sequence, itemText): a block list's new item on a line after the last item's last line, at the list's dash column; a flow list's after its last item as, item; an empty[]becomes[item]. A list not written yet isaddKey(text, mapping, key, "[" + item + "]").removeItem(text, item): a block item's lines, comments on them included; a flow item with its,. A list left empty is written[].setScalar(text, scalar, value): the value as text, quoted when it needs it (below); a block scalar's lines go.addKey(text, mapping, key, valueText)at the mapping's end (a block mapping's new line at its first key's column, a flow mapping's before}); a key already written is refused.removeKey(text, mapping, key)takes its lines, or its place in the line with its,; a mapping left empty is written{}.itemText(fields, indent)writes a new entry, keys in the order given: one flow mapping,{code: RETURNED, name: Returned}, whenindentplus its length is at most 118 characters (YamlEdits.LINE_LIMIT) and no value is a mapping; else a block mapping, its later lines atindent(the entry's first key's column: the list'sConfigNode.indent()plus 2). Lists of values are[A, B], mappings are block style, lists of mappings are block items written by the same rule; numbers and flags are bare.scalarText(value): bare when YAML reads it back as the same text, else double-quoted with\escapes: an empty value, one holding:,#,?or a flow indicator (, [ ] { }), one starting with a special character or a space, one with a line break, and one YAML would read as a number, flag, date or null (007,yes,~).
Every change is read again before it is returned; one that does not read is refused with the reader's message,
<file>:<line>: <problem>, as in workflows/wf.appeal.v1.yml:28: expected ',' or ']', but got : (while parsing a flow sequence at line 27). Whether the file still means a valid configuration is the registries' check at publish.
ConfigNode.span() (Span(startLine, startColumn, endLine, endColumn): lines from 1, columns from 0, the end
exclusive) says where a node is written, a block mapping or list ending at its last value, not at the next key;
ConfigNode.indent() is a block list's dash column or a mapping's first key's column.
Staged editing
A kind the application reads at startup only is edited in the studio as any other, and its publish is <em>staged</em>:
checked, written and recorded like every publish, applied at run time by nothing. StudioEditing.staging(area) says
which: RESTART for a registered folder no registry reloads (case-types), REBUILD for a kind fixed when the
application is built (model, roles, access, the shared and extension forms), each only when some ConfigCheck
names its folder in startupFolders() (CaseTypeFileCheck, ModelFileCheck, RoleFileCheck, AccessFileCheck,
SharedForms, ExtensionForms). A kind read at startup only that no check reads as the start does (audit, whose
AuditFileParser runs at startup alone) is never staged: its area is refused whatever its switch, Editing <label> is on (jcm.studio.edit.<area>), but <label> files are read at startup only and no check here reads them as the next start does, so a staged change could stop it. Edit the files in the source, rebuild and restart. Each staged kind
is an area under its own switch (jcm.studio.edit.case-types, .roles, .access, .model), with the folder, the
server count and the editor role as every area has; the text editor is the editor (the Case types area links each
card to its layout file in Files, and its intro says how the layout, the model and the roles are changed here).
-
Only on a developer's own machine.
jcm.studio.files-are-source=trueand the switch of a kind fixed when the application is built (jcm.studio.edit.roles,.model,.access, ...) stop startup unless thedevprofile or thelocal-previewprofile is active (StudioSettings.LOCAL_PROFILES):jcm.studio.files-are-source=true is refused: writing the application's own source folder is for a developer's own machine and needs the dev or local-preview profile active; the active profiles are <profiles>.(none is active), andjcm.studio.edit.<area>=true is refused: <label> files are fixed when the application is built, and staging them is for a developer's own machine; it needs the dev or local-preview profile active; ....local-previewis for a local preview run under a profile of its own (and for tests that stage a fixed kind); no environment shared by people sets either. Case types stage under any profile, in any writable studio folder. -
Where it lands. Case types, roles and
access.ymlunderjcm.studio.filesat their own paths; the model injcm.studio.model-files(model/<Entity>.ymlin the studio's paths,<Entity>.ymlon disk). Under the dev profile these are the project's own source files, so./gradlew bootRuncopies the case types, roles andaccess.ymlto the classpath andgenerateJcmModelreads the model, andgit diffshows the change. A fixed kind stages only wherejcm.studio.files-are-sourceis true (StudioEditingrefuses it elsewhere, with why: an override folder's copy of one is refused by the loader at the next start); a case type stages in any writable studio folder, where it is an override the next start reads and shows as "only here" or "changed here" to promote by Download. -
The checks. The startup readers run against the candidate as
ConfigCheckbeans (Configuration layout, "Configuration generations"), socheckandpublishrefuse what the next start refuses with the same file and line: a case type binding an unknown entity, a form naming a field the entity lacks, a rule naming a state the workflow lacks, a role granting an unknown entity or attribute, a model file the parser refuses, a model differencejcmChangelogrefuses. The candidate reads a fixed kind as the next build would copy it (ConfigFiles.asRebuilt, Publish: the pipeline, step 3). While the candidate's case types differ from the startup ones, every kind and check runs a second time against them (NextStart, Configuration generations): a staged case type that takes away a child type a rule, a queue or a letter names, or a case type a workflow binds, is refused with that file's own sentence followed byThe next start would refuse this: it reads the case types staged in the studio folder, which this server does not run yet. Change the file, or discard the staged case type in History.(StudioPublisher.NEXT_START; a refusal at a line of the change's own file is the startup reader's sentence alone), and a publish of a kind applied at run time is held against the running and the staged case types both. A case type binding an entity only the staged model declares is refused with the loader's ownrefers to unknown entityuntil the rebuild: stage the model, rebuild and restart, then the case type (the editor's intro says so for a model file). -
What is not checked, and recovery. The checks see the files, not the database or the code: records already stored on a case type, child type or state a staged change takes away, Java code naming them, a bean that keeps what it read from the case types in a field of its own, and, for a fixed kind, the build itself (the model is held against
schema.jsonand the running metamodel, not the classes the build makes). So a restart can still refuse a staged change, and then the application, and the studio with it, does not start. Every place a staged change is shown says so, and how to put the file back by hand (StagedChanges.recovery(pending)): in a source folder or the model's,restore <absolute path> from version control (git checkout -- <absolute path>) and start again, ordelete <absolute path> and start again.for a file the change added; in any other folder,delete <absolute path> and start again; the application's own file counts again.(delete the marker <path of the .removed marker> ...for a removal). With the application down, the folder is the record:git statusin the source, or the studio folder's files against the deployed ones. -
The result.
PublishedandCheckedcarry, in their notes, one sentence per staged area the change writes,StudioEditing.stagingWords(area):Changes to case types wait for a restart; this server keeps the case types it started with.(Changes to roles wait for a rebuild and a restart; ...), and for the modelModelFileCheck's advice (Configuration generations). Files saysStaged: <summary>. <notes> <limits>instudioFilesPublishedrather thanPublished: <summary>, where<limits>isStudioEditing.stagedLimits(area): for case typesIt was checked as the next start reads it, with the queues, workflows, letters and other kinds held against these case types; a restart can still refuse what no check here sees, such as records already stored or code that names a case type., for a fixed kindIt was checked by its own startup check; the build and the restart can still refuse it, since nothing here runs the build.The line is a status (jcm-studio-result): a clock icon and the warning tone for a staged save, a check icon and the ok tone for one applied at run time; its text is the words alone. The generation is swapped as for any publish, so the Files area and where-used show the staged text; the registries that read these kinds keep what they loaded at startup, and no session is told (What open sessions see). -
The pending state.
StagedChanges(jcm_StagedChanges, jcm-studio) reads it from the files, never from History, so it is right after a studio publish, a restart without a rebuild, or an edit made outside the studio: for each file of a staged kind this target stages (pending(), in path order, asPending(relative, area, label, code, kind, need, words, startupText, nextText)), the text the next start would read (the folder's copy, the model folder's file, else what the application loaded; a marker or, in a source folder, a missing file as none;StudioPublisher.currentText) against the text this server read at startup (the startupConfigFilesbean); one that differs is pending,CHANGED,ADDEDorREMOVED(kindWords():changed here,added here,removed here), with itsNeed:RESTART(a restart; the wordsrestart the application),REBUILD(a rebuild and a restart;rebuild and restart the application (./gradlew bootRun does both)),CHANGELOG(a changelog, a rebuild and a restart; the model whose tables change,ModelFileCheck.need(candidate, startup), with the wordsThe entity model change alters the tables (<summary>): run ./gradlew jcmChangelog, then rebuild and restart the application for it to count.) orREFUSED(the entity model files to be put right, then a changelog, a rebuild and a restart; a model the parser orjcmChangelogrefuses, which an outside edit can leave: a file the loader cannot read, one without itsentity:key, givesThe entity model files cannot be built as they are: <the loader's sentence>. Change the model files, then run ./gradlew jcmChangelog, rebuild and restart., never an exception, so the header and History keep drawing).of(relative),count()andheaderLine()(1 staged change waits for a restart,3 staged changes wait for a rebuild and a restart, the strongest need named; empty when none waits); a page that asks often takespending()once and passes it down (StagedChanges.in(pending, relative),StagedChanges.headerLine(pending)). The folder is read on everypending(), but what waits is worked out again (the model parsed, the schema diffed) only when the folder's contents changed since the last call. A fixed kind's file in a folder that is not the source is never pending: the loader refuses it at the next start. -
Where it shows. The header, on every area, has one status strip,
studioStatusStrip(role=group, namedStudio status), of chips (jcm-studio-chip, a pill with an icon, a count and a label, the tone tinted behind text mixed toward the text colour; a chip that links underlines its label on hover only):studioEditingOn(the accent tone,<n> areas with editing on,1 area with editing on; hidden above one server or with every area off),studioOverrideCount(neutral, linked to History,<n> files here differ from the deployed application), the status regionstudioStaged(role=status) holdingstudioStagedLink(the warning tone, a clock, theheaderLine()words, to History's "Waiting for a restart"), and whilejcm.ymlis read from the studio folderstudioAppWideShadow(warning) with the linkstudioAppWideDiff; the strip is hidden when it holds nothing. History: above "Differs here", the sectionstudioStagedSectionwithstudioStagedHeading"Waiting for a restart",studioStagedIntro(that each file was checked as the next start reads it, that a restart can still refuse what no check sees and then nothing starts, and that each row says how to put its file back) and the cardstudioStagedList(role=list), one rowstudioStaged-<n>(role=listitem) per pending file:studioStaged-<n>-words(<name> (<code>) — <path>: changed here; Restart the application., the name and path in bold),studioStaged-<n>-recover(If a restart refuses it, <recovery>), the need as a chipstudioStaged-<n>-need(Restart,Rebuild and restart,Changelog, rebuild, restart, orBuild refuses itin the danger tone), then at the right, in one small tertiary style,studioStaged-<n>-diff("Diff", a link to?staged=<path>,StudioLinks.stagedDiff, read asDiff of <path> against what the application started with) andstudioStaged-<n>-discard("Discard", namedDiscard the staged change to <path>; enabled where the user may edit the area, else disabled with the reason as tooltip andaria-description). Discard asks first, as Undo does: the dialogstudioDiscardStagedConfirm"Discard the staged change?" (studioDiscardStagedConfirmText:Discard the staged change to <path>? The text the application started with is written back; History records it, and Undo of that publish puts the staged text back.), Cancel (studioDiscardStagedConfirmNo, focused) and Discard (studioDiscardStagedConfirmYes, primary). In "Differs here" a file that also waits for a restart carries the chipAlso waiting for a restart, linked to the section.?staged=<path>showsstudioStagedDiffSummary(<path>: what the application started with, then what the next start reads. <words>;: added here; the application started without it;: removed here; the application started with it;<path> is not staged; this server runs with the file it started with) anddiff-0of the startup text against the next start's;?stagedalone opens History at the section (StudioLinks.staged()). A refusal of Discard shows beside the list asNot discarded: <message>(studioStagedRefusal,role=alert); a discard that applied saysDiscarded the staged change to <path>; the file reads as the application started with it.instudioHistoryPublished(role=status, the ok status) and lists History again. Files: the Difference column holds the chipStaged(warning tone, a clock) for a pending file, a link to its diff read as<path> is staged and waits for <need>; its difference against what the application started with; the open file's notestudioFileStaged(classjcm-studio-staged-note) readsStaged: this file is changed here and waits for a restart; this server runs with the text it started with. Restart the application. A restart can still refuse what no check here sees; if it does, <recovery>while it is pending, else the area'sstagingWords; hidden for a kind applied at run time. The text editor's intro, for a staged kind, readsSave runs the checks a publish runs; nothing is written unless they pass. This kind is read at startup only: a save is staged and waits for <waits for>; this server keeps what it started with., then for case typesThe save is checked as the next start reads it, the other kinds held against these case types; a restart can still refuse what no check here sees, such as records already stored.and for a fixed kindThe save is checked by this kind's own startup check; the build and the restart can still refuse it.(and, for a model file, the order with the case types that bind its entities); for any other kindSave runs every check the application runs at startup; nothing is written unless they pass.The Overview's Why column readsEditable here; changes wait for <waits for>. The Case types area's card addscaseTypeStaged-<id>:Staged: the layout file is changed here and waits for a restart; this server shows the case type it started with.while its layout file is pending. -
Discard.
StagedChanges.discard(relative)publishes the startup text back throughStudioPublisher, summaryDiscarded the staged change to <path>: an added file removed; a removed one written back (in a source folder or the model's; elsewhere the marker taken out); a changed one written back in a source folder or the model's, its copy taken out elsewhere (FileChange.dropCopy). History records it, Undo reverses it as any publish, and the checks may refuse it.Nothing is staged at <path>when nothing waits there. -
Not here. No reload of these kinds at run time, no propagation, no in-app restart, no discard while the application is down other than by hand (What is not checked, and recovery), and the application never runs
jcmChangelogor a build: the words say what to run.