gRPC Server Skeleton for Java

  • A skeleton gRPC server is available for download to help implement your own server.

  • To get started, create a Java Gradle project, download necessary proto files, and update the build.gradle file with dependencies and the protobuf plugin.

  • Building the project with ./gradlew build will generate necessary code from the protoc build plugin.

  • To enable TLS, place server certificate and key files, along with trusted client roots, in the specified certificates directory.

  • The provided sample code for BookingService.java and Health.java needs to be integrated into the project, following the TODOs for completion.

You can download our skeleton gRPC server to help get started with implementing your complete gRPC server.

Get Started

  1. Create a java gradle project (grpc-booking-service), under the src/main, create a 'proto' directory.

  2. Download the booking service definition and health checking protocol, place them under src/main/proto. These files define the gRPC methods and messages for the Actions Center API and Health Check.

  3. Update the build.gradle file, add dependencies and the protobuf plugin for Gradle. The introduction and guide for protobuf-gradle-plugin can be found here.

        apply plugin: 'java'
    apply plugin: 'com.google.protobuf'

    repositories {
        mavenCentral()
    }

    // updating the version in our release process.
    def grpcVersion = '1.8.0' // CURRENT_GRPC_VERSION
    def nettyTcNativeVersion = '2.0.7.Final'

    dependencies {
        compile "com.google.api.grpc:proto-google-common-protos:0.1.9"
        compile "io.grpc:grpc-netty:${grpcVersion}"
        compile "io.grpc:grpc-protobuf:${grpcVersion}"
        compile "io.grpc:grpc-stub:${grpcVersion}"
        compile "io.netty:netty-tcnative-boringssl-static:${nettyTcNativeVersion}"
        compile "org.bouncycastle:bcmail-jdk15:1.46"

        testCompile "io.grpc:grpc-testing:${grpcVersion}"
        testCompile "junit:junit:4.12"
        testCompile "org.mockito:mockito-core:1.9.5"
    }

    buildscript {
        repositories {
            mavenCentral()
        }
        dependencies {
            // ASSUMES GRADLE 2.12 OR HIGHER. Use plugin version 0.7.5 with earlier
            // gradle versions
            classpath 'com.google.protobuf:protobuf-gradle-plugin:0.8.1'
        }
    }

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

    // Inform IDEs like IntelliJ IDEA, Eclipse or NetBeans about the generated code.
    sourceSets {
        main {
            java {
                srcDirs 'build/generated/source/proto/main/grpc'
                srcDirs 'build/generated/source/proto/main/java'
            }
        }
    }

    // Generate IntelliJ IDEA's .idea & .iml project files
    apply plugin: 'idea'

    // Provide convenience executables for trying out the examples.
    apply plugin: 'application'

    startScripts.enabled = false

  4. Run the following command to build the library and auto-generate code from protoc build plugin:

      ./gradlew build

  5. To enable TLS on the server, under src/main/certificates/ the following files are required:

    • server_cert_chain.pem your server certificate chain in PEM format
    • server_private_key.pem your private key for the server certificate chain, needs to be the PKCS#8 private key
    • trusted_client_roots.pem the root certificates that are trusted when authenticating clients, you can choose to obtain this set of trusted roots from an authority like Mozilla, or install the set of roots currently recommended by the Google Internet Authority G2. In the latter case, you may have to manually update the root certificate at times

  6. Retrieve the sample code from this repo:

      git clone https://maps-booking.googlesource.com/java-maps-booking-grpc-server-skeleton

    place the BookingService.java under src/main/java/ext/maps/booking/partner/v2, place Health.java under src/main/java/grpc/health/v1. In both files, follow the TODOs to complete your implementations.

  7. Update the gradle.build file to specify the generation of server executable by adding the following code:

    task bookingService(type: CreateStartScripts) {
    mainClassName = 'ext.maps.booking.partner.v2.BookingService'
    applicationName = 'booking-service'
    outputDir = new File(project.buildDir, 'tmp')
    classpath = jar.outputs.files + project.configurations.runtime
}

applicationDistribution.into('bin') {
    from(bookingService)
    fileMode = 0755
}

  8. Compile the server:

    ./gradlew installDist

  9. Run the booking server:

    ./build/install/grpc-booking-service/bin/booking-service

Final Directory Structure

src
|---main
    |---certificates
        |---server_cert_chain.pem
        |---server_private_key.pem
        |---trusted_client_roots.pem
    |---java
        |---ext.maps.booking.partner.v2.BookingService.java
        |---grpc.health.v1.Health.java
    |---proto
        |---booking_service.proto
        |---health.proto
|---test

Other Reference