Using the Java/Kotlin HTTP-RPC client

In the Corda 5 Developer Preview, you can send requests and retrieve their responses via the HTTP API in two ways:

HttpRpcClient simplifies Java/Kotlin calls to the HTTP-RPC service.

Implement HttpRpcClient

HttpRpcClient translates a standard interface call on the HTTP-RPC client side JVM into an HTTP remote communication. It then waits for the server to respond. The interface call is completed when the server responds with a result.

Here is an example of an RPCOps interface from the HTTP client side:

@HttpRpcResource(
        name = "HealthCheckAPI",
        description = "Health Check",
        path = "health/"
)
interface HealthCheckAPI : RPCOps {
    @HttpRpcPOST(
            path = "plusone/{number}",
            title = "AddOne",
            description = "Add One"
    )
    fun plus(
            @HttpRpcPathParameter number: Long
    ): Long
}

The corresponding remote interface HttpRpcClient in Java:

  1. Creates the HttpRpcClient and binds it to HealthCheckAPI.
  2. When the client starts, produces HttpRpcConnection and uses this to obtain the proxy. (proxy is an instance of a dynamic proxy which translates interface calls into remote calls to the HTTP-RPC server side.)
  3. Makes the remote HTTP-RPC call.
HttpRpcClient<HealthCheckAPI> client = new HttpRpcClient<>(...);

try (client) {
    HttpRpcConnection<HealthCheckAPI> connection = client.start();
    HealthCheckAPI proxy = connection.getProxy();
    assertEquals(3, proxy.plus(2L));
}

The code snippet in the example uses try-with-resource Java construct. This means HttpRpcClient is closed at the end of the try scope. Because HttpRpcClient is AutoCloseable, all the necessary tidy-up (including the release of all previously acquired resources) is completed.

Implement HttpRpcConnectionListener

HttpRpcClient contains a facility which allows listeners to be added so that they are notified when the connection goes up or down. It is perfectly legitimate to add a listener even before HttpRpcClient is started. Then when the start method is called and the HTTP connection is successfully established, the attached listener is notified about such an event.

Connection listeners need to implement the HttpRpcConnectionListener interface.

For more information, refer to HttpRpcClient and HttpRpcConnectionListener in the KDocs .

Was this page helpful?

Thanks for your feedback!

Chat with us

Chat with us on our #docs channel on slack. You can also join a lot of other slack channels there and have access to 1-on-1 communication with members of the R3 team and the online community.

Propose documentation improvements directly

Help us to improve the docs by contributing directly. It's simple - just fork this repository and raise a PR of your own - R3's Technical Writers will review it and apply the relevant suggestions.

We're sorry this page wasn't helpful. Let us know how we can make it better!

Chat with us

Chat with us on our #docs channel on slack. You can also join a lot of other slack channels there and have access to 1-on-1 communication with members of the R3 team and the online community.

Create an issue

Create a new GitHub issue in this repository - submit technical feedback, draw attention to a potential documentation bug, or share ideas for improvement and general feedback.

Propose documentation improvements directly

Help us to improve the docs by contributing directly. It's simple - just fork this repository and raise a PR of your own - R3's Technical Writers will review it and apply the relevant suggestions.