This guide gets you started with Kotlin gRPC on Android with a simple working example.
Quick start
This guide gets you started with Kotlin gRPC on Android with a simple working example.
Prerequisites
Kotlin
version 1.3 or higher
JDK
version 7 or higher
Android SDK, API level 16 or higher
Install
Android Studio
or the Android
command-line tools
.
Let other tools and scripts know where to find your Android SDK by setting
the following environment variable:
$
export
ANDROID_SDK_ROOT
=
"<path-to-your-android-sdk>"
An android device set up for
USB debugging
or an
Android Virtual Device
Note
gRPC Kotlin does not support running a server on an Android device. For this
quick start, the Android client app will connect to a server running on your
local (non-Android) computer.
Get the example code
The example code is part of the
grpc-kotlin
repo.
Download the repo as a zip file
and unzip it, or clone
the repo:
$ git clone https://github.com/grpc/grpc-kotlin
Change to the examples directory:
$
cd
grpc-kotlin/examples
Run the example
Compile the server:
Run the server:
$ ./server/build/install/server/bin/hello-world-server
Server started, listening on
50051
From another terminal, build the client and install it on your device:
$ ./gradlew :android:installDebug
Launch the client app from your device.
Type “Alice” in the
Name
box and click
Send
. You’ll see the
following response:
Hello Alice
Congratulations! You’ve just run a client-server application with gRPC.
Update the gRPC service
In this section you’ll update the application by adding an extra server method.
The gRPC service is defined using
protocol buffers
. To learn more about
how to define a service in a
.proto
file see
Basics tutorial
. For now, all
you need to know is that both the server and the client stub have a
SayHello()
RPC method that takes a
HelloRequest
parameter from the client and returns a
HelloReply
from the server, and that the method is defined like this:
// The greeting service definition.
service
Greeter {
// Sends a greeting
rpc
SayHello (HelloRequest)
returns
(HelloReply) {}
}
// The request message containing the user's name.
message
HelloRequest
{
string
name
=
1
;
}
// The response message containing the greetings
message
HelloReply
{
string
message
=
1
;
}
Open
helloworld/hello_world.proto
from the
protos/src/main/proto/io/grpc/examples
folder, and add a
new
SayHelloAgain()
method, with the same request and response types:
// The greeting service definition.
service
Greeter {
// Sends a greeting
rpc
SayHello (HelloRequest)
returns
(HelloReply) {}
// Sends another greeting
rpc
SayHelloAgain (HelloRequest)
returns
(HelloReply) {}
}
// The request message containing the user's name.
message
HelloRequest
{
string
name
=
1
;
}
// The response message containing the greetings
message
HelloReply
{
string
message
=
1
;
}
Remember to save the file!
Update the app
When you build the example, the build process regenerates
HelloWorldProtoGrpcKt.kt
,
which contains the generated gRPC client and server classes. This also
regenerates classes for populating, serializing, and retrieving our request and
response types.
However, you still need to implement and call the new method in the
hand-written parts of the example app.
Update the server
Follow the instructions given in
Update the
server
of the Kotlin
quick start page.
Update the client
Follow these steps:
Open
helloworld/MainActivity.kt
from the
client/src/main/kotlin/io/grpc/examples
folder.
Locate the function containing the call to
sayHello()
. You’ll see these
lines of code:
val
response = greeter.sayHello(request)
responseText.text = response.message
Add a call to
sayHelloAgain()
and change how the response message is
created. Replace the lines of code above with the following:
val
response = greeter.sayHello(request)
val
againResponse = greeter.sayHelloAgain(request)
val
message =
"
${response.message}
\n
${againResponse.message}
"
responseText.text = message
Run the updated app
Run the client and server like you did before. Execute the following commands
from the
examples
directory:
Compile the server:
Run the server:
$ ./server/build/install/server/bin/hello-world-server
Server started, listening on
50051
From another terminal, build the client and install it on your device:
$ ./gradlew :android:installDebug
Launch the client app from your device.
Type “Alice” in the
Message
box and click
Send
. You’ll see the
following response:
Hello Alice
Hello again Alice
What’s next