ExternalVendorCode/corda
1
0
Fork 0
mirror of https://github.com/corda/corda.git synced 2025-02-21 09:51:57 +00:00
Code Issues Actions 2 Packages Projects Releases Wiki Activity

Mirrors changes to shell docs.

Browse Source
This commit is contained in:
Joel Dudley 2017-12-21 17:04:47 +00:00 committed by GitHub
parent df3afb2dc1
commit 2144320009
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
1 changed files with 135 additions and 85 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

220
docs/source/shell.rst
View File

@ -7,70 +7,127 @@
Shell Shell
===== =====
The Corda shell is an embedded command line that allows an administrator to control and monitor the node. .. contents::
Some of its features include:
* Invoking any of the RPCs the node exposes to applications. The Corda shell is an embedded command line that allows an administrator to control and monitor a node. It is based on
* Starting flows. the `CRaSH`_ shell and supports many of the same features. These features include:
* View a dashboard of threads, heap usage, VM properties.
* Uploading and downloading zips from the attachment store.
* Issue SQL queries to the underlying database.
* View JMX metrics and monitoring exports.
* UNIX style pipes for both text and objects, an ``egrep`` command and a command for working with columnular data.
.. note:: A future version of Corda will add SSH access to the node. * Invoking any of the node's RPC methods
* Viewing a dashboard of threads, heap usage, VM properties
* Uploading and downloading attachments
* Issuing SQL queries to the underlying database
* Viewing JMX metrics and monitoring exports
* UNIX style pipes for both text and objects, an ``egrep`` command and a command for working with columnular data
It is based on the popular `CRaSH`_ shell used in various other projects and supports many of the same features. In development mode, the shell will display in the node's terminal window. It may be disabled by passing the
``--no-local-shell`` flag when running the node.
The shell may be disabled by passing the ``--no-local-shell`` flag to the node. Interacting with the node via the shell
---------------------------------------
Getting help The shell interacts with the node by issuing RPCs (remote procedure calls). You make an RPC from the shell by typing
------------ ``run`` followed by the name of the desired RPC method. For example, you'd see a list of the registered flows on your
node by running:
You can run ``help`` to list the available commands. ``run registeredFlows``
The shell has a ``man`` command that can be used to get interactive help on many commands. You can also use the Some RPCs return a stream of events that will be shown on screen until you press Ctrl-C.
``--help`` or ``-h`` flags to a command to get info about what switches it supports.
Commands may have subcommands, in the same style as ``git``. In that case running the command by itself will You can find a list of the available RPC methods
list the supported subcommands. `here <https://docs.corda.net/api/kotlin/corda/net.corda.core.messaging/-corda-r-p-c-ops/index.html>`_.
Starting flows and performing remote method calls Flow commands
------------------------------------------------- *************
**Flows** are the way the ledger is changed. If you aren't familiar with them, please review ":doc:`flow-state-machines`" The shell also has special commands for working with flows:
first. The ``flow list`` command can be used to list the flows understood by the node, ``flow watch`` shows all the flows
currently running on the node with the result (or error) information in a user friendly way, ``flow start`` can be
used to start flows. The ``flow start`` command takes the class name of a flow, or *any unambiguous substring* and
then the data to be passed to the flow constructor. The unambiguous substring feature is helpful for reducing
the needed typing. If the match is ambiguous the possible matches will be printed out. If a flow has multiple
constructors then the names and types of the arguments will be used to try and determine which to use automatically.
If the match against available constructors is unclear, the reasons each available constructor failed to match
will be printed out. In the case of an ambiguous match, the first applicable will be used.
**RPCs** (remote procedure calls) are commands that can be sent to the node to query it, control it and manage it. * ``flow list`` lists the flows available on the node
RPCs don't typically do anything that changes the global ledger, but they may change node-specific data in the * ``flow watch`` shows all the flows currently running on the node with result (or error) information
database. Each RPC is one method on the ``CordaRPCOps`` interface, and may return a stream of events that will * ``flow start`` starts a flow. The ``flow start`` command takes the name of a flow class, or
be shown on screen until you press Ctrl-C. You perform an RPC by using ``run`` followed by the name. *any unambiguous substring* thereof, as well as the data to be passed to the flow constructor. If there are several
matches for a given substring, the possible matches will be printed out. If a flow has multiple constructors then the
names and types of the arguments will be used to try and automatically determine which one to use. If the match
against available constructors is unclear, the reasons each available constructor failed to match will be printed
out. In the case of an ambiguous match, the first applicable constructor will be used
.. raw:: html Parameter syntax
****************
<center><b><a href="api/kotlin/corda/net.corda.core.messaging/-corda-r-p-c-ops/index.html">Documentation of available RPCs</a></b><p></center> Parameters are passed to RPC or flow commands using a syntax called `Yaml`_ (yet another markup language), a
simple JSON-like language. The key features of Yaml are:
Whichever form of change is used, there is a need to provide *parameters* to either the RPC or the flow * Parameters are separated by commas
constructor. Because parameters can be any arbitrary Java object graph, we need a convenient syntax to express * Each parameter is specified as a ``key: value`` pair
this sort of data. The shell uses a syntax called `Yaml`_ to do this.
Data syntax * There **MUST** to be a space after the colon, otherwise you'll get a syntax error
-----------
Yaml (yet another markup language) is a simple JSON-like way to describe object graphs. It has several features * Strings do not need to be surrounded by quotes unless they contain commas, colons or embedded quotes
that make it helpful for our use case, like a lightweight syntax and support for "bare words" which mean you can * Class names must be fully-qualified (e.g. ``java.lang.String``)
often skip the quotes around strings. Here is an example of how this syntax is used:
.. note:: If your CorDapp is written in Java, named arguments won't work unless you compiled the node using the
``-parameters`` argument to javac. See :doc:`generating-a-node` for how to specify it via Gradle.
Creating an instance of a class
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Class instances are created using curly-bracket syntax. For example, if we have a ``Campaign`` class with the following
constructor:
``data class Campaign(val name: String, val target: Int)``
Then we could create an instance of this class to pass as a parameter as follows:
``newCampaign: { name: Roger, target: 1000 }``
Where ``newCampaign`` is a parameter of type ``Campaign``.
Mappings from strings to types
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Several parameter types can automatically be mapped from strings. See the `defined parsers`_ for more information. We
cover the most common types here.
Amount
~~~~~~
A parameter of type ``Amount<Currency>`` can be written as either:
* A dollar ($), pound (£) or euro (€) symbol followed by the amount as a decimal
* The amount as a decimal followed by the ISO currency code (e.g. "100.12 CHF")
OpaqueBytes
~~~~~~~~~~~
A parameter of type ``OpaqueBytes`` can be provided as a string, which will be automatically converted to
``OpaqueBytes``.
Party
~~~~~
A parameter of type ``Party`` can be written in several ways:
* By using the node's full name: ``"O=Monogram Bank,L=Sao Paulo,C=GB"``
* By specifying the organisation name only: ``"Monogram Bank"``
* By specifying any other non-ambiguous part of the name: ``"Sao Paulo"`` (if only one network node is located in Sao
Paulo)
Instant
~~~~~~~
A parameter of type ``Instant`` can be written as follows: ``"2017-12-22T00:00:00Z"``.
Examples
^^^^^^^^
Starting a flow
~~~~~~~~~~~~~~~
We would start the ``CashIssue`` flow as follows:
``flow start CashIssue amount: $1000, issueRef: 1234, recipient: "O=Bank A,L=London,C=GB", notary: "O=Notary Service,OU=corda,L=London,C=GB"`` ``flow start CashIssue amount: $1000, issueRef: 1234, recipient: "O=Bank A,L=London,C=GB", notary: "O=Notary Service,OU=corda,L=London,C=GB"``
This invokes a constructor of a flow with the following prototype in the code: This breaks down as follows:
* ``flow start`` is a shell command for starting a flow
* ``CashIssue`` is the flow we want to start
* Each ``name: value`` pair after that is a flow constructor argument
This command invokes the following ``CashIssue`` constructor:
.. container:: codeset .. container:: codeset
@ -81,53 +138,47 @@ This invokes a constructor of a flow with the following prototype in the code:
val recipient: Party, val recipient: Party,
val notary: Party) : AbstractCashFlow(progressTracker) val notary: Party) : AbstractCashFlow(progressTracker)
Here, everything after ``CashIssue`` is specifying the arguments to the constructor of a flow. In Yaml, an object Querying the vault
is specified as a set of ``key: value`` pairs and in our form, we separate them by commas. There are a few things ~~~~~~~~~~~~~~~~~~
to note about this syntax:
* When a parameter is of type ``Amount<Currency>`` you can write it as either one of the dollar symbol ($), We would query the vault for ``IOUState`` states as follows:
pound (£), euro (€) followed by the amount as a decimal, or as the value followed by the ISO currency code
e.g. "100.12 CHF"
* ``OpaqueBytes`` is filled with the contents of whatever is provided as a string.
* ``Party`` objects are looked up by name.
* Strings do not need to be surrounded by quotes unless they contain a comma or embedded quotes. This makes it
a lot more convenient to type such strings.
Other types also have sensible mappings from strings. See `the defined parsers`_ for more information. ``run vaultQuery contractStateType: com.template.IOUState``
Nested objects can be created using curly braces, as in ``{ a: 1, b: 2}``. This is helpful when no particular This breaks down as follows:
parser is defined for the type you need, for instance, if an API requires a ``Pair<String, Int>``
which could be represented as ``{ first: foo, second: 123 }``.
.. note:: If your CorDapp is written in Java, * ``run`` is a shell command for making an RPC call
named arguments won't work unless you compiled using the ``-parameters`` argument to javac. * ``vaultQuery`` is the RPC call we want to make
See :doc:`generating-a-node` for how to specify it via Gradle. * ``contractStateType: com.template.IOUState`` is the fully-qualified name of the state type we are querying for
The same syntax is also used to specify the parameters for RPCs, accessed via the ``run`` command, like this:
``run registeredFlows``
Attachments Attachments
----------- ***********
The shell can be used to upload and download attachments from the node interactively. To learn more, see The shell can be used to upload and download attachments from the node. To learn more, see the tutorial
the tutorial ":doc:`tutorial-attachments`". ":doc:`tutorial-attachments`".
Getting help
************
You can type ``help`` in the shell to list the available commands, and ``man`` to get interactive help on many
commands. You can also pass the ``--help`` or ``-h`` flags to a command to get info about what switches it supports.
Commands may have subcommands, in the same style as ``git``. In that case, running the command by itself will
list the supported subcommands.
Extending the shell Extending the shell
------------------- -------------------
The shell can be extended using commands written in either Java or `Groovy`_ (Groovy is a scripting language that The shell can be extended using commands written in either Java or `Groovy`_ (a Java-compatible scripting language).
is Java compatible). Such commands have full access to the node internal APIs and thus can be used to achieve These commands have full access to the node's internal APIs and thus can be used to achieve almost anything.
almost anything.
A full tutorial on how to write such commands is out of scope for this documentation, to learn more please A full tutorial on how to write such commands is out of scope for this documentation. To learn more, please refer to
refer to the `CRaSH`_ documentation. New commands can be placed in the ``shell-commands`` subdirectory in the the `CRaSH`_ documentation. New commands are placed in the ``shell-commands`` subdirectory in the node directory. Edits
node directory. Edits to existing commands will be used automatically, but at this time commands added after the to existing commands will be used automatically, but currently commands added after the node has started won't be
node has started won't be automatically detected. Commands should be named in all lower case with either a automatically detected. Commands must have names all in lower-case with either a ``.java`` or ``.groovy`` extension.
``.java`` or ``.groovy`` extension.
.. warning:: Commands written in Groovy ignore Java security checks, so have unrestricted access to node and JVM .. warning:: Commands written in Groovy ignore Java security checks, so have unrestricted access to node and JVM
internals regardless of any sandboxing that may be in place. Don't allow untrusted users to edit files in the internals regardless of any sandboxing that may be in place. Don't allow untrusted users to edit files in the
shell-commands directory! shell-commands directory!
Limitations Limitations
@ -135,14 +186,13 @@ Limitations
The shell will be enhanced over time. The currently known limitations include: The shell will be enhanced over time. The currently known limitations include:
* SSH access is currently not available. * There is no command completion for flows or RPCs
* There is no command completion for flows or RPCs. * Command history is not preserved across restarts
* Command history is not preserved across restarts. * The ``jdbc`` command requires you to explicitly log into the database first
* The ``jdbc`` command requires you to explicitly log into the database first. * Commands placed in the ``shell-commands`` directory are only noticed after the node is restarted
* Commands placed in the ``shell-commands`` directory are only noticed after the node is restarted. * The ``jul`` command advertises access to logs, but it doesn't work with the logging framework we're using
* The ``jul`` command advertises access to logs, but it doesn't work with the logging framework we're using.
.. _Yaml: http://www.yaml.org/spec/1.2/spec.html .. _Yaml: http://www.yaml.org/spec/1.2/spec.html
.. _the defined parsers: api/kotlin/corda/net.corda.client.jackson/-jackson-support/index.html .. _defined parsers: api/kotlin/corda/net.corda.client.jackson/-jackson-support/index.html
.. _Groovy: http://groovy-lang.org/ .. _Groovy: http://groovy-lang.org/
.. _CRaSH: http://www.crashub.org/ .. _CRaSH: http://www.crashub.org/