Find file History
Robin Howlett
Latest commit 16a6762 May 22, 2015

README.md

![Bootstrap Shell](http://i.imgur.com/PypWRjx.png)

Bootstrap Shell is a Spring Shell-based framework to aid creating command-line interface (CLI) applications for API clients built on Spring Social Bootstrap SDK.

e.g. Mockbin CLI: an Bootstrap Shell-based CLI application for Mockbin powered by Spring Social Mockbin CLI Example

Spring Shell Influence

The underlying Spring Shell version is based on version 1.1.0.RELEASE but with the following modifications:

CLI applications based on Bootstrap Shell can also be executed from within an IDE, although the output is formatted for Terminals. Installing an ANSI-compatible console in your IDE is recommended e.g. ANSI Escape in Console for Eclipse.

Creating a CLI application for an API Client built on Spring Social Bootstrap SDK

The process of developing a CLI application for an API client based on Spring Social Bootstrap SDK consists of just a few steps:

  1. Create a base CLI class that extends BaseApiCli and specify the base package path to scan in the basePackages() method.
  2. Create a @Configuration class that declares an instance of an Spring Social Bootstrap SDK-based API client.
  3. Create @Component Command classes that either implement Spring Shell's CommandMarker or ExecutionProcessor interfaces.
  4. @Autowire the Spring Social Bootstrap SDK-based API client that was declared in the configuration.
  5. Create command methods annotated with @CliCommand that execute operations on the API client. Parameters annotated with @CliOption denote arguments to the command.

Multi-Step Commands

Traditionally, Spring Shell will execute a command and then return control to the terminal.

Multi-step commands allow interrupting this flow by adding additional control either before or after the original command has been invoked. This can be useful for user control of the CLI application e.g. paginating paged API responses.

  • If multi-step commands are desired, the Command class should extend the AbstractStepExecutionProcessor abstract class that adds multi-step support instead of implementing the CommandMarker or ExecutionProcessor interfaces.
  • Annotate multi-step Command methods with the additional @CliStepIndicator annotation
  • Implement the following methods:
    • handleStepExecutionResult(ParseResult invocationContext, Object stepResult)
    • hasMoreSteps(Object stepResult)
    • configureStep(Object stepResult)
    • executeStep(Object stepResult, Object stepConfig)

Multiple Command Output Formats

Traditionally, Spring Shell will log the output of a command result's toString() method.

If commands that support multiple output formats are desired, then the following steps are required:

  1. As the final argument to a Command method, add the following: @CliPrinter CliPrinterTypeConverter<XYZ> printer, where XYZ is the BaseApiResource type of the command result
    • By default, the @CliPrinter argument is bound to the CLI parameter p e.g. --p json. The key may be customized on the annotation.
    • A default value may also be specified on the @CliPrinter annotation
  2. Declare an instance of a converter that implements CliPrinterTypeConverter in the @Configuration class.
    • The bean name must follow the naming convention of "xyzOutputConverter", where xyz will be the argument value passed to the @CliPrinter CliPrinterTypeConverter command method argument e.g. jsonOutputConverter() will permit the following example command result to be printed as JSON: access-log --id 123456 --p json
    • Spring Shell Bootstrap CLI ships with JsonCliPrinterTypeConverter that will write the JSON representation of a BaseApiResource using Jackson's ObjectMapper.