138 lines
4.6 KiB
Plaintext
138 lines
4.6 KiB
Plaintext
[[dynamic-command-availability]]
|
|
= Dynamic Command Availability
|
|
|
|
Registered commands do not always make sense, due to the internal state of the application.
|
|
For example, there may be a `download` command, but it only works once the user has used `connect` on a remote
|
|
server. Now, if the user tries to use the `download` command, the shell should explain that
|
|
the command exists but that it is not available at the time.
|
|
Spring Shell lets you do that, even letting you provide a short explanation of the reason for
|
|
the command not being available.
|
|
|
|
There are three possible ways for a command to indicate availability.
|
|
They all use a no-arg method that returns an instance of `Availability`.
|
|
Consider the following example:
|
|
|
|
[source, java]
|
|
----
|
|
@ShellComponent
|
|
public class MyCommands {
|
|
|
|
private boolean connected;
|
|
|
|
@ShellMethod("Connect to the server.")
|
|
public void connect(String user, String password) {
|
|
[...]
|
|
connected = true;
|
|
}
|
|
|
|
@ShellMethod("Download the nuclear codes.")
|
|
public void download() {
|
|
[...]
|
|
}
|
|
|
|
public Availability downloadAvailability() {
|
|
return connected
|
|
? Availability.available()
|
|
: Availability.unavailable("you are not connected");
|
|
}
|
|
}
|
|
----
|
|
|
|
The `connect` method is used to connect to the server (details omitted), altering the state
|
|
of the command through the `connected` boolean when done.
|
|
The `download` command as marked as unavailable until the user has connected, thanks to the presence
|
|
of a method named exactly as the `download` command method with the `Availability` suffix in its name.
|
|
The method returns an instance of `Availability`, constructed with one of the two factory methods.
|
|
If the command is not available, an explanation has to be provided.
|
|
Now, if the user tries to invoke the command while not being connected, here is what happens:
|
|
|
|
[source]
|
|
----
|
|
shell:>download
|
|
Command 'download' exists but is not currently available because you are not connected.
|
|
Details of the error have been omitted. You can use the stacktrace command to print the full stacktrace.
|
|
----
|
|
|
|
Information about currently unavailable commands is also used in the integrated help. See xref:using-shell-commands-builtin-help.adoc[Help].
|
|
|
|
[TIP]
|
|
====
|
|
The reason provided when the command is not available should read nicely if appended after "`Because`".
|
|
|
|
You should not start the sentence with a capital or add a final period
|
|
====
|
|
|
|
If naming the availability method after the name of the command method does not suit you, you
|
|
can provide an explicit name by using the `@ShellMethodAvailability` annotation:
|
|
|
|
[source, java]
|
|
----
|
|
@ShellMethod("Download the nuclear codes.")
|
|
@ShellMethodAvailability("availabilityCheck") // <1>
|
|
public void download() {
|
|
[...]
|
|
}
|
|
|
|
public Availability availabilityCheck() { // <1>
|
|
return connected
|
|
? Availability.available()
|
|
: Availability.unavailable("you are not connected");
|
|
}
|
|
----
|
|
<1> the names have to match
|
|
|
|
Finally, it is often the case that several commands in the same class share the same internal state and, thus,
|
|
should all be available or unavailable as a group. Instead of having to stick the `@ShellMethodAvailability`
|
|
on all command methods, Spring Shell lets you flip things around and put the `@ShellMethodAvailabilty`
|
|
annotation on the availability method, specifying the names of the commands that it controls:
|
|
|
|
[source, java]
|
|
----
|
|
@ShellMethod("Download the nuclear codes.")
|
|
public void download() {
|
|
[...]
|
|
}
|
|
|
|
@ShellMethod("Disconnect from the server.")
|
|
public void disconnect() {
|
|
[...]
|
|
}
|
|
|
|
@ShellMethodAvailability({"download", "disconnect"})
|
|
public Availability availabilityCheck() {
|
|
return connected
|
|
? Availability.available()
|
|
: Availability.unavailable("you are not connected");
|
|
}
|
|
----
|
|
|
|
[TIP]
|
|
=====
|
|
The default value for the `@ShellMethodAvailability.value()` attribute is `*`. This special
|
|
wildcard matches all command names. This makes it easy to turn all commands of a single class on or off
|
|
with a single availability method:
|
|
|
|
[source,java]
|
|
----
|
|
@ShellComponent
|
|
public class Toggles {
|
|
@ShellMethodAvailability
|
|
public Availability availabilityOnWeekdays() {
|
|
return Calendar.getInstance().get(DAY_OF_WEEK) == SUNDAY
|
|
? Availability.available()
|
|
: Availability.unavailable("today is not Sunday");
|
|
}
|
|
|
|
@ShellMethod
|
|
public void foo() {}
|
|
|
|
@ShellMethod
|
|
public void bar() {}
|
|
}
|
|
----
|
|
=====
|
|
|
|
TIP: Spring Shell does not impose many constraints on how to write commands and how to organize classes.
|
|
However, it is often good practice to put related commands in the same class, and the availability indicators
|
|
can benefit from that.
|