From 2f0a8d0f061e8225466b9a19e79681a3c2a9b2a8 Mon Sep 17 00:00:00 2001 From: Mark Pollack Date: Wed, 19 Sep 2012 11:47:31 -0400 Subject: [PATCH] SHL-53 - Documentation Corrections --- docs/src/reference/docbook/preface.xml | 4 +- .../reference/dev-guide/dev-spring-shell.xml | 53 +++++++++++-------- .../src/reference/docbook/reference/shell.xml | 44 ++++++++------- 3 files changed, 59 insertions(+), 42 deletions(-) diff --git a/docs/src/reference/docbook/preface.xml b/docs/src/reference/docbook/preface.xml index 5fef05fe..d9bc1b89 100644 --- a/docs/src/reference/docbook/preface.xml +++ b/docs/src/reference/docbook/preface.xml @@ -28,8 +28,8 @@ - Use of Spring's classpath scanning functionality as the basis for a - command plugin strategy and command develoment + Use of Spring's classpath scanning functionality as the basis for + a command plugin strategy and command development diff --git a/docs/src/reference/docbook/reference/dev-guide/dev-spring-shell.xml b/docs/src/reference/docbook/reference/dev-guide/dev-spring-shell.xml index 6fd78352..fb39cdc4 100644 --- a/docs/src/reference/docbook/reference/dev-guide/dev-spring-shell.xml +++ b/docs/src/reference/docbook/reference/dev-guide/dev-spring-shell.xml @@ -24,13 +24,14 @@ (Note there is an open JIRA issue to provide a @CliCommand meta-annotation to avoid having to use a marker interface). Using the code from the helloworld sample - application, the code of a HelloWorldCommands - class is shown below: + application, the code of a HelloWorldCommands class + is shown below: - @Component + @Component public class HelloWorldCommands implements CommandMarker { - // use any Spring annotations for Dependency Injection or other Spring interfaces as required. + // use any Spring annotations for Dependency Injection or other Spring interfaces + // as required. // methods with @Cli annotations go here @@ -40,10 +41,10 @@ public class HelloWorldCommands implements CommandMarker {
Logging - Logging is currently done using JDK logging. Due to the intrincacies of console, JLine and Ansi - handling, it is generally advised to display messages as return values to the method commands. However, - when logging is required, the typical JDK logger declaration should suffice. - + Logging is currently done using JDK logging. Due to the intricacies + of console, JLine and Ansi handling, it is generally advised to display + messages as return values to the method commands. However, when logging is + required, the typical JDK logger declaration should suffice. @Component public class HelloWorldCommands implements CommandMarker { @@ -54,15 +55,17 @@ public class HelloWorldCommands implements CommandMarker { } - Note: it is the responsability of the packager/developer to handle logging for third-party libraries. Typically one wants - to reduce the logging level so the console/shell does not get affected by logging messages. + + Note: it is the responsibility of the packager/developer to handle logging for third-party libraries. Typically one wants to reduce the logging level so the console/shell does not get affected by logging messages. +
CLI Annotations There are three annotations used on methods and method arguments - that define the main contract for interacting with the shell. These are: + that define the main contract for interacting with the shell. These + are: @@ -85,12 +88,12 @@ public class HelloWorldCommands implements CommandMarker { CliOptions - Placed on the arguments of a - command method, allowing it to declare the argument value as - mandatory or optional with a default value. + command method, allowing it to declare the argument value as mandatory + or optional with a default value. - Here is a simple use of these annotations in a command class + Here is a simple use of these annotations in a command class @Component public class HelloWorldCommands implements CommandMarker { @@ -102,8 +105,12 @@ public class HelloWorldCommands implements CommandMarker { @CliCommand(value = "hw simple", help = "Print a simple hello world message") public String simple( - @CliOption(key = { "message" }, mandatory = true, help = "The hello world message") final String message, - @CliOption(key = { "location" }, mandatory = false, help = "Where you are saying hello", specifiedDefaultValue="At work") final String location) { + @CliOption(key = { "message" }, mandatory = true, help = "The hello world message") + final String message, + + @CliOption(key = { "location" }, mandatory = false, + help = "Where you are saying hello", specifiedDefaultValue="At work") + final String location) { return "Message = [" + message + "] Location = [" + location + "]"; @@ -125,9 +132,10 @@ public class HelloWorldCommands implements CommandMarker { command arguments is where you will spend most of your time authoring commands. You need to decide which arguments are required, which are optional, and if they are optional is there a default value. In this case - there are two arguments or options to the command: message and location. The - message option is required and a help message is provided to give guidance to - the user when tabbing to get completion for the command. + there are two arguments or options to the command: message and location. + The message option is required and a help message is provided to give + guidance to the user when tabbing to get completion for the + command. The implementation of the 'simple' method is trivial, just a log statement, but this is where you would typically @@ -143,9 +151,10 @@ public class HelloWorldCommands implements CommandMarker { register your own implementation of the org.springframework.shell.core.Converter interface with the container in your plugin. - - Note that the method return argument can be non-void - in our example, it is the actual - message we want to display. Whenever an object is returned, the shell will display its toString() + + Note that the method return argument can be non-void - in our + example, it is the actual message we want to display. Whenever an object + is returned, the shell will display its toString() representation.
diff --git a/docs/src/reference/docbook/reference/shell.xml b/docs/src/reference/docbook/reference/shell.xml index 3a322c10..e85fc273 100644 --- a/docs/src/reference/docbook/reference/shell.xml +++ b/docs/src/reference/docbook/reference/shell.xml @@ -20,8 +20,7 @@ will be loaded to bootstrap a Spring ApplicationContext when the shell is started. The essential boostrapping code that looks for your contributions - looks like this: - new ClassPathXmlApplicationContext("classpath*:/META-INF/spring/spring-shell-plugin.xml"); + looks like this: new ClassPathXmlApplicationContext("classpath*:/META-INF/spring/spring-shell-plugin.xml"); In the spring-shell-plugin.xml file you should define the command classes and any other collaborating objects that @@ -35,7 +34,8 @@ Note that the current plugin model loads all plugins under the same - class loader. An open JIRA issue + class loader. An open JIRA issue suggests providing a classloader per plugin to provide isolation.
@@ -49,10 +49,13 @@ <beans xmlns="http://www.springframework.org/schema/beans" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:context="http://www.springframework.org/schema/context" - xsi:schemaLocation="http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans.xsd - http://www.springframework.org/schema/context http://www.springframework.org/schema/context/spring-context-3.1.xsd"> + xsi:schemaLocation="http://www.springframework.org/schema/beans + http://www.springframework.org/schema/beans/spring-beans.xsd + http://www.springframework.org/schema/context + http://www.springframework.org/schema/context/spring-context-3.1.xsd"> - <context:component-scan base-package="org.springframework.shell.samples.helloworld.commands" /> + <context:component-scan + base-package="org.springframework.shell.samples.helloworld.commands" /> </beans> @@ -64,7 +67,8 @@ @Component public class HelloWorldCommands implements CommandMarker { - // use any Spring annotations for Dependency Injection or other Spring interfaces as required. + // use any Spring annotations for Dependency Injection or other Spring + // interfaces as required. // methods with @Cli annotations go here @@ -165,7 +169,9 @@ public class HelloWorldCommands implements CommandMarker { PromptProvider - Specifies the command prompt text, eg. "shell>" or - "#" or "$" + "#" or "$". This will be called + after every command execution so it does not need to be a static + string. @@ -177,23 +183,23 @@ public class HelloWorldCommands implements CommandMarker { There is a default implementation for these interfaces but you should create your own implementations for your own shell application. Use Spring's @Ordered annotation to set the priority of the - provider. This allows your provider implementations to take precidence + provider. This allows your provider implementations to take precedence over any other implementations that maybe present on the classpath from - other plugins. + other plugins. To make cool "ASCII art" banners the website http://patorjk.com/software/taag - is quite neat! + is quite neat!
Communicating between plugins As this is a standard Spring application you can use Spring's - ApplicationContext event infrastructure to communicate across - plugins. + ApplicationContext event infrastructure to + communicate across plugins.
@@ -212,8 +218,8 @@ public class HelloWorldCommands implements CommandMarker { /** * Method called before invoking the target command (described by {@link ParseResult}). - * Additionally, for advanced cases, the parse result itself effectively changing the invocation - * calling site. + * Additionally, for advanced cases, the parse result itself effectively changing the + * invocation calling site. * * @param invocationContext target command context * @return the invocation target @@ -221,7 +227,8 @@ public class HelloWorldCommands implements CommandMarker { ParseResult beforeInvocation(ParseResult invocationContext); /** - * Method called after successfully invoking the target command (described by {@link ParseResult}). + * Method called after successfully invoking the target command (described by + * {@link ParseResult}). * * @param invocationContext target command context * @param result the invocation result @@ -229,7 +236,8 @@ public class HelloWorldCommands implements CommandMarker { void afterReturningInvocation(ParseResult invocationContext, Object result); /** - * Method called after invoking the target command (described by {@link ParseResult}) had thrown an exception . + * Method called after invoking the target command (described by {@link ParseResult}) + * had thrown an exception . * * @param invocationContext target command context * @param thrown the thrown object @@ -243,7 +251,7 @@ public class HelloWorldCommands implements CommandMarker { Command line options There are a few command line options that can be specified when - starting the shell. They are + starting the shell. They are