WIP-CRUD on top of Event Sourcing

java-support/src/main/java/io/cloudstate/javasupport/CloudState.java

@@ -18,13 +18,17 @@
 
 import com.typesafe.config.Config;
 import com.google.protobuf.Descriptors;
+import io.cloudstate.javasupport.crud.CrudEntity;
 import io.cloudstate.javasupport.crdt.CrdtEntity;
 import io.cloudstate.javasupport.crdt.CrdtEntityFactory;
+import io.cloudstate.javasupport.crud.CrudEntityFactory;
 import io.cloudstate.javasupport.eventsourced.EventSourcedEntity;
 import io.cloudstate.javasupport.eventsourced.EventSourcedEntityFactory;
 import io.cloudstate.javasupport.impl.AnySupport;
 import io.cloudstate.javasupport.impl.crdt.AnnotationBasedCrdtSupport;
 import io.cloudstate.javasupport.impl.crdt.CrdtStatefulService;
+import io.cloudstate.javasupport.impl.crud.AnnotationBasedCrudSupport;
+import io.cloudstate.javasupport.impl.crud.CrudStatefulService;
 import io.cloudstate.javasupport.impl.eventsourced.AnnotationBasedEventSourcedSupport;
 import io.cloudstate.javasupport.impl.eventsourced.EventSourcedStatefulService;
 
@@ -137,7 +141,7 @@ public CloudState registerEventSourcedEntity(
   }
 
   /**
-   * Register an event sourced entity factor.
+   * Register an event sourced entity factory.
    *
    * <p>This is a low level API intended for custom (eg, non reflection based) mechanisms for
    * implementing the entity.
@@ -205,7 +209,7 @@ public CloudState registerCrdtEntity(
   }
 
   /**
-   * Register an CRDt entity factory.
+   * Register an CRDT entity factory.
    *
    * <p>This is a low level API intended for custom (eg, non reflection based) mechanisms for
    * implementing the entity.
@@ -227,6 +231,86 @@ public CloudState registerCrdtEntity(
     return this;
   }
 
+  /**
+   * Register an annotated CRUD entity.
+   *
+   * <p>The entity class must be annotated with {@link io.cloudstate.javasupport.crud.CrudEntity}.
+   *
+   * @param entityClass The entity class.
+   * @param descriptor The descriptor for the service that this entity implements.
+   * @param additionalDescriptors Any additional descriptors that should be used to look up protobuf
+   *     types when needed.
+   * @return This stateful service builder.
+   */
+  public CloudState registerCrudEntity(
+      Class<?> entityClass,
+      Descriptors.ServiceDescriptor descriptor,
+      Descriptors.FileDescriptor... additionalDescriptors) {
+
+    CrudEntity entity = entityClass.getAnnotation(CrudEntity.class);
+    if (entity == null) {
+      throw new IllegalArgumentException(
+          entityClass + " does not declare an " + CrudEntity.class + " annotation!");
+    }
+
+    final String persistenceId;
+    final int snapshotEvery;
+    if (entity.persistenceId().isEmpty()) {
+      persistenceId = entityClass.getSimpleName();
+      snapshotEvery = 0; // Default
+    } else {
+      persistenceId = entity.persistenceId();
+      snapshotEvery = entity.snapshotEvery();
+    }
+
+    final AnySupport anySupport = newAnySupport(additionalDescriptors);
+
+    services.put(
+        descriptor.getFullName(),
+        new CrudStatefulService(
+            new AnnotationBasedCrudSupport(entityClass, anySupport, descriptor),
+            descriptor,
+            anySupport,
+            persistenceId,
+            snapshotEvery));
+
+    return this;
+  }
+
+  /**
+   * Register an CRUD entity factory.
+   *
+   * <p>This is a low level API intended for custom (eg, non reflection based) mechanisms for
+   * implementing the entity.
+   *
+   * @param factory The CRUD factory.
+   * @param descriptor The descriptor for the service that this entity implements.
+   * @param persistenceId The persistence id for this entity.
+   * @param snapshotEvery Specifies how snapshots of the entity state should be made: Zero means use
+   *     default from configuration file. (Default) Any negative value means never snapshot. Any
+   *     positive value means snapshot at-or-after that number of events.
+   * @param additionalDescriptors Any additional descriptors that should be used to look up protobuf
+   *     types when needed.
+   * @return This stateful service builder.
+   */
+  public CloudState registerCrudEntity(
+      CrudEntityFactory factory,
+      Descriptors.ServiceDescriptor descriptor,
+      String persistenceId,
+      int snapshotEvery,
+      Descriptors.FileDescriptor... additionalDescriptors) {
+    services.put(
+        descriptor.getFullName(),
+        new CrudStatefulService(
+            factory,
+            descriptor,
+            newAnySupport(additionalDescriptors),
+            persistenceId,
+            snapshotEvery));
+
+    return this;
+  }
+
   /**
    * Starts a server with the configured entities.
    *

java-support/src/main/java/io/cloudstate/javasupport/crud/CommandContext.java

@@ -0,0 +1,60 @@
+/*
+ * Copyright 2019 Lightbend Inc.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package io.cloudstate.javasupport.crud;
+
+import io.cloudstate.javasupport.ClientActionContext;
+import io.cloudstate.javasupport.EffectContext;
+
+/**
+ * An CRUD command context.
+ *
+ * <p>Methods annotated with {@link CommandHandler} may take this is a parameter. It allows updating
+ * or deleting the entity state in response to a command, along with forwarding the result to other
+ * entities, and performing side effects on other entities.
+ */
+public interface CommandContext extends CrudContext, ClientActionContext, EffectContext {
+  /**
+   * The current sequence number of state in this entity.
+   *
+   * @return The current sequence number.
+   */
+  long sequenceNumber();
+
+  /**
+   * The name of the command being executed.
+   *
+   * @return The name of the command.
+   */
+  String commandName();
+
+  /**
+   * The id of the command being executed.
+   *
+   * @return The id of the command.
+   */
+  long commandId();
+
+  /**
+   * Update the entity with the new state. The state will be persisted.
+   *
+   * @param state The state to persist.
+   */
+  void update(Object state);
+
+  /** Delete the entity. */
+  void delete();
+}

java-support/src/main/java/io/cloudstate/javasupport/crud/CommandHandler.java

@@ -0,0 +1,54 @@
+/*
+ * Copyright 2019 Lightbend Inc.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package io.cloudstate.javasupport.crud;
+
+import io.cloudstate.javasupport.impl.CloudStateAnnotation;
+
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+/**
+ * Marks a method as a command handler.
+ *
+ * <p>This method will be invoked whenever the service call with name that matches this command
+ * handlers name is invoked.
+ *
+ * <p>The method may take the command object as a parameter, its type must match the gRPC service
+ * input type.
+ *
+ * <p>The return type of the method must match the gRPC services output type.
+ *
+ * <p>The method may also take a {@link CommandContext}, and/or a {@link
+ * io.cloudstate.javasupport.EntityId} annotated {@link String} parameter.
+ */
+@CloudStateAnnotation
+@Target(ElementType.METHOD)
+@Retention(RetentionPolicy.RUNTIME)
+public @interface CommandHandler {
+
+  /**
+   * The name of the command to handle.
+   *
+   * <p>If not specified, the name of the method will be used as the command name, with the first
+   * letter capitalized to match the gRPC convention of capitalizing rpc method names.
+   *
+   * @return The command name.
+   */
+  String name() default "";
+}

java-support/src/main/java/io/cloudstate/javasupport/crud/CrudContext.java

@@ -0,0 +1,22 @@
+/*
+ * Copyright 2019 Lightbend Inc.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package io.cloudstate.javasupport.crud;
+
+import io.cloudstate.javasupport.EntityContext;
+
+/** Root context for all CRUD contexts. */
+public interface CrudContext extends EntityContext {}

java-support/src/main/java/io/cloudstate/javasupport/crud/CrudEntity.java

@@ -0,0 +1,45 @@
+/*
+ * Copyright 2019 Lightbend Inc.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package io.cloudstate.javasupport.crud;
+
+import io.cloudstate.javasupport.impl.CloudStateAnnotation;
+
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+/** An CRUD entity. */
+@CloudStateAnnotation
+@Target(ElementType.TYPE)
+@Retention(RetentionPolicy.RUNTIME)
+public @interface CrudEntity {
+  /**
+   * The name of the persistence id.
+   *
+   * <p>If not specified, defaults to the entities unqualified classname. It's strongly recommended
+   * that you specify it explicitly.
+   */
+  String persistenceId() default "";
+
+  /**
+   * Specifies how snapshots of the entity state should be made: Zero means use default from
+   * configuration file. (Default) Any negative value means never snapshot. Any positive value means
+   * snapshot at-or-after that number of events.
+   */
+  int snapshotEvery() default 0;
+}

java-support/src/main/java/io/cloudstate/javasupport/crud/CrudEntityCreationContext.java

@@ -0,0 +1,24 @@
+/*
+ * Copyright 2019 Lightbend Inc.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package io.cloudstate.javasupport.crud;
+
+/**
+ * Creation context for {@link CrudEntity} annotated entities.
+ *
+ * <p>This may be accepted as an argument to the constructor of an CRUD entity.
+ */
+public interface CrudEntityCreationContext extends CrudContext {}

java-support/src/main/java/io/cloudstate/javasupport/crud/CrudEntityFactory.java

@@ -0,0 +1,36 @@
+/*
+ * Copyright 2019 Lightbend Inc.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package io.cloudstate.javasupport.crud;
+
+import io.cloudstate.javasupport.eventsourced.CommandHandler;
+import io.cloudstate.javasupport.eventsourced.EventHandler;
+
+/**
+ * Low level interface for handling commands on an CRUD entity.
+ *
+ * <p>Generally, this should not be needed, instead, a class annotated with the {@link
+ * CommandHandler} and similar annotations should be used.
+ */
+public interface CrudEntityFactory {
+  /**
+   * Create an entity handler for the given context.
+   *
+   * @param context The context.
+   * @return The handler for the given context.
+   */
+  CrudEntityHandler create(CrudContext context);
+}