Getting Started

<- Back to index

This section deals with how to get Spring to connect to a grpc server and manage the connection for you.

Table of Contents

• Project Setup
• Dependencies
  • Interface-Project
  • Server-Project
  • Client-Project
• Using the Stubs to connect to the Server
  • Explaining the client components
  • Accessing the Client

Additional Topics

• Getting Started
• Configuration
• Security
• Tests with Grpc-Stubs

Project Setup

Before we start adding the dependencies lets start with some of our recommendation for your project setup.

We recommend splitting your project into 2-3 separate modules.

1. The interface project Contains the raw protobuf files and generates the java model and service classes. You probably share this part.
2. The server project Contains the actual implementation of your project and uses the interface project as dependency.
3. The client projects (optional and possibly many) Any client projects that use the pre-generated stubs to access the server.

Dependencies

Interface-Project

See the server getting started page

Server-Project

See the server getting started page

Client-Project

Maven (Client)

    <dependencies>
        <dependency>
            <groupId>net.devh</groupId>
            <artifactId>grpc-client-spring-boot-starter</artifactId>
        </dependency>

        <dependency>
            <groupId>example</groupId>
            <artifactId>my-grpc-interface</artifactId>
        </dependency>
    </dependencies>

    <build>
        <plugins>
            <plugin>
                <groupId>org.springframework.boot</groupId>
                <artifactId>spring-boot-maven-plugin</artifactId>
            </plugin>
        </plugins>
    </build>

Gradle (Client)

apply plugin: 'org.springframework.boot'

dependencies {
    compile('org.springframework.boot:spring-boot-starter')
    compile('net.devh:grpc-client-spring-boot-starter')
    compile('my-example:my-grpc-interface')
}

buildscript {
    dependencies {
        classpath("org.springframework.boot:spring-boot-gradle-plugin:${springBootVersion}")
    }
}

Using the Stubs to connect to the Server

This section assumes that you have already defined and generated your Protobuf service.

Explaining the client components

• Channel: The Channel is a connection pool for a single address. The target servers might serve multiple grpc-services though. The address will be resolved using a NameResolver and might point to a fixed or dynamic number of servers.
• ManagedChannel: The ManagedChannel is a special variant of a Channel as it allows management operations to the connection pool such as shuting it down.
• NameResolver respectively NameResolver.Factory: A class that will be used to resolve the address to a list of SocketAddresses, the address will usually be re-resolved when a connection to a previously listed server fails or the channel was idle. See also Configuration -> Choosing the Target.
• ClientInterceptor: Intercepts every call before they are handed to the Channel. Can be used for logging, monitoring, metadata handling, and request/response rewriting. grpc-spring-boot-starter will automatically pick up all client interceptors that are annotated with @GrpcGlobalClientInterceptor or are manually registered to the GlobalClientInterceptorRegistry. See also Configuration -> ClientInterceptor.
• CallCredentials: A potentially active component that manages the authentication for the calls. It can be used to store credentials or session tokens. It can also be used to authenticate at an authentication provider and then use returned tokens (such as OAuth) to authorize the actual request. In addition to that, it is able to renew the token, if it expired and re-sent the request. If exactly one CallCredentials bean is present on your application context then spring will automatically attach it to all Stubs (NOT Channels). The CallCredentialsHelper utility class helps you to create commonly used CallCredentials types and related StubTransformer.
• StubTransformer: A transformer that will be applied to all client Stubs before they are injected. See also Configuration -> StubTransformer.
• @GrpcClient: The annotation that marks fields and setters for auto injection of clients. Supports Channels, and all kind of Stubs. Do not use @GrpcClient in conjunction with @Autowired or @Inject.

Accessing the Client

We recommended to inject (@GrpcClient) Stubs instead of plain Channels.

Note: There are different types of Stubs. Not all of them support all request types (streaming calls).

import example.HelloReply;
import example.HelloRequest;
import example.MyServiceGrpc;

import io.grpc.stub.StreamObserver;

import net.devh.boot.grpc.server.service.GrpcService;

@Service
public class FoobarService {

    @GrpcClient("myService")
    private MyServiceBlockingStub myServiceStub;

    public String receiveGreeting(String name) {
        HelloRequest request = HelloRequest.newBuilder()
                .setName(name)
                .build()
        return myServiceStub.sayHello(request).getMessage();
    }

}

Additional Topics

• Getting Started
• Configuration
• Security

<- Back to index