From 3dd3924721841743fae82a32f99314b96e291cdd Mon Sep 17 00:00:00 2001 From: dan-s1 Date: Mon, 9 Feb 2026 23:15:39 +0000 Subject: [PATCH] NIFI-15574 Added the Javadoc snippet tag for the code examples in the Nifi API Javadocs. --- .../components/ConfigurableComponent.java | 4 +-- .../nifi/components/PropertyDescriptor.java | 12 ++++++-- .../nifi/controller/ControllerService.java | 19 +++++++------ .../nifi/migration/PropertyConfiguration.java | 18 ++++++------ .../migration/RelationshipConfiguration.java | 14 +++++----- .../apache/nifi/processor/ProcessSession.java | 28 +++++++++---------- .../org/apache/nifi/time/DurationFormat.java | 14 +++++----- 7 files changed, 58 insertions(+), 51 deletions(-) diff --git a/src/main/java/org/apache/nifi/components/ConfigurableComponent.java b/src/main/java/org/apache/nifi/components/ConfigurableComponent.java index 2c47dab..4ab462c 100644 --- a/src/main/java/org/apache/nifi/components/ConfigurableComponent.java +++ b/src/main/java/org/apache/nifi/components/ConfigurableComponent.java @@ -63,7 +63,7 @@ public interface ConfigurableComponent { * onPropertyModified method. This can be done as follows: *

* - * 
{@code
+     * {@snippet :
      *    private volatile boolean configurationRestored = false;
      *
      *    @OnConfigurationRestored
@@ -76,7 +76,7 @@ public interface ConfigurableComponent {
      *            return;
      *        }
      *    }
-     * }
+ * } * * @param descriptor the descriptor for the property being modified * @param oldValue the value that was previously set. Will be null if no value diff --git a/src/main/java/org/apache/nifi/components/PropertyDescriptor.java b/src/main/java/org/apache/nifi/components/PropertyDescriptor.java index 5e959d2..3e316d6 100644 --- a/src/main/java/org/apache/nifi/components/PropertyDescriptor.java +++ b/src/main/java/org/apache/nifi/components/PropertyDescriptor.java @@ -561,9 +561,15 @@ private boolean isValueAllowed(final String value) { * Any property descriptor that identifies an external resource will be automatically validated against the following rules: * diff --git a/src/main/java/org/apache/nifi/controller/ControllerService.java b/src/main/java/org/apache/nifi/controller/ControllerService.java index e8f9850..c8acebe 100644 --- a/src/main/java/org/apache/nifi/controller/ControllerService.java +++ b/src/main/java/org/apache/nifi/controller/ControllerService.java @@ -70,21 +70,22 @@ *

* For example: *

- * 

+ * {@snippet :
  *    public static final PropertyDescriptor MY_PROPERTY = new PropertyDescriptor.Builder()
  *     .name("My Property")
  *     .description("Example Property")
  *     .identifiesControllerService( MyControllerServiceInterface.class )
  *     .build();
  *
- *    ...
+ *    // Other code
+ *
  *    public void onTrigger(ProcessContext context, ProcessSessionFactory sessionFactory) throws ProcessException {
  *     // Obtain the user-selected controller service
  *     final MyControllerServiceInterface service = context.getProperty(MY_PROPERTY).asControllerService( MyControllerServiceInterface.class );
- *     ...
- *    }
  *
- *
+ * // Other code + * } + * } *
  • A Controller Service can be obtained via a * {@link ControllerServiceLookup}. This lookup may be obtained, for example, * from the {@link ProcessContext} that is provided to a {@link Processor}'s @@ -94,11 +95,11 @@ * For example: *

    * - * 
    
+ * {@snippet :
  *    public void onTrigger(ProcessContext context, ProcessSessionFactory sessionFactory) throws ProcessException {
  *      final MyControllerServiceInterface service = (MyControllerServiceInterface) context.getControllerServiceLookup().getControllerService("service_identifier");
  *    }
- *
    + * } *
    • * * @@ -139,14 +140,14 @@ * *

    * Typically, this is done by creating a NAR structure as follows: - * 

    + * {@snippet lang="text" :
  *   + my-services-api-nar
  *   +--- service-X-implementation-nar
  *   +--- service-Y-implementation-nar
  *   +--- service-Z-implementation-nar
  *   +--- processor-A-nar
  *   +--- processor-B-nar
- *
    + * } * *

    * In this case, the {@code MyControllerServiceInterface} interface, and any diff --git a/src/main/java/org/apache/nifi/migration/PropertyConfiguration.java b/src/main/java/org/apache/nifi/migration/PropertyConfiguration.java index e6e2cc9..92bf371 100644 --- a/src/main/java/org/apache/nifi/migration/PropertyConfiguration.java +++ b/src/main/java/org/apache/nifi/migration/PropertyConfiguration.java @@ -50,9 +50,9 @@ public interface PropertyConfiguration { *

    * An idiom to determine if the property was explicitly set to null is as follows: *

    - * 
    
-     *     final boolean setToNull = configuration.hasProperty("MyProperty") && !configuration.isPropertySet("MyProperty");
-     *
    + * {@snippet : + * final boolean setToNull = configuration.hasProperty("MyProperty") && !configuration.isPropertySet("MyProperty"); + * } * * @param propertyName the name of the property * @return true if the property name is known to this configuration, false otherwise. @@ -69,9 +69,9 @@ public interface PropertyConfiguration { *

    * An idiom to determine if the property was explicitly set to null is as follows: *

    - * 
    
-     *     final boolean setToNull = configuration.hasProperty(MY_PROPERTY) && !configuration.isSet(MY_PROPERTY);
-     *
    + * {@snippet : + * final boolean setToNull = configuration.hasProperty(MY_PROPERTY) && !configuration.isSet(MY_PROPERTY); + * } * * @param descriptor the property descriptor that identifies the property * @return true if the property name is known to this configuration, false otherwise. @@ -176,10 +176,10 @@ default Optional getRawPropertyValue(PropertyDescriptor descriptor) { * use this method as such: *

    * - * 
    
+     * {@snippet :
      *     // Create a new Controller Service of type org.apache.nifi.services.authentication.UsernamePassword whose Username and Password
      *     // properties match those currently configured for this Processor.
-     *     final Map<String, String> serviceProperties = Map.of("Username", propertyConfiguration.getRawPropertyValue("Username"),
+     *     final Map serviceProperties = Map.of("Username", propertyConfiguration.getRawPropertyValue("Username"),
      *          "Password", propertyConfiguration.getRawPropertyValue("Password"));
      *     final String serviceId = propertyConfiguration.createControllerService("org.apache.nifi.services.authentication.UsernamePassword", serviceProperties);
      *
@@ -189,7 +189,7 @@ default Optional getRawPropertyValue(PropertyDescriptor descriptor) {
      *     // Remove the Username and Password properties from this Processor, since we are now going to use then Authentication Service.
      *     propertyConfiguration.removeProperty("Username");
      *     propertyConfiguration.removeProperty("Password");
-     *
    + * } * *

    * Note the use of {@link #getRawPropertyValue(String)} here instead of {@link #getPropertyValue(String)}. Because we want to set diff --git a/src/main/java/org/apache/nifi/migration/RelationshipConfiguration.java b/src/main/java/org/apache/nifi/migration/RelationshipConfiguration.java index e43aa64..da5ab2c 100644 --- a/src/main/java/org/apache/nifi/migration/RelationshipConfiguration.java +++ b/src/main/java/org/apache/nifi/migration/RelationshipConfiguration.java @@ -58,9 +58,9 @@ public interface RelationshipConfiguration { * It is possible to split an existing relationship into the same relationship and additional relationships. For example, it is * valid to call this method as: *

    - * 
    
-     * relationshipConfiguration.splitRelationship("A", "A", "B", "C");
-     *
    + * {@snippet : + * relationshipConfiguration.splitRelationship("A", "A", "B", "C"); + * } * *

    * In order to split the "A" relationship into three relationships: "A", "B", and "C". However, upon restart, NiFi will have already split the "A" @@ -69,11 +69,11 @@ public interface RelationshipConfiguration { * exist first: *

    * - * 
    
-     * if (!relationshipConfiguration.hasRelationship("B")) {
-     *     relationshipConfiguration.splitRelationship("A", "A", "B", "C");
+     * {@snippet :
+     *     if (!relationshipConfiguration.hasRelationship("B")) {
+     *         relationshipConfiguration.splitRelationship("A", "A", "B", "C");
+     *     }
      * }
-     *
    * *

    * This ensures that we do not attempt to split relationship "A" if it has already been done. diff --git a/src/main/java/org/apache/nifi/processor/ProcessSession.java b/src/main/java/org/apache/nifi/processor/ProcessSession.java index 7028962..2f4b630 100644 --- a/src/main/java/org/apache/nifi/processor/ProcessSession.java +++ b/src/main/java/org/apache/nifi/processor/ProcessSession.java @@ -105,24 +105,24 @@ public interface ProcessSession { * and implementing that action in the provided callback. *

    * As a result, the following very common idiom: - * 

    
-     * getDataFromSource();
-     * session.commit();
-     * acknowledgeReceiptOfData();
-     *
    + * {@snippet : + * getDataFromSource(); + * session.commit(); + * acknowledgeReceiptOfData(); + * } * Cannot be simply changed to: - * 
    
-     * getDataFromSource();
-     * session.commitAsync();
-     * acknowledgeReceiptOfData();
-     *
    + * {@snippet : + * getDataFromSource(); + * session.commitAsync(); + * acknowledgeReceiptOfData(); + * } * Doing so could result in acknowledging receipt of data from the source system before data has been committed to the repositories. * If NiFi were to then be restarted, there is potential for data loss. * Rather, the following idiom should take its place to ensure that there is no data loss: - * 
    
-     * getDataFromSource();
-     * session.commitAsync( () -> acknowledgeReceiptOfData() );
-     *
    + * {@snippet : + * getDataFromSource(); + * session.commitAsync( () -> acknowledgeReceiptOfData() ); + * } *

    * If the session cannot be committed, an error will be logged and the session will be rolled back instead. * diff --git a/src/main/java/org/apache/nifi/time/DurationFormat.java b/src/main/java/org/apache/nifi/time/DurationFormat.java index 5c7cb33..0527cc4 100644 --- a/src/main/java/org/apache/nifi/time/DurationFormat.java +++ b/src/main/java/org/apache/nifi/time/DurationFormat.java @@ -72,13 +72,13 @@ public static long getTimeDuration(final String value, final TimeUnit desiredUni * This method handles decimal values over {@code 1 ns}, but {@code < 1 ns} will return {@code 0} in any other unit. *

    * Examples: - *

    - * "10 seconds", {@code TimeUnit.MILLISECONDS} -> 10_000.0 - * "0.010 s", {@code TimeUnit.MILLISECONDS} -> 10.0 - * "0.010 s", {@code TimeUnit.SECONDS} -> 0.010 - * "0.010 ns", {@code TimeUnit.NANOSECONDS} -> 1 - * "0.010 ns", {@code TimeUnit.MICROSECONDS} -> 0 - * + * {@snippet lang="text" : + * "10 seconds", {@code TimeUnit.MILLISECONDS} -> 10_000.0 + * "0.010 s", {@code TimeUnit.MILLISECONDS} -> 10.0 + * "0.010 s", {@code TimeUnit.SECONDS} -> 0.010 + * "0.010 ns", {@code TimeUnit.NANOSECONDS} -> 1 + * "0.010 ns", {@code TimeUnit.MICROSECONDS} -> 0 + * } * @param value the {@code String} input * @param desiredUnit the desired output {@link TimeUnit} * @return the parsed and converted amount (without a unit)