documentation/android-channel-builder.md

# AndroidChannelBuilder

 The `grpc-android` package provides access to the
`AndroidChannelBuilder` class. Given an Android Context, this builder
registers a network event listener upon channel construction.  The listener
automatically responds to changes in the device's network state, avoiding
delays and interrupted RPCs that may otherwise occur.

By default, gRPC uses exponential backoff to recover from connection failures.
Depending on the scheduled backoff delay when the device regains connectivity,
this could result in a  one minute or longer delay before gRPC re-establishes
the connection. This delay is removed when `AndroidChannelBuilder` is provided
with the app's Android Context.  Notifications from the network listener
cause the channel to immediately reconnect upon network recovery.

On Android API levels 24+, `AndroidChannelBuilder`'s network listener mechanism
allows graceful switching from cellular to wifi connections. When an Android
device on a cellular network connects to a wifi network, there is a brief
(typically 30 second) interval when both cellular and wifi networks remain
available, then any connections on the cellular network are terminated.  By
listening for changes in the device's default network, `AndroidChannelBuilder`
sends new RPCs via wifi rather than using an already-established cellular
connection. Without listening for pending network changes, new RPCs sent on an
already established cellular connection would fail when the device terminates
cellular connections.

***Note:*** *Currently, `AndroidChannelBuilder` is only compatible with gRPC
OkHttp. We plan to offer additional Android-specific features compatible with
both the OkHttp and Cronet transports in the future, but the network listener
mechanism is only necessary with OkHttp; the Cronet library internally handles
connection management on Android devices.*

## Example usage:

In your `build.gradle` file, include a dependency on both `io.grpc:grpc-android` and
`io.grpc:grpc-okhttp`.

You also need permission to access the device's network state in your
`AndroidManifest.xml`:

```
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
```

When constructing your channel, use `AndroidChannelBuilder` and provide it with
your app's Context:

```
import io.grpc.android.AndroidChannelBuilder;
...
ManagedChannel channel = AndroidChannelBuilder.forAddress("localhost", 8080)
    .context(getApplicationContext())
    .build();
```

You continue to use the constructed channel exactly as you would any other
channel. gRPC will now monitor and respond to the device's network state
automatically. When you shutdown the managed channel, the network listener
registered by `AndroidChannelBuilder` will be unregistered.