Repository files navigation

gRPC-Java supports Java 8 and later. Android minSdkVersion 21 (Lollipop) andlater are supported withJava 8 language desugaring.

TLS usage on Android typically requires Play Services Dynamic Security Provider.Please see theSecurity Readme.

Older Java versions are not directly supported, but a branch remains availablefor fixes and releases. SeegRFC P5 JDK Version SupportPolicy.

For a guided tour, take a look at thequick startguide or the more explanatorygRPCbasics.

Theexamples and theAndroid exampleare standalone projects that showcase the usage of gRPC.

Downloadthe JARs. Or for Maven with non-Android, add to yourpom.xml:

<dependency>  <groupId>io.grpc</groupId>  <artifactId>grpc-netty-shaded</artifactId>  <version>1.71.0</version>  <scope>runtime</scope></dependency><dependency>  <groupId>io.grpc</groupId>  <artifactId>grpc-protobuf</artifactId>  <version>1.71.0</version></dependency><dependency>  <groupId>io.grpc</groupId>  <artifactId>grpc-stub</artifactId>  <version>1.71.0</version></dependency><dependency><!-- necessary for Java 9+-->  <groupId>org.apache.tomcat</groupId>  <artifactId>annotations-api</artifactId>  <version>6.0.53</version>  <scope>provided</scope></dependency>

Or for Gradle with non-Android, add to your dependencies:

runtimeOnly'io.grpc:grpc-netty-shaded:1.71.0'implementation'io.grpc:grpc-protobuf:1.71.0'implementation'io.grpc:grpc-stub:1.71.0'compileOnly'org.apache.tomcat:annotations-api:6.0.53'// necessary for Java 9+

For Android client, usegrpc-okhttp instead ofgrpc-netty-shaded andgrpc-protobuf-lite instead ofgrpc-protobuf:

implementation'io.grpc:grpc-okhttp:1.71.0'implementation'io.grpc:grpc-protobuf-lite:1.71.0'implementation'io.grpc:grpc-stub:1.71.0'compileOnly'org.apache.tomcat:annotations-api:6.0.53'// necessary for Java 9+

ForBazel, you can eitheruse Maven(with the GAVs from above), or use@io_grpc_grpc_java//api et al (see below).

Development snapshots are available inSonatypes's snapshotrepository.

For protobuf-based codegen, you can put your proto files in thesrc/main/protoandsrc/test/proto directories along with an appropriate plugin.

For protobuf-based codegen integrated with the Maven build system, you can useprotobuf-maven-plugin (Eclipse and NetBeans users should also look atos-maven-plugin'sIDE documentation):

<build>  <extensions>    <extension>      <groupId>kr.motd.maven</groupId>      <artifactId>os-maven-plugin</artifactId>      <version>1.7.1</version>    </extension>  </extensions>  <plugins>    <plugin>      <groupId>org.xolstice.maven.plugins</groupId>      <artifactId>protobuf-maven-plugin</artifactId>      <version>0.6.1</version>      <configuration>        <protocArtifact>com.google.protobuf:protoc:3.25.5:exe:${os.detected.classifier}</protocArtifact>        <pluginId>grpc-java</pluginId>        <pluginArtifact>io.grpc:protoc-gen-grpc-java:1.71.0:exe:${os.detected.classifier}</pluginArtifact>      </configuration>      <executions>        <execution>          <goals>            <goal>compile</goal>            <goal>compile-custom</goal>          </goals>        </execution>      </executions>    </plugin>  </plugins></build>

For non-Android protobuf-based codegen integrated with the Gradle build system,you can useprotobuf-gradle-plugin:

plugins {    id'com.google.protobuf' version'0.9.4'}protobuf {  protoc {    artifact="com.google.protobuf:protoc:3.25.5"  }  plugins {    grpc {      artifact='io.grpc:protoc-gen-grpc-java:1.71.0'    }  }  generateProtoTasks {    all()*.plugins {      grpc {}    }  }}

The prebuilt protoc-gen-grpc-java binary uses glibc on Linux. If you arecompiling on Alpine Linux, you may want to use theAlpine grpc-java packagewhich uses musl instead.

For Android protobuf-based codegen integrated with the Gradle build system, alsouse protobuf-gradle-plugin but specify the 'lite' options:

plugins {    id'com.google.protobuf' version'0.9.4'}protobuf {  protoc {    artifact="com.google.protobuf:protoc:3.25.5"  }  plugins {    grpc {      artifact='io.grpc:protoc-gen-grpc-java:1.71.0'    }  }  generateProtoTasks {    all().each {task->      task.builtins {        java { option'lite' }      }      task.plugins {        grpc { option'lite' }      }    }  }}

ForBazel, use theproto_libraryand thejava_proto_library (noload() required)andload("@io_grpc_grpc_java//:java_grpc_library.bzl", "java_grpc_library") (from this project), as inthis exampleBUILD.bazel.

APIs annotated with@Internal are for internal use by the gRPC library andshould not be used by gRPC users. APIs annotated with@ExperimentalApi aresubject to change in future releases, and library code that other projectsmay depend on should not use these APIs.

We recommend using thegrpc-java-api-checker(anError Prone plugin)to check for usages of@ExperimentalApi and@Internal in any library codethat depends on gRPC. It may also be used to check for@Internal usage orunintended@ExperimentalApi consumption in non-library code.

If you are making changes to gRPC-Java, see thecompilinginstructions.

At a high level there are three distinct layers to the library:Stub,Channel, andTransport.

The Stub layer is what is exposed to most developers and provides type-safebindings to whatever datamodel/IDL/interface you are adapting. gRPC comes withaplugin to theprotocol-buffers compiler that generates Stub interfaces out of.proto files,but bindings to other datamodel/IDL are easy and encouraged.

The Channel layer is an abstraction over Transport handling that is suitable forinterception/decoration and exposes more behavior to the application than theStub layer. It is intended to be easy for application frameworks to use thislayer to address cross-cutting concerns such as logging, monitoring, auth, etc.

The Transport layer does the heavy lifting of putting and taking bytes off thewire. The interfaces to it are abstract just enough to allow plugging in ofdifferent implementations. Note the transport layer API is considered internalto gRPC and has weaker API guarantees than the core API under packageio.grpc.

gRPC comes with multiple Transport implementations:

1. The Netty-based HTTP/2 transport is the main transport implementation basedonNetty. It is not officially supported on Android.There is a "grpc-netty-shaded" version of this transport. It is generallypreferred over using the Netty-based transport directly as it requires lessdependency management and is easier to upgrade within many applications.
2. The OkHttp-based HTTP/2 transport is a lightweight transport based onOkio and forked low-level parts ofOkHttp. It is mainly for use on Android.
3. The in-process transport is for when a server is in the same process as theclient. It is used frequently for testing, while also being safe forproduction use.
4. The Binder transport is for Android cross-process communication on a singledevice.