Implementation overview

As mentioned previously, your project needs to include Cloudstate libraries. Each of your service projects will need a gRPC descriptor from which you generate code, and you need to add logic to start the gRPC server. The following sections illustrate how you can accomplish these basics in the context of a shopping cart application.

You can download the complete shopping cart example from: github. To deploy it on Akka Serverless, follow the directions in the top-level README.

Build file examples

The following illustrate how to configure build tools for the shopping cart example:


A full example can be found here: Java Shopping Cart - build.gradle new tab:

plugins {
  id "java"
  id "idea"
  id "" version "0.8.12"
  id "" version "2.2.0"

repositories {

group = "com.example"
version = "0.1.0"

dependencies {
  implementation "io.cloudstate:cloudstate-java-support:0.4.7"

protobuf {
  protoc {
    artifact = ""

java {
  sourceCompatibility = JavaVersion.VERSION_1_8
  targetCompatibility = JavaVersion.VERSION_1_8

jib {
  from {
    image = "adoptopenjdk/openjdk8:debian"
  to {
    image = ""
    tags = [version]
  container {
    mainClass = "io.cloudstate.samples.shoppingcart.Main"
    ports = ["8080"]

The following Maven example uses the Xolstice Maven Protocol Buffers Plugin and the Fabric8 Docker Maven Plugin.


<project xmlns=""


          <!-- java version -->


              <!-- <shadedArtifactAttached>true</shadedArtifactAttached>
              <shadedClassifierName>allinone</shadedClassifierName> -->
                <transformer implementation="org.apache.maven.plugins.shade.resource.AppendingTransformer">
               <transformer implementation="org.apache.maven.plugins.shade.resource.ManifestResourceTransformer">
                <!-- main entry class -->

              <!-- Please change it to your Docker repository info -->
                <!-- Base Docker image which contains jre-->
                  <!-- tag for generated image -->
                  <!-- expose port in Docker container -->
                  <!-- NOTE: (optional) switch to "artifact-with-dependencies" to show dependencies library-->




Subsequent source locations and build commands will assume the above Maven project, and may need to be adapted to your particular build tool and setup.


In your dependencies file, add the following:

libraryDependencies += "io.cloudstate" % "cloudstate-java-support" % "11"

Protobuf files

The Xolstice Maven plugin assumes a location of src/main/proto for your protobuf files. In addition, it includes any protobuf files from your Java dependencies in the protoc include path, so the Cloudstate protobuf types and the Google standard protobuf types are all automatically available for import.

If you were to build the example shopping cart application shown earlier in gRPC descriptors, you could simply paste that protobuf into src/main/proto/shoppingcart.proto. You may wish to also define the Java package, to ensure the package name used conforms to Java package naming conventions:

option java_package = "com.example";

Now if you run mvn compile, you’ll find your generated protobuf files in target/generated-sources/protobuf/java.

Create a main class

Your main class will be responsible for creating the Cloudstate gRPC server, registering the entities for it to serve, and starting it. To do this, you can use the CloudStatenew tab server builder. The following file contains a full example: Java Shopping Cart - new tab:

package io.cloudstate.samples.shoppingcart;

import io.cloudstate.javasupport.*;
import com.example.shoppingcart.Shoppingcart;
import static java.util.Collections.singletonMap;

public final class Main {
  public static final void main(String[] args) throws Exception {
    new CloudState()

We will see more details on registering entities in the coming pages.

Parameter injection

Cloudstate entities work by annotating classes and methods to be instantiated and invoked by the Cloudstate server. The methods and constructors invoked by the server can be injected with parameters of various types from the context of the invocation. For example, an @CommandHandler annotated method may take an argument for the message type for that gRPC service call, in addition it may take a CommandContext parameter.

Exactly which context parameters are available depend on the type of entity and the type of handler, in subsequent pages we’ll detail which parameters are available in which circumstances. The order of the parameters in the method signature can be anything, parameters are matched by type and sometimes by annotation. The following context parameters are available in every context:

Type Annotation Description

Contextnew tab

The super type of all Cloudstate contexts. Every invoker makes a subtype of this available for injection, and method or constructor may accept that sub type, or any super type of that subtype that is a subtype of Context.



The ID of the entity.