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.
With programmatic registration you can use availability method which takes
Supplier<Availability>.
link:../../../../src/test/java/org/springframework/shell/docs/CommandAvailabilitySnippets.java[role=include]With annotation based commands you can use @CommandAvailability together with
AvailabilityProvider.
link:../../../../src/test/java/org/springframework/shell/docs/CommandAvailabilitySnippets.java[role=include]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:
link:../../../../src/test/java/org/springframework/shell/docs/CommandAvailabilitySnippets.java[role=include]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:
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 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:
link:../../../../src/test/java/org/springframework/shell/docs/CommandAvailabilitySnippets.java[role=include]-
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:
link:../../../../src/test/java/org/springframework/shell/docs/CommandAvailabilitySnippets.java[role=include]|
Tip
|
The default value for the link:../../../../src/test/java/org/springframework/shell/docs/CommandAvailabilitySnippets.java[role=include] |
|
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. |