Maven

To add the Akka gRPC maven plugin to a project:

pom.xml

<project>
  <modelVersion>4.0.0</modelVersion>
  <name>Project name</name>
  <groupId>com.example</groupId>
  <artifactId>my-grpc-app</artifactId>
  <version>0.1-SNAPSHOT</version>
  <properties>
<akka.grpc.version>2.5.11</akka.grpc.version>
<grpc.version>1.77.1</grpc.version>
<project.encoding>UTF-8</project.encoding>
  </properties>
  <repositories>
<repository>
  <id>akka-repository</id>
  <name>Akka library repository</name>
  <url>https://repo.akka.io/<your token>/secure</url>
</repository>
  </repositories>
  <pluginRepositories>
<pluginRepository>
  <id>akka-repository</id>
  <name>Akka library repository</name>
  <url>https://repo.akka.io/<your token>/secure</url>
</pluginRepository>
  </pluginRepositories>
  <dependencies>
<dependency>
  <groupId>com.lightbend.akka.grpc</groupId>
  <artifactId>akka-grpc-runtime_2.13</artifactId>
  <version>${akka.grpc.version}</version>
</dependency>
<!-- for loading of cert, issue #89 -->
<dependency>
  <groupId>io.grpc</groupId>
  <artifactId>grpc-testing</artifactId>
  <version>${grpc.version}</version>
</dependency>
  </dependencies>
  <build>
<plugins>
  <plugin>
    <groupId>com.lightbend.akka.grpc</groupId>
    <artifactId>akka-grpc-maven-plugin</artifactId>
    <version>${akka.grpc.version}</version>
    <!-- Hook the generate goal into the lifecycle,
         automatically tied to generate-sources -->
    <executions>
      <execution>
        <goals>
          <goal>generate</goal>
        </goals>
      </execution>
    </executions>
  </plugin>
</plugins>
  </build>
</project>

For a step by step getting started with Akka gRPC read the client or server introductions.

Configuring what to generate

The plugin can be configured to generate either Java or Scala classes, and then server and or client for the chosen language. By default, both client and server in Java are generated.

Java

<plugin>
    <groupId>com.lightbend.akka.grpc</groupId>
    <artifactId>akka-grpc-maven-plugin</artifactId>
    <version>${akka.grpc.version}</version>
    <configuration>
      <language>Java</language>
      <generateClient>false</generateClient>
      <generateServer>true</generateServer>
    </configuration>
</plugin>

Scala

<plugin>
    <groupId>com.lightbend.akka.grpc</groupId>
    <artifactId>akka-grpc-maven-plugin</artifactId>
    <version>${akka.grpc.version}</version>
    <configuration>
      <language>Scala</language>
      <generateClient>false</generateClient>
      <generateServer>true</generateServer>
    </configuration>
</plugin>

Filtering generated services

You can filter which services to generate client or server code for independently, using include and exclude glob patterns. The patterns match against the full gRPC service name (e.g., com.example.MyService).

pom.xml

<plugin>
    <groupId>com.lightbend.akka.grpc</groupId>
    <artifactId>akka-grpc-maven-plugin</artifactId>
    <version>${akka.grpc.version}</version>
    <configuration>
      <clientInclude>
        <param>com.example.*</param>
        <param>com.myapp.MyService</param>
      </clientInclude>
      <clientExclude>
        <param>com.example.internal.*</param>
      </clientExclude>
      <serverInclude>
        <param>com.example.MyService</param>
      </serverInclude>
      <serverExclude>
        <param>com.example.internal.*</param>
      </serverExclude>
    </configuration>
</plugin>

The trait/interface is generated for any service that passes either the client or server filter.

If include is empty, all services are included. The exclude patterns are applied to the result of include.

Examples: - * matches any service name - com.example.* matches any service whose name starts with com.example. (including services in nested packages such as com.example.sub.MyService, since * matches across .) - com.example.MyService matches a specific service

Patterns must not contain commas (the brace-alternation syntax {A,B} is therefore not supported). To match several explicit names, list them as separate <param> entries:

<serverInclude>
    <param>com.example.Foo</param>
    <param>com.example.Bar</param>
