A Command is a one-shot action (load file, show model, attach UI). Get it from any component with getCommand(MyCommand.class).run(), or trigger it indirectly with callCommand / linkCommand / waves. Pick the thread with @RunInto or base classes (DefaultUICommand = JAT, DefaultPoolCommand = JTP).
DefaultCommand, DefaultUICommand, or DefaultPoolCommand (or bean variants).initCommand() for setup and perform(Wave) for the action body.@RunInto(RunType.JAT|JIT|JTP) if you do not use a default base class.getCommand(MyCommand.class).run().linkCommand(node, eventType, MyCommand.class, waveData...).DefaultMultiBeanCommand and list sub-commands in defineSubCommand().A command is an atomic reusable action that could be triggered from anywhere. There are two kinds of Commands:
Single Commands are atomic and are run independently. If you trigger several commands in-a-row you will trigger them in parallel according to their predefined running thread. JRebirth engine will serialize their instantiation and their startup but they will be processed into JAT, JIT or one of JTP slots. JAT and JIT will process command one after the other. JTP will act in the same manner but internal engine will dispatch all actions to its pooled threads (by default {2 x Number of CPU core} slots are available by Thread Pool).
Minimal single command:
@RunInto(RunType.JIT)
public class LogActionCommand extends DefaultCommand {
@Override
protected void perform(final Wave wave) {
LOGGER.info("Action executed");
}
}
DefaultCommand — runs on JIT by default (via class annotation).perform(Wave) — only mandatory method; called once per run().getCommand(LogActionCommand.class).run() from any component.MultiCommand provides the ability to run some Single Commands sequentially (even across several threads) or in parallel.
Hereafter you will find an example of MultiCommand used to display a model UI:
package org.jrebirth.af.core.command.basic.showmodel;
import java.util.Arrays;
import java.util.List;
import org.jrebirth.af.api.command.Command;
import org.jrebirth.af.api.key.UniqueKey;
import org.jrebirth.af.core.command.multi.DefaultMultiBeanCommand;
/**
* The class <strong>ShowModelCommand</strong>.
*
* Run into JIT and is sequential
*
* @author Sébastien Bordes
*/
public class ShowModelCommand extends DefaultMultiBeanCommand<DisplayModelWaveBean> {
/**
* {@inheritDoc}
*/
@Override
protected List<UniqueKey<? extends Command>> defineSubCommand() {
return Arrays.asList(
getCommandKey(PrepareModelCommand.class),
getCommandKey(AttachModelCommand.class));
}
}
extends DefaultMultiBeanCommand<DisplayModelWaveBean> — multi-step command sharing one wave bean type.defineSubCommand() — ordered list of child commands; ShowModelCommand runs prepare then attach.getCommandKey(PrepareModelCommand.class) — resolves each sub-command's registration key from the facade.@RunInto / base-class thread (JTP for prepare, JAT for attach).The multi command code will be run into JIT, but its sub-command will be run respectively into JTP and JAT (according to their own configuration).
Why are they using these threads ?
ShowModelCommand use the annotation defined into DefaultMultiCommand to run into JIT.
PrepareModelCommand use the annotation defined into DefaultPoolCommand to run into JTP.
ShowModelCommand use the annotation defined into DefaultUICommand to run into JAT (it's mandatory to update scene's nodes within JAT).
Commands are designed to be disposable after usage, but they could be retained by strong references to be executed twice or more or store data. Each call will return a new instance of the command class, because each command was stored with a timestamp key-based. (Timestamp is added to the default key and also for custom key).
You can create a command using four different ways:
Please note that Commands are JRebirth top-level components (with Services and Models), they follow the component lifecycle as described in Facade Page.
Thus AbstractBaseCommand extends BehavioredComponent and Component and their descendants must provide initCommand(), processAction() and execute() methods.
It's possible to call a command from any JRebirth component (Command, Service, Model).
You just need to call the getCommand method to build an instance. You can provide either the Command Class or its unique key (if required).
<C extends Command> C getCommand(final Class<C> clazz, final Object... keyPart);
getCommand(Class, keyPart...) — retrieves or creates a command from CommandFacade.Once you have retrieved your command, you can store it with a strong reference to avoid GC collecting it. Your command life will depend on the lifetime of your strong reference. Thus you will be able to configure directly your command properties. Finally to trigger it you must call its run() method. The perform method of the command will be executed into the Thread Type chosen (JAT, JIT, JTP) by the Command declaration.
Minimal direct trigger from a Model:
@Override
protected void initModel() {
getCommand(OpenFileCommand.class).run();
}
getCommand(OpenFileCommand.class) — retrieves (or creates) the command instance from the CommandFacade..run() — schedules perform(Wave) on the thread declared for that command class. Wave run();
run() — returns the wave used for this execution (useful for chaining or debugging).Be careful: As explained here each call to getCommand could retrieve the same OR another instance of the command class depending on key parts provided and instance's strong references. (in this case no timestamp is added to the command key)
You can trigger a command execution by calling callCommand from any component, it will use JIT to trigger the command then the command will be run using the thread declared.
You can provide some parameters into WaveData that will be hold by the wave and so available into the command.
public final Wave callCommand(final Class<? extends CommandBean<? extends WaveBean>> commandClass, final WaveBean waveBean, final WaveBean... waveBeans) {
callCommand(Class, WaveBean, ...) — indirect trigger via JIT; command runs on its own thread.You can also provide a WaveBean object to store all data.
callCommand(ShowModelCommand.class, displayModelWaveBean);
callCommand — schedules command creation/run via JIT; command then runs on its own thread.WaveBean — typed bag of properties instead of raw WaveData varargs.UI's controllers provide a convenient method named void linkCommand(Node, EventType<E>, Class<? extends Command>, WaveData<?>…)
This method is useful to declare with only one line of code the call of a command triggered when the chosen JavaFX event occurred on a node belonging to the View.
It's also possible to add a callback function, in example to manage double-click detection (see LinkedCallback).
linkCommand(view().getOpenButton(), MouseEvent.MOUSE_CLICKED, OpenEventTrackerFileCommand.class, CHECK_MOUSE_SINGLE_CLICK);
view().getOpenButton() — JavaFX node in the View (Controller has view() accessor).MouseEvent.MOUSE_CLICKED — JavaFX event type that fires the command.OpenEventTrackerFileCommand.class — command class resolved from CommandFacade.CHECK_MOUSE_SINGLE_CLICK — optional WaveData / callback to filter events (e.g. ignore double-click).Any Command is a JRebirth component and can benefits of Observer features. It's possible to listen a WaveType (registration done into the initModel, initService and initCommand methods, or using @OnWave) in order to be notified when a such wave is sent. You can manage custom methods called by reflection to handle waves and can you catch all waves into the processAction(Wave) method.
More information is available in Notifier & Component page.
Be careful, commands can handle asynchronous wave only if they haven't been collected by the Garbage Collector! So you need to create a instance and to keep a strong references on it somewhere.
@Override
protected void initCommand() {
listen(MyWaves.DO_SAVE);
// keep this command instance alive while listening
}
@Override
protected void perform(final Wave wave) {
// default path when no doXxx handler matches
}
listen(...) in initCommand() — command reacts to waves while the instance is retained.getCommand(...) stored in a Model field) or the listener is GC'd.perform(Wave) — fallback when wave handling is not delegated to a doXxx method.A command is an atomic action reusable or not that can be run into a predefined thread. A command provides specific features:
Each command will be launch by JRebirth Internal engine and run into a dedicated thread. Threads involved in a JRebirth application are explained into the Thread page.
The runner thread can be configured using two ways:
The priority rule is : Annotation > Constructor argument > Default value. The default value is : JIT (JRebirth Internal Thread). The top-level annotation will be systematically used overriding lower ones and also constructor arguments.
To run a command into the JAT (JavaFX Application Thread), use this annotation :
@RunInto(RunType.JAT)
RunType.JAT — JavaFX Application Thread; required for direct scene/node updates.RunType.JIT — JRebirth Internal Thread; messaging-safe, not for UI nodes in scene.RunType.JTP — thread pool slot; long I/O or CPU work off UI and JIT.To run a command into the JIT (JRebirth Internal Thread), use this annotation :
@RunInto(RunType.JIT)
To run a command into JTP (JRebirth Thread Pool, the command will be run into a slot), use this annotation :
@RunInto(RunType.JTP)
To run a command into the JAT (JavaFX Application Thread), extends the DefaultUICommand class :
public class AttachModelCommand extends DefaultUIBeanCommand<DisplayModelWaveBean> {
DefaultUICommand / DefaultUIBeanCommand — @RunInto(JAT) baked in for scene updates.To run a command into the JIT (JRebirth Internal Thread), extends the DefaultCommand class :
public class ChainWaveCommand extends DefaultCommand implements WaveListener {
DefaultCommand — runs on JIT; base for messaging-safe atomic commands.WaveListener — optional; receive all waves in processWave in addition to doXxx handlers.To run a command into JTP (JRebirth Thread Pool, the command will be run into a slot), extends the DefaultPoolCommand class :
public class PrepareModelCommand extends DefaultPoolBeanCommand<DisplayModelWaveBean> {
DefaultPoolCommand / DefaultPoolBeanCommand — runs on JTP for I/O or CPU-heavy work.It's also possible to define the runType (The thread which will handle the command) by passing RunType, each descendant classes of AbstractBaseCommand offer at least one constructor allowing this enum value to the command constructor.
public AbstractBaseCommand(final RunType runType, final PriorityLevel priority) {
RunType — alternative to @RunInto when subclassing AbstractBaseCommand directly.The component key as described in the Facade page allow storing unique commands.
All objects provided as key part will be serialized (toString call) to build the key. Warning : When a command is built consequently to a wave reception, the wave UID will be concatenated to the class name instead of using key parts.
Command are run in a custom thread in 3 steps:
Only the perform method must be implemented to execute your action.
Minimal custom command:
@RunInto(RunType.JTP)
public class LoadDataCommand extends DefaultCommand {
@Override
protected void initCommand() { /* optional setup */ }
@Override
protected void perform(final Wave wave) {
// long work on JTP — send result via sendWave when done
}
}
@RunInto(JTP) — runs perform on a thread-pool slot, not on the JavaFX thread.initCommand() — called once when the command instance is prepared (register waves here if needed).perform(Wave) — your action; may read wave data or an attached WaveBean.A WaveBean is a Java Bean that allow carrying a lot of named properties into a Wave.
Command Classes can declare a generic type that allow to cast the Wave Bean into the right one, it allows to use getWaveBean().getMyProperty() into source code which is more convenient than parsing WaveData (but it implies to create a dedicated Java Class).
public class OpenFileCommand extends DefaultPoolBeanCommand<OpenFileWaveBean> {
@Override
protected void perform(final Wave wave) {
final File file = getWaveBean().getFile();
// ...
}
}
public class OpenFileWaveBean implements WaveBean {
private File file;
public File getFile() { return file; }
public void setFile(final File file) { this.file = file; }
}
DefaultPoolBeanCommand<OpenFileWaveBean> — generic binds the bean type for typed access.getWaveBean() — cast-free access inside perform; populated by callCommand or linkCommand.Each command is a simple Java Object, you can add fields or JavaFX Properties to help configuring your execution code. You must pay attention that these values will be kept until the command is disposed (after execution if no strong references exists).
For example you can attach a command to a Model and launch it several times while updating command's properties.
private final SaveCommand saveCommand = getCommand(SaveCommand.class);
void saveDraft() {
saveCommand.setDraft(true);
saveCommand.run();
}
void saveFinal() {
saveCommand.setDraft(false);
saveCommand.run();
}
getCommand(...) in a field — strong reference keeps the instance and its custom properties.run() for reusable commands.JRebirth provides several ready-to-use commands:
| Command | Purpose | Thread |
|---|---|---|
ShowModelCommand |
Display a model's view (prepare + attach) | JIT → JTP → JAT |
ShowFadingModelCommand |
Show with fade transition | JIT → JTP → JAT |
FadeInOutCommand |
Fade a node in or out | JAT |
ChainWaveCommand |
Execute a list of waves sequentially | JIT |
AttachModelCommand |
Attach a model's node to a parent | JAT |
DetachModelCommand |
Remove a model's node from parent | JAT |
PrepareModelCommand |
Build model's view off-screen | JTP |