net.corda.jackson

## Class StringToMethodCallParser<T>

- net.corda.jackson.StringToMethodCallParser<T>

-     public class StringToMethodCallParser<T>

  This class parses strings in a format designed for human usability into `class StringToMethodCallParser.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 `class StringToMethodCallParser.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

  - The target class must be either a Kotlin class, or a Java class compiled with the -parameters command line switch, as the class relies on knowing the names of parameters which isn't data provided by default by the Java compiler.

  - Vararg methods are not supported, as the type information that'd be required is missing.

  - Method overloads that have identical parameter names but different types can't be handled, because often a string could map to multiple types, so which one to use is ambiguous. If you want your interface to be usable with this utility make sure the parameter and method names don't rely on type overloading.

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

  `
  See Also:
    `class StringToMethodCallParser.ParsedMethodCall`, Yaml, java.lang.Object, online Yaml parser, `class StringToMethodCallParser.ParsedMethodCall`

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class and Description
    --- | ---
    `static class` | `StringToMethodCallParser.Companion`
    `class` | `StringToMethodCallParser.ParsedMethodCall`

  - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static StringToMethodCallParser.Companion` | `Companion`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `StringToMethodCallParser(java.lang.Class<? extends T> targetType, com.fasterxml.jackson.databind.ObjectMapper om)` This class parses strings in a format designed for human usability into `class StringToMethodCallParser.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.
    `StringToMethodCallParser(java.lang.Class<? extends T> targetType)` This class parses strings in a format designed for human usability into `class StringToMethodCallParser.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.
    `StringToMethodCallParser(kotlin.reflect.KClass<? extends T> targetType)` Same as the regular constructor but takes a Kotlin reflection KClass instead of a Java Class.

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `java.util.Map<java.lang.String,java.lang.String>` | `getAvailableCommands()` Returns a string-to-string map of commands to a string describing available parameter types.
    `com.google.common.collect.Multimap<java.lang.String,java.lang.reflect.Method>` | `getMethodMap()` The methods that can be invoked via this parser.
    `java.util.Map<java.lang.String,java.util.List>` | `getMethodParamNames()` A map of method name to parameter names for the target type.
    `java.util.List<java.lang.String>` | `paramNamesFromConstructor(java.lang.reflect.Constructor<?> ctor)` Uses either Kotlin or Java 8 reflection to learn the names of the parameters to a constructor.
    `java.util.List<java.lang.String>` | `paramNamesFromMethod(java.lang.reflect.Method method)` Uses either Kotlin or Java 8 reflection to learn the names of the parameters to a method.
    `StringToMethodCallParser.ParsedMethodCall` | `parse(T target, java.lang.String command)` Parses the given command as a call on the target type. The target should be specified, if it's null then the resulting `class StringToMethodCallParser.ParsedMethodCall` can't be invoked, just inspected.
    `java.lang.Object[]` | `parseArguments(java.lang.String methodNameHint, java.util.List<? extends kotlin.Pair<java.lang.String,? extends java.lang.Class<?>>> parameters, java.lang.String args)` Parses only the arguments string given the info about parameter names and types.

- - ### Field Detail

    - #### Companion

          public static StringToMethodCallParser.Companion Companion

  - ### Constructor Detail

    - #### StringToMethodCallParser

          public StringToMethodCallParser(java.lang.Class<? extends T> targetType,
                                          com.fasterxml.jackson.databind.ObjectMapper om)

      This class parses strings in a format designed for human usability into `class StringToMethodCallParser.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 `class StringToMethodCallParser.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

      - The target class must be either a Kotlin class, or a Java class compiled with the -parameters command line switch, as the class relies on knowing the names of parameters which isn't data provided by default by the Java compiler.

      - Vararg methods are not supported, as the type information that'd be required is missing.

      - Method overloads that have identical parameter names but different types can't be handled, because often a string could map to multiple types, so which one to use is ambiguous. If you want your interface to be usable with this utility make sure the parameter and method names don't rely on type overloading.

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

      `
      See Also:
        `class StringToMethodCallParser.ParsedMethodCall`, Yaml, java.lang.Object, online Yaml parser, `class StringToMethodCallParser.ParsedMethodCall`

    - #### StringToMethodCallParser

          public StringToMethodCallParser(java.lang.Class<? extends T> targetType)

      This class parses strings in a format designed for human usability into `class StringToMethodCallParser.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 `class StringToMethodCallParser.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

      - The target class must be either a Kotlin class, or a Java class compiled with the -parameters command line switch, as the class relies on knowing the names of parameters which isn't data provided by default by the Java compiler.

      - Vararg methods are not supported, as the type information that'd be required is missing.

      - Method overloads that have identical parameter names but different types can't be handled, because often a string could map to multiple types, so which one to use is ambiguous. If you want your interface to be usable with this utility make sure the parameter and method names don't rely on type overloading.

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

      `
      See Also:
        `class StringToMethodCallParser.ParsedMethodCall`, Yaml, java.lang.Object, online Yaml parser, `class StringToMethodCallParser.ParsedMethodCall`

    - #### StringToMethodCallParser

          public StringToMethodCallParser(kotlin.reflect.KClass<? extends T> targetType)

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

      See Also:
        Class

  - ### Method Detail

    - #### getMethodMap

          public com.google.common.collect.Multimap<java.lang.String,java.lang.reflect.Method> getMethodMap()

      The methods that can be invoked via this parser.

    - #### getMethodParamNames

          public java.util.Map<java.lang.String,java.util.List> getMethodParamNames()

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

    - #### paramNamesFromMethod

          public java.util.List<java.lang.String> paramNamesFromMethod(java.lang.reflect.Method method)

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

    - #### paramNamesFromConstructor

          public java.util.List<java.lang.String> paramNamesFromConstructor(java.lang.reflect.Constructor<?> ctor)

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

    - #### parse

          public StringToMethodCallParser.ParsedMethodCall parse(T target,
                                                                 java.lang.String command)

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

      See Also:
        `class StringToMethodCallParser.ParsedMethodCall`

    - #### parseArguments

          public java.lang.Object[] parseArguments(java.lang.String methodNameHint,
                                                   java.util.List<? extends kotlin.Pair<java.lang.String,? extends java.lang.Class<?>>> parameters,
                                                   java.lang.String args)

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

      Parameters:
        `methodNameHint` - A name that will be used in exceptions if thrown; not used for any other purpose.

    - #### getAvailableCommands

          public java.util.Map<java.lang.String,java.lang.String> getAvailableCommands()

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