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

SHL-53 - Documentation Corrections

Browse Source
This commit is contained in:
Mark Pollack
2012-09-19 11:47:31 -04:00
parent 8620061363
commit 2f0a8d0f06
3 changed files with 59 additions and 42 deletions
Download Patch File Download Diff File Expand all files Collapse all files

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

@@ -28,8 +28,8 @@
</listitem>
<listitem>
<para>Use of Spring's classpath scanning functionality as the basis for a
command plugin strategy and command develoment</para>
<para>Use of Spring's classpath scanning functionality as the basis for
a command plugin strategy and command development</para>
</listitem>
<listitem>

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

@@ -24,13 +24,14 @@
(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 code 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
<programlisting language="java">@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 {
<section>
<title>Logging</title>
<para>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.
</para>
<para>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.</para>
<programlisting language="java">@Component
public class HelloWorldCommands implements CommandMarker {
@@ -54,15 +55,17 @@ public class HelloWorldCommands implements CommandMarker {
}</programlisting>
<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>
<warning>
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.
</warning>
</section>
<section>
<title>CLI Annotations</title>
<para>There are three annotations used on methods and method arguments
that define the 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,12 +88,12 @@ public class HelloWorldCommands implements CommandMarker {
<listitem>
<para><classname>CliOptions</classname> - Placed on the arguments of a
command method, allowing it to declare the argument value as
mandatory or optional with a default value.</para>
command method, allowing it to declare the argument value as mandatory
or optional with a default value.</para>
</listitem>
</itemizedlist>
<para>Here is a simple use of these annotations in a command class </para>
<para>Here is a simple use of these annotations in a command class</para>
<programlisting language="java">@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. </para>
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
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
<interfacename>org.springframework.shell.core.Converter</interfacename>
interface with the container in your plugin.</para>
<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()
<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 <literal>toString()</literal>
representation.</para>
</section>

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

@@ -20,8 +20,7 @@
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
@@ -35,7 +34,8 @@
</mediaobject>
<para>Note that the current plugin model loads all plugins under the same
class loader. An open <link xlink:href="https://jira.springsource.org/browse/SHL-37">JIRA issue</link>
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>
@@ -49,10 +49,13 @@
<programlisting language="xml">&lt;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"&gt;
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"&gt;
&lt;context:component-scan base-package="org.springframework.shell.samples.helloworld.commands" /&gt;
&lt;context:component-scan
base-package="org.springframework.shell.samples.helloworld.commands" /&gt;
&lt;/beans&gt;</programlisting>
@@ -64,7 +67,8 @@
<programlisting language="java">@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 {
<listitem>
<para><interfacename>PromptProvider</interfacename> - Specifies the
command prompt text, eg. "<literal>shell&gt;</literal>" or
"<literal>#</literal>" or "<literal>$</literal>"</para>
"<literal>#</literal>" or "<literal>$</literal>". This will be called
after every command execution so it does not need to be a static
string.</para>
</listitem>
<listitem>
@@ -177,23 +183,23 @@ public class HelloWorldCommands implements CommandMarker {
<para>There is a default implementation for these interfaces but you
should create your own implementations for your own shell application. Use
Spring's <literal>@Ordered</literal> 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. </para>
other plugins.</para>
<para>To make cool "<link
xlink:href="http://en.wikipedia.org/wiki/ASCII_art">ASCII art</link>"
banners the website <link
xlink:href="http://patorjk.com/software/taag">http://patorjk.com/software/taag</link>
is quite neat! </para>
is quite neat!</para>
</section>
<section>
<title>Communicating between plugins</title>
<para>As this is a standard Spring application you can use Spring's
ApplicationContext event infrastructure to communicate across
plugins.</para>
<classname>ApplicationContext</classname> event infrastructure to
communicate across plugins.</para>
</section>
<section>
@@ -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 {
<title>Command line options</title>
<para>There are a few command line options that can be specified when
starting the shell. They are </para>
starting the shell. They are</para>
<itemizedlist>
<listitem>