Spring/spring-shell
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Reference documentation polishing

Browse Source
This commit is contained in:
Erwin Vervaet
2012-08-01 08:24:31 +02:00
parent b17cf76bf0
commit 74f00aa855
7 changed files with 33 additions and 36 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
docs/src/reference/docbook/introduction/requirements.xml
View File

@@ -9,6 +9,6 @@
<title>Requirements</title>
<para>The Spring Shell requires JDK level 6.0 and above as well as the
Spring <ulink url="http://www.springsource.org/about">Framework</ulink> 3.0
<ulink url="http://www.springsource.org/about">Spring Framework</ulink> 3.0
(3.1 recommended) and above.</para>
</chapter>

4
docs/src/reference/docbook/preface.xml
View File

@@ -15,7 +15,7 @@
ns2:href="http://www.springsource.org/spring-roo/">Spring Roo
project</link>, 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.</para>
@@ -28,7 +28,7 @@
</listitem>
<listitem>
<para>Use of Spring's classpath scanning functionality asthe basis for a
<para>Use of Spring's classpath scanning functionality as the basis for a
command plugin strategy and command develoment</para>
</listitem>

25
docs/src/reference/docbook/reference/dev-guide/dev-spring-shell.xml
View File

@@ -11,7 +11,7 @@
<para>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.</para>
@@ -24,8 +24,8 @@
(Note there is an open JIRA issue to provide a
<classname>@CliCommand</classname> meta-annotation to avoid having to use
a marker interface). Using the code from the helloworld sample
application, the shell of a <classname>HelloWorldCommands</classname>
class is shown below </para>
application, the code of a <classname>HelloWorldCommands</classname>
class is shown below:</para>
<programlisting language="java">@Component
public class HelloWorldCommands implements CommandMarker {
@@ -54,7 +54,7 @@ public class HelloWorldCommands implements CommandMarker {
}</programlisting>
<warning>Note it's the packager/developer responsability to handle logging for third-party libraries. Typically one wants
<warning>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.</warning>
</section>
@@ -62,7 +62,7 @@ public class HelloWorldCommands implements CommandMarker {
<title>CLI Annotations</title>
<para>There are three annotations used on methods and method arguments
that define main contract for interacting with the shell. These are</para>
that define the main contract for interacting with the shell. These are:</para>
<itemizedlist>
<listitem>
@@ -85,7 +85,7 @@ public class HelloWorldCommands implements CommandMarker {
<listitem>
<para><classname>CliOptions</classname> - 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.</para>
</listitem>
</itemizedlist>
@@ -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 '<literal>hw simple</literal>' in the shell. The help message is
what will be printed if you use the build in <literal>help</literal>
command. The method name is '<methodname>simple</methodname>' but it could
just have well been any other name.</para>
just have been any other name.</para>
<para>The <classname>@CliOption</classname> 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. </para>
<para>The implementation of the '<methodname>simple</methodname>' method
@@ -145,7 +144,7 @@ public class HelloWorldCommands implements CommandMarker {
<interfacename>org.springframework.shell.core.Converter</interfacename>
interface with the container in your plugin.</para>
<para>Note that the the method return argument can be non-void - in our example, it is the actual
<para>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.</para>
</section>
@@ -153,7 +152,7 @@ public class HelloWorldCommands implements CommandMarker {
<section>
<title>Building and running the shell</title>
<para>In our opinion, the easiest way to build an execute the shell is to
<para>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

2
docs/src/reference/docbook/reference/introduction.xml
View File

@@ -1,7 +1,5 @@
<?xml version="1.0" encoding="UTF-8"?>
<partintro>
<title>Document structure</title>
<para>This part of the reference documentation explains the core components
of the Spring Shell.</para>
</partintro>

23
docs/src/reference/docbook/reference/shell.xml
View File

@@ -9,18 +9,19 @@
<title>Spring Shell</title>
<para>The core components of the shell are its plugin model, built-in
commands, and converters</para>
commands, and converters.</para>
<section>
<title>Plugin Model</title>
<para>The plugin model is based Spring. Each plugin jar is required to
<para>The plugin model is based on Spring. Each plugin jar is required to
contain the file
<literal>META-INF/spring/spring-shell-plugin.xml</literal>. These files
will be loaded to bootstrap a Spring
<interfacename>ApplicationContext</interfacename> when the shell is
started. The essential boostrapping code that looks for your contributions
looks like this<programlisting>new ClassPathXmlApplicationContext("classpath*:/META-INF/spring/spring-shell-plugin.xml");</programlisting></para>
looks like this:
<programlisting>new ClassPathXmlApplicationContext("classpath*:/META-INF/spring/spring-shell-plugin.xml");</programlisting></para>
<para>In the <literal>spring-shell-plugin.xml</literal> file you should
define the command classes and any other collaborating objects that
@@ -34,16 +35,16 @@
</mediaobject>
<para>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.</para>
class loader. An open <link xlink:href="https://jira.springsource.org/browse/SHL-37">JIRA issue</link>
suggests providing a classloader per plugin to provide isolation.</para>
<section>
<title>Commands</title>
<para>An easy way to declare the commands is to use Spring's component
scanning functionality. Here is an example
<literal>spring-shell-plugin.xml </literal>that from the sample
application.</para>
<literal>spring-shell-plugin.xml </literal> from the sample
application:</para>
<programlisting language="xml">&lt;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 {
}</programlisting>
<para>One the commands are registered and instantiated by the Spring
<para>Once the commands are registered and instantiated by the Spring
container, they are registered with the core shell parser so that the
<literal>@Cli</literal> 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
<interfacename>ExecutionProcess</interfacename> should be implemented
<interfacename>ExecutionProcessor</interfacename> should be implemented
instead of <interfacename>CommandMarker</interfacename> to access this
functionality. The <interfacename>ExecutionProcess</interfacename>
functionality. The <interfacename>ExecutionProcessor</interfacename>
interface is shown below</para>
<programlisting language="java">public interface ExecutionProcessor extends CommandMarker {
@@ -273,7 +274,7 @@ public class HelloWorldCommands implements CommandMarker {
<literal>script</literal> 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 <literal>/*</literal> and <literal>*/</literal> or an inline
one line command using <literal>//</literal> or <literal>;</literal>
one line comment using the <literal>//</literal> or <literal>;</literal>
characters.</para>
</section>
</chapter>

8
docs/src/reference/docbook/samples/introduction.xml
View File

@@ -1,11 +1,9 @@
<?xml version="1.0" encoding="UTF-8"?>
<partintro>
<title>Document structure</title>
<para>This part of the reference documentation covers the sample
applications included with Spring Shell that demonstrate the features in a
code centric manner. </para>
code centric manner.</para>
<para><xref linkend="simple-application"/> Describes a simple Spring Shell
application that echo's the command parameters to the console</para>
<para><xref linkend="simple-application"/>Describes a simple Spring Shell
application that echo's the command parameters to the console.</para>
</partintro>

5
docs/src/reference/docbook/samples/simple-application.xml
View File

@@ -22,7 +22,8 @@
<literal>&lt;spring-shell-install-dir&gt;/samples/helloworld</literal>.</para>
<para>To build the example cd to the helloworld directory and execute
<literal>..\..\gradlew installApp</literal>. To run the application cd to
<literal>gradlew installApp</literal> (you first need to add the <literal>gradlew</literal>
gradle wrapper to your path). To run the application cd to
<literal>build\install\helloworld\bin</literal> and execute the helloworld
script.</para>
</section>
@@ -119,7 +120,7 @@ public class HelloWorldCommands implements CommandMarker {
</mediaobject>
<para>The '<literal>hw enum</literal>' command shows how the shell
supports the use of Enumeration as command method arguments.</para>
supports the use of an enumeration as command method arguments.</para>
<mediaobject>
<imageobject>