From b17cf76bf09bcda88f6e541551a29ddac77ab52c Mon Sep 17 00:00:00 2001 From: Erwin Vervaet Date: Tue, 31 Jul 2012 13:32:28 +0200 Subject: [PATCH 1/2] Fixed forum link, removed bogus Hadoop reference + readme polishing --- README.md | 5 ++--- docs/src/info/readme.txt | 9 +++++---- 2 files changed, 7 insertions(+), 7 deletions(-) diff --git a/README.md b/README.md index 207f86b4..17dc0277 100644 --- a/README.md +++ b/README.md @@ -64,7 +64,6 @@ Spring Shell is built with Gradle. To build Spring Shell, run Here are some ways for you to get involved in the community: -* Get involved with the Spring community on the Spring Community Forums. Please help out on the [forum](http://forum.springsource.org/forumdisplay.php?f=80) by responding to questions and joining the debate. -Please add 'Hadoop' as a prefix to easily spot the post topic. +* Get involved with the Spring community on the Spring Community Forums. Please help out on the [forum](http://forum.springsource.org/forumdisplay.php?90-Shell) by responding to questions and joining the debate. * Create [JIRA](https://jira.springframework.org/browse/SHL) tickets for bugs and new features and comment and vote on the ones that you are interested in. -Github is for social coding: if you want to write code, we encourage contributions through pull requests from [forks of this repository](http://help.github.com/forking/). If you want to contribute code this way, please reference a tracker ticket as well covering the specific issue you are addressing. Before we accept a non-trivial patch or pull request we will need you to sign the [contributor's agreement](https://support.springsource.com/spring_committer_signup). Signing the contributor's agreement does not grant anyone commit rights to the main repository, but it does mean that we can accept your contributions, and you will get an author credit if we do. Active contributors might be asked to join the core team, and given the ability to merge pull requests. +Github is for social coding: if you want to write code, we encourage contributions through pull requests from [forks of this repository](http://help.github.com/forking/). If you want to contribute code this way, please reference a JIRA tracker ticket covering the specific issue you are addressing. Before we accept a non-trivial patch or pull request we will need you to sign the [contributor's agreement](https://support.springsource.com/spring_committer_signup). Signing the contributor's agreement does not grant anyone commit rights to the main repository, but it does mean that we can accept your contributions, and you will get an author credit if we do. Active contributors might be asked to join the core team, and given the ability to merge pull requests. diff --git a/docs/src/info/readme.txt b/docs/src/info/readme.txt index 70417961..9d88d8fb 100644 --- a/docs/src/info/readme.txt +++ b/docs/src/info/readme.txt @@ -13,13 +13,14 @@ details, consult the provided javadoc for specific packages and classes. 3. DISTRIBUTION JAR FILES -The Spring Shell jars files can be found in the 'dist' directory. +The Spring Shell jar files can be found in the 'dist' directory. 4. GETTING STARTED Please see the reference documentation. -Additionally the blog at http://blog.springsource.com as well +Additionally, consult the blog at http://blog.springsource.com as well as sections of interest in the reference documentation. -ADDITIONAL RESOURCES -Spring Shell Homepage: http://www.springsource.org/spring-shell +5. ADDITIONAL RESOURCES + +Spring Shell homepage: http://www.springsource.org/spring-shell From 74f00aa855e3bbafbdd5ba0c1175e9d1593962f5 Mon Sep 17 00:00:00 2001 From: Erwin Vervaet Date: Wed, 1 Aug 2012 08:24:31 +0200 Subject: [PATCH 2/2] Reference documentation polishing --- .../docbook/introduction/requirements.xml | 2 +- docs/src/reference/docbook/preface.xml | 4 +-- .../reference/dev-guide/dev-spring-shell.xml | 25 +++++++++---------- .../docbook/reference/introduction.xml | 2 -- .../src/reference/docbook/reference/shell.xml | 23 +++++++++-------- .../docbook/samples/introduction.xml | 8 +++--- .../docbook/samples/simple-application.xml | 5 ++-- 7 files changed, 33 insertions(+), 36 deletions(-) diff --git a/docs/src/reference/docbook/introduction/requirements.xml b/docs/src/reference/docbook/introduction/requirements.xml index f3175eef..9cf5c3d7 100644 --- a/docs/src/reference/docbook/introduction/requirements.xml +++ b/docs/src/reference/docbook/introduction/requirements.xml @@ -9,6 +9,6 @@ Requirements The Spring Shell requires JDK level 6.0 and above as well as the - Spring Framework 3.0 + Spring Framework 3.0 (3.1 recommended) and above. diff --git a/docs/src/reference/docbook/preface.xml b/docs/src/reference/docbook/preface.xml index 5674382f..5fef05fe 100644 --- a/docs/src/reference/docbook/preface.xml +++ b/docs/src/reference/docbook/preface.xml @@ -15,7 +15,7 @@ ns2:href="http://www.springsource.org/spring-roo/">Spring Roo project, giving it a strong foundation and rich feature set. One significant change from Spring Roo is that the plugin model is no longer - based on OSGi but instead uses Spring IoC container to discover commands + based on OSGi but instead uses the Spring IoC container to discover commands through classpath scanning. There is currently no classloader isolation between plugins, however that maybe added in future versions. @@ -28,7 +28,7 @@ - Use of Spring's classpath scanning functionality asthe basis for a + Use of Spring's classpath scanning functionality as the basis for a command plugin strategy and command develoment 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 26a8075b..6fd78352 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 @@ -11,7 +11,7 @@ Contributing commands to the shell is very easy. There are only a few annotations you need to learn. The implementation style of the command is - the same as developing classes in for application that uses dependency + the same as developing classes for an application that uses dependency injection. You can leverage all the features of the Spring container to implement your command classes. @@ -24,8 +24,8 @@ (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 shell of a HelloWorldCommands - class is shown below + application, the code of a HelloWorldCommands + class is shown below: @Component public class HelloWorldCommands implements CommandMarker { @@ -54,7 +54,7 @@ public class HelloWorldCommands implements CommandMarker { } - Note it's the packager/developer responsability to handle logging for third-party libraries. Typically one wants + 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. @@ -62,7 +62,7 @@ public class HelloWorldCommands implements CommandMarker { CLI Annotations There are three annotations used on methods and method arguments - that define main contract for interacting with the shell. These are + that define the main contract for interacting with the shell. These are: @@ -85,7 +85,7 @@ public class HelloWorldCommands implements CommandMarker { CliOptions - Placed on the arguments of a - command methods, allowing it to declare the argument value as + command method, allowing it to declare the argument value as mandatory or optional with a default value. @@ -103,8 +103,7 @@ 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 = { "location" }, mandatory = false, help = "Where you are saying hello", specifiedDefaultValue="At work") final String location) { return "Message = [" + message + "] Location = [" + location + "]"; @@ -120,14 +119,14 @@ public class HelloWorldCommands implements CommandMarker { command 'hw simple' in the shell. The help message is what will be printed if you use the build in help command. The method name is 'simple' but it could - just have well been any other name. + just have been any other name. The @CliOption annotation on each of the 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 keys to the command, message and location. The - key message is required and a help message is provided to give guidance to + 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 @@ -145,7 +144,7 @@ public class HelloWorldCommands implements CommandMarker { org.springframework.shell.core.Converter interface with the container in your plugin. - Note that the the method return argument can be non-void - in our example, it is the actual + 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. @@ -153,7 +152,7 @@ public class HelloWorldCommands implements CommandMarker {
Building and running the shell - In our opinion, the easiest way to build an execute the shell is to + In our opinion, the easiest way to build and execute the shell is to cut-n-paste the gradle script in the example application. This uses the application plugin from gradle to create a bin directory with a startup script for windows and Unix and places all dependent jars in a lib diff --git a/docs/src/reference/docbook/reference/introduction.xml b/docs/src/reference/docbook/reference/introduction.xml index b9552d18..7bad5ca8 100644 --- a/docs/src/reference/docbook/reference/introduction.xml +++ b/docs/src/reference/docbook/reference/introduction.xml @@ -1,7 +1,5 @@ - Document structure - This part of the reference documentation explains the core components of the Spring Shell. diff --git a/docs/src/reference/docbook/reference/shell.xml b/docs/src/reference/docbook/reference/shell.xml index 7e4d3b18..3a322c10 100644 --- a/docs/src/reference/docbook/reference/shell.xml +++ b/docs/src/reference/docbook/reference/shell.xml @@ -9,18 +9,19 @@ Spring Shell The core components of the shell are its plugin model, built-in - commands, and converters + commands, and converters.
Plugin Model - The plugin model is based Spring. Each plugin jar is required to + The plugin model is based on Spring. Each plugin jar is required to contain the file META-INF/spring/spring-shell-plugin.xml. These files will be loaded to bootstrap a Spring ApplicationContext when the shell is started. The essential boostrapping code that looks for your contributions - looks like thisnew 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 @@ -34,16 +35,16 @@ Note that the current plugin model loads all plugins under the same - class loader. An open JIRA issus is to provide a classloader per plugin to - provide isolation. + class loader. An open JIRA issue + suggests providing a classloader per plugin to provide isolation.
Commands An easy way to declare the commands is to use Spring's component scanning functionality. Here is an example - spring-shell-plugin.xml that from the sample - application. + spring-shell-plugin.xml from the sample + application: <beans xmlns="http://www.springframework.org/schema/beans" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" @@ -69,7 +70,7 @@ public class HelloWorldCommands implements CommandMarker { } - One the commands are registered and instantiated by the Spring + Once the commands are registered and instantiated by the Spring container, they are registered with the core shell parser so that the @Cli annotations can be processed. The way the commands are identified is through the use of the @@ -202,9 +203,9 @@ public class HelloWorldCommands implements CommandMarker { around the invocation of a command method. This enables the command class to check for updates to state, such as configuration information modified by other plugins, before the command method is executed. The interface - ExecutionProcess should be implemented + ExecutionProcessor should be implemented instead of CommandMarker to access this - functionality. The ExecutionProcess + functionality. The ExecutionProcessor interface is shown below public interface ExecutionProcessor extends CommandMarker { @@ -273,7 +274,7 @@ public class HelloWorldCommands implements CommandMarker { script command inside the shell. When using scripts it helps to add comments and this can be done using block comments that start and end with /* and */ or an inline - one line command using // or ; + one line comment using the // or ; characters.
diff --git a/docs/src/reference/docbook/samples/introduction.xml b/docs/src/reference/docbook/samples/introduction.xml index 2b34c4d4..fba417d0 100644 --- a/docs/src/reference/docbook/samples/introduction.xml +++ b/docs/src/reference/docbook/samples/introduction.xml @@ -1,11 +1,9 @@ - Document structure - This part of the reference documentation covers the sample applications included with Spring Shell that demonstrate the features in a - code centric manner. + code centric manner. - Describes a simple Spring Shell - application that echo's the command parameters to the console + Describes a simple Spring Shell + application that echo's the command parameters to the console. diff --git a/docs/src/reference/docbook/samples/simple-application.xml b/docs/src/reference/docbook/samples/simple-application.xml index 16e0ab1d..1670656e 100644 --- a/docs/src/reference/docbook/samples/simple-application.xml +++ b/docs/src/reference/docbook/samples/simple-application.xml @@ -22,7 +22,8 @@ <spring-shell-install-dir>/samples/helloworld. To build the example cd to the helloworld directory and execute - ..\..\gradlew installApp. To run the application cd to + gradlew installApp (you first need to add the gradlew + gradle wrapper to your path). To run the application cd to build\install\helloworld\bin and execute the helloworld script.
@@ -119,7 +120,7 @@ public class HelloWorldCommands implements CommandMarker { The 'hw enum' command shows how the shell - supports the use of Enumeration as command method arguments. + supports the use of an enumeration as command method arguments.