PR aws-powertools#717: document exceptions

Author: jeromevdl

powertools-idempotency/src/main/java/software/amazon/lambda/powertools/idempotency/exceptions/IdempotencyAlreadyInProgressException.java

@@ -13,6 +13,10 @@
  */
 package software.amazon.lambda.powertools.idempotency.exceptions;
 
+/**
+ * This exception is thrown when the same payload is sent
+ * while the previous one was not yet fully stored in the persistence layer (marked as COMPLETED).
+ */
 public class IdempotencyAlreadyInProgressException extends RuntimeException {
     private static final long serialVersionUID = 7229475093418832265L;
 

powertools-idempotency/src/main/java/software/amazon/lambda/powertools/idempotency/exceptions/IdempotencyConfigurationException.java

@@ -13,7 +13,15 @@
  */
 package software.amazon.lambda.powertools.idempotency.exceptions;
 
-public class IdempotencyConfigurationException extends RuntimeException{
+/**
+ * Exception thrown when Idempotency is not well configured:
+ * <ul>
+ *     <li>An annotated method does not return anything</li>
+ *     <li>An annotated method does not have parameters or more than one without
+ *     the {@link software.amazon.lambda.powertools.idempotency.IdempotencyKey} annotation</li>
+ * </ul>
+ */
+public class IdempotencyConfigurationException extends RuntimeException {
     private static final long serialVersionUID = 560587720373305487L;
 
     public IdempotencyConfigurationException(String message) {

powertools-idempotency/src/main/java/software/amazon/lambda/powertools/idempotency/exceptions/IdempotencyInconsistentStateException.java

@@ -13,6 +13,10 @@
  */
 package software.amazon.lambda.powertools.idempotency.exceptions;
 
+/**
+ * IdempotencyInconsistentStateException can happen under rare but expected cases
+ * when persistent state changes in the small-time between put & get requests.
+ */
 public class IdempotencyInconsistentStateException extends RuntimeException {
     private static final long serialVersionUID = -4293951999802300672L;
 

powertools-idempotency/src/main/java/software/amazon/lambda/powertools/idempotency/exceptions/IdempotencyItemAlreadyExistsException.java

@@ -13,6 +13,9 @@
  */
 package software.amazon.lambda.powertools.idempotency.exceptions;
 
+/**
+ * Exception thrown when trying to store an item which already exists.
+ */
 public class IdempotencyItemAlreadyExistsException extends RuntimeException {
     private static final long serialVersionUID = 9027152772149436500L;
 

powertools-idempotency/src/main/java/software/amazon/lambda/powertools/idempotency/exceptions/IdempotencyItemNotFoundException.java

@@ -13,6 +13,9 @@
  */
 package software.amazon.lambda.powertools.idempotency.exceptions;
 
+/**
+ * Exception thrown when the item was not found in the persistence store.
+ */
 public class IdempotencyItemNotFoundException extends RuntimeException{
     private static final long serialVersionUID = 4818288566747993032L;
 

powertools-idempotency/src/main/java/software/amazon/lambda/powertools/idempotency/exceptions/IdempotencyKeyException.java

@@ -13,6 +13,10 @@
  */
 package software.amazon.lambda.powertools.idempotency.exceptions;
 
+/**
+ * Exception thrown only when using {@link software.amazon.lambda.powertools.idempotency.IdempotencyConfig#throwOnNoIdempotencyKey()},
+ * and if a key could not be found in the event (for example when having a bad JMESPath configured)
+ */
 public class IdempotencyKeyException extends RuntimeException {
     private static final long serialVersionUID = -8514965705001281773L;
 

powertools-idempotency/src/main/java/software/amazon/lambda/powertools/idempotency/exceptions/IdempotencyPersistenceLayerException.java

@@ -13,7 +13,10 @@
  */
 package software.amazon.lambda.powertools.idempotency.exceptions;
 
-public class IdempotencyPersistenceLayerException extends RuntimeException{
+/**
+ * Exception thrown when a technical error occurred with the persistence layer (eg. insertion, deletion, ... in database)
+ */
+public class IdempotencyPersistenceLayerException extends RuntimeException {
     private static final long serialVersionUID = 6781832947434168547L;
 
     public IdempotencyPersistenceLayerException(String msg, Exception e) {

powertools-idempotency/src/main/java/software/amazon/lambda/powertools/idempotency/exceptions/IdempotencyValidationException.java

@@ -13,6 +13,12 @@
  */
 package software.amazon.lambda.powertools.idempotency.exceptions;
 
+import software.amazon.lambda.powertools.idempotency.IdempotencyConfig;
+
+/**
+ * Exception thrown only when using {@link IdempotencyConfig#getPayloadValidationJMESPath()} is configured
+ * and the payload changed between two calls (but with the same idempotency key).
+ */
 public class IdempotencyValidationException extends RuntimeException {
     private static final long serialVersionUID = -4218652810664634761L;