Implementing services in Java

Cloudstate offers an idiomatic, annotation-based Java support library for writing stateful services. Before you attempt to write your first service in Java, we recommend that you read the general information on Developing services.


The following are required to start writing Cloudstate services in Java:

Java version

Cloudstate Java support requires at least Java 8, though we recommend using Java 11, which has better support for running in containers. While it is possible to build a GraalVM native image for Cloudstate Java service implementations, at this stage Cloudstate offers no specific assistance or configuration to aid in doing that.

Build tool

Cloudstate does not require any particular build tool, you can select your own.


Since Cloudstate is based on gRPC, you need a protoc compiler to compile gRPC protobuf descriptors. While this can be done by downloading, installing and running protoc manually, most popular build tools have a protoc plugin which will automatically compile protobuf descriptors during your build.


Cloudstate runs in Kubernetes using Docker. You will need Docker to build container images that you can deploy to Kubernetes. Most popular build tools have plugins that assist in building Docker images.

Cloudstate Java support library

See the instructions in Install the Cloudstate library.

Install the Cloudstate library

As mentioned, you can use the build tool of your choice. The following examples show how to install the Java Cloudstate library for Gradle, Maven, and sbt.


In your build.gradle file, add the following:

compile group: 'io.cloudstate', name: 'cloudstate-java-support', version: '11'

In your .pom file, add the following:


In your dependencies file, add the following:

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

What’s next

This section provides details on how to accomplish common tasks in Java. Before implementing a service, you need to choose whether it will use event sourced or Replicated Entities.