</serverInclude>

Generating server “power APIs”

To additionally generate server “power APIs” that have access to request metadata, as described here, set the serverPowerApis tag as true:

pom.xml

<plugin>
    ...
    <configuration>
      ...
      <generatorSettings>
        <serverPowerApis>true</serverPowerApis>
      </generatorSettings>
    </configuration>
</plugin>

Proto source directory

By default, the plugin looks for .proto-files under src/main/protobuf (and src/main/proto). This can be changed with the protoPaths setting, which is a relative path to the project basedir. The below configuration overrides the proto path to be only src/main/protobuf:

pom.xml

<plugin>
    <groupId>com.lightbend.akka.grpc</groupId>
    <artifactId>akka-grpc-maven-plugin</artifactId>
    <version>${akka.grpc.version}</version>
    <configuration>
      <protoPaths>
        <protoPath>src/main/protobuf</protoPath>
      </protoPaths>
    </configuration>
</plugin>

Using a local protoc executable

By default, the plugin downloads protoc. If the download is not possible — for example behind an authenticated proxy/repository, or on a platform without a matching pre-built binary — you can point the plugin at a protoc executable already present on the machine with the protocExecutable setting. When set, it is used instead of the downloaded protoc.

pom.xml

<plugin>
    <groupId>com.lightbend.akka.grpc</groupId>
    <artifactId>akka-grpc-maven-plugin</artifactId>
    <version>${akka.grpc.version}</version>
    <configuration>
      <protocExecutable>/usr/bin/protoc</protocExecutable>
    </configuration>
</plugin>

The value may also be provided on the command line via -Dakka-grpc.protoc-executable=....

The configured executable must belong to the same protobuf release as protocVersion. The plugin runs protoc --version and fails the build if they belong to different releases, since mixing protoc and protobuf versions is unsupported and leads to build failures. Patch differences within the same release (for example 25.1 vs 25.8) are allowed.

Loading proto files from artifacts

Instead of duplicating the .proto definitions between server and client projects, you can add artifacts that contain proto definitions to your build.

A full example of a maven build definition can be found here which allows to import external protos like this:

Java

copysourceimport "google/api/annotations.proto";
import "google/api/httpbody.proto";

The pom.xml has to be adjusted as follows. As a first step in the <build>, the maven-dependency-plugin needs to pull in the artifacts containing the protobuf file. The <outputDirectory> is the place where the protos from the dependencies are getting placed into (target):

Java

copysource<execution>
  <id>unpack</id>
  <phase>generate-sources</phase>
  <goals>
    <goal>unpack</goal>
  </goals>
  <configuration>
    <artifactItems>
      <artifactItem>
        <groupId>com.google.protobuf</groupId>
        <artifactId>protobuf-java</artifactId>
        <version>${protobuf-java.version}</version>
        <type>jar</type>
        <overWrite>true</overWrite>
        <outputDirectory>${project.build.directory}/proto</outputDirectory>
        <includes>**/*.proto</includes>
      </artifactItem>
      <artifactItem>
        <groupId>com.google.api.grpc</groupId>
        <artifactId>proto-google-common-protos</artifactId>
        <version>${proto-google-common-protos.version}</version>
        <type>jar</type>
        <overWrite>true</overWrite>
        <outputDirectory>${project.build.directory}/proto</outputDirectory>
        <includes>**/*.proto</includes>
      </artifactItem>
    </artifactItems>
    <overWriteReleases>false</overWriteReleases>
    <overWriteSnapshots>true</overWriteSnapshots>
  </configuration>
</execution>

Finally, the target/proto directory has to be introduced to the akka-grpc-maven-plugin to be picket up during protoc compilation. Make sure to include all other folders from the project as well, since the definition of <protoPaths> overrides the default:

Java

copysource<protoPaths>
  <protoPath>target/proto</protoPath>
  <protoPath>src/main/proto</protoPath>
  <protoPath>src/main/protobuf</protoPath>
</protoPaths>

Starting your Akka gRPC server from Maven

You can start your gRPC application as usual with:

mvn compile exec:exec