review

Author: pvillard31

nifi-extension-bundles/nifi-extension-utils/nifi-record-utils/nifi-json-record-utils/src/main/java/org/apache/nifi/json/WriteJsonResult.java

@@ -178,6 +178,25 @@ public WriteResult writeRawRecord(final Record record) throws IOException {
         return WriteResult.of(incrementRecordCount(), attributes);
     }
 
+    /**
+     * Determines whether the record's original serialized JSON bytes can be emitted verbatim as a throughput optimization,
+     * bypassing field-by-field re-serialization. All of the following conditions must hold for the fast path to apply:
+     * <ol>
+     *   <li>The caller enabled the optimization (the {@code reuseInputSerialization} constructor argument is {@code true}).</li>
+     *   <li>The record carries a {@link SerializedForm} produced by the upstream reader. Today this is only set by
+     *       {@code JsonTreeRowRecordReader}; readers such as {@code JsonPathRowRecordReader} that transform the input
+     *       cannot reuse their input bytes and therefore never trigger the fast path.</li>
+     *   <li>The serialized form's MIME type matches the writer's configured MIME type and the reader's record schema is
+     *       equal to the writer's record schema (no projection, no field renames, no type coercion).</li>
+     *   <li>The cached bytes are a {@code String}.</li>
+     *   <li>The cached bytes' pretty-print state matches the writer's {@code prettyPrint} setting.</li>
+     *   <li>If scientific notation is disabled on the writer, the cached bytes do not contain scientific notation.</li>
+     * </ol>
+     * When the fast path is taken, the writer emits the cached bytes via {@link JsonGenerator#writeRawValue(String)} and
+     * therefore does <em>not</em> apply the writer's Timestamp Format, Date Format, Time Format, or Suppress Null Values
+     * settings to that record. Operators that need those writer-side properties to be honored uniformly must construct
+     * this writer with {@code reuseInputSerialization = false}.
+     */
     private boolean isUseSerializeForm(final Record record, final RecordSchema writeSchema) {
         if (!reuseInputSerialization) {
             return false;

nifi-extension-bundles/nifi-standard-services/nifi-record-serialization-services-bundle/nifi-record-serialization-services/src/main/java/org/apache/nifi/json/JsonRecordSetWriter.java

@@ -124,14 +124,11 @@ public class JsonRecordSetWriter extends DateTimeTextRecordSetWriter implements
             .dependsOn(COMPRESSION_FORMAT, COMPRESSION_FORMAT_GZIP)
             .build();
     public static final PropertyDescriptor REUSE_INPUT_SERIALIZATION = new PropertyDescriptor.Builder()
-            .name("Reuse Input Serialization")
+            .name("Use Input Serialization")
             .description("""
-                    Controls a throughput optimization that only applies to pure JSON pass-through flows. When set to true, and all of the \
-                    following conditions are met, the writer will emit the record's original JSON bytes verbatim instead of re-serializing from typed field \
-                    values: (1) the upstream reader is JsonTreeReader, (2) no data change, (3) the reader's and writer's record schemas are identical, \
-                    (4) the writer is not using compression, and (5) the Pretty Print JSON and Allow Scientific Notation settings are compatible with the \
-                    cached bytes. When the optimization kicks in, the Timestamp Format, Date Format, Time Format, and Suppress Null Values properties \
-                    have no effect on those records. Set this to false to have those properties honored uniformly for every record.""")
+                    When set to true (default), the writer may emit the upstream reader's original JSON bytes verbatim when it can do so safely, as a \
+                    throughput optimization. In that case, the Timestamp Format, Date Format, Time Format, and Suppress Null Values properties may not be \
+                    applied to those records. Set this to false to force re-serialization so that these properties are honored uniformly for every record.""")
             .expressionLanguageSupported(ExpressionLanguageScope.NONE)
             .allowableValues("true", "false")
             .defaultValue("true")

nifi-extension-bundles/nifi-standard-services/nifi-record-serialization-services-bundle/nifi-record-serialization-services/src/test/java/org/apache/nifi/json/TestWriteJsonResult.java

@@ -656,8 +656,7 @@ void testReuseInputSerializationDefaultTrueUsesFastPath() throws IOException {
         }
 
         final String output = baos.toString(StandardCharsets.UTF_8);
-        assertTrue(output.contains("\"ignoredExtra\":\"preserved\""),
-                "Default constructor preserves legacy fast-path behavior: raw bytes should be emitted verbatim");
+        assertEquals("[{\"name\":\"John Doe\",\"age\":42,\"ignoredExtra\":\"preserved\"}]", output);
     }
 
     @Test
@@ -685,7 +684,7 @@ void testReuseInputSerializationFalseForcesReserialization() throws IOException
 
         final String output = baos.toString(StandardCharsets.UTF_8);
         assertFalse(output.contains("ignoredExtra"),
-                "When Reuse Input Serialization is false, the writer must re-serialize from typed values and ignore raw bytes");
+                "When Use Input Serialization is false, the writer must re-serialize from typed values and ignore raw bytes");
         assertEquals("[{\"name\":\"John Doe\",\"age\":42}]", output);
     }
 
@@ -699,32 +698,34 @@ void testReuseInputSerializationFalseHonorsTimestampFormat() throws IOException
         final Map<String, Object> values = new HashMap<>();
         values.put("event", eventTimestamp);
 
-        final String rawForm = "{\"event\":\"2025-03-20T17:33:11.000+0000\"}";
+        final String timestampValue = "2025-03-20T17:33:11.000+0000";
+        final String timestampFormat = "yyyy-MM-dd'T'HH:mm:ss.SSSX";
+        final String rawForm = "{\"event\":\"%s\"}".formatted(timestampValue);
         final SerializedForm serializedForm = SerializedForm.of(rawForm, "application/json");
         final Record record = new MapRecord(schema, values, serializedForm);
 
         final ByteArrayOutputStream fastPathBaos = new ByteArrayOutputStream();
         try (final WriteJsonResult writer = new WriteJsonResult(Mockito.mock(ComponentLog.class), schema, new SchemaNameAsAttribute(), fastPathBaos, false,
                 NullSuppression.NEVER_SUPPRESS, OutputGrouping.OUTPUT_ARRAY, RecordFieldType.DATE.getDefaultFormat(),
-                RecordFieldType.TIME.getDefaultFormat(), "yyyy-MM-dd'T'HH:mm:ss.SSSX",
+                RecordFieldType.TIME.getDefaultFormat(), timestampFormat,
                 "application/json", false, true)) {
             writer.write(RecordSet.of(schema, record));
         }
 
-        assertTrue(fastPathBaos.toString(StandardCharsets.UTF_8).contains("+0000"),
-                "With Reuse Input Serialization enabled, raw '+0000' form is passed through even though Timestamp Format would normalize to 'Z'");
+        assertTrue(fastPathBaos.toString(StandardCharsets.UTF_8).contains(timestampValue),
+                "With Use Input Serialization enabled, raw '+0000' form is passed through even though Timestamp Format would normalize to 'Z'");
 
         final ByteArrayOutputStream slowPathBaos = new ByteArrayOutputStream();
         try (final WriteJsonResult writer = new WriteJsonResult(Mockito.mock(ComponentLog.class), schema, new SchemaNameAsAttribute(), slowPathBaos, false,
                 NullSuppression.NEVER_SUPPRESS, OutputGrouping.OUTPUT_ARRAY, RecordFieldType.DATE.getDefaultFormat(),
-                RecordFieldType.TIME.getDefaultFormat(), "yyyy-MM-dd'T'HH:mm:ss.SSSX",
+                RecordFieldType.TIME.getDefaultFormat(), timestampFormat,
                 "application/json", false, false)) {
             writer.write(RecordSet.of(schema, record));
         }
 
         final String slowPathOutput = slowPathBaos.toString(StandardCharsets.UTF_8);
         assertFalse(slowPathOutput.contains("+0000"),
-                "With Reuse Input Serialization disabled, writer's Timestamp Format must be applied even when SerializedForm is present");
+                "With Use Input Serialization disabled, writer's Timestamp Format must be applied even when SerializedForm is present");
         assertTrue(slowPathOutput.contains("\"event\":\"2025-03-20T17:33:11.000"),
                 "Re-serialized timestamp should reflect the configured format");
     }
@@ -754,7 +755,7 @@ void testReuseInputSerializationFalseHonorsSuppressNulls() throws IOException {
 
         final String output = baos.toString(StandardCharsets.UTF_8);
         assertFalse(output.contains("middleName"),
-                "Suppress Null Values must be honored when Reuse Input Serialization is false, even though the input JSON contained the null field");
+                "Suppress Null Values must be honored when Use Input Serialization is false, even though the input JSON contained the null field");
         assertEquals("[{\"name\":\"John Doe\"}]", output);
     }
 }