1 gRPC-Java - An RPC library and framework 2 ======================================== 3 4 gRPC-Java works with JDK 7. gRPC-Java clients are supported on Android API 5 levels 14 and up (Ice Cream Sandwich and later). Deploying gRPC servers on an 6 Android device is not supported. 7 8 TLS usage typically requires using Java 8, or Play Services Dynamic Security 9 Provider 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 (a] googlegroups.com</a></td> 19 </tr> 20 </table> 21 22 [](https://gitter.im/grpc/grpc?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge) 23 [](https://travis-ci.org/grpc/grpc-java) 24 [](https://coveralls.io/github/grpc/grpc-java?branch=master) 25 26 Getting Started 27 --------------- 28 29 For a guided tour, take a look at the [quick start 30 guide](https://grpc.io/docs/quickstart/java.html) or the more explanatory [gRPC 31 basics](https://grpc.io/docs/tutorials/basic/java.html). 32 33 The [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) 35 are standalone projects that showcase the usage of gRPC. 36 37 Download 38 -------- 39 40 Download [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 59 Or for Gradle with non-Android, add to your dependencies: 60 ```gradle 61 compile 'io.grpc:grpc-netty-shaded:1.15.0' 62 compile 'io.grpc:grpc-protobuf:1.15.0' 63 compile 'io.grpc:grpc-stub:1.15.0' 64 ``` 65 66 For Android client, use `grpc-okhttp` instead of `grpc-netty-shaded` and 67 `grpc-protobuf-lite` instead of `grpc-protobuf`: 68 ```gradle 69 compile 'io.grpc:grpc-okhttp:1.15.0' 70 compile 'io.grpc:grpc-protobuf-lite:1.15.0' 71 compile 'io.grpc:grpc-stub:1.15.0' 72 ``` 73 74 [the JARs]: 75 https://search.maven.org/search?q=g:io.grpc%20AND%20v:1.15.0 76 77 Development snapshots are available in [Sonatypes's snapshot 78 repository](https://oss.sonatype.org/content/repositories/snapshots/). 79 80 Generated Code 81 -------------- 82 83 For protobuf-based codegen, you can put your proto files in the `src/main/proto` 84 and `src/test/proto` directories along with an appropriate plugin. 85 86 For 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 124 For protobuf-based codegen integrated with the Gradle build system, you can use 125 [protobuf-gradle-plugin][]: 126 ```gradle 127 apply plugin: 'com.google.protobuf' 128 129 buildscript { 130 repositories { 131 mavenCentral() 132 } 133 dependencies { 134 classpath 'com.google.protobuf:protobuf-gradle-plugin:0.8.5' 135 } 136 } 137 138 protobuf { 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 157 The prebuilt protoc-gen-grpc-java binary uses glibc on Linux. If you are 158 compiling on Alpine Linux, you may want to use the [Alpine grpc-java package][] 159 which uses musl instead. 160 161 [Alpine grpc-java package]: https://pkgs.alpinelinux.org/package/edge/testing/x86_64/grpc-java 162 163 API Stability 164 ------------- 165 166 APIs annotated with `@Internal` are for internal use by the gRPC library and 167 should not be used by gRPC users. APIs annotated with `@ExperimentalApi` are 168 subject to change in future releases, and library code that other projects 169 may depend on should not use these APIs. 170 171 We 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) 174 to check for usages of `@ExperimentalApi` and `@Internal` in any library code 175 that depends on gRPC. It may also be used to check for `@Internal` usage or 176 unintended `@ExperimentalApi` consumption in non-library code. 177 178 How to Build 179 ------------ 180 181 If you are making changes to gRPC-Java, see the [compiling 182 instructions](COMPILING.md). 183 184 High-level Components 185 --------------------- 186 187 At a high level there are three distinct layers to the library: *Stub*, 188 *Channel*, and *Transport*. 189 190 ### Stub 191 192 The Stub layer is what is exposed to most developers and provides type-safe 193 bindings to whatever datamodel/IDL/interface you are adapting. gRPC comes with 194 a [plugin](https://github.com/google/grpc-java/blob/master/compiler) to the 195 protocol-buffers compiler that generates Stub interfaces out of `.proto` files, 196 but bindings to other datamodel/IDL are easy and encouraged. 197 198 ### Channel 199 200 The Channel layer is an abstraction over Transport handling that is suitable for 201 interception/decoration and exposes more behavior to the application than the 202 Stub layer. It is intended to be easy for application frameworks to use this 203 layer to address cross-cutting concerns such as logging, monitoring, auth, etc. 204 205 ### Transport 206 207 The Transport layer does the heavy lifting of putting and taking bytes off the 208 wire. The interfaces to it are abstract just enough to allow plugging in of 209 different implementations. Note the transport layer API is considered internal 210 to gRPC and has weaker API guarantees than the core API under package `io.grpc`. 211 212 gRPC comes with three Transport implementations: 213 214 1. 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. 216 2. 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. 219 3. 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
