docs: adapt samples and documentation for new codegen annotation (#748)

Co-authored-by: Peter Vlugter <[email protected]>

codegen/core/src/test/resources/test-shoppingcart/shoppingcart_api.proto

@@ -14,16 +14,16 @@
 
 syntax = "proto3";
 
-package com.example.shoppingcart;  // <1>
+package com.example.shoppingcart;  
 
-import "google/protobuf/empty.proto"; // <2>
+import "google/protobuf/empty.proto";
 import "akkaserverless/annotations.proto";
 import "google/api/annotations.proto";
 
-option java_outer_classname = "ShoppingCartApi";  // <3>
+option java_outer_classname = "ShoppingCartApi";
 
-message AddLineItem { // <4>
-  string cart_id = 1 [(akkaserverless.field).entity_key = true];  // <5>
+message AddLineItem {
+  string cart_id = 1 [(akkaserverless.field).entity_key = true];
   string product_id = 2;
   string name = 3;
   int32 quantity = 4;
@@ -49,14 +49,17 @@ message LineItem {
   int64 quantity = 3;
 }
 
-message Cart {  // <6>
+message Cart {
   repeated LineItem items = 1;
 }
 
-service ShoppingCartService {  // <7>
-  option (akkaserverless.service) = {  // <8>
-    type: SERVICE_TYPE_ENTITY
-    component: ".domain.ShoppingCart"
+service ShoppingCartService { 
+  option (akkaserverless.codegen) = {
+    value_entity: {
+      name: ".domain.ShoppingCart"
+      entity_type: "shopping-cart"
+      state: ".domain.Cart"
+    }
   };
 
   rpc AddItem (AddLineItem) returns (google.protobuf.Empty) {
@@ -86,4 +89,3 @@ service ShoppingCartService {  // <7>
     option (google.api.http).post = "/carts/{cart_id}/remove";
   }
 }
-

codegen/core/src/test/resources/test-shoppingcart/shoppingcart_domain.proto

@@ -13,30 +13,12 @@
 // limitations under the License.
 
 // These are the messages that get persisted - the current state (Cart).
-
-// tag::domain[]
-// tag::proto_syntax[]
 syntax = "proto3";
-// end::proto_syntax[]
 
 package com.example.shoppingcart.domain;
 
 option java_outer_classname = "ShoppingCartDomain";
 
-// tag::proto_imports[]
-import "akkaserverless/annotations.proto";
-// end::proto_imports[]
-
-// tag::proto_state[]
-// Describes how this domain relates to a value entity
-option (akkaserverless.file).value_entity = {
-  name: "ShoppingCart"
-  entity_type: "shopping-cart"
-  state: "Cart"
-};
-// end::proto_state[]
-
-// tag::proto_messages[]
 message LineItem {
   string productId = 1;
   string name = 2;
@@ -47,5 +29,3 @@ message LineItem {
 message Cart {
   repeated LineItem items = 1;
 }
-// end::proto_messages[]
-// end::domain[]

docs/src/modules/java/pages/actions-publishing-subscribing.adoc

@@ -29,7 +29,7 @@ Java::
 include::example$java-eventsourced-counter/src/main/proto/com/example/actions/counter_topic.proto[tag=counter-topic]
 ----
 <1> Import the Counter Domain file containing the definitions of the events. This is typically a proto definition within the same service.
-<2> The protobuf option (akkaserverless.service) is specific to code-generation as provided by the Akka Serverless Maven plugin. This annotation indicates to the code-generation that an Action must be generated.
+<2> The protobuf option (akkaserverless.codegen) is specific to code-generation as provided by the Akka Serverless Maven plugin. This annotation indicates to the code-generation that an Action must be generated.
 <3> The `Increase` method receives the event `ValueIncreased` and returns the transformed type `Increased`. 
 <4> The `(akkaserverless.method).eventing.in` annotation indicates that events from the entity type `counter` should be delivered to this method (when the type is `ValueIncreased`).
 <5> The `(akkaserverless.method).eventing.out` annotation indicates that the returned value from this method should be published to the topic called `counter-events`.
@@ -42,7 +42,7 @@ Scala::
 include::example$scala-eventsourced-counter/src/main/proto/com/example/actions/counter_topic.proto[tag=counter-topic]
 ----
 <1> Import the Counter Domain file containing the definitions of the events. This is typically a proto definition within the same service.
-<2> The protobuf option (akkaserverless.service) is specific to code-generation as provided by the Akka Serverless sbt plugin. This annotation indicates to the code-generation that an Action must be generated.
+<2> The protobuf option (akkaserverless.codegen) is specific to code-generation as provided by the Akka Serverless sbt plugin. This annotation indicates to the code-generation that an Action must be generated.
 <3> The `Increase` method receives the event `ValueIncreased` and returns the transformed type `Increased`.
 <4> The `(akkaserverless.method).eventing.in` annotation indicates that events from the entity type `counter` should be delivered to this method (when the type is `ValueIncreased`).
 <5> The `(akkaserverless.method).eventing.out` annotation indicates that the returned value from this method should be published to the topic called `counter-events`.
@@ -84,7 +84,7 @@ Java::
 include::example$java-valueentity-counter/src/main/proto/com/example/actions/counter_states_sub.proto[tag=state-subscription]
 ----
 <1> Import the Counter Domain from the Value Entity example (see xref:java:value-entity.adoc[Implementing Value Entities])
-<2> The protobuf option (akkaserverless.service) is specific to code-generation as provided by the Akka Serverless Maven plugin. This annotation indicates to the code-generation that an Action must be generated.
+<2> The protobuf option (akkaserverless.codegen) is specific to code-generation as provided by the Akka Serverless Maven plugin. This annotation indicates to the code-generation that an Action must be generated.
 <3> The `(akkaserverless.method).eventing.in` annotation indicates that state changes from the value entity type `counter` should be delivered to this method. 
 
 Scala::
@@ -95,7 +95,7 @@ Scala::
 include::example$scala-valueentity-counter/src/main/proto/com/example/actions/counter_states_sub.proto[tag=state-subscription]
 ----
 <1> Import the Counter Domain from the Value Entity example (see xref:java:value-entity.adoc[Implementing Value Entities])
-<2> The protobuf option (akkaserverless.service) is specific to code-generation as provided by the Akka Serverless sbt plugin. This annotation indicates to the code-generation that an Action must be generated.
+<2> The protobuf option (akkaserverless.codegen) is specific to code-generation as provided by the Akka Serverless sbt plugin. This annotation indicates to the code-generation that an Action must be generated.
 <3> The `(akkaserverless.method).eventing.in` annotation indicates that state changes from the value entity type `counter` should be delivered to this method. 
 
 == Subscribing to a Topic
@@ -115,7 +115,7 @@ Java::
 include::example$java-eventsourced-counter/src/main/proto/com/example/actions/counter_topic_sub.proto[tag=counter-topic-sub]
 ----
 <1> Import the Counter Topic types from previous example.
-<2> The protobuf option (akkaserverless.service) is specific to code-generation as provided by the Akka Serverless Maven plugin. This annotation indicates to the code-generation that an Action must be generated.
+<2> The protobuf option (akkaserverless.codegen) is specific to code-generation as provided by the Akka Serverless Maven plugin. This annotation indicates to the code-generation that an Action must be generated.
 <3> Define methods for each of the possible incoming messages and annotate them with `(akkaserverless.method).eventing.in` indicating that the source of events is the topic `counter-events`.
 
 Scala::
@@ -126,7 +126,7 @@ Scala::
 include::example$scala-eventsourced-counter/src/main/proto/com/example/actions/counter_topic_sub.proto[tag=counter-topic-sub]
 ----
 <1> Import the Counter Topic types from previous example.
-<2> The protobuf option (akkaserverless.service) is specific to code-generation as provided by the Akka Serverless sbt plugin. This annotation indicates to the code-generation that an Action must be generated.
+<2> The protobuf option (akkaserverless.codegen) is specific to code-generation as provided by the Akka Serverless sbt plugin. This annotation indicates to the code-generation that an Action must be generated.
 <3> Define methods for each of the possible incoming messages and annotate them with `(akkaserverless.method).eventing.in` indicating that the source of events is the topic `counter-events`.
 
 The class `CounterTopicSubscriptionAction` gets generated for us based on the proto file defined above.

docs/src/modules/java/pages/actions.adoc

@@ -21,7 +21,7 @@ include::example$java-fibonacci-action/src/main/proto/com/example/fibonacci/fibo
 <1> Any classes generated from this protobuf file will be in the `com.example.fibonacci` package.
 <2> Import the Akka Serverless protobuf annotations or options.
 <3> Let the messages declared in this protobuf file be inner classes to the Java class `FibonacciApi`.
-<4> The protobuf option (akkaserverless.service) is specific to code-generation as provided by the Akka Serverless Maven plugin. This annotation indicates to the code-generation that an Action must be generated.
+<4> The protobuf option (akkaserverless.codegen) is specific to code-generation as provided by the Akka Serverless Maven plugin. This annotation indicates to the code-generation that an Action must be generated.
 
 Scala::
 +
@@ -32,7 +32,7 @@ include::example$scala-fibonacci-action/src/main/proto/com/example/fibonacci/fib
 ----
 <1> Any classes generated from this protobuf file will be in the `com.example.fibonacci` package.
 <2> Import the Akka Serverless protobuf annotations or options.
-<3> The protobuf option (akkaserverless.service) is specific to code-generation as provided by the Akka Serverless sbt plugin. This annotation indicates to the code-generation that an Action must be generated.
+<3> The protobuf option (akkaserverless.codegen) is specific to code-generation as provided by the Akka Serverless sbt plugin. This annotation indicates to the code-generation that an Action must be generated.
 
 == Implementing the Action
 

docs/src/modules/java/pages/event-sourced-entities.adoc

@@ -33,13 +33,7 @@ Java::
 include::example$java-eventsourced-shopping-cart/src/main/proto/com/example/shoppingcart/domain/shoppingcart_domain.proto[tag=domain]
 ----
 <1> Any classes generated from this protobuf file will be in the Java package `com.example.shoppingcart.domain`.
-<2> Import the Akka Serverless protobuf annotations or options.
-<3> Let the messages declared in this protobuf file be inner classes to the Java class `ShoppingCartDomain`.
-<4> The protobuf option `(akkaserverless.file).event_sourced_entity` is specific to code-generation as provided by the Akka Serverless Maven plugin.
-<5> `name` denotes the base name for the Event Sourced Entity, the code-generation will create initial sources `ShoppingCart`, `ShoppingCartTest` and `ShoppingCartIntegrationTest`. Once these files exist, they are not overwritten, so you can freely add logic to them.
-<6> `entity_type` is a unique identifier of the "state storage". The entity name may be changed even after data has been created, the `entity_type` can't.
-<7> `state` points to the protobuf message representing the entity's state which is kept by Akka Serverless. It is stored as snapshots.
-<8> `events` points to the protobuf message representing the entity's events, which are stored by Akka Serverless.
+<2> Let the messages declared in this protobuf file be inner classes to the Java class `ShoppingCartDomain`.
 
 Scala::
 +
@@ -49,13 +43,6 @@ Scala::
 include::example$scala-eventsourced-shopping-cart/src/main/proto/com/example/shoppingcart/domain/shoppingcart_domain.proto[tag=domain]
 ----
 <1> Any classes generated from this protobuf file will be in the Scala package `com.example.shoppingcart.domain`.
-<2> Import the Akka Serverless protobuf annotations or options.
-<3> The protobuf option `(akkaserverless.file).event_sourced_entity` is specific to code-generation as provided by the Akka Serverless sbt plugin.
-<4> `name` denotes the base name for the Event Sourced Entity, the code-generation will create initial sources `ShoppingCart`, `ShoppingCartTest` and `ShoppingCartIntegrationTest`. Once these files exist, they are not overwritten, so you can freely add logic to them.
-<5> `entity_type` is a unique identifier of the "state storage". The entity name may be changed even after data has been created, the `entity_type` can't.
-<6> `state` points to the protobuf message representing the entity's state which is kept by Akka Serverless. It is stored as snapshots.
-<7> `events` points to the protobuf message representing the entity's events, which are stored by Akka Serverless.
-
 
 The `shoppingcart_api.proto` file defines the commands we can send to the shopping cart service to manipulate or access the cart's state. They make up the service API:
 
@@ -74,7 +61,13 @@ include::example$java-eventsourced-shopping-cart/src/main/proto/com/example/shop
 <5> Every Command must contain a `string` field that contains the entity ID and is marked with the `(akkaserverless.field).entity_key` option.
 <6> Messages describe the return value for our API. For methods that don't have return values, we use `google.protobuf.Empty`.
 <7> The service descriptor shows the API of the entity. It lists the methods a client can use to issue Commands to the entity.
-<8> The protobuf option `(akkaserverless.service)`  is specific to code-generation as provided by the Akka Serverless Maven plugin and points to the protobuf definition `ShoppingCart` we've seen above (in the `com.example.shoppingcart.domain` package).
+<8> The protobuf option `(akkaserverless.codegen)`  is specific to code-generation as provided by the Akka Serverless Maven plugin.
+<9> `event_sourced_entity` indicates that we want the codegen to generate an Event Sourced Entity for this service.
+<10> `name` denotes the base name for the Event Sourced Entity, the code-generation will create initial sources `ShoppingCart`, `ShoppingCartTest` and `ShoppingCartIntegrationTest`. Once these files exist, they are not overwritten, so you can freely add logic to them.
+<11> `entity_type` is a unique identifier of the "state storage". The entity name may be changed even after data has been created, the `entity_type` can't.
+<12> `state` points to the protobuf message representing the entity's state which is kept by Akka Serverless. It is stored as snapshots.
+<13> `events` points to the protobuf message representing the entity's events, which are stored by Akka Serverless.
+
 
 Scala::
 +
@@ -89,7 +82,12 @@ include::example$scala-eventsourced-shopping-cart/src/main/proto/com/example/sho
 <4> Every Command must contain a `string` field that contains the entity ID and is marked with the `(akkaserverless.field).entity_key` option.
 <5> Messages describe the return value for our API. For methods that don't have return values, we use `google.protobuf.Empty`.
 <6> The service descriptor shows the API of the entity. It lists the methods a client can use to issue Commands to the entity.
-<7> The protobuf option `(akkaserverless.service)`  is specific to code-generation as provided by the Akka Serverless sbt plugin and points to the protobuf definition `ShoppingCart` we've seen above (in the `com.example.shoppingcart.domain` package).
+<7> The protobuf option `(akkaserverless.codegen)`  is specific to code-generation as provided by the Akka Serverless sbt plugin.
+<8> `event_sourced_entity` indicates that we want the codegen to generate an Event Sourced Entity for this service.
+<9> `name` denotes the base name for the Event Sourced Entity, the code-generation will create initial sources `ShoppingCart`, `ShoppingCartTest` and `ShoppingCartIntegrationTest`. Once these files exist, they are not overwritten, so you can freely add logic to them.
+<10> `entity_type` is a unique identifier of the "state storage". The entity name may be changed even after data has been created, the `entity_type` can't.
+<11> `state` points to the protobuf message representing the entity's state which is kept by Akka Serverless. It is stored as snapshots.
+<12> `events` points to the protobuf message representing the entity's events, which are stored by Akka Serverless.
 
 
 == Implementing behavior
@@ -157,7 +155,7 @@ include::example$scala-eventsourced-shopping-cart/src/main/scala/com/example/sho
 <3> We store the event by returning an `Effect` with `effects.emitEvent`.
 <4> The acknowledgment that the command was successfully processed is only sent if the event was successfully stored, otherwise there will be an error reply.
 
-The new state is created from the event and the previous state in the event handler. Event handlers are implemented in the `ShoppingCart` class as methods that override abstract methods from `AbstractShoppingCart`.
+The new state is created from the event and the previous state in the event handler. Event handlers are implemented in the `ShoppingCart` class as methods that override abstract methods from `AbstractShoppingCart`. Event handlers are generated for each event declared in  `(akkaserverless.codegen).event_sourced_entity.events`.
 
 [.tabset]
 Java::
@@ -177,26 +175,6 @@ include::example$scala-eventsourced-shopping-cart/src/main/scala/com/example/sho
 ----
 
 
-Note that you have to define the events in the `(akkaserverless.file).event_sourced_entity`:
-
-[.tabset]
-Java::
-+
-[source,proto]
-.src/main/proto/com/example/shoppingcart/domain/shoppingcart_domain.proto
-----
-include::example$java-eventsourced-shopping-cart/src/main/proto/com/example/shoppingcart/domain/shoppingcart_domain.proto[tag=event_sourced_entity]
-----
-
-Scala::
-+
-[source,proto]
-.src/main/proto/com/example/shoppingcart/domain/shoppingcart_domain.proto
-----
-include::example$scala-eventsourced-shopping-cart/src/main/proto/com/example/shoppingcart/domain/shoppingcart_domain.proto[tag=event_sourced_entity]
-----
-
-
 === Retrieving state
 
 The following example shows the implementation of the `GetCart` command handler. This command handler is a read-only command handler--it doesn't update the state, it just returns it:
@@ -344,4 +322,3 @@ This class is generated by AkkaServerless when the project is compiled and locat
 
 * `currentState` - the current state of the entity, it is updated on each method call emitting events.
 * `allEvents` - all events emitted since the creation of the testkit instance.
-