From a8728ccb5ba2905ca7308a5c7a6f45e49951c76c Mon Sep 17 00:00:00 2001 From: Maarten Tutak Date: Wed, 13 Dec 2017 18:46:26 +0100 Subject: [PATCH] docs: add example of Java gRPC client --- docs/grpc/java.md | 184 ++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 184 insertions(+) create mode 100644 docs/grpc/java.md diff --git a/docs/grpc/java.md b/docs/grpc/java.md new file mode 100644 index 00000000..23a0878e --- /dev/null +++ b/docs/grpc/java.md @@ -0,0 +1,184 @@ + +# How to write a Java gRPC client for the Lightning Network Daemon + +This section enumerates what you need to do to write a client that communicates +with lnd in Java. We'll be using Maven as our build tool. + +### Prerequisites + - Maven + - running lnd + - running btcd + +### Setup and Installation +#### Project Structure +``` +. +├── pom.xml +└── src + ├── main + ├── java + │ └── Main.java + ├── proto + ├── google + │ └── api + │ ├── annotations.proto + │ └── http.proto + └── lnrpc + └── rpc.proto + +``` +Note the ***proto*** folder, where all the proto files are kept. + + - [rpc.proto](https://github.com/lightningnetwork/lnd/blob/master/lnrpc/rpc.proto) + - [annotations.proto](https://github.com/grpc-ecosystem/grpc-gateway/blob/master/third_party/googleapis/google/api/annotations.proto) + - [http.proto](https://github.com/grpc-ecosystem/grpc-gateway/blob/master/third_party/googleapis/google/api/http.proto) + +#### pom.xml +``` + + 1.8.0 + +``` +The following dependencies are required. +``` + + + io.grpc + grpc-netty + ${grpc.version} + + + io.grpc + grpc-protobuf + ${grpc.version} + + + io.grpc + grpc-stub + ${grpc.version} + + + io.netty + netty-tcnative-boringssl-static + 2.0.7.Final + + +``` +In the build section, we'll need to configure the following things : +``` + + + + kr.motd.maven + os-maven-plugin + 1.5.0.Final + + + + + org.xolstice.maven.plugins + protobuf-maven-plugin + 0.5.0 + + com.google.protobuf:protoc:3.4.0:exe:${os.detected.classifier} + grpc-java + io.grpc:protoc-gen-grpc-java:${grpc.version}:exe:${os.detected.classifier} + + + + + compile + compile-custom + + + + + + +``` +#### Main.java +```java +import io.grpc.ManagedChannel; +import io.grpc.netty.GrpcSslContexts; +import io.grpc.netty.NettyChannelBuilder; +import io.netty.handler.ssl.SslContext; +import lnrpc.LightningGrpc; +import lnrpc.LightningGrpc.LightningBlockingStub; +import lnrpc.Rpc.*; + +import javax.net.ssl.SSLException; +import java.io.File; + +public class Main { + + private static final String CERT_PATH = "/Users/user/Library/Application Support/Lnd/tls.cert"; + private static final String HOST = "localhost"; + private static final int PORT = 10009; + + public static void main(String... args) throws SSLException { + SslContext sslContext = GrpcSslContexts.forClient().trustManager(new File(CERT_PATH)).build(); + NettyChannelBuilder channelBuilder = NettyChannelBuilder.forAddress(HOST, PORT); + ManagedChannel channel = channelBuilder.sslContext(sslContext).build(); + LightningBlockingStub stub = LightningGrpc.newBlockingStub(channel); + + GetInfoResponse response = stub.getInfo(GetInfoRequest.getDefaultInstance()); + System.out.println(response.getIdentityPubkey()); + } +} +``` +#### Running the example +Execute the following command in the directory where the **pom.xml** file is located. +``` +mvn compile exec:java -Dexec.mainClass="Main" -Dexec.cleanupDaemonThreads=false +``` +##### Sample ouput +``` +[INFO] Scanning for projects... +[INFO] ------------------------------------------------------------------------ +[INFO] Detecting the operating system and CPU architecture +[INFO] ------------------------------------------------------------------------ +[INFO] os.detected.name: osx +[INFO] os.detected.arch: x86_64 +[INFO] os.detected.version: 10.13 +[INFO] os.detected.version.major: 10 +[INFO] os.detected.version.minor: 13 +[INFO] os.detected.classifier: osx-x86_64 +[INFO] +[INFO] ------------------------------------------------------------------------ +[INFO] Building lightning-client 0.0.1-SNAPSHOT +[INFO] ------------------------------------------------------------------------ +[INFO] +[INFO] --- protobuf-maven-plugin:0.5.0:compile (default) @ lightning-client --- +[INFO] Compiling 3 proto file(s) to /Users/user/Documents/Projects/lightningclient/target/generated-sources/protobuf/java +[INFO] +[INFO] --- protobuf-maven-plugin:0.5.0:compile-custom (default) @ lightning-client --- +[INFO] Compiling 3 proto file(s) to /Users/user/Documents/Projects/lightningclient/target/generated-sources/protobuf/grpc-java +[INFO] +[INFO] --- maven-resources-plugin:2.6:resources (default-resources) @ lightning-client --- +[INFO] Using 'UTF-8' encoding to copy filtered resources. +[INFO] Copying 0 resource +[INFO] Copying 3 resources +[INFO] Copying 3 resources +[INFO] +[INFO] --- maven-compiler-plugin:3.1:compile (default-compile) @ lightning-client --- +[INFO] Changes detected - recompiling the module! +[INFO] Compiling 12 source files to /Users/user/Documents/Projects/lightningclient/target/classes +[INFO] +[INFO] --- exec-maven-plugin:1.6.0:java (default-cli) @ lightning-client --- +032562215c38dede6f1f2f262ff4c8db58a38ecf889e8e907eee8e4c320e0b5e81 +[INFO] ------------------------------------------------------------------------ +[INFO] BUILD SUCCESS +[INFO] ------------------------------------------------------------------------ +[INFO] Total time: 7.408 s +[INFO] Finished at: 2018-01-13T19:05:49+01:00 +[INFO] Final Memory: 30M/589M +[INFO] ------------------------------------------------------------------------ +``` + +### Java proto options + +There are 2 options available that can be used in the *rpc.proto* file : + +* option java_multiple_files = true; +* option java_package = "network.lightning.rpc"; +>The package you want to use for your generated Java classes. If no explicit java_package option is given in the .proto file, then by default the proto package (specified using the "package" keyword in the .proto file) will be used. However, proto packages generally do not make good Java packages since proto packages are not expected to start with reverse domain names. If not generating Java code, this option has no effect. \ No newline at end of file