diff --git a/docs/src/reference/docbook/images/logo.png b/docs/src/reference/docbook/images/logo.png new file mode 100644 index 00000000..a9f6d959 Binary files /dev/null and b/docs/src/reference/docbook/images/logo.png differ diff --git a/docs/src/reference/docbook/index.xml b/docs/src/reference/docbook/index.xml index cec7bae7..ce8cb3b7 100644 --- a/docs/src/reference/docbook/index.xml +++ b/docs/src/reference/docbook/index.xml @@ -16,6 +16,16 @@ Pollack SpringSource + + Jarred + Li + VMware + + + Costin + Leau + SpringSource + @@ -32,41 +42,28 @@ - + \ No newline at end of file diff --git a/docs/src/reference/docbook/introduction/introduction.xml b/docs/src/reference/docbook/introduction/introduction.xml new file mode 100644 index 00000000..212f77ab --- /dev/null +++ b/docs/src/reference/docbook/introduction/introduction.xml @@ -0,0 +1,15 @@ + + + The Spring Shell provides an interactive shell that lets you + contribute commands using a simple POJO based programming model. + + This document is the reference guide for the Spring Shell and covers + the key classes that are part of the Shell infrastructure, the plugin model, + how to create commands for the shell as well as discussion of the sample + application. + diff --git a/docs/src/reference/docbook/introduction/requirements.xml b/docs/src/reference/docbook/introduction/requirements.xml new file mode 100644 index 00000000..19dde886 --- /dev/null +++ b/docs/src/reference/docbook/introduction/requirements.xml @@ -0,0 +1,18 @@ + + + Requirements + + The Spring Shell requires JDK level 6.0 (just like Hadoop) and above + and the 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 6800d9d4..74418e05 100644 --- a/docs/src/reference/docbook/preface.xml +++ b/docs/src/reference/docbook/preface.xml @@ -1,6 +1,63 @@ - + Preface - + The Spring Shell provides an interactive shell that allows you to + plugin your own custom commands using a Spring based POJO programming + model. + + The shell has been extracted from the 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 through classpath scanning. There + is currently no classloader isolation between plugins, however that maybe + added in future versions. + + Spring Shell's features include + + + + A POJO based programming model to contribute custom + commands + + + + Use Spring's classpath scanning functionality as a basis for a + command plugin strategy + + + + Inheritance of the Roo + Shell features + + + + Tab completion + + + + Scripting and Script recording + + + + Customize command prompt, banner, shell history file name. + + + + This document assumes that the reader already has a basic familiarity + with the Spring Framework. + + While every effort has been made to ensure that this documentation is + comprehensive and there are no errors, nevertheless some topics might + require more explanation and some typos might have crept in. If you do spot + any mistakes or even more serious errors and you can spare a few cycles + during lunch, please do bring the error to the attention of the Spring Shell + team by raising an + issue. 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 new file mode 100644 index 00000000..34e6922e --- /dev/null +++ b/docs/src/reference/docbook/reference/dev-guide/dev-spring-shell.xml @@ -0,0 +1,43 @@ + + + Developing Spring Shell Applications + + The commands are + + + + + + + +
+ Marker Interface + + The marker interface.... +
+ +
+ CLI Annotations + + annotations +
+ +
+ Logging + + +
+ +
+ Building and running the shell + + +
+ diff --git a/docs/src/reference/docbook/reference/dev-guide/introduction.xml b/docs/src/reference/docbook/reference/dev-guide/introduction.xml new file mode 100644 index 00000000..a0f0a240 --- /dev/null +++ b/docs/src/reference/docbook/reference/dev-guide/introduction.xml @@ -0,0 +1,5 @@ + + + This section provides some guidance on how one can create commands for + the Spring Shell. + diff --git a/docs/src/reference/docbook/reference/introduction.xml b/docs/src/reference/docbook/reference/introduction.xml new file mode 100644 index 00000000..825f2b95 --- /dev/null +++ b/docs/src/reference/docbook/reference/introduction.xml @@ -0,0 +1,7 @@ + + + Document structure + + This part of the reference documentation explains the core componets + of the Spring Shell. + diff --git a/docs/src/reference/docbook/reference/shell.xml b/docs/src/reference/docbook/reference/shell.xml new file mode 100644 index 00000000..81558b7a --- /dev/null +++ b/docs/src/reference/docbook/reference/shell.xml @@ -0,0 +1,112 @@ + + + Spring Shell + + The core components of the shell are its plugin model, built-in + commands, and converters + +
+ Plugin Model + + The plugin model is based 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"); + + In the spring-shell-plugin.xml file you should + declare the commands and any collaboration objects that support the + commands actions. 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. + + <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"> + + <context:component-scan base-package="org.springframework.shell.samples.helloworld.commands" /> + +</beans> + + The commands are Spring components, demarcated as such using the + @Component annotation. For example, the + HelloWorldCommands class from the sample + application looks like this + + @Component +public class HelloWorldCommands implements CommandMarker { + + // methods with @Cli annotations go here + + // use any Spring annotations for Dependency Injection or other Spring interfaces as required. + +} + + One the commands are registered and instantiated by the Spring + container, they are registered with the core shell parser so that the + @Cli annotationscan be processed. The way the commands + are identified is through the use of the + CommandMarker interface. + +
+ Converters + + The + org.springframework.shell.core.Converter + interface provides the contract to convert the strings that are entered + in the command to rich Java types passed into the arguments of + @Cli-annotated methods. + + By default converters for common types are registered. These cover + primitive types (boolean, int, float...) as well as Date, Character, and + File. + + If you need to register any additional + Converter instances, register them with + the Spring container in the + spring-shell-plugin.xml file and they will be + picked up automatically. +
+
+ +
+ Built in commands + + There are a few built in commands. Here is a listing of their class + name and functionality + + + + EssentialCommands - + exit and quit - to exit the + shell. + + + + HelpCommands - help - + list all commands and their usage + + + + OsCommands - the keyword for this command + is the exclamation point, !. After the exclamation + point you can pass in a unix/windows command string to be + executed. + + + + +
+ diff --git a/docs/src/reference/docbook/samples/introduction.xml b/docs/src/reference/docbook/samples/introduction.xml new file mode 100644 index 00000000..2b34c4d4 --- /dev/null +++ b/docs/src/reference/docbook/samples/introduction.xml @@ -0,0 +1,11 @@ + + + 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. + + 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 new file mode 100644 index 00000000..cad272a1 --- /dev/null +++ b/docs/src/reference/docbook/samples/simple-application.xml @@ -0,0 +1,19 @@ + + + Simple sample application using the Spring Shell + +
+ Introduction + + This sample demonstrates how to execute a MapReduce application and a script that interacts with HDFS inside a Spring based application. It does not use spring Batch or Spring Integration. + + The example code is located in the distribution directory + <spring-hadoop-install-dir>/samples/wordcount. +
+