gRPC Server Skeleton for Java

  • A skeleton gRPC server is available for download to aid in the implementation of a complete gRPC server.

  • The process involves setting up a Java Gradle project, including adding dependencies, the protobuf plugin, and defining necessary .proto files for booking service and health checks.

  • TLS encryption can be enabled on the server using certificate chain, private key, and trusted client root files.

  • Sample code from the repository is required to implement specific service files while completing TODOs.

  • The build process involves using Gradle to compile, generate code, and install the distribution for running the booking server.

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