1gRPC-Java - An RPC library and framework
2========================================
3
4gRPC-Java works with JDK 7. gRPC-Java clients are supported on Android API
5levels 14 and up (Ice Cream Sandwich and later). Deploying gRPC servers on an
6Android device is not supported.
7
8TLS usage typically requires using Java 8, or Play Services Dynamic Security
9Provider on Android. Please see the [Security Readme](SECURITY.md).
10
11<table>
12  <tr>
13    <td><b>Homepage:</b></td>
14    <td><a href="https://grpc.io/">grpc.io</a></td>
15  </tr>
16  <tr>
17    <td><b>Mailing List:</b></td>
18    <td><a href="https://groups.google.com/forum/#!forum/grpc-io">grpc-io@googlegroups.com</a></td>
19  </tr>
20</table>
21
22[![Join the chat at https://gitter.im/grpc/grpc](https://badges.gitter.im/grpc/grpc.svg)](https://gitter.im/grpc/grpc?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge)
23[![Build Status](https://travis-ci.org/grpc/grpc-java.svg?branch=master)](https://travis-ci.org/grpc/grpc-java)
24[![Coverage Status](https://coveralls.io/repos/grpc/grpc-java/badge.svg?branch=master&service=github)](https://coveralls.io/github/grpc/grpc-java?branch=master)
25
26Getting Started
27---------------
28
29For a guided tour, take a look at the [quick start
30guide](https://grpc.io/docs/quickstart/java.html) or the more explanatory [gRPC
31basics](https://grpc.io/docs/tutorials/basic/java.html).
32
33The [examples](https://github.com/grpc/grpc-java/tree/v1.15.0/examples) and the
34[Android example](https://github.com/grpc/grpc-java/tree/v1.15.0/examples/android)
35are standalone projects that showcase the usage of gRPC.
36
37Download
38--------
39
40Download [the JARs][]. Or for Maven with non-Android, add to your `pom.xml`:
41```xml
42<dependency>
43  <groupId>io.grpc</groupId>
44  <artifactId>grpc-netty-shaded</artifactId>
45  <version>1.15.0</version>
46</dependency>
47<dependency>
48  <groupId>io.grpc</groupId>
49  <artifactId>grpc-protobuf</artifactId>
50  <version>1.15.0</version>
51</dependency>
52<dependency>
53  <groupId>io.grpc</groupId>
54  <artifactId>grpc-stub</artifactId>
55  <version>1.15.0</version>
56</dependency>
57```
58
59Or for Gradle with non-Android, add to your dependencies:
60```gradle
61compile 'io.grpc:grpc-netty-shaded:1.15.0'
62compile 'io.grpc:grpc-protobuf:1.15.0'
63compile 'io.grpc:grpc-stub:1.15.0'
64```
65
66For Android client, use `grpc-okhttp` instead of `grpc-netty-shaded` and
67`grpc-protobuf-lite` instead of `grpc-protobuf`:
68```gradle
69compile 'io.grpc:grpc-okhttp:1.15.0'
70compile 'io.grpc:grpc-protobuf-lite:1.15.0'
71compile 'io.grpc:grpc-stub:1.15.0'
72```
73
74[the JARs]:
75https://search.maven.org/search?q=g:io.grpc%20AND%20v:1.15.0
76
77Development snapshots are available in [Sonatypes's snapshot
78repository](https://oss.sonatype.org/content/repositories/snapshots/).
79
80Generated Code
81--------------
82
83For protobuf-based codegen, you can put your proto files in the `src/main/proto`
84and `src/test/proto` directories along with an appropriate plugin.
85
86For protobuf-based codegen integrated with the Maven build system, you can use
87[protobuf-maven-plugin][] (Eclipse and NetBeans users should also look at
88`os-maven-plugin`'s
89[IDE documentation](https://github.com/trustin/os-maven-plugin#issues-with-eclipse-m2e-or-other-ides)):
90```xml
91<build>
92  <extensions>
93    <extension>
94      <groupId>kr.motd.maven</groupId>
95      <artifactId>os-maven-plugin</artifactId>
96      <version>1.5.0.Final</version>
97    </extension>
98  </extensions>
99  <plugins>
100    <plugin>
101      <groupId>org.xolstice.maven.plugins</groupId>
102      <artifactId>protobuf-maven-plugin</artifactId>
103      <version>0.5.1</version>
104      <configuration>
105        <protocArtifact>com.google.protobuf:protoc:3.5.1-1:exe:${os.detected.classifier}</protocArtifact>
106        <pluginId>grpc-java</pluginId>
107        <pluginArtifact>io.grpc:protoc-gen-grpc-java:1.15.0:exe:${os.detected.classifier}</pluginArtifact>
108      </configuration>
109      <executions>
110        <execution>
111          <goals>
112            <goal>compile</goal>
113            <goal>compile-custom</goal>
114          </goals>
115        </execution>
116      </executions>
117    </plugin>
118  </plugins>
119</build>
120```
121
122[protobuf-maven-plugin]: https://www.xolstice.org/protobuf-maven-plugin/
123
124For protobuf-based codegen integrated with the Gradle build system, you can use
125[protobuf-gradle-plugin][]:
126```gradle
127apply plugin: 'com.google.protobuf'
128
129buildscript {
130  repositories {
131    mavenCentral()
132  }
133  dependencies {
134    classpath 'com.google.protobuf:protobuf-gradle-plugin:0.8.5'
135  }
136}
137
138protobuf {
139  protoc {
140    artifact = "com.google.protobuf:protoc:3.5.1-1"
141  }
142  plugins {
143    grpc {
144      artifact = 'io.grpc:protoc-gen-grpc-java:1.15.0'
145    }
146  }
147  generateProtoTasks {
148    all()*.plugins {
149      grpc {}
150    }
151  }
152}
153```
154
155[protobuf-gradle-plugin]: https://github.com/google/protobuf-gradle-plugin
156
157The prebuilt protoc-gen-grpc-java binary uses glibc on Linux. If you are
158compiling on Alpine Linux, you may want to use the [Alpine grpc-java package][]
159which uses musl instead.
160
161[Alpine grpc-java package]: https://pkgs.alpinelinux.org/package/edge/testing/x86_64/grpc-java
162
163API Stability
164-------------
165
166APIs annotated with `@Internal` are for internal use by the gRPC library and
167should not be used by gRPC users. APIs annotated with `@ExperimentalApi` are
168subject to change in future releases, and library code that other projects
169may depend on should not use these APIs.
170
171We recommend using the
172[grpc-java-api-checker](https://github.com/grpc/grpc-java-api-checker)
173(an [Error Prone](https://github.com/google/error-prone) plugin)
174to check for usages of `@ExperimentalApi` and `@Internal` in any library code
175that depends on gRPC. It may also be used to check for `@Internal` usage or
176unintended `@ExperimentalApi` consumption in non-library code.
177
178How to Build
179------------
180
181If you are making changes to gRPC-Java, see the [compiling
182instructions](COMPILING.md).
183
184High-level Components
185---------------------
186
187At a high level there are three distinct layers to the library: *Stub*,
188*Channel*, and *Transport*.
189
190### Stub
191
192The Stub layer is what is exposed to most developers and provides type-safe
193bindings to whatever datamodel/IDL/interface you are adapting. gRPC comes with
194a [plugin](https://github.com/google/grpc-java/blob/master/compiler) to the
195protocol-buffers compiler that generates Stub interfaces out of `.proto` files,
196but bindings to other datamodel/IDL are easy and encouraged.
197
198### Channel
199
200The Channel layer is an abstraction over Transport handling that is suitable for
201interception/decoration and exposes more behavior to the application than the
202Stub layer. It is intended to be easy for application frameworks to use this
203layer to address cross-cutting concerns such as logging, monitoring, auth, etc.
204
205### Transport
206
207The Transport layer does the heavy lifting of putting and taking bytes off the
208wire. The interfaces to it are abstract just enough to allow plugging in of
209different implementations. Note the transport layer API is considered internal
210to gRPC and has weaker API guarantees than the core API under package `io.grpc`.
211
212gRPC comes with three Transport implementations:
213
2141. The Netty-based transport is the main transport implementation based on
215   [Netty](http://netty.io). It is for both the client and the server.
2162. The OkHttp-based transport is a lightweight transport based on
217   [OkHttp](http://square.github.io/okhttp/). It is mainly for use on Android
218   and is for client only.
2193. The in-process transport is for when a server is in the same process as the
220   client. It is useful for testing, while also being safe for production use.
221