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 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 support the command's actions. The plugin model is depicted in the following diagram

Note that the current plugin model loads all plugins under the same class loader. An open JIRA issue suggests providing a classloader per plugin to provide isolation.

<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>

@Component
public class HelloWorldCommands implements CommandMarker {

  // use any Spring annotations for Dependency Injection or other Spring 
  // interfaces as required.

  // methods with @Cli annotations go here

}

There are a few built in commands. Here is a listing of their class name and functionality

There are also a few commands that are provided by the AbstractShell class, these are

There are a few extension points that allow you to customize the shell. The extension points are the interfaces

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 precedence over any other implementations that maybe present on the classpath from other plugins.

To make cool "ASCII art" banners the website http://patorjk.com/software/taag is quite neat!

As this is a standard Spring application you can use Spring's ApplicationContext event infrastructure to communicate across plugins.

It has shown to be useful to provide a simple form of interception 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 ExecutionProcessor should be implemented instead of CommandMarker to access this functionality. The ExecutionProcessor interface is shown below

public interface ExecutionProcessor extends 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.
  * 
  * @param invocationContext target command context
  * @return the invocation target 
  */
 ParseResult beforeInvocation(ParseResult invocationContext);

 /**
  * Method called after successfully invoking the target command (described by 
  * {@link ParseResult}).
  * 
  * @param invocationContext target command context
  * @param result the invocation result
  */
 void afterReturningInvocation(ParseResult invocationContext, Object result);

 /**
  * 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
  */
 void afterThrowingInvocation(ParseResult invocationContext, Throwable thrown);

}

There are a few command line options that can be specified when starting the shell. They are

Scripts can be executed either by passing in the --cmdfile argument at startup or by executing the 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 comment using the // or ; characters.

The first step to creating a command is to implement the marker interface CommandMarker and to annotate your class with Spring's @Component annotation. (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:

@Component
public class HelloWorldCommands implements CommandMarker {
 
  // use any Spring annotations for Dependency Injection or other Spring interfaces 
  // as required.

  // methods with @Cli annotations go here  

}

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 {
 
  protected final Logger LOG = Logger.getLogger(getClass().getName());

  // methods with @Cli annotations go here  

}

	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.

There are three annotations used on methods and method arguments that define the main contract for interacting with the shell. These are:

Here is a simple use of these annotations in a command class

@Component
public class HelloWorldCommands implements CommandMarker {

  @CliAvailabilityIndicator({"hw simple"})
  public boolean isCommandAvailable() {
    return true;
  }

  @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) {

    return "Message = [" + message + "] Location = [" + location + "]";

  }
}

The method annotated with @CliAvailabilityIndicator is returning true so that the one and only command in this class is exposed to the shell to be invoked. If there were more commands in the class, you would list them as comma separated value.

The @CliCommand annotation is creating the 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 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 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 call other collaborating objects that were injected into the class via Spring.

The method argument types in this example are String, which doesn't present any issue with type conversion. You can specify methods with any rich object type as well as basic primitive types such as int, float etc. For all types other than those handled by the shell by default (basic types, Date, File) you will need to 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() representation.

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 directory. Maven has a similar plugin - the AppAssembler plugin.

The main class of the shell is org.springframework.shell.Bootstrap. As long as you place other plugins, perhaps developed independently, on the classpath, the Bootstrap class will incorporate them into the shell.

The sample application named 'helloworld' contains three 'hw' commands, they are 'hw simple', 'hw complex' and 'hw enum' and demonstrate simple to intermediate level usage of the @Cli annotation classes for creating commands.

The example code is located in the distribution directory <spring-shell-install-dir>/samples/helloworld.

To build the example cd to the helloworld directory and execute 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.

The HelloWorldCommands class is show below

package org.springframework.shell.samples.helloworld.commands;

import org.springframework.shell.core.CommandMarker;
import org.springframework.shell.core.annotation.CliAvailabilityIndicator;
import org.springframework.shell.core.annotation.CliCommand;
import org.springframework.shell.core.annotation.CliOption;
import org.springframework.stereotype.Component;

@Component
public class HelloWorldCommands implements CommandMarker {
	
	private boolean simpleCommandExecuted = false;
	
	@CliAvailabilityIndicator({"hw simple"})
	public boolean isSimpleAvailable() {
		//always available
		return true;
	}
	
	@CliAvailabilityIndicator({"hw complex", "hw enum"})
	public boolean isComplexAvailable() {
		if (simpleCommandExecuted) {
			return true;
		} else {
			return false;
		}
	}
		
	@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) {		
		simpleCommandExecuted = true;
		return "Message = [" + message + "] Location = [" + location + "]";
	}
	
	@CliCommand(value = "hw complex", help = "Print a complex hello world message")
	public String hello(
		@CliOption(key = { "message" }, mandatory = true, help = "The hello world message") final String message,
		@CliOption(key = { "name1"}, mandatory = true, help = "Say hello to the first name") final String name1,
		@CliOption(key = { "name2" }, mandatory = true, help = "Say hello to a second name") final String name2,
		@CliOption(key = { "time" }, mandatory = false, specifiedDefaultValue="now", help = "When you are saying hello") final String time,
		@CliOption(key = { "location" }, mandatory = false, help = "Where you are saying hello") final String location) {		
		return "Hello " + name1 + " and " + name2 + ". Your special message is "  + message + ". time=[" + time + "] location=[" + location + "]";
	}
	
	@CliCommand(value = "hw enum", help = "Print a simple hello world message from an enumerated value")
	public String eenum(
		@CliOption(key = { "message" }, mandatory = true, help = "The hello world message") final MessageType message){		
		return "Hello.  Your special enumerated message is " + message;
	}
	
	enum MessageType {		
		Type1("type1"),
		Type2("type2"),
		Type3("type3");
		
		private String type;
		
		private MessageType(String type){
			this.type = type;
		}
		
		public String getType(){
			return type;
		}
	}
}

The use of the @CliAvailabilityIndicator annotation on two methods, isSimpleAvailable and isComplexAvailable shows how you can enable the presence of the 'hw complex' and 'hw enum' commands only if the 'hw simple' command was executed.

Here is an example session showing the behavior.

The 'hw enum' command shows how the shell supports the use of an enumeration as command method arguments.