8. Components
Components are a set of features which are either build-in or something you can re-use or extend for your own needs. Components in question are either built-in commands or UI side components providing higher level features within commands itself.
8.1. Built-In Commands
8.1.1. Help
Running a shell application often implies that the user is in a graphically limited
environment. Also, while we are nearly always connected in the era of mobile phones,
accessing a web browser or any other rich UI application (such as a PDF viewer) may not always
be possible. This is why it is important that the shell commands are correctly self-documented, and this is where the help
command comes in.
Typing help + ENTER lists all the commands known to the shell (including unavailable commands)
and a short description of what they do, similar to the following:
my-shell:>help
AVAILABLE COMMANDS
Built-In Commands
exit: Exit the shell.
help: Display help about available commands
stacktrace: Display the full stacktrace of the last error.
clear: Clear the shell screen.
quit: Exit the shell.
history: Display or save the history of previously run commands
completion bash: Generate bash completion script
version: Show version info
script: Read and execute commands from a file.Typing help <command> shows more detailed information about a command, including the available parameters, their
type, whether they are mandatory or not, and other details.
The following listing shows the help command applied to itself:
my-shell:>help help
NAME
help - Display help about available commands
SYNOPSIS
help --command String
OPTIONS
--command or -C String
The command to obtain help for.
[Optional]Help is templated and can be customized if needed. Settings are under spring.shell.command.help where you can use
enabled to disable command, grouping-mode taking group or flat if you want to hide groups by flattening
a structure, command-template to define your template for output of a command help, commands-template to define
output of a command list.
If spring.shell.command.help.grouping-mode=flat is set, then help would show:
my-shell:>help help
AVAILABLE COMMANDS
exit: Exit the shell.
help: Display help about available commands
stacktrace: Display the full stacktrace of the last error.
clear: Clear the shell screen.
quit: Exit the shell.
history: Display or save the history of previously run commands
completion bash: Generate bash completion script
version: Show version info
script: Read and execute commands from a file.Output from help and help <commmand> are both templated with a default implementation
which can be changed.
Option spring.shell.command.help.commands-template defaults to
classpath:template/help-commands-default.stg and is passed GroupsInfoModel
as a model.
Option spring.shell.command.help.command-template defaults to
classpath:template/help-command-default.stg and is passed CommandInfoModel
as a model.
| Key | Description |
|---|---|
|
|
|
The commands variables (see GroupCommandInfoModel Variables). |
|
The commands variables (see CommandInfoModel Variables). |
|
|
| Key | Description |
|---|---|
|
The name of a group, if set. Otherwise, empty. |
|
The commands, if set. Otherwise, empty. Type is a multi value, see CommandInfoModel Variables. |
| Key | Description |
|---|---|
|
The name of a command, if set. Otherwise, null. Type is string and contains full command. |
|
The names of a command, if set. Otherwise, null. Type is multi value essentially |
|
The possible aliases, if set. Type is multi value with strings. |
|
The description of a command, if set. Otherwise, null. |
|
The parameters variables, if set. Otherwise empty. Type is a multi value, see CommandParameterInfoModel Variables. |
|
The availability variables (see CommandAvailabilityInfoModel Variables). |
| Key | Description |
|---|---|
|
The type of a parameter if set. Otherwise, null. |
|
The arguments, if set. Otherwise, null. Type is multi value with strings. |
|
|
|
The description of a parameter, if set. Otherwise, null. |
|
The default value of a parameter, if set. Otherwise, null. |
|
|
| Key | Description |
|---|---|
|
|
|
The reason if not available if set. Otherwise, null. |
8.1.2. Clear
The clear command does what you would expect and clears the screen, resetting the prompt
in the top left corner.
8.1.3. Exit
The quit command (also aliased as exit) requests the shell to quit, gracefully
closing the Spring application context. If not overridden, a JLine History bean writes a history of all
commands to disk, so that they are available again on the next launch.
8.1.4. Stacktrace
When an exception occurs inside command code, it is caught by the shell and a simple, one-line message is displayed so as not to overflow the user with too much information. There are cases, though, when understanding what exactly happened is important (especially if the exception has a nested cause).
To this end, Spring Shell remembers the last exception that occurred, and the user can later use the stacktrace
command to print all the details on the console.
8.1.5. Script
The script command accepts a local file as an argument and replays commands found there, one at a time.
Reading from the file behaves exactly like inside the interactive shell, so lines starting with // are considered
to be comments and are ignored, while lines ending with \ trigger line continuation.
8.1.6. History
The history command shows the history of commands that has been executed.
There are a few configuration options that you can use to configure behavior
of a history. History is kept in a log file, which is enabled by default and can
be turned off by setting spring.shell.history.enabled. The name of a log file
is resolved from spring.application.name and defaults to spring-shell.log,
which you can change by setting spring.shell.history.name.
By default, a log file is generated to a current working directory, which you can dictate
by setting spring.shell.config.location. This property can contain
a placeholder ({userconfig}), which resolves to a common shared config directory.
| Run the Spring Shell application to see how the sample application works as it uses these options. |
8.1.7. Completion
The completion command set lets you create script files that can be used
with am OS shell implementations to provide completion. This is very useful when
working with non-interactive mode.
Currently, the only implementation is for bash, which works with bash sub-command.
8.1.8. Version
The version command shows existing build and git info by integrating into
Boot’s BuildProperties and GitProperties if those exist in the shell application.
By default, only version information is shown, and you can enable other information through configuration
options.
The relevant settings are under spring.shell.command.version, where you can use enabled to
disable a command and, optionally, define your own template with template. You can use the
show-build-artifact, show-build-group, show-build-name, show-build-time,
show-build-version, show-git-branch, show-git-commit-id,
show-git-short-commit-id and show-git-commit-time commands to control
fields in a default template.
The template defaults to classpath:template/version-default.st, and you can define
your own, as the following example shows:
<buildVersion>This setting would output something like the following:
X.X.XYou can add the following attributes to the default template rendering: buildVersion, buildGroup,
buildGroup, buildName, buildTime, gitShortCommitId, gitCommitId,
gitBranch, and gitCommitTime.
8.2. Flow
When you use Flow Components to build something that involves
use of a multiple components, your implementation may become a bit cluttered.
To ease these use cases, we added a
ComponentFlow that can hook multiple component executions together
as a “flow”.
The following listings show examples of flows and their output in a shell:
static class FlowSampleComplex {
@Autowired
private ComponentFlow.Builder componentFlowBuilder;
public void runFlow() {
Map<String, String> single1SelectItems = new HashMap<>();
single1SelectItems.put("key1", "value1");
single1SelectItems.put("key2", "value2");
List<SelectItem> multi1SelectItems = Arrays.asList(SelectItem.of("key1", "value1"),
SelectItem.of("key2", "value2"), SelectItem.of("key3", "value3"));
ComponentFlow flow = componentFlowBuilder.clone().reset()
.withStringInput("field1")
.name("Field1")
.defaultValue("defaultField1Value")
.and()
.withStringInput("field2")
.name("Field2")
.and()
.withConfirmationInput("confirmation1")
.name("Confirmation1")
.and()
.withPathInput("path1")
.name("Path1")
.and()
.withSingleItemSelector("single1")
.name("Single1")
.selectItems(single1SelectItems)
.and()
.withMultiItemSelector("multi1")
.name("Multi1")
.selectItems(multi1SelectItems)
.and()
.build();
flow.run();
}
}
Normal execution order of a components is same as defined with a builder. It’s
possible to conditionally choose where to jump in a flow by using a next
function and returning target component id. If this returned id is aither null
or doesn’t exist flow is essentially stopped right there.
static class FlowSampleConditional {
@Autowired
private ComponentFlow.Builder componentFlowBuilder;
public void runFlow() {
Map<String, String> single1SelectItems = new HashMap<>();
single1SelectItems.put("Field1", "field1");
single1SelectItems.put("Field2", "field2");
ComponentFlow flow = componentFlowBuilder.clone().reset()
.withSingleItemSelector("single1")
.name("Single1")
.selectItems(single1SelectItems)
.next(ctx -> ctx.getResultItem().get().getItem())
.and()
.withStringInput("field1")
.name("Field1")
.defaultValue("defaultField1Value")
.next(ctx -> null)
.and()
.withStringInput("field2")
.name("Field2")
.defaultValue("defaultField2Value")
.next(ctx -> null)
.and()
.build();
flow.run();
}
}
The result from running a flow returns ComponentFlowResult, which you can
use to do further actions.
|
8.3. Flow Components
Starting from version 2.1.x, a new component model provides an easier way to create higher-level user interaction for the usual use cases, such as asking for input in various forms. These usually are just plain text input or choosing something from a list.
Templates for built-in components are in the
org/springframework/shell/component classpath.
Built-in components generally follow this logic:
-
Enter a run loop for user input.
-
Generate component-related context.
-
Render the runtime status of a component state.
-
Exit.
-
Render the final status of a component state.
| Flow gives better interface for defining the flow of components that are better suited for defining interactive command flows. |
8.3.1. Component Render
You can implement component rendering in either of two ways: fully
programmatically or by using a ANTLR Stringtemplate.
Strictly speaking, there is a simple Function renderer interface
that takes Context as an input and outputs a list of AttributedString.
This lets you choose between templating and code.
Templating is a good choice if you do not need to do anything complex or you just want to slightly modify existing component layouts. Rendering through code then gives you flexibility to do whatever you need.
The programmatic way to render is to create a Function:
class StringInputCustomRenderer implements Function<StringInputContext, List<AttributedString>> {
@Override
public List<AttributedString> apply(StringInputContext context) {
AttributedStringBuilder builder = new AttributedStringBuilder();
builder.append(context.getName());
builder.append(" ");
if (context.getResultValue() != null) {
builder.append(context.getResultValue());
}
else {
String input = context.getInput();
if (StringUtils.hasText(input)) {
builder.append(input);
}
else {
builder.append("[Default " + context.getDefaultValue() + "]");
}
}
return Arrays.asList(builder.toAttributedString());
}
}
Then you can hook it to a component:
@ShellMethod(key = "component stringcustom", value = "String input", group = "Components")
public String stringInputCustom(boolean mask) {
StringInput component = new StringInput(getTerminal(), "Enter value", "myvalue",
new StringInputCustomRenderer());
component.setResourceLoader(getResourceLoader());
component.setTemplateExecutor(getTemplateExecutor());
if (mask) {
component.setMaskCharacter('*');
}
StringInputContext context = component.run(StringInputContext.empty());
return "Got value " + context.getResultValue();
}
Components have their own context but usually share some functionality from a parent component types. The following tables show those context variables:
| Key | Description |
|---|---|
|
The value after a component renders its result. |
|
The name of a component — that is, its title. |
|
The possible message set for a component. |
|
The level of a message — one of |
|
Return |
|
Return |
|
Return |
|
The raw user input. |
| Key | Description |
|---|---|
|
The name of a component — that is, its title. |
|
The raw user input — mostly used for filtering. |
|
The full list of item states. |
|
The visible list of item states. |
|
Return |
|
The current cursor row in a selector. |
8.3.2. String Input
The string input component asks a user for simple text input, optionally masking values if the content contains something sensitive. The following listing shows an example:
@ShellComponent
public class ComponentCommands extends AbstractShellComponent {
@ShellMethod(key = "component string", value = "String input", group = "Components")
public String stringInput(boolean mask) {
StringInput component = new StringInput(getTerminal(), "Enter value", "myvalue");
component.setResourceLoader(getResourceLoader());
component.setTemplateExecutor(getTemplateExecutor());
if (mask) {
component.setMaskCharacter('*');
}
StringInputContext context = component.run(StringInputContext.empty());
return "Got value " + context.getResultValue();
}
}
The following image shows typical output from a string input component:
The context object is StringInputContext. The following table lists its context variables:
| Key | Description |
|---|---|
|
The default value, if set. Otherwise, null. |
|
The masked input value |
|
The masked result value |
|
The mask character, if set. Otherwise, null. |
|
|
|
The parent context variables (see TextComponentContext Template Variables). |
8.3.3. Path Input
The path input component asks a user for a Path and gives additional information about a path itself.
@ShellComponent
public class ComponentCommands extends AbstractShellComponent {
@ShellMethod(key = "component path", value = "Path input", group = "Components")
public String pathInput() {
PathInput component = new PathInput(getTerminal(), "Enter value");
component.setResourceLoader(getResourceLoader());
component.setTemplateExecutor(getTemplateExecutor());
PathInputContext context = component.run(PathInputContext.empty());
return "Got value " + context.getResultValue();
}
}
The following image shows typical output from a path input component:
The context object is PathInputContext. The following table describes its context variables:
| Key | Description |
|---|---|
|
The parent context variables (see TextComponentContext Template Variables). |
8.3.4. Confirmation
The confirmation component asks a user for a simple confirmation. It is essentially a yes-or-no question.
@ShellComponent
public class ComponentCommands extends AbstractShellComponent {
@ShellMethod(key = "component confirmation", value = "Confirmation input", group = "Components")
public String confirmationInput(boolean no) {
ConfirmationInput component = new ConfirmationInput(getTerminal(), "Enter value", !no);
component.setResourceLoader(getResourceLoader());
component.setTemplateExecutor(getTemplateExecutor());
ConfirmationInputContext context = component.run(ConfirmationInputContext.empty());
return "Got value " + context.getResultValue();
}
}
The following image shows the typical output from a confirmation component:
The context object is ConfirmationInputContext. The following table describes its context variables:
| Key | Description |
|---|---|
|
The default value — either |
|
The parent context variables (see TextComponentContext Template Variables). |
8.3.5. Single Select
A single select component asks a user to choose one item from a list. It is similar to a simple dropbox implementation. The following listing shows an example:
@ShellComponent
public class ComponentCommands extends AbstractShellComponent {
@ShellMethod(key = "component single", value = "Single selector", group = "Components")
public String singleSelector() {
SelectorItem<String> i1 = SelectorItem.of("key1", "value1");
SelectorItem<String> i2 = SelectorItem.of("key2", "value2");
List<SelectorItem<String>> items = Arrays.asList(i1, i2);
SingleItemSelector<String, SelectorItem<String>> component = new SingleItemSelector<>(getTerminal(),
items, "testSimple", null);
component.setResourceLoader(getResourceLoader());
component.setTemplateExecutor(getTemplateExecutor());
SingleItemSelectorContext<String, SelectorItem<String>> context = component
.run(SingleItemSelectorContext.empty());
String result = context.getResultItem().flatMap(si -> Optional.ofNullable(si.getItem())).get();
return "Got value " + result;
}
}
The following image shows typical output for a single select component:
The context object is SingleItemSelectorContext. The following table describes its context variables:
| Key | Description |
|---|---|
|
The returned value when the component exists. |
|
The visible items, where rows contains maps of name and selected items. |
|
The parent context variables (see SelectorComponentContext Template Variables). |
You can pre-select an item by defining it to get exposed. This is
useful if you know the default and lets the user merely press Enter to make a choice.
The following listing sets a default:
SelectorItem<String> i1 = SelectorItem.of("key1", "value1");
SelectorItem<String> i2 = SelectorItem.of("key2", "value2");
List<SelectorItem<String>> items = Arrays.asList(i1, i2);
SingleItemSelector<String, SelectorItem<String>> component = new SingleItemSelector<>(getTerminal(),
items, "testSimple", null);
component.setDefaultExpose(i2);
8.3.6. Multi Select
The multi select component asks a user to select multiple items from a list. The following listing shows an example:
@ShellComponent
public class ComponentCommands extends AbstractShellComponent {
@ShellMethod(key = "component multi", value = "Multi selector", group = "Components")
public String multiSelector() {
List<SelectorItem<String>> items = new ArrayList<>();
items.add(SelectorItem.of("key1", "value1"));
items.add(SelectorItem.of("key2", "value2", false, true));
items.add(SelectorItem.of("key3", "value3"));
MultiItemSelector<String, SelectorItem<String>> component = new MultiItemSelector<>(getTerminal(),
items, "testSimple", null);
component.setResourceLoader(getResourceLoader());
component.setTemplateExecutor(getTemplateExecutor());
MultiItemSelectorContext<String, SelectorItem<String>> context = component
.run(MultiItemSelectorContext.empty());
String result = context.getResultItems().stream()
.map(si -> si.getItem())
.collect(Collectors.joining(","));
return "Got value " + result;
}
}
The following image shows a typical multi-select component:
The context object is MultiItemSelectorContext. The following table describes its context variables:
| Key | Description |
|---|---|
|
The values returned when the component exists. |
|
The visible items, where rows contain maps of name, selected, on-row, and enabled items. |
|
The parent context variables (see SelectorComponentContext Template Variables). |