corda / net.corda.client.jackson / StringToMethodCallParser

StringToMethodCallParser

@ThreadSafe open class StringToMethodCallParser<in T : Any>

This class parses strings in a format designed for human usability into ParsedMethodCall objects representing a ready-to-invoke call on the given target object. The strings accepted by this class are a minor variant of Yaml and can be easily typed at a command line. Intended use cases include things like the Corda shell, text-based RPC dispatch, simple scripting and so on.

Syntax

The format of the string is as follows. The first word is the name of the method and must always be present. The rest, which is optional, is wrapped in curly braces and parsed as if it were a Yaml object. The keys of this object are then mapped to the parameters of the method via the usual Jackson mechanisms. The standard java.lang.Object methods are excluded.

One convenient feature of Yaml is that barewords collapse into strings, thus you can write a call like the following:

    fun someCall(note: String, option: Boolean)

    someCall note: This is a really helpful feature, option: true

... and it will be parsed in the intuitive way. Quotes are only needed if you want to put a comma into the string.

There is an online Yaml parser which can be used to explore the allowed syntax.

Usage

This class is thread safe. Multiple strings may be parsed in parallel, and the resulting ParsedMethodCall objects may be reused multiple times and also invoked in parallel, as long as the underling target object is thread safe itself.

You may pass in an alternative ObjectMapper to control what types can be parsed, but it must be configured with the YAMLFactory for the class to work.

Limitations

Examples

    fun simple() = ...
    "simple"   -> runs the no-args function 'simple'

    fun attachmentExists(id: SecureHash): Boolean
    "attachmentExists id: b6d7e826e87"  -> parses the given ID as a SecureHash

    fun addNote(id: SecureHash, note: String)
    "addNote id: b6d7e826e8739ab2eb6e077fc4fba9b04fb880bb4cbd09bc618d30234a8827a4, note: Some note"

Types

ParsedMethodCall

inner class ParsedMethodCall<in T : Any> : Callable<Any?>

Exceptions

UnparseableCallException

open class UnparseableCallException : CordaException

Constructors

<init>

StringToMethodCallParser(targetType: KClass<out T>)

Same as the regular constructor but takes a Kotlin reflection KClass instead of a Java Class.

StringToMethodCallParser(targetType: Class<out T>, om: ObjectMapper = JacksonSupport.createNonRpcMapper(YAMLFactory()))

This class parses strings in a format designed for human usability into ParsedMethodCall objects representing a ready-to-invoke call on the given target object. The strings accepted by this class are a minor variant of Yaml and can be easily typed at a command line. Intended use cases include things like the Corda shell, text-based RPC dispatch, simple scripting and so on.

Properties

availableCommands

val availableCommands: Map<String, String>

Returns a string-to-string map of commands to a string describing available parameter types.

methodMap

val methodMap: Multimap<String, Method>

The methods that can be invoked via this parser.

methodParamNames

val methodParamNames: Map<String, List<String>>

A map of method name to parameter names for the target type.

Functions

paramNamesFromConstructor

open fun paramNamesFromConstructor(ctor: Constructor<*>): List<String>

Uses either Kotlin or Java 8 reflection to learn the names of the parameters to a constructor.

paramNamesFromMethod

open fun paramNamesFromMethod(method: Method): List<String>

Uses either Kotlin or Java 8 reflection to learn the names of the parameters to a method.

parse

fun parse(target: T?, command: String): ParsedMethodCall<T>

Parses the given command as a call on the target type. The target should be specified, if it's null then the resulting ParsedMethodCall can't be invoked, just inspected.

parseArguments

fun parseArguments(methodNameHint: String, parameters: List<Pair<String, Type>>, args: String): Array<Any?>

Parses only the arguments string given the info about parameter names and types.

Extension Functions

contextLogger

fun Any.contextLogger(): Logger

When called from a companion object, returns the logger for the enclosing class.