Skip to content

index.adoc

Latest commit

 

History

History
115 lines (85 loc) · 5.7 KB

index.adoc

File metadata and controls

115 lines (85 loc) · 5.7 KB

Developing with Java

ROOT:partial$include.adoc partial$attributes.adoc

The Akka Serverless Java SDK offers an idiomatic, annotation-based Java language SDK for writing components. This page describes prerequisites for Java development and basic requirements for a development project.

Note
 Lightbend provides Tier 1 support for the Java SDK. See an explanation of support tiers for more information.

Your development project needs to include the Akka Serverless Java SDK and logic to start the gRPC server. You define your components in gRPC descriptors and use protoc to compile them. Finally, you implement business logic for service components.

To save the work of starting from scratch, the Java code generation tool creates a project, complete with descriptors and implementations. Or, you can start from one of our quickstart example applications.

Prerequisites

The following are required to develop services in Java:

Java

Akka Serverless requires at least Java {minimum-java-version}, though we recommend using Java {recommended-java-version}, which has better support for running in containers.

Build tool

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

protoc

Since Akka Serverless 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.

Docker

Akka Serverless requires Docker {tab-icon} {minimum_docker_version} for building your service images. Most popular build tools have plugins that assist in building Docker images.

Reference the Akka Serverless SDK

The following examples show how to install the SDK to build your services with Gradle, Maven, or sbt. The code generation tools include an Akka Serverless Maven archetype that generates the recommended project structure, including a .pom file with the necessary references.

Maven

In your .pom file, add the following:

<dependencies>
    <dependency>
        <groupId>com.akkaserverless</groupId>
        <artifactId>akkaserverless-java-sdk</artifactId>
        <version>{akkaserverless-java-sdk-version}</version>
    </dependency>
    <dependency>
        <groupId>com.akkaserverless</groupId>
        <artifactId>akkaserverless-java-sdk-testkit</artifactId>
        <version>{akkaserverless-java-sdk-version}</version>
        <scope>test</scope>
    </dependency>
</dependencies>
Gradle

In your build.gradle file, add the following:

compile group: 'com.akkaserverless', name: 'akkaserverless-java-sdk', version: '{akkaserverless-java-sdk-version}'
sbt

In your dependencies file, add the following:

libraryDependencies ++= Seq(
    "com.akkaserverless" % "akkaserverless-java-sdk" % "{akkaserverless-java-sdk-version}",
    "com.akkaserverless" % "akkaserverless-java-sdk-testkit" % "{akkaserverless-java-sdk-version}" % Test
  )

Configure JSON formatted logging

Akka Serverless supports JSON formatted logging to provide multi-line messages formatted in JSON syntax. Always use JSON formatted logging for your Akka Serverless projects to efficiently analyze and easily leverage logging information.

Tip
 Build and deploy the Quickstart example to see JSON formatted logging in action.

JSON formatted logging is enabled by default in the projects created by the Akka Serverless Maven archetype. It includes a dependency in pom.xml to logback-json-classic and a logback.xml file as shown here:

src/main/resources/logback.xml
link:example$java-first-service/src/main/resources/logback.xml[role=include]

In the logback.xml you may want to adjust the log level for different loggers (typically a package or class name).

For local development you can switch to the STDOUT appender to make the logs more readable, or use <prettyPrint>true</prettyPrint> in the jsonFormatter. Don’t use prettyPrint in production since the logging infrastructure will not handle multi-line log messages.

Note
 There is a separate src/test/resources/logback-test.xml that is used when running tests.

Create a main class

Your main class will be responsible for creating the gRPC server, registering the services and components for it to serve, and starting it. The following code snippet shows an example that registers an Event Sourced Entity and starts the server:

link:example$java-eventing-shopping-cart/src/main/java/shopping/Main.java[role=include]

What’s next

This section provides details on how to accomplish common tasks in Java: