Migrate Structure

spring-shell-docs/modules/ROOT/pages/using-shell-commands-availability.adoc

@@ -0,0 +1,147 @@
+[[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 <<built-in-commands-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.