diff --git a/spring-shell-docs/src/main/asciidoc/using-shell-commands-registration-annotation.adoc b/spring-shell-docs/src/main/asciidoc/using-shell-commands-registration-annotation.adoc new file mode 100644 index 00000000..e8772b00 --- /dev/null +++ b/spring-shell-docs/src/main/asciidoc/using-shell-commands-registration-annotation.adoc @@ -0,0 +1,52 @@ +[[commands-registration-annotation]] +==== Annotation +ifndef::snippets[:snippets: ../../test/java/org/springframework/shell/docs] + +`@Command` annotation when used on a method marks it as a candidate for command registration. +In below example a command `example` is defined. + +==== +[source, java, indent=0] +---- +include::{snippets}/CommandAnnotationSnippets.java[tag=command-anno-in-method] +---- +==== + +`@Command` annotation can be placed on a class which either defines defaults or shared settings +for `@Command` methods defined in a same class. In below example a command `parent example` is +defined. + +==== +[source, java, indent=0] +---- +include::{snippets}/CommandAnnotationSnippets.java[tag=command-anno-in-class] +---- +==== + +Using a `@Command` will not automatically register command targets, instead it is required to use +`@EnableCommand` and/or `@CommandScan` annotations. This model is familiar from other parts +of Spring umbrella and provides better flexibility for a user being inclusive rather than exclusive +for command targets. + +You can define target classes using `@EnableCommand`. It will get picked from all _Configuration_ +classes. + +==== +[source, java, indent=0] +---- +include::{snippets}/CommandAnnotationSnippets.java[tag=enablecommand-with-class] +---- +==== + +You can define target classes using `@CommandScan`. It will get picked from all _Configuration_ +classes. + +TIP: Define `@CommandScan` in Spring Boot `App` class on a top level and it will automatically +scan all command targets from all packages and classes under `App`. + +==== +[source, java, indent=0] +---- +include::{snippets}/CommandAnnotationSnippets.java[tag=commandscan-no-args] +---- +==== diff --git a/spring-shell-docs/src/main/asciidoc/using-shell-commands-registration-legacyannotation.adoc b/spring-shell-docs/src/main/asciidoc/using-shell-commands-registration-legacyannotation.adoc index 0d6d0a59..0474e5d5 100644 --- a/spring-shell-docs/src/main/asciidoc/using-shell-commands-registration-legacyannotation.adoc +++ b/spring-shell-docs/src/main/asciidoc/using-shell-commands-registration-legacyannotation.adoc @@ -1,4 +1,5 @@ -==== Annotation Model +[[commands-registration-legacyannotation]] +==== Annotation Legacy ifndef::snippets[:snippets: ../../test/java/org/springframework/shell/docs] When you use the standard API, methods on beans are turned into executable commands, provided that: diff --git a/spring-shell-docs/src/main/asciidoc/using-shell-commands-registration-programmatic.adoc b/spring-shell-docs/src/main/asciidoc/using-shell-commands-registration-programmatic.adoc index f0830291..ad7b8a2a 100644 --- a/spring-shell-docs/src/main/asciidoc/using-shell-commands-registration-programmatic.adoc +++ b/spring-shell-docs/src/main/asciidoc/using-shell-commands-registration-programmatic.adoc @@ -1,5 +1,5 @@ -[[using-shell-commands-programmaticmodel]] -==== Programmatic Model +[[commands-registration-programmatic]] +==== Programmatic ifndef::snippets[:snippets: ../../test/java/org/springframework/shell/docs] In the programmatic model, `CommandRegistration` can be defined as a `@Bean` diff --git a/spring-shell-docs/src/main/asciidoc/using-shell-commands-registration.adoc b/spring-shell-docs/src/main/asciidoc/using-shell-commands-registration.adoc index bd3a16a3..b27443e9 100644 --- a/spring-shell-docs/src/main/asciidoc/using-shell-commands-registration.adoc +++ b/spring-shell-docs/src/main/asciidoc/using-shell-commands-registration.adoc @@ -7,6 +7,15 @@ in a class and annotate the class and the methods with specific annotations. In the programmatic model, you use a more low level approach, defining command registrations (either as beans or by dynamically registering with a command catalog). +Starting from _3.1.x_ a better support for defining commands using +<> were added. Firstly because eventually standard +package providing <> will get deprecated +and removed. Secondly so that we're able to provide same set of features than using underlying +`CommandRegistration`. Creating new a annotation model allows us to rethink and modernise that +part without breaking existing applications. + +include::using-shell-commands-registration-annotation.adoc[] + include::using-shell-commands-registration-legacyannotation.adoc[] include::using-shell-commands-registration-programmatic.adoc[] diff --git a/spring-shell-docs/src/test/java/org/springframework/shell/docs/CommandAnnotationSnippets.java b/spring-shell-docs/src/test/java/org/springframework/shell/docs/CommandAnnotationSnippets.java new file mode 100644 index 00000000..6e24bd26 --- /dev/null +++ b/spring-shell-docs/src/test/java/org/springframework/shell/docs/CommandAnnotationSnippets.java @@ -0,0 +1,66 @@ +/* + * Copyright 2023 the original author or authors. + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * https://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ +package org.springframework.shell.docs; + +import org.springframework.shell.command.annotation.Command; +import org.springframework.shell.command.annotation.CommandScan; +import org.springframework.shell.command.annotation.EnableCommand; + +class CommandAnnotationSnippets { + + class Dump1 { + + // tag::enablecommand-with-class[] + @EnableCommand(Example.class) + class App { + } + // end::enablecommand-with-class[] + + // tag::command-anno-in-method[] + class Example { + + @Command(command = "example") + public String example() { + return "Hello"; + } + } + // end::command-anno-in-method[] + } + + class Dump2 { + + // tag::command-anno-in-class[] + @Command(command = "parent") + class Example { + + @Command(command = "example") + public String example() { + return "Hello"; + } + } + // end::command-anno-in-class[] + } + + class Dump3 { + + // tag::commandscan-no-args[] + @CommandScan + class App { + } + // end::commandscan-no-args[] + } + +}