Merge pull request #187 from akka/main

chore: Publish docs for release 3.1.0

.github/workflows/ci.yml

@@ -440,7 +440,7 @@ jobs:
           fi
           if [ true == '${{matrix.it}}' ]; then
             ${PRE_CMD}
-            KALIX_TESTKIT_DEBUG=true mvn integration-test --no-transfer-progress
+            KALIX_TESTKIT_DEBUG=true mvn verify --no-transfer-progress
           fi
 
       - name: ${{ matrix.sample }} rm & test-compile

LICENSE

@@ -3,10 +3,10 @@ Business Source License 1.1
 Parameters
 
 Licensor:             Lightbend, Inc.
-Licensed Work:        Akka SDK for Java v 3.0.2
+Licensed Work:        Akka SDK for Java v 3.1.0
                       The Licensed Work is (c) 2024 Lightbend Inc.
 
-Change Date:          2027-12-12
+Change Date:          2028-01-28
 
 Change License:       Apache License, Version 2.0
 

akka-javasdk-annotation-processor-tests/entites-and-views-descriptors/src/main/java/com/example/AbstractInbetweenKvEntity2.java

@@ -1,3 +1,7 @@
+/*
+ * Copyright (C) 2021-2024 Lightbend Inc. <https://www.lightbend.com>
+ */
+
 package com.example;
 
 // covering that there can be more than one supertype inbetween

akka-javasdk-maven/akka-javasdk-archetype/pom.xml

@@ -2,12 +2,12 @@
     <modelVersion>4.0.0</modelVersion>
 
     <artifactId>akka-javasdk-archetype</artifactId>
-    <version>3.0.2</version>
+    <version>3.1.0</version>
     <packaging>maven-archetype</packaging>
     <parent>
         <groupId>io.akka</groupId>
         <artifactId>akka-javasdk-maven</artifactId>
-        <version>3.0.2</version>
+        <version>3.1.0</version>
     </parent>
 
     <name>Akka SDK for Java Maven Archetype</name>

akka-javasdk-maven/akka-javasdk-archetype/src/main/resources/archetype-resources/src/main/java/__packageInPathFormat__/api/package-info.java

@@ -0,0 +1,4 @@
+/**
+ * This module is for the public API of the service, where the classes that define endpoints of the service should live.
+ */
+package ${package}.api;

akka-javasdk-maven/akka-javasdk-archetype/src/main/resources/archetype-resources/src/main/java/__packageInPathFormat__/application/package-info.java

@@ -0,0 +1,5 @@
+/**
+ * This module is for the application layer of the service. It is where the internal Akka components like entities and
+ * views should be defined.
+ */
+package ${package}.application;

akka-javasdk-maven/akka-javasdk-archetype/src/main/resources/archetype-resources/src/main/java/__packageInPathFormat__/domain/package-info.java

@@ -0,0 +1,5 @@
+/**
+ * This module is for the domain model of the service. It is should contain plain Java classes that does not
+ * depend on the Akka APIs.
+ */
+package ${package}.domain;

akka-javasdk-maven/akka-javasdk-parent/pom.xml

@@ -7,12 +7,12 @@
     <parent>
         <groupId>io.akka</groupId>
         <artifactId>akka-javasdk-maven</artifactId>
-        <version>3.0.2</version>
+        <version>3.1.0</version>
     </parent>
 
     <groupId>io.akka</groupId>
     <artifactId>akka-javasdk-parent</artifactId>
-    <version>3.0.2</version>
+    <version>3.1.0</version>
     <packaging>pom</packaging>
 
 
@@ -34,11 +34,11 @@
 
         <maven.build.timestamp.format>yyyyMMddHHmmss</maven.build.timestamp.format>
 
-        <akka-javasdk.version>3.0.2</akka-javasdk.version>
+        <akka-javasdk.version>3.1.0</akka-javasdk.version>
 
         <!-- These are dependent on runtime environment and cannot be customized by users -->
         <maven.compiler.release>21</maven.compiler.release>
-        <kalix-runtime.version>1.2.5</kalix-runtime.version>
+        <kalix-runtime.version>1.3.0</kalix-runtime.version>
 
         <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
         <skip.docker>false</skip.docker>
@@ -160,8 +160,6 @@
                                                         <exclude>com.typesafe.akka:akka-stream_2.13</exclude>
                                                         <exclude>com.hierynomus:asn-one</exclude>
                                                         <exclude>org.reactivestreams:reactive-streams</exclude>
-                                                        <!-- Runtime -->
-                                                        <exclude>io.kalix:kalix-proxy-protocol</exclude>
                                                         <!-- Scala stdlib -->
                                                         <exclude>org.scala-lang.modules:scala-collection-compat_2.13</exclude>
                                                         <exclude>org.scala-lang:scala-library</exclude>
@@ -172,9 +170,7 @@
                                                         <exclude>io.grpc:grpc-stub</exclude>
                                                         <exclude>io.grpc:grpc-api</exclude>
                                                         <exclude>com.google.protobuf:protobuf-java</exclude>
-                                                        <exclude>com.google.protobuf:protobuf-java-util</exclude>
                                                         <!-- guava and related -->
-                                                        <exclude>com.google.code.gson:gson</exclude>
                                                         <exclude>com.google.guava:guava</exclude>
                                                         <exclude>com.google.guava:failureaccess</exclude>
                                                         <exclude>com.google.guava:listenablefuture</exclude>
@@ -313,7 +309,7 @@
                     <artifactId>exec-maven-plugin</artifactId>
                     <version>3.4.1</version>
                     <configuration>
-                        <mainClass>kalix.runtime.KalixRuntimeMain</mainClass>
+                        <mainClass>kalix.runtime.AkkaRuntimeMain</mainClass>
                         <systemProperties>
                             <systemProperty>
                                 <key>akka.javasdk.dev-mode.enabled</key>
@@ -348,7 +344,7 @@
                 <groupId>org.apache.maven.plugins</groupId>
                 <artifactId>maven-surefire-plugin</artifactId>
             </plugin>
-            
+
             <plugin>
                 <groupId>org.apache.maven.plugins</groupId>
                 <artifactId>maven-failsafe-plugin</artifactId>
@@ -393,7 +389,7 @@
                                 </goals>
                                 <configuration>
                                     <source>
-                                        log.warn('The 'it' profile is deprecated. It will be removed in future versions. Integration tests only need `mvn integration-test` to run.')
+                                        log.warn('The 'it' profile is deprecated. It will be removed in future versions. Integration tests only need `mvn verify` to run.')
                                     </source>
                                 </configuration>
                             </execution>

akka-javasdk-maven/pom.xml

@@ -5,7 +5,7 @@
 
   <groupId>io.akka</groupId>
   <artifactId>akka-javasdk-maven</artifactId>
-  <version>3.0.2</version>
+  <version>3.1.0</version>
   <packaging>pom</packaging>
 
   <name>Akka SDK for Java Maven</name>

akka-javasdk-testkit/src/main/java/akka/javasdk/testkit/EventSourcedResult.java

@@ -44,8 +44,18 @@ public interface EventSourcedResult<R> {
    */
   Object getUpdatedState();
 
+  /**
+   * @return Whether the command handler persist events or not.
+   * @deprecated Use {@link #didPersistEvents()} instead.
+   */
+  @Deprecated(since = "3.0.2", forRemoval = true)
   boolean didEmitEvents();
 
+  /**
+   * @return Whether the command handler persist events or not.
+   */
+  boolean didPersistEvents();
+
   /** @return All the events that were emitted by handling this command. */
   List<Object> getAllEvents();
 

akka-javasdk-testkit/src/main/java/akka/javasdk/testkit/EventSourcedTestKit.java

@@ -7,10 +7,10 @@
 import akka.javasdk.Metadata;
 import akka.javasdk.eventsourcedentity.EventSourcedEntity;
 import akka.javasdk.eventsourcedentity.EventSourcedEntityContext;
-import akka.javasdk.impl.JsonMessageCodec;
 import akka.javasdk.testkit.impl.EventSourcedEntityEffectsRunner;
 import akka.javasdk.testkit.impl.TestKitEventSourcedEntityContext;
 
+import java.util.List;
 import java.util.function.Function;
 import java.util.function.Supplier;
 
@@ -26,16 +26,23 @@
 public class EventSourcedTestKit<S, E, ES extends EventSourcedEntity<S, E>>
     extends EventSourcedEntityEffectsRunner<S, E> {
 
-  private final ES entity;
   private final String entityId;
 
-  private final JsonMessageCodec messageCodec;
+  public static final String DEFAULT_TEST_ENTITY_ID = "testkit-entity-id";
 
   private EventSourcedTestKit(ES entity, String entityId) {
     super(entity);
-    this.entity = entity;
     this.entityId = entityId;
-    this.messageCodec = new JsonMessageCodec();
+  }
+
+  private EventSourcedTestKit(ES entity, String entityId, S initialState) {
+    super(entity, initialState);
+    this.entityId = entityId;
+  }
+
+  private EventSourcedTestKit(ES entity, String entityId, List<E> initialEvents) {
+    super(entity, initialEvents);
+    this.entityId = entityId;
   }
 
   /**
@@ -45,7 +52,28 @@ private EventSourcedTestKit(ES entity, String entityId) {
    */
   public static <S, E, ES extends EventSourcedEntity<S, E>> EventSourcedTestKit<S, E, ES> of(
       Supplier<ES> entityFactory) {
-    return of("testkit-entity-id", entityFactory);
+    return of(DEFAULT_TEST_ENTITY_ID, entityFactory);
+  }
+
+  /**
+   * Creates a new testkit instance from a Supplier of EventSourcedEntity and a state.
+   *
+   * <p>A default test entity id will be automatically provided.
+   */
+  public static <S, E, ES extends EventSourcedEntity<S, E>> EventSourcedTestKit<S, E, ES> ofEntityWithState(
+      Supplier<ES> entityFactory, S initialState) {
+    return ofEntityWithState(DEFAULT_TEST_ENTITY_ID, entityFactory, initialState);
+  }
+
+  /**
+   * Creates a new testkit instance from a Supplier of EventSourcedEntity and events from which to
+   * derive a state for the generated entity.
+   *
+   * <p>A default test entity id will be automatically provided.
+   */
+  public static <S, E, ES extends EventSourcedEntity<S, E>> EventSourcedTestKit<S, E, ES> ofEntityFromEvents(
+      Supplier<ES> entityFactory, List<E> initialEvents) {
+    return ofEntityFromEvents(DEFAULT_TEST_ENTITY_ID, entityFactory, initialEvents);
   }
 
   /**
@@ -55,7 +83,29 @@ public static <S, E, ES extends EventSourcedEntity<S, E>> EventSourcedTestKit<S,
    */
   public static <S, E, ES extends EventSourcedEntity<S, E>> EventSourcedTestKit<S, E, ES> of(
       Function<EventSourcedEntityContext, ES> entityFactory) {
-    return of("testkit-entity-id", entityFactory);
+    return of(DEFAULT_TEST_ENTITY_ID, entityFactory);
+  }
+
+  /**
+   * Creates a new testkit instance from a factory function for EventSourcedEntity and a state into
+   * which the built entity will be placed for tests.
+   *
+   * <p>A default test entity id will be automatically provided.
+   */
+  public static <S, E, ES extends EventSourcedEntity<S, E>> EventSourcedTestKit<S, E, ES> ofEntityWithState(
+      Function<EventSourcedEntityContext, ES> entityFactory, S initialState) {
+    return ofEntityWithState(DEFAULT_TEST_ENTITY_ID, entityFactory, initialState);
+  }
+
+  /**
+   * Creates a new testkit instance from a factory function for EventSourcedEntity and events from
+   * which to derive a state for the generated entity for tests.
+   *
+   * <p>A default test entity id will be automatically provided.
+   */
+  public static <S, E, ES extends EventSourcedEntity<S, E>> EventSourcedTestKit<S, E, ES> ofEntityFromEvents(
+      Function<EventSourcedEntityContext, ES> entityFactory, List<E> initialEvents) {
+    return ofEntityFromEvents(DEFAULT_TEST_ENTITY_ID, entityFactory, initialEvents);
   }
 
   /**
@@ -67,14 +117,49 @@ public static <S, E, ES extends EventSourcedEntity<S, E>> EventSourcedTestKit<S,
     return of(entityId, ctx -> entityFactory.get());
   }
 
+  /**
+   * Creates a new testkit instance from a user defined entity id, a Supplier of EventSourcedEntity,
+   * and a state into which the supplied entity will be placed for tests.
+   */
+  public static <S, E, ES extends EventSourcedEntity<S, E>> EventSourcedTestKit<S, E, ES> ofEntityWithState(
+      String entityId, Supplier<ES> entityFactory, S initialState) {
+    return ofEntityWithState(entityId, ctx -> entityFactory.get(), initialState);
+  }
+
+  /**
+   * Creates a new testkit instance from a user defined entity id, a Supplier of EventSourcedEntity,
+   * and events from which to derive a state for the generated entity for tests.
+   */
+  public static <S, E, ES extends EventSourcedEntity<S, E>> EventSourcedTestKit<S, E, ES> ofEntityFromEvents(
+      String entityId, Supplier<ES> entityFactory, List<E> initialEvents) {
+    return ofEntityFromEvents(entityId, ctx -> entityFactory.get(), initialEvents);
+  }
+
   /**
    * Creates a new testkit instance from a user defined entity id and a function
    * EventSourcedEntityContext to EventSourcedEntity.
    */
   public static <S, E, ES extends EventSourcedEntity<S, E>> EventSourcedTestKit<S, E, ES> of(
       String entityId, Function<EventSourcedEntityContext, ES> entityFactory) {
-    EventSourcedEntityContext context = new TestKitEventSourcedEntityContext(entityId);
-    return new EventSourcedTestKit<>(entityFactory.apply(context), entityId);
+    return new EventSourcedTestKit<>(entityWithId(entityId, entityFactory), entityId);
+  }
+
+  /**
+   * Creates a new testkit instance from a user defined entity id, a factory function for
+   * EventSourcedEntity, and a state into which the built entity will be placed for tests.
+   */
+  public static <S, E, ES extends EventSourcedEntity<S, E>> EventSourcedTestKit<S, E, ES> ofEntityWithState(
+      String entityId, Function<EventSourcedEntityContext, ES> entityFactory, S initialState) {
+    return new EventSourcedTestKit<>(entityWithId(entityId, entityFactory), entityId, initialState);
+  }
+
+  /**
+   * Creates a new testkit instance from a user defined entity id, a factory function for
+   * EventSourcedEntity, and events from which to derive a state for the generated entity for tests.
+   */
+  public static <S, E, ES extends EventSourcedEntity<S, E>> EventSourcedTestKit<S, E, ES> ofEntityFromEvents(
+      String entityId, Function<EventSourcedEntityContext, ES> entityFactory, List<E> initialEvents) {
+    return new EventSourcedTestKit<>(entityWithId(entityId, entityFactory), entityId, initialEvents);
   }
 
   /**
@@ -100,12 +185,19 @@ public <R> EventSourcedResult<R> call(Function<ES, EventSourcedEntity.Effect<R>>
    * @param <R>      The type of reply that is expected from invoking a command handler
    * @return a EventSourcedResult
    */
+  @SuppressWarnings("unchecked") // entity() returns the entity we were constructed with
   public <R> EventSourcedResult<R> call(Function<ES, EventSourcedEntity.Effect<R>> func, Metadata metadata) {
-    return interpretEffects(() -> func.apply(entity), entityId, metadata);
+    return interpretEffects(() -> func.apply((ES)entity()), entityId, metadata);
   }
 
   @Override
   protected final S handleEvent(S state, E event) {
-    return entity.applyEvent(event);
+    return entity().applyEvent(event);
+  }
+
+  private static <S, E, ES extends EventSourcedEntity<S, E>> ES entityWithId(
+      String entityId, Function<EventSourcedEntityContext, ES> entityFactory) {
+    EventSourcedEntityContext context = new TestKitEventSourcedEntityContext(entityId);
+    return entityFactory.apply(context);
   }
 }