Add comments to CRUD hooks

crud-framework-core/src/main/java/com/antelopesystem/crudframework/crud/hooks/interfaces/CreateFromHooks.java

@@ -5,14 +5,36 @@
 
 import java.io.Serializable;
 
+/**
+ * This class contains all hook callbacks for the CreateFrom operation. It can be implemented
+ * as many times as needed per entity, or even for abstract entities for use with {@link com.antelopesystem.crudframework.crud.annotation.WithHooks}. Implementations of this interface should be declared as Spring beans.
+ * @param <Entity> the entity to listen to
+ * @param <ID> the ID type of the entity
+ */
 public interface CreateFromHooks<ID extends Serializable, Entity extends BaseCrudEntity<ID>> extends CRUDHooks<ID, Entity> {
 
+	/**
+	 * Called prior to a CreateFrom operation
+	 * @param ro represents the object that will be transformed to the entity
+	 */
 	default void preCreateFrom(@NotNull Object ro) {
 	}
 
+	/**
+	 * Called during a CreateFrom operation.
+	 * This method will be called after field mapping / object decoration between the
+	 * RO and the entity and data access checks, and before validation.
+	 * This method will run inside of a read/write transaction.
+	 * @param entity represents the entity being created
+	 * @param ro represents the object that will be transformed to the entity
+	 */
 	default void onCreateFrom(@NotNull Entity entity, @NotNull Object ro) {
 	}
 
+	/**
+	 * Called after a CreateFrom operation
+	 * @param entity represents the entity that has been created
+	 */
 	default void postCreateFrom(@NotNull Entity entity) {
 	}
 }

crud-framework-core/src/main/java/com/antelopesystem/crudframework/crud/hooks/interfaces/CreateHooks.java

@@ -5,14 +5,34 @@
 
 import java.io.Serializable;
 
+/**
+ * This class contains all hook callbacks for the Create operation. It can be implemented
+ * as many times as needed per entity, or even for abstract entities for use with {@link com.antelopesystem.crudframework.crud.annotation.WithHooks}. Implementations of this interface should be declared as Spring beans.
+ * @param <Entity> the entity to listen to
+ * @param <ID> the ID type of the entity
+ */
 public interface CreateHooks<ID extends Serializable, Entity extends BaseCrudEntity<ID>> extends CRUDHooks<ID, Entity> {
 
+	/**
+	 * Called prior to a Create operation
+	 * @param entity represents the entity being created
+	 */
 	default void preCreate(@NotNull Entity entity) {
 	}
 
+	/**
+	 * Called during a Create operation.
+	 * This method will be called after data access checks, and before validation.
+	 * This method will run inside of a read/write transaction.
+	 * @param entity represents the entity being created
+	 */
 	default void onCreate(@NotNull Entity entity) {
 	}
 
+	/**
+	 * Called after a Create operation
+	 * @param entity represents the entity that has been created
+	 */
 	default void postCreate(@NotNull Entity entity) {
 	}
 }

crud-framework-core/src/main/java/com/antelopesystem/crudframework/crud/hooks/interfaces/DeleteHooks.java

@@ -6,14 +6,35 @@
 import java.io.Serializable;
 
 
+/**
+ * This class contains all hook callbacks for the Delete operation. It can be implemented
+ * as many times as needed per entity, or even for abstract entities for use with {@link com.antelopesystem.crudframework.crud.annotation.WithHooks}. Implementations of this interface should be declared as Spring beans.
+ * @param <Entity> The entity to listen to
+ */
 public interface DeleteHooks<ID extends Serializable, Entity extends BaseCrudEntity<ID>> extends CRUDHooks<ID, Entity> {
 
+	/**
+	 * Called prior to a Delete operation.
+	 * Runs after the entity is verified to be deletable (Not immutable and deletable. -- whether hard or soft)
+	 * The validity of the ID at this point is still unknown.
+	 * @param id represents the ID of the entity to be deleted
+	 */
 	default void preDelete(ID id) {
 	}
 
+	/**
+	 * Called during a Delete operation.
+	 * This method will be called after validating the entity with the provided ID exists.
+	 * This method will run inside of a read/write transaction.
+	 * @param entity represents the entity being deleted
+	 */
 	default void onDelete(@NotNull Entity entity) {
 	}
 
+	/**
+	 * Called after a DeleteFrom operation
+	 * @param entity represents the entity that has been deleted
+	 */
 	default void postDelete(@NotNull Entity entity) {
 	}
 }

crud-framework-core/src/main/java/com/antelopesystem/crudframework/crud/hooks/interfaces/IndexHooks.java

@@ -7,14 +7,36 @@
 
 import java.io.Serializable;
 
+/**
+ * This class contains all hook callbacks for the Index operation. It can be implemented
+ * as many times as needed per entity, or even for abstract entities for use with {@link com.antelopesystem.crudframework.crud.annotation.WithHooks}. Implementations of this interface should be declared as Spring beans.
+ * @param <Entity> the entity to listen to
+ * @param <ID> the ID type of the entity
+ */
 public interface IndexHooks<ID extends Serializable, Entity extends BaseCrudEntity<ID>> extends CRUDHooks<ID, Entity> {
 
+	/**
+	 * Called prior to an Index operation.
+	 * Runs after the filter has been validated for the given entity
+	 * @param filter the filter used in the operation
+	 */
 	default void preIndex(@NotNull DynamicModelFilter filter) {
 	}
 
+	/**
+	 * Called during an Index operation.
+	 * If {@link com.antelopesystem.crudframework.crud.model.ReadCRUDRequestBuilder#fromCache} is used, this method will be skipped. It will be called  data access checks and run inside of a read-only transaction.
+	 * @param filter the filter used in the operation
+	 * @param result represents the paginated list of results from the given filter for the give entity
+	 */
 	default void onIndex(@NotNull DynamicModelFilter filter, @NotNull PagingDTO<Entity> result) {
 	}
 
+	/**
+	 * Called after a Index operation
+	 * @param filter the filter used in the operation
+	 * @param result represents the paginated list of results from the given filter for the give entity
+	 */
 	default void postIndex(@NotNull DynamicModelFilter filter, @NotNull PagingDTO<Entity> result) {
 	}
 }

crud-framework-core/src/main/java/com/antelopesystem/crudframework/crud/hooks/interfaces/ShowByHooks.java

@@ -7,14 +7,34 @@
 
 import java.io.Serializable;
 
+/**
+ * This class contains all hook callbacks for the ShowBy operation. It can be implemented
+ * as many times as needed per entity, or even for abstract entities for use with {@link com.antelopesystem.crudframework.crud.annotation.WithHooks}. Implementations of this interface should be declared as Spring beans.
+ * @param <Entity> the entity to listen to
+ * @param <ID> the ID type of the entity
+ */
 public interface ShowByHooks<ID extends Serializable, Entity extends BaseCrudEntity<ID>> extends CRUDHooks<ID, Entity> {
 
+	/**
+	 * Called prior to an ShowBy operation.
+	 * Runs after the filter has been validated for the given entity
+	 * @param filter the filter used in the operation
+	 */
 	default void preShowBy(@NotNull DynamicModelFilter filter) {
 	}
 
+	/**
+	 * Called during a ShowBy operation.
+	 * If {@link com.antelopesystem.crudframework.crud.model.ReadCRUDRequestBuilder#fromCache} is used, this method will be skipped. It will be called after data access checks and run inside of a read-only transaction.
+	 * @param entity represents the entity that was found, or null if not found
+	 */
 	default void onShowBy(@Nullable Entity entity) {
 	}
 
+	/**
+	 * Called after a ShowBy operation.
+	 * @param entity represents the entity that was found, or null if not found
+	 */
 	default void postShowBy(@Nullable Entity entity) {
 	}
 }

crud-framework-core/src/main/java/com/antelopesystem/crudframework/crud/hooks/interfaces/ShowHooks.java

@@ -5,14 +5,34 @@
 
 import java.io.Serializable;
 
+/**
+ * This class contains all hook callbacks for the Show operation. It can be implemented
+ * as many times as needed per entity, or even for abstract entities for use with {@link com.antelopesystem.crudframework.crud.annotation.WithHooks}. Implementations of this interface should be declared as Spring beans.
+ * @param <Entity> the entity to listen to
+ * @param <ID> the ID type of the entity
+ */
 public interface ShowHooks<ID extends Serializable, Entity extends BaseCrudEntity<ID>> extends CRUDHooks<ID, Entity> {
 
+	/**
+	 * Called prior to a Show operation.
+	 * The validity of the ID at this point is still unknown.
+	 * @param id represents the ID of the entity to be shown
+	 */
 	default void preShow(ID id) {
 	}
 
+	/**
+	 * Called during a Show operation.
+	 * If {@link com.antelopesystem.crudframework.crud.model.ReadCRUDRequestBuilder#fromCache} is used, this method will be skipped. It will be called after data access checks and run inside of a read-only transaction.
+	 * @param entity represents the entity that was found, or null if not found
+	 */
 	default void onShow(@Nullable Entity entity) {
 	}
 
+	/**
+	 * Called after a Show operation.
+	 * @param entity represents the entity that was found, or null if not found
+	 */
 	default void postShow(@Nullable Entity entity) {
 	}
 }

crud-framework-core/src/main/java/com/antelopesystem/crudframework/crud/hooks/interfaces/UpdateFromHooks.java

@@ -5,14 +5,38 @@
 
 import java.io.Serializable;
 
+/**
+ * This class contains all hook callbacks for the UpdateFrom operation. It can be implemented
+ * as many times as needed per entity, or even for abstract entities for use with {@link com.antelopesystem.crudframework.crud.annotation.WithHooks}. Implementations of this interface should be declared as Spring beans.
+ * @param <Entity> the entity to listen to
+ * @param <ID> the ID type of the entity
+ */
 public interface UpdateFromHooks<ID extends Serializable, Entity extends BaseCrudEntity<ID>> extends CRUDHooks<ID, Entity> {
 
+	/**
+	 * Called prior to an UpdateFrom operation.
+	 * Runs after the entity is verified to be updatable. (Not immutable)
+	 * @param id represents the ID of the entity to be updated
+	 * @param ro represents the object that will be transformed to the entity
+	 */
 	default void preUpdateFrom(ID id, @NotNull Object ro) {
 	}
 
+	/**
+	 * Called during an UpdateFrom operation.
+	 * This method will be called after field mapping / object decoration between the
+	 * RO and the entity and data access checks, and before validation.
+	 * This method will run inside of a read/write transaction.
+	 * @param entity represents the entity being updated
+	 * @param ro represents the object that will be transformed to the entity
+	 */
 	default void onUpdateFrom(@NotNull Entity entity, @NotNull Object ro) {
 	}
 
+	/**
+	 * Called after a UpdateFrom operation
+	 * @param entity represents the entity that has been created
+	 */
 	default void postUpdateFrom(@NotNull Entity entity) {
 	}
 }

crud-framework-core/src/main/java/com/antelopesystem/crudframework/crud/hooks/interfaces/UpdateHooks.java

@@ -5,14 +5,36 @@
 
 import java.io.Serializable;
 
+/**
+ * This class contains all hook callbacks for the Update operation. It can be implemented
+ * as many times as needed per entity, or even for abstract entities for use with {@link com.antelopesystem.crudframework.crud.annotation.WithHooks}. Implementations of this interface should be declared as Spring beans.
+ * @param <Entity> the entity to listen to
+ * @param <ID> the ID type of the entity
+ */
 public interface UpdateHooks<ID extends Serializable, Entity extends BaseCrudEntity<ID>> extends CRUDHooks<ID, Entity> {
 
+	/**
+	 * Called prior to an Update operation.
+	 * Runs after the entity is verified to be updatable (Not immutable)
+	 * @param entity represents the entity being created
+	 */
 	default void preUpdate(@NotNull Entity entity) {
 	}
 
+	/**
+	 * Called during an Update operation.
+	 * This method will be called after field mapping / object decoration between the
+	 * RO and the entity and data access checks, and before validation.
+	 * This method will run inside of a read/write transaction.
+	 * @param entity represents the entity being updated
+	 */
 	default void onUpdate(@NotNull Entity entity) {
 	}
 
+	/**
+	 * Called after an Update operation
+	 * @param entity represents the entity that has been created
+	 */
 	default void postUpdate(@NotNull Entity entity) {
 	}
 }