new_feature_release

Author: deepakarora3

pom.xml

@@ -19,7 +19,7 @@
 
     <groupId>com.americanexpress.unify.jdocs</groupId>
     <artifactId>unify-jdocs</artifactId>
-    <version>1.3.9</version>
+    <version>1.4.0</version>
     <packaging>jar</packaging>
 
     <name>unify-jdocs</name>

readme.md

@@ -15,7 +15,7 @@ JDocs is available as a jar file in Maven central with the following latest Mave
 ````pom
 <groupId>com.americanexpress.unify.jdocs</groupId>
 <artifactId>unify-jdocs</artifactId>
-<version>1.3.9</version>
+<version>1.4.0</version>
 ````
 
 ---
@@ -392,9 +392,9 @@ public interface Document {
    */
   boolean pathExists(String path, String... vargs);
 
-  /**
-   * Used to determine if the specified path is an array in the document
-   *
+   /**
+    * Used to determine if the specified path to a leaf node is an array in the document
+    *
    * @param path  the path
    * @param vargs the values to replace the % characters in path
    * @return true if the path is an array else false
@@ -1236,17 +1236,43 @@ d.setString("$.start_date", "15-Apr-2019") // incorrect date format
 d.setString("$.phones[0].number", "111111") // incorrect data type
 ```
 
-As regards constraints, the validation is done against the specified regular expression. If a match
-returns true, the validation is assumed to succeed else an exception is thrown. 
+As regards constraints, the validation is done against the specified regular expression. If a match returns true, the
+validation is assumed to succeed else an exception is thrown.
 
 The following attributes are implemented as part of specifying a constraint on a path:
 
 S. No. | Field Name | Description | Type | Mandatory?
 ------ | --------------- | ------------| ---- | ----------
 1 | type | Defines the type of the field. Possible values are string, integer, long, decimal, boolean, date | String | Yes
-2 | null_allowed | Specifies if null is a valid value for the field. If not specified, default is no null allowed | boolean | No
-3 | regex | The pattern against which the value will be validated | string | No
-4 | format | Only applicable for date type. Specification is as per DateTimeFormatter | string | Yes only for date type
+2 | regex | The pattern against which the value will be validated | string | No
+3 | null_allowed | Specifies if null is a valid value for the field. If not specified, default is null not allowed. If value is null and allowed, regex will be ignored | boolean | No
+4 | ignore_regex_if_empty_string | If not specified, default is false. If specified to true, regex will be ignored if value is empty. Applicable only for string type fields | boolean | No
+5 | format | Only applicable for date type. Specification is as per DateTimeFormatter | string | Yes
+6 | empty_date_allowed | Only applicable for date type fields. If not specified, default is true. If allowed format check is ignored  | boolean | No
+
+**Validating typed documents**
+
+By default, typed documents are validated when they are created and when any read / write operation is performed on
+them. However there may be cases, when we do not want to validate the document at the time of creation but only at the
+time of reading and writing. This is a typical scenario in the use of APIs which can return extra blocks and paths which
+may not be present in the model document and which we may not be interested in. If we were to validate at the time of
+creating the document, the model validations would fail unless we kept the model document in sync with all the changes
+happening on the API side. Most of the times this is not possible as the teams are separate and there is no reason that
+adding fields to the response which we are not interested in should cause a failure. To take care of this scenario, we
+have two alternatives:
+
+1. Use the overloaded JDocument constructor to specify that the validation should only be done while reading / writing
+   paths. This way the default behaviour will not change but can be set at a per document level
+2. Specify the default behaviour of JDocs to do the validation only while reading / writing paths. This can be set using
+   the public static init method while initializing JDocs. Of course this can be overridden as desired by using the
+   JDocument overloaded constructor
+
+The two methods are shown below:
+
+```java
+public JDocument(String type,String json,boolean validateAtReadWriteOnly);
+public static void init(boolean defaultValidateAtReadWriteOnly);
+```
 
 ---
 

src/main/java/com/americanexpress/unify/jdocs/CONSTS_JDOCS.java

@@ -32,6 +32,8 @@ public class FORMAT_FIELDS {
     public static final String REGEX = "regex";
     public static final String FORMAT = "format"; // used only for date
     public static final String NULL_ALLOWED = "null_allowed";
+    public static final String IGNORE_REGEX_IF_EMPTY_STRING = "ignore_regex_if_empty_string";
+    public static final String EMPTY_DATE_ALLOWED = "empty_date_allowed";
 
   }
 

src/main/java/com/americanexpress/unify/jdocs/ERRORS_JDOCS.java

@@ -90,6 +90,8 @@ public static void load() {
     map.put("jdoc_err_67", "Name value pair not allowed in this method. Path is -> {0}");
     map.put("jdoc_err_68", "Path does not exist in document. Path -> {0}");
     map.put("jdoc_err_69", "Path specified cannot be a leaf node. Path -> {0}");
+    map.put("jdoc_err_70", "Empty value not allowed for a date at path -> {0}");
+    map.put("jdoc_err_71", "Date format missing for path -> {0}");
   }
 
 }

src/main/java/com/americanexpress/unify/jdocs/JDocument.java

@@ -39,6 +39,9 @@
 import java.util.regex.Pattern;
 import java.util.stream.Collectors;
 
+import static com.americanexpress.unify.jdocs.DataType.DATE;
+import static com.americanexpress.unify.jdocs.DataType.STRING;
+
 /*
  * @author Deepak Arora
  */
@@ -2219,6 +2222,18 @@ private static void validateField(String format, Object value, String path, List
     JsonNode node = getFormatNode(type, path, format);
 
     while (true) {
+      // check that the format field is specified if we are dealing with a date
+      DataType dataType = DataType.valueOf(node.get(CONSTS_JDOCS.FORMAT_FIELDS.TYPE).asText().toUpperCase());
+
+      // check that a date field has to have a format. Whether the format is correct or not will be validated later
+      if (dataType == DATE) {
+        String formatValue = node.get(CONSTS_JDOCS.FORMAT_FIELDS.FORMAT).asText();
+        if (formatValue.isEmpty() == true) {
+          throwExceptionOrSetErrorList("jdoc_err_71", path, errorList);
+          break;
+        }
+      }
+
       // if the value is null, check if nulls are allowed
       if (value == null) {
         JsonNode node1 = node.get(CONSTS_JDOCS.FORMAT_FIELDS.NULL_ALLOWED);
@@ -2233,7 +2248,6 @@ private static void validateField(String format, Object value, String path, List
       }
 
       // check data types
-      DataType dataType = DataType.valueOf(node.get(CONSTS_JDOCS.FORMAT_FIELDS.TYPE).asText().toUpperCase());
       switch (dataType) {
         case STRING:
           if ((value instanceof String) == false) {
@@ -2278,6 +2292,45 @@ private static void validateField(String format, Object value, String path, List
           break;
       }
 
+      // check if value is empty and if so do we need to ignore regex
+      if (dataType == STRING) {
+        String s = value.toString();
+        if (s.isEmpty()) {
+          JsonNode node1 = node.get(CONSTS_JDOCS.FORMAT_FIELDS.IGNORE_REGEX_IF_EMPTY_STRING);
+
+          // by default do not ignore. Historically we have been disallowing an empty string if it does not match
+          // regex pattern. The new requirement is to be able to ignore regex if the value is empty
+          boolean ignoreRegex = false;
+          if (node1 != null) {
+            ignoreRegex = node.get(CONSTS_JDOCS.FORMAT_FIELDS.IGNORE_REGEX_IF_EMPTY_STRING).booleanValue();
+          }
+          if (ignoreRegex == true) {
+            break;
+          }
+        }
+      }
+
+      // check if value is empty and if it is allowed
+      if (dataType == DATE) {
+        String s = value.toString();
+        if (s.isEmpty()) {
+          JsonNode node1 = node.get(CONSTS_JDOCS.FORMAT_FIELDS.EMPTY_DATE_ALLOWED);
+
+          // by default we ignore. Historically we have been ignoring the format if an empty date value
+          // is provided. The new requirement is to not allow an empty date value
+          boolean emptyDateAllowed = true;
+          if (node1 != null) {
+            emptyDateAllowed = node.get(CONSTS_JDOCS.FORMAT_FIELDS.EMPTY_DATE_ALLOWED).booleanValue();
+          }
+          if (emptyDateAllowed == true) {
+            break;
+          }
+          else {
+            throwExceptionOrSetErrorList("jdoc_err_70", path, errorList);
+          }
+        }
+      }
+
       // check against regex pattern and format
       switch (dataType) {
         case STRING:
@@ -2305,17 +2358,13 @@ private static void validateField(String format, Object value, String path, List
 
         case DATE:
           // Match input date with the format provided
-          String fieldValue = node.get(CONSTS_JDOCS.FORMAT_FIELDS.FORMAT).asText();
-          if (fieldValue.isEmpty() == false) {
-            try {
-              DateTimeFormatter dfs = DateTimeFormatter.ofPattern(fieldValue).withResolverStyle(ResolverStyle.STRICT);
-              if (value.toString().isEmpty() == false) {
-                dfs.parse(value.toString());
-              }
-            }
-            catch (Exception e) {
-              throwExceptionOrSetErrorList("jdoc_err_51", path, errorList);
-            }
+          String formatValue = node.get(CONSTS_JDOCS.FORMAT_FIELDS.FORMAT).asText();
+          try {
+            DateTimeFormatter dfs = DateTimeFormatter.ofPattern(formatValue).withResolverStyle(ResolverStyle.STRICT);
+            dfs.parse(value.toString());
+          }
+          catch (Exception e) {
+            throwExceptionOrSetErrorList("jdoc_err_51", path, errorList);
           }
           break;
 
@@ -2702,7 +2751,7 @@ else if (fieldNode.isLong()) {
 
           case STRING:
             value = fieldNode.asText();
-            dt = DataType.STRING;
+            dt = STRING;
             break;
 
           default:

src/test/java/com/americanexpress/unify/jdocs/DocumentTest.java

@@ -1202,4 +1202,37 @@ void testMergeDelete() {
     d = getTypedDocument("sample_24_model", "/jdocs/sample_24.json");
   }
 
+  @Test
+  void testIgnoreRegexIfEmpty() {
+    setDocModel("sample_26_model");
+    Document d = new JDocument("sample_26_model", null);
+
+    d.setString("$.id1", "GO2");
+    assertEquals(true, true);
+
+    UnifyException e = assertThrows(UnifyException.class, () -> {
+      d.setString("$.id1", "");
+    });
+
+    d.setString("$.id2", "");
+    assertEquals(true, true);
+
+    d.setString("$.id2", "GNA");
+    assertEquals(true, true);
+
+    e = assertThrows(UnifyException.class, () -> {
+      d.setString("$.id2", "hhh");
+    });
+
+    d.setString("$.id3", "2023-Jan-26");
+    assertEquals(true, true);
+
+    d.setString("$.id3", "");
+    assertEquals(true, true);
+
+    e = assertThrows(UnifyException.class, () -> {
+      d.setString("$.id4", "");
+    });
+  }
+
 }

src/test/resources/jdocs/sample_26_model.json

@@ -0,0 +1,6 @@
+{
+  "id1": "{\"type\":\"string\", \"regex\":\"^(GNA|GO2)\"}",
+  "id2": "{\"type\":\"string\", \"regex\":\"^(GNA|GO2)\", \"ignore_regex_if_empty_string\":true}",
+  "id3": "{\"type\":\"date\", \"format\":\"uuuu-MMM-dd\"}",
+  "id4": "{\"type\":\"date\", \"format\":\"uuuu-MMM-dd\", \"empty_date_allowed\":false}"
+}