Go to file
Grant Oakley e28145ab6a
Enclose all operations using obtained Parcels in try-finally blocks that will recycle the Parcel in the case that any exception is thrown. (#8733)
2021-12-08 14:39:42 -08:00
.github .github/workflows: Bump codecov-action to v2 2021-10-13 10:37:31 -07:00
all all: Only depend on evaluation of enumerated subprojects 2021-04-19 14:18:54 -07:00
alts javadoc: update new API `@since` version (#8727) 2021-11-29 10:22:32 -08:00
android android: bump min Android SDK version to 19 (#8583) 2021-10-06 10:02:32 -07:00
android-interop-testing android: bump min Android SDK version to 19 (#8583) 2021-10-06 10:02:32 -07:00
api Revert "Revert "core/auth: Remove CallCredentials2 (#8464)"" (#8572) 2021-10-05 10:34:44 -07:00
auth Revert "Revert "core/auth: Remove CallCredentials2 (#8464)"" (#8572) 2021-10-05 10:34:44 -07:00
benchmarks compiler: Add GrpcGenerated annotation to generated class 2021-07-02 22:11:40 -07:00
binder Enclose all operations using obtained Parcels in try-finally blocks that will recycle the Parcel in the case that any exception is thrown. (#8733) 2021-12-08 14:39:42 -08:00
bom bom: Do not include grpc-binder (#8038) 2021-04-02 13:03:08 -07:00
buildscripts buildscripts: add config for building grpc-binder artifact (#8722) 2021-11-23 18:11:54 +01:00
census census: fix NPE in calling recordFinishedAttempt() (#8706) 2021-11-29 08:48:51 -08:00
compiler Start 1.44.0 development cycle (#8729) 2021-11-30 11:53:56 -08:00
context context: Remove misleading example that leaks CancellableContext 2021-10-04 13:36:20 -07:00
core Start 1.44.0 development cycle (#8729) 2021-11-30 11:53:56 -08:00
cronet Update README etc to reference 1.42.1 (#8694) 2021-11-12 16:54:35 -08:00
documentation Update README etc to reference 1.42.1 (#8694) 2021-11-12 16:54:35 -08:00
examples Start 1.44.0 development cycle (#8729) 2021-11-30 11:53:56 -08:00
gae-interop-testing Migrate away from Jcenter (#8111) 2021-04-22 15:59:36 -07:00
gradle/wrapper Bump Gradle and plugin versions 2020-12-17 15:02:27 -08:00
grpclb grpclb: fallback timer only when not already using fallback backends. (#8646) 2021-11-02 12:47:47 -07:00
interop-testing interop-testing: assign server as soon as it is built instead of after start (#8662) 2021-11-04 12:31:11 -07:00
netty netty: Add system property to disable Connection header check 2021-11-09 09:26:18 -08:00
okhttp javadoc: update new API `@since` version (#8727) 2021-11-29 10:22:32 -08:00
protobuf Replace failOnVersionConflict() with custom requireUpperBoundDeps 2021-06-11 14:01:18 -07:00
protobuf-lite Replace failOnVersionConflict() with custom requireUpperBoundDeps 2021-06-11 14:01:18 -07:00
rls rls: Fix RouteLookupConfig test arguments 2021-12-01 18:54:13 -05:00
services compiler: Add GrpcGenerated annotation to generated class 2021-07-02 22:11:40 -07:00
stub default throw ServerCallStreamObserver.setOnCloseHandler (#8564) 2021-09-28 13:31:40 -07:00
testing Support BinderChannelBuilder.forTarget. (#8633) 2021-11-01 14:01:56 +01:00
testing-proto compiler: Add GrpcGenerated annotation to generated class 2021-07-02 22:11:40 -07:00
xds Replace C2P resolver env var with experimental scheme suffix (#8744) 2021-12-07 13:29:29 -08:00
.bazelignore bazel: ignore examples/ from root WORKSPACE 2018-12-18 14:54:57 -07:00
.gitattributes gitattributes: Show diffs for golden generated code 2021-07-02 22:11:40 -07:00
.gitignore Port from Travis-CI to GitHub Actions 2021-06-17 13:32:56 -07:00
AUTHORS all: update to Apache 2 licence 2017-05-31 13:29:01 -07:00
BUILD.bazel core: Move io.grpc to grpc-api 2019-04-16 21:45:40 -07:00
CODE-OF-CONDUCT.md Update governance, contributing, code of conduct docs (#6171) 2019-09-20 16:28:42 -07:00
COMPILING.md Bump Protobuf to 3.17.2 2021-06-07 11:20:48 -07:00
CONTRIBUTING.md CONTRIBUTING.md: Fix out-of-date CLA documentation 2020-12-09 14:32:57 -08:00
GOVERNANCE.md Update governance, contributing, code of conduct docs (#6171) 2019-09-20 16:28:42 -07:00
LICENSE fix LICENSE file (#3107) 2017-06-20 08:52:39 +02:00
MAINTAINERS.md Update MAINTAINERS.md 2021-11-04 14:50:34 -04:00
NOTICE.txt xds: rollback PGV dependency from using maven artifact to importing proto source 2020-03-27 17:09:27 -07:00
README.md Update README etc to reference 1.42.1 (#8694) 2021-11-12 16:54:35 -08:00
RELEASING.md RELEASING.md: Individual OSSRH account is no longer needed 2021-11-03 11:26:27 -07:00
SECURITY.md dep: bump netty to 4.1.63.Final and tcnative to 2.0.38.Final (#8167) 2021-09-21 09:14:54 -07:00
WORKSPACE bazel: Support maven_install 2019-12-30 12:08:42 -08:00
build.gradle Start 1.44.0 development cycle (#8729) 2021-11-30 11:53:56 -08:00
codecov.yml Disable codecov comment and changes status 2016-05-01 22:39:12 -07:00
gradlew all: update to gradle 4.0.1 2017-07-12 10:07:14 -07:00
gradlew.bat all: update to gradle 3.2 2016-11-23 14:43:18 -08:00
java_grpc_library.bzl java_grpc_library.bzl: Fix parameters of java_common.compile (#7598) 2021-10-08 13:48:22 -07:00
repositories.bzl dep: bump netty to 4.1.63.Final and tcnative to 2.0.38.Final (#8167) 2021-09-21 09:14:54 -07:00
run-test-client.sh Avoid interop build instructions when already built 2018-10-11 17:17:13 -07:00
run-test-server.sh Avoid interop build instructions when already built 2018-10-11 17:17:13 -07:00
settings.gradle Bump Protobuf Gradle Plugin to 0.8.17 (#8336) 2021-07-21 19:30:38 -07:00

README.md

gRPC-Java - An RPC library and framework

gRPC-Java works with JDK 7. gRPC-Java clients are supported on Android API levels 19 and up (KitKat and later). Deploying gRPC servers on an Android device is not supported.

TLS usage typically requires using Java 8, or Play Services Dynamic Security Provider on Android. Please see the Security Readme.

Homepage: grpc.io
Mailing List: grpc-io@googlegroups.com

Join the chat at https://gitter.im/grpc/grpc Build Status Line Coverage Status Branch-adjusted Line Coverage Status

Getting Started

For a guided tour, take a look at the quick start guide or the more explanatory gRPC basics.

The examples and the Android example are standalone projects that showcase the usage of gRPC.

Download

Download the JARs. Or for Maven with non-Android, add to your pom.xml:

<dependency>
  <groupId>io.grpc</groupId>
  <artifactId>grpc-netty-shaded</artifactId>
  <version>1.42.1</version>
</dependency>
<dependency>
  <groupId>io.grpc</groupId>
  <artifactId>grpc-protobuf</artifactId>
  <version>1.42.1</version>
</dependency>
<dependency>
  <groupId>io.grpc</groupId>
  <artifactId>grpc-stub</artifactId>
  <version>1.42.1</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:

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

For Android client, use grpc-okhttp instead of grpc-netty-shaded and grpc-protobuf-lite instead of grpc-protobuf:

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

Development snapshots are available in Sonatypes's snapshot repository.

Generated Code

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

For protobuf-based codegen integrated with the Maven build system, you can use protobuf-maven-plugin (Eclipse and NetBeans users should also look at os-maven-plugin's IDE documentation):

<build>
  <extensions>
    <extension>
      <groupId>kr.motd.maven</groupId>
      <artifactId>os-maven-plugin</artifactId>
      <version>1.6.2</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.17.2:exe:${os.detected.classifier}</protocArtifact>
        <pluginId>grpc-java</pluginId>
        <pluginArtifact>io.grpc:protoc-gen-grpc-java:1.42.1: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 use protobuf-gradle-plugin:

plugins {
    id 'com.google.protobuf' version '0.8.17'
}

protobuf {
  protoc {
    artifact = "com.google.protobuf:protoc:3.17.2"
  }
  plugins {
    grpc {
      artifact = 'io.grpc:protoc-gen-grpc-java:1.42.1'
    }
  }
  generateProtoTasks {
    all()*.plugins {
      grpc {}
    }
  }
}

The prebuilt protoc-gen-grpc-java binary uses glibc on Linux. If you are compiling on Alpine Linux, you may want to use the Alpine grpc-java package which uses musl instead.

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

plugins {
    id 'com.google.protobuf' version '0.8.17'
}

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

API Stability

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

We recommend using the grpc-java-api-checker (an Error Prone plugin) to check for usages of @ExperimentalApi and @Internal in any library code that depends on gRPC. It may also be used to check for @Internal usage or unintended @ExperimentalApi consumption in non-library code.

How to Build

If you are making changes to gRPC-Java, see the compiling instructions.

High-level Components

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

Stub

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

Channel

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

Transport

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

gRPC comes with three Transport implementations:

  1. The Netty-based transport is the main transport implementation based on Netty. It is for both the client and the server.
  2. The OkHttp-based transport is a lightweight transport based on OkHttp. It is mainly for use on Android and is for client only.
  3. The in-process transport is for when a server is in the same process as the client. It is useful for testing, while also being safe for production use.