Designing Objects in JavaFX
In this pack: sizing and rule strictness are set by the core
plugin's oo-design skill; each rule here keeps a core rule in this
language.
Overview
JavaFX adds three things to oo-java that change how a clinic's rules
are kept: properties a control can observe and bind, a view model a
toolkit can drive, and a Task that runs work on a background thread.
This skill covers only those changes; load oo-java too, because its
rules for records, refusals and final classes still hold. Each change
brings a shortcut that looks harmless: a control bound straight to a
domain object, a writable property handed to a view, and a Task that
writes the screen from its own thread. The rules below close those
shortcuts with a view model whose properties are shaped for the screen,
a domain value no control binds to, a read-only property for state the
view only shows, a handler that hands on intent, and one composition
root in the Application subclass.
When to use
- A
CheckBox, aTextFieldor another control is bound to a domain object's property. - A domain class carries a JavaFX property, such as a
BooleanProperty, or imports a JavaFX property type. - Screen state or screen logic lives in the view, or a test needs a
Stageto reach it. - A
Taskor another background thread writes a control, or a property a control shows. - A handler decides a clinic rule, reaches a store, or constructs a domain object.
- A window creates its own store or view model with
new. - You are choosing where a view model's properties live, or whether a control may bind to a domain object.
When not to use
- There is no user interface, so
oo-javaalone answers the question. - The application is built with Swing:
oo-java-swingcovers it. - No JavaFX feature bears on the question, such as where a rule
belongs; start with the core skills, at
oo-design.
Core rules
Rule. Keep every change to a showing scene on the JavaFX Application Thread: a slow use case runs in a
Task'scall, which touches no node and no property a node is bound to, and its result reaches the scene from anonSucceededhandler or aPlatform.runLatercall. A node may be built and changed on any thread until it is attached to a scene in a window that is showing; from then on, a change to it, or to a property a control is bound to, belongs on the JavaFX Application Thread. ATask'scallruns on a background thread and returns a result; it does not write the screen. This keepsoo-separating-presentation-from-domainrule 6 andoo-managing-shared-staterules 2 and 3.Default. Give each screen a view model whose JavaFX properties hold the screen's state in the shape the screen needs; it imports nothing from
javafx.scene, so a test drives it with no stage, and the view binds its controls to those properties. This settlesoo-separating-presentation-from-domainrule 3 for JavaFX, which binds: the view sets no state of its own, and a test builds the view model with a plain background seam and never builds aStage. This keepsoo-separating-presentation-from-domainrules 2 and 3 andoo-designing-for-testabilityrule 1.The exception is a screen with no decision to make, such as a line of fixed text: it needs no view model.
Rule. Bind a control only to a view model's property, never to a domain object's property, and leave a domain class with no JavaFX property: when the user acts, the view model builds the domain value from what the user entered, and the domain object refuses what its rules forbid. A two-way binding between a control and a domain property writes the domain object as the user ticks, before any rule checks the value, and leaves a half-entered object that the store may save. The view model holds plain properties, turns them into a domain value in its save action, and lets that value's constructor refuse a forbidden combination. This keeps
oo-separating-presentation-from-domainrule 5,oo-encapsulating-state-and-behaviourrules 1 and 2, andoo-working-within-a-frameworkrule 1.Rule. Give the view a read-only property for every state it must not change, from a
ReadOnly...Wrapperthe view model keeps for itself; hand out a writable property only where a control writes what the user enters. A wrapper makes two synchronized properties: the read-only one is the one a view may keep, and the writable one stays inside the view model. The notice a view shows is read-only; the tick boxes the user sets are writable because a control writes them. This keepsoo-separating-presentation-from-domainrule 4 andoo-encapsulating-state-and-behaviourrule 5.Rule. Let a control's handler do no more than pass the user's intent to the view model; the view model asks a use case, and no handler calls a store or decides a clinic rule. A handler that checks a rule or calls a store keeps its own copy of a decision the domain owns, and only a test that starts the toolkit can reach that copy. The button's handler calls one method on the view model; the view model builds the domain value and asks the use case. This keeps
oo-separating-presentation-from-domainrules 1 and 4.Rule. Build the view models, use cases and stores in one composition root that
Application.startreaches, and pass every collaborator through a constructor; theApplicationsubclass JavaFX requires is an edge class that holds no clinic rule. JavaFX constructs theApplicationsubclass and callsstarton the JavaFX Application Thread, sostartis where the object graph is built, before the stage shows. Each collaborator arrives through a constructor, and the subclass only creates the objects and sets the scene. This keepsoo-inverting-dependenciesrules 2 and 3 andoo-working-within-a-frameworkrule 2.
Pattern
AccessNeedsForm is the desk's form for a patient's access needs:
three tick boxes record whether the patient needs step-free access, a
hearing loop or a canine, and a Save button records them. The
third tick box is labelled Canine and records the canine. The clinic's
rule is that a canine needs step-free access, because the room that
takes one is reached by the step-free route. The form shows what the
desk ticked and hands the save to a view model; the view model builds
the patient's access needs and asks a use case.
Before:
import javafx.beans.property.BooleanProperty;
import javafx.beans.property.SimpleBooleanProperty;
public final class PatientAccessNeeds {
private final BooleanProperty stepFree = new SimpleBooleanProperty();
private final BooleanProperty hearingLoop = new SimpleBooleanProperty();
private final BooleanProperty canine =
new SimpleBooleanProperty();
public BooleanProperty stepFreeProperty() {
return stepFree;
}
public BooleanProperty hearingLoopProperty() {
return hearingLoop;
}
public BooleanProperty canineProperty() {
return canine;
}
}
PatientAccessNeeds is the domain class in the Before: three JavaFX
properties and no rule. AccessNeedsForm binds each CheckBox's
selectedProperty to one of those properties with bindBidirectional,
so a tick writes the domain object, and its Save handler calls
AccessNeedsStore.save with that object.
import javafx.scene.Parent;
import javafx.scene.control.Button;
import javafx.scene.control.CheckBox;
import javafx.scene.layout.VBox;
public final class AccessNeedsForm {
private final CheckBox stepFree = new CheckBox("Step-free access");
private final CheckBox hearingLoop = new CheckBox("Hearing loop");
private final CheckBox canine = new CheckBox("Canine");
private final Button save = new Button("Save");
private final VBox root =
new VBox(8, stepFree, hearingLoop, canine, save);
private final PatientAccessNeeds needs;
private final AccessNeedsStore store;
public AccessNeedsForm(
PatientAccessNeeds needs, AccessNeedsStore store) {
this.needs = needs;
this.store = store;
stepFree.selectedProperty()
.bindBidirectional(needs.stepFreeProperty());
hearingLoop.selectedProperty()
.bindBidirectional(needs.hearingLoopProperty());
canine.selectedProperty()
.bindBidirectional(needs.canineProperty());
save.setOnAction(event -> store.save("p-204", needs));
}
public Parent root() {
return root;
}
}
AccessNeedsStore is the port the form calls; its adapter is outside
this fence.
public interface AccessNeedsStore {
PatientAccessNeeds save(String patientId, PatientAccessNeeds needs);
}
In the Before, PatientAccessNeeds carries JavaFX properties and no
rule, so a tick can record a canine without step-free access
(rule 3). The two-way bindings write the domain object as the user
ticks, before any rule checks it (rule 3), and the Save handler calls
the store itself (rule 5). No view model holds the screen's state
(rule 2). The fences store nothing themselves: they change the domain
object the form was given. They leave out what the store does with the
object, its transaction and its version, and they need no current time.
After:
PatientAccessNeeds is now a value with no JavaFX property: its compact
constructor refuses a canine without step-free access.
public record PatientAccessNeeds(
boolean stepFree, boolean hearingLoop, boolean canine) {
public PatientAccessNeeds {
if (canine && !stepFree) {
throw new IllegalArgumentException(
"a canine needs step-free access");
}
}
}
RecordAccessNeeds is the use case the view model asks; it calls the
same AccessNeedsStore port and answers the access needs the store
recorded.
public final class RecordAccessNeeds {
private final AccessNeedsStore store;
public RecordAccessNeeds(AccessNeedsStore store) {
this.store = store;
}
public PatientAccessNeeds record(
String patientId, PatientAccessNeeds needs) {
return store.save(patientId, needs);
}
}
OffThreadWork is the seam between the view model and the thread; a
test implements it synchronously, so the view model needs no stage.
import java.util.concurrent.Callable;
import java.util.function.Consumer;
public interface OffThreadWork {
<T> void run(Callable<T> work, Consumer<T> done,
Consumer<Throwable> failed);
}
AccessNeedsViewModel holds the screen's state. The three entry
properties are writable because the form's controls write them, and the
notice is a ReadOnlyStringWrapper the view model keeps for itself.
import javafx.beans.property.BooleanProperty;
import javafx.beans.property.ReadOnlyStringProperty;
import javafx.beans.property.ReadOnlyStringWrapper;
import javafx.beans.property.SimpleBooleanProperty;
public final class AccessNeedsViewModel {
private final String patientId;
private final RecordAccessNeeds recorder;
private final OffThreadWork offThread;
private final BooleanProperty stepFree = new SimpleBooleanProperty();
private final BooleanProperty hearingLoop = new SimpleBooleanProperty();
private final BooleanProperty canine =
new SimpleBooleanProperty();
private final ReadOnlyStringWrapper notice =
new ReadOnlyStringWrapper("");
public AccessNeedsViewModel(String patientId, RecordAccessNeeds recorder,
OffThreadWork offThread) {
this.patientId = patientId;
this.recorder = recorder;
this.offThread = offThread;
}
public BooleanProperty stepFreeProperty() {
return stepFree;
}
public BooleanProperty hearingLoopProperty() {
return hearingLoop;
}
public BooleanProperty canineProperty() {
return canine;
}
public ReadOnlyStringProperty noticeProperty() {
return notice.getReadOnlyProperty();
}
public void save() {
PatientAccessNeeds needs;
try {
needs = new PatientAccessNeeds(
stepFree.get(), hearingLoop.get(), canine.get());
} catch (IllegalArgumentException refused) {
notice.set(refused.getMessage());
return;
}
notice.set("Saving");
offThread.run(
() -> recorder.record(patientId, needs),
saved -> notice.set("Saved"),
failure -> notice.set(messageOf(failure)));
}
private String messageOf(Throwable failure) {
String message = failure.getMessage();
return message == null
? "the access needs could not be saved"
: message;
}
}
AccessNeedsForm receives the view model through its constructor and
binds to it there: each CheckBox writes its writable property, the
label reads the read-only notice, and the handler calls only save.
import javafx.scene.Parent;
import javafx.scene.control.Button;
import javafx.scene.control.CheckBox;
import javafx.scene.control.Label;
import javafx.scene.layout.VBox;
public final class AccessNeedsForm {
private final CheckBox stepFree = new CheckBox("Step-free access");
private final CheckBox hearingLoop = new CheckBox("Hearing loop");
private final CheckBox canine = new CheckBox("Canine");
private final Label notice = new Label();
private final Button save = new Button("Save");
private final VBox root =
new VBox(8, stepFree, hearingLoop, canine, save, notice);
public AccessNeedsForm(AccessNeedsViewModel viewModel) {
stepFree.selectedProperty()
.bindBidirectional(viewModel.stepFreeProperty());
hearingLoop.selectedProperty()
.bindBidirectional(viewModel.hearingLoopProperty());
canine.selectedProperty()
.bindBidirectional(viewModel.canineProperty());
notice.textProperty().bind(viewModel.noticeProperty());
save.setOnAction(event -> viewModel.save());
}
public Parent root() {
return root;
}
}
In the After, AccessNeedsViewModel holds the screen's state and its
logic, and it imports no javafx.scene type, so a test builds it with a
synchronous OffThreadWork and no Stage (rule 2). The form binds each
CheckBox to a writable property of the view model and the label to its
read-only notice, and its handler only calls viewModel.save() (rules
3, 4 and 5). PatientAccessNeeds has no JavaFX property: it is built
only when the user saves, and its constructor refuses a canine
without step-free access (rule 3). The form receives the view model
through its constructor and binds to it there; the view model never
holds the form. The composition root that builds the store, the use
case, the view model, the thread seam and the form in Application.start
is in the thread reference.
A save gives RecordAccessNeeds the patient's id and the new
PatientAccessNeeds; the store keeps one row per patient id, inside one
transaction. A second save for the same patient at the same moment is
refused by the store's key on the patient id, which the fence leaves
out. The fences leave the store, its transaction and its version out,
and no fence needs the current time.
Red flags
Places to look, not verdicts. A red flag becomes a finding only with evidence: a measurement, a reproducible bug, or a failing test.
- A control bound to a property of a domain object, such as
CheckBox.selectedProperty()bound to a domainBooleanProperty. - A domain class that imports
javafx.beans.property,javafx.beans.valueorjavafx.scene. - A
Task'scallthat writes aLabelor a property a control is bound to. - A handler that decides a clinic rule, reaches a store, or constructs a domain object.
- A view that creates its view model with
new. - A
Taskkept in a field and started a second time. - A
ReadOnlyStringWrapperhanded to a view instead of its read-only property. - Screen logic that a test can reach only through
Platform.startupor aStage.
Common mistakes
- Binding a control to a domain object's property because the form already holds the object.
- Calling
viewModel.save()from aTask'scall, so the task writes the notice. - Building the
SceneinApplication.init, which runs on the launcher thread, instead of instart. - Reusing a
Taskfor the next save after it has finished. - Adding a setter to the domain value so the form can write a tick back into it.
- Catching a domain refusal in the button's handler and showing its message there, instead of letting the view model answer.
- Putting a
Stageor aScenein the view model, so the view model importsjavafx.scene.
Related skills
oo-javasupplies the Java language rules this skill builds on.oo-java-swingcovers a Swing application: the event dispatch thread, and domain objects behind a table.oo-separating-presentation-from-domainweighs what a view knows and keeps clinic rules behind a use case.oo-designing-for-testabilitymakes a screen's logic reachable with plain objects and no toolkit.oo-encapsulating-state-and-behaviourkeeps a value's rules inside its own methods.oo-inverting-dependencieschooses how collaborators arrive and where the object graph is built.oo-managing-shared-stategives changing state one owner and moves only complete values between threads.oo-working-within-a-frameworkjudges how much of a framework's shape to follow.
Further reading
- Tasks and the thread