80ec92ea84
- Docs for annotation and registration - Remove dynamic from header - Move samples to snippets - Fixes #1053
104 lines
4.1 KiB
Plaintext
104 lines
4.1 KiB
Plaintext
[[dynamic-command-availability]]
|
|
= Command Availability
|
|
|
|
ifndef::snippets[:snippets: ../../../../src/test/java/org/springframework/shell/docs]
|
|
|
|
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.
|
|
|
|
== Programmatic
|
|
|
|
With programmatic registration you can use `availability` method which takes
|
|
`Supplier<Availability>`.
|
|
|
|
[source, java, indent=0]
|
|
----
|
|
include::{snippets}/CommandAvailabilitySnippets.java[tag=availability-method-programmatic]
|
|
----
|
|
|
|
== Annotation
|
|
|
|
With annotation based commands you can use `@CommandAvailability` together with
|
|
`AvailabilityProvider`.
|
|
|
|
[source, java, indent=0]
|
|
----
|
|
include::{snippets}/CommandAvailabilitySnippets.java[tag=availability-method-annotation]
|
|
----
|
|
|
|
== Legacy Annotation
|
|
|
|
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, indent=0]
|
|
----
|
|
include::{snippets}/CommandAvailabilitySnippets.java[tag=availability-method-in-shellcomponent]
|
|
----
|
|
|
|
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: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, indent=0]
|
|
----
|
|
include::{snippets}/CommandAvailabilitySnippets.java[tag=availability-method-name-in-shellcomponent]
|
|
----
|
|
|
|
<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, indent=0]
|
|
----
|
|
include::{snippets}/CommandAvailabilitySnippets.java[tag=availability-method-name-multi-in-shellcomponent]
|
|
----
|
|
|
|
[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, indent=0]
|
|
----
|
|
include::{snippets}/CommandAvailabilitySnippets.java[tag=availability-method-default-value-in-shellcomponent]
|
|
----
|
|
|
|
=====
|
|
|
|
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.
|