From 3c0927e4acbd8780aada8c7fa8f17cf7f35b420b Mon Sep 17 00:00:00 2001 From: Artem Bilan Date: Mon, 15 May 2023 12:50:46 -0400 Subject: [PATCH] GH-8585: Add Javadocs to Pollers & PollerFactory (#8621) * GH-8585: Add Javadocs to Pollers & PollerFactory Fixes https://github.com/spring-projects/spring-integration/issues/8585 * * Fix Javadoc tags order * * One more Javadoc tags order --- .../integration/dsl/PollerFactory.java | 137 +++++++++++++++++- .../integration/dsl/Pollers.java | 135 ++++++++++++++++- 2 files changed, 262 insertions(+), 10 deletions(-) diff --git a/spring-integration-core/src/main/java/org/springframework/integration/dsl/PollerFactory.java b/spring-integration-core/src/main/java/org/springframework/integration/dsl/PollerFactory.java index dab50532fe..0151ce4571 100644 --- a/spring-integration-core/src/main/java/org/springframework/integration/dsl/PollerFactory.java +++ b/spring-integration-core/src/main/java/org/springframework/integration/dsl/PollerFactory.java @@ -38,52 +38,183 @@ import org.springframework.scheduling.Trigger; */ public final class PollerFactory { + /** + * Create a {@link PollerSpec} based on the provided {@link Trigger}. + * @param trigger the {@link Trigger} to use. + * @return the {@link PollerSpec} + * @see Pollers#trigger(Trigger) + */ public PollerSpec trigger(Trigger trigger) { return Pollers.trigger(trigger); } + /** + * Create a {@link PollerSpec} based on the provided cron expression. + * @param cronExpression the cron to use. + * @return the {@link PollerSpec} + * @see Pollers#cron(String) + */ public PollerSpec cron(String cronExpression) { return Pollers.cron(cronExpression); } + /** + * Create a {@link PollerSpec} based on the provided cron expression and {@link TimeZone}. + * @param cronExpression the cron to use. + * @param timeZone the {@link TimeZone} to use. + * @return the {@link PollerSpec} + * @see Pollers#cron(String, TimeZone) + */ public PollerSpec cron(String cronExpression, TimeZone timeZone) { return Pollers.cron(cronExpression, timeZone); } + /** + * Create a {@link PollerSpec} based on the provided fixed rate period. + * @param period the fixed rate period to use. + * @return the {@link PollerSpec} + * @see Pollers#fixedRate(long) + */ public PollerSpec fixedRate(long period) { return Pollers.fixedRate(period); } + /** + * Create a {@link PollerSpec} based on the provided fixed rate period and {@link TimeUnit}. + * @param period the fixed rate period to use. + * @param timeUnit the {@link TimeUnit} to use. + * @return the {@link PollerSpec} + * @deprecated since 6.1 in favor of {@link #fixedRate(Duration)} + * @see Pollers#fixedRate(Duration) + */ + @Deprecated(forRemoval = true) public PollerSpec fixedRate(long period, TimeUnit timeUnit) { return Pollers.fixedRate(Duration.of(period, timeUnit.toChronoUnit())); } + /** + * Create a {@link PollerSpec} based on the provided fixed rate period. + * @param period the fixed rate period to use. + * @return the {@link PollerSpec} + * @since 6.1 + * @see Pollers#fixedRate(Duration) + */ + public static PollerSpec fixedRate(Duration period) { + return Pollers.fixedRate(period); + } + + /** + * Create a {@link PollerSpec} based on the provided fixed rate period and initial delay. + * @param period the fixed rate period (in milliseconds) to use. + * @param initialDelay the initial delay (in milliseconds) to use. + * @return the {@link PollerSpec} + * @see Pollers#fixedRate(long, long) + */ public PollerSpec fixedRate(long period, long initialDelay) { return Pollers.fixedRate(period, initialDelay); } - public PollerSpec fixedDelay(long period, TimeUnit timeUnit, long initialDelay) { - ChronoUnit chronoUnit = timeUnit.toChronoUnit(); - return Pollers.fixedDelay(Duration.of(period, chronoUnit), Duration.of(initialDelay, chronoUnit)); + /** + * Create a {@link PollerSpec} based on the provided fixed rate period and initial delay . + * @param period the fixed rate period to use. + * @param initialDelay the initial delay to use. + * @return the {@link PollerSpec} + * @since 6.1 + * @see Pollers#fixedRate(Duration) + */ + public static PollerSpec fixedRate(Duration period, Duration initialDelay) { + return Pollers.fixedRate(period, initialDelay); } + /** + * Create a {@link PollerSpec} based on the provided fixed rate period and {@link TimeUnit} + * with an initial delay. + * @param period the fixed rate period to use. + * @param timeUnit the {@link TimeUnit} to use. + * @param initialDelay the initial delay to use. + * @return the {@link PollerSpec} + * @deprecated since 6.1 in favor of {@link #fixedRate(Duration, Duration)} + * @see Pollers#fixedRate(Duration, Duration) + */ + @Deprecated(forRemoval = true) public PollerSpec fixedRate(long period, TimeUnit timeUnit, long initialDelay) { ChronoUnit chronoUnit = timeUnit.toChronoUnit(); return Pollers.fixedRate(Duration.of(period, chronoUnit), Duration.of(initialDelay, chronoUnit)); } + /** + * Create a {@link PollerSpec} based on the provided fixed delay period and {@link TimeUnit} + * with an initial delay. + * @param period the fixed delay period to use. + * @param timeUnit the {@link TimeUnit} to use. + * @param initialDelay the initial delay to use. + * @return the {@link PollerSpec} + * @deprecated since 6.1 in favor of {@link #fixedDelay(Duration, Duration)} + * @see Pollers#fixedDelay(Duration, Duration) + */ + @Deprecated(forRemoval = true) + public PollerSpec fixedDelay(long period, TimeUnit timeUnit, long initialDelay) { + ChronoUnit chronoUnit = timeUnit.toChronoUnit(); + return Pollers.fixedDelay(Duration.of(period, chronoUnit), Duration.of(initialDelay, chronoUnit)); + } + + /** + * Create a {@link PollerSpec} based on the provided fixed delay period and {@link TimeUnit}. + * @param period the fixed delay period to use. + * @param timeUnit the {@link TimeUnit} to use. + * @return the {@link PollerSpec} + * @deprecated since 6.1 in favor of {@link #fixedDelay(Duration)} + * @see Pollers#fixedDelay(Duration) + */ + @Deprecated(forRemoval = true) public PollerSpec fixedDelay(long period, TimeUnit timeUnit) { return Pollers.fixedDelay(Duration.of(period, timeUnit.toChronoUnit())); } + /** + * Create a {@link PollerSpec} based on the provided fixed delay period and initial delay. + * @param period the fixed delay period (in milliseconds) to use. + * @param initialDelay the initial delay (in milliseconds) to use. + * @return the {@link PollerSpec} + * @see Pollers#fixedDelay(long, long) + */ public PollerSpec fixedDelay(long period, long initialDelay) { return Pollers.fixedDelay(period, initialDelay); } + /** + * Create a {@link PollerSpec} based on the provided fixed delay period. + * @param period the fixed delay period to use. + * @return the {@link PollerSpec} + * @see Pollers#fixedDelay(long) + */ public PollerSpec fixedDelay(long period) { return Pollers.fixedDelay(period); } + /** + * Create a {@link PollerSpec} based on the provided fixed delay period. + * @param period the fixed delay period to use. + * @return the {@link PollerSpec} + * @since 6.1 + * @see Pollers#fixedDelay(Duration) + */ + public static PollerSpec fixedDelay(Duration period) { + return Pollers.fixedDelay(period); + } + + /** + * Create a {@link PollerSpec} based on the provided fixed delay period and initial delay . + * @param period the fixed delay period to use. + * @param initialDelay the initial delay to use. + * @return the {@link PollerSpec} + * @since 6.1 + * @see Pollers#fixedDelay(Duration) + */ + public static PollerSpec fixedDelay(Duration period, Duration initialDelay) { + return Pollers.fixedDelay(period, initialDelay); + } + PollerFactory() { } diff --git a/spring-integration-core/src/main/java/org/springframework/integration/dsl/Pollers.java b/spring-integration-core/src/main/java/org/springframework/integration/dsl/Pollers.java index 6c8c863e3e..ac4befe78b 100644 --- a/spring-integration-core/src/main/java/org/springframework/integration/dsl/Pollers.java +++ b/spring-integration-core/src/main/java/org/springframework/integration/dsl/Pollers.java @@ -27,7 +27,7 @@ import org.springframework.scheduling.support.CronTrigger; import org.springframework.scheduling.support.PeriodicTrigger; /** - * An utility class to provide {@link PollerSpec}s for + * A utility class to provide {@link PollerSpec}s for * {@link org.springframework.integration.scheduling.PollerMetadata} configuration * variants. * @@ -38,36 +38,84 @@ import org.springframework.scheduling.support.PeriodicTrigger; */ public final class Pollers { - public static PollerSpec trigger(Trigger trigger) { - return new PollerSpec(trigger); - } - + /** + * Create a {@link PollerSpec} based on the provided fixed rate period. + * The "fixed rate" means that periodic interval should be measured between the + * scheduled start times rather than between actual completion times. + * @param period the fixed rate period (in milliseconds) to use. + * @return the {@link PollerSpec} + * @see PeriodicTrigger + */ public static PollerSpec fixedRate(long period) { return fixedRate(Duration.ofMillis(period)); } + /** + * Create a {@link PollerSpec} based on the provided fixed rate period. + * The "fixed rate" means that periodic interval should be measured between the + * scheduled start times rather than between actual completion times. + * @param period the fixed rate period to use. + * @return the {@link PollerSpec} + * @see PeriodicTrigger + */ public static PollerSpec fixedRate(Duration period) { return periodicTrigger(period, true, null); } /** + * Create a {@link PollerSpec} based on the provided fixed rate period. + * The "fixed rate" means that periodic interval should be measured between the + * scheduled start times rather than between actual completion times. + * @param period the fixed rate period to use. + * @param timeUnit the {@link TimeUnit} to use. + * @return the {@link PollerSpec} * @deprecated since 6.0 in favor of {@link #fixedRate(Duration)} + * @see PeriodicTrigger */ @Deprecated(forRemoval = true) public static PollerSpec fixedRate(long period, TimeUnit timeUnit) { return fixedRate(Duration.of(period, timeUnit.toChronoUnit())); } + /** + * Create a {@link PollerSpec} based on the provided fixed rate period + * and initial delay. + * The "fixed rate" means that periodic interval should be measured between the + * scheduled start times rather than between actual completion times. + * @param period the fixed rate period to use. + * @param initialDelay the initial delay to use. + * @return the {@link PollerSpec} + * @see PeriodicTrigger + */ public static PollerSpec fixedRate(Duration period, Duration initialDelay) { return periodicTrigger(period, true, initialDelay); } + /** + * Create a {@link PollerSpec} based on the provided fixed rate period + * and initial delay. + * The "fixed rate" means that periodic interval should be measured between the + * scheduled start times rather than between actual completion times. + * @param period the fixed rate period to use. + * @param initialDelay the initial delay to use. + * @return the {@link PollerSpec} + * @see PeriodicTrigger + */ public static PollerSpec fixedRate(long period, long initialDelay) { return fixedRate(Duration.ofMillis(period), Duration.ofMillis(initialDelay)); } /** + * Create a {@link PollerSpec} based on the provided fixed rate period + * and initial delay. + * The "fixed rate" means that periodic interval should be measured between the + * scheduled start times rather than between actual completion times. + * @param period the fixed rate period to use. + * @param timeUnit the {@link TimeUnit} to use. + * @param initialDelay the initial delay to use. + * @return the {@link PollerSpec} * @deprecated since 6.0 in favor of {@link #fixedRate(Duration, Duration)} + * @see PeriodicTrigger */ @Deprecated(forRemoval = true) public static PollerSpec fixedRate(long period, TimeUnit timeUnit, long initialDelay) { @@ -75,32 +123,82 @@ public final class Pollers { return fixedRate(Duration.of(period, chronoUnit), Duration.of(initialDelay, chronoUnit)); } + /** + * Create a {@link PollerSpec} based on the provided fixed delay period. + * The "fixed delay" means that periodic interval should be measured between the + * scheduled tasks actual completion times. + * @param period the fixed delay period to use. + * @return the {@link PollerSpec} + * @see PeriodicTrigger + */ public static PollerSpec fixedDelay(Duration period) { return periodicTrigger(period, false, null); } + /** + * Create a {@link PollerSpec} based on the provided fixed delay period. + * The "fixed delay" means that periodic interval should be measured between the + * scheduled tasks actual completion times. + * @param period the fixed delay period to use. + * @return the {@link PollerSpec} + * @see PeriodicTrigger + */ public static PollerSpec fixedDelay(long period) { return fixedDelay(Duration.ofMillis(period)); } + /** + * Create a {@link PollerSpec} based on the provided fixed delay period and initial delay. + * The "fixed delay" means that periodic interval should be measured between the + * scheduled tasks actual completion times. + * @param period the fixed delay period to use. + * @param initialDelay the initial delay to use. + * @return the {@link PollerSpec} + * @see PeriodicTrigger + */ public static PollerSpec fixedDelay(Duration period, Duration initialDelay) { return periodicTrigger(period, false, initialDelay); } /** + * Create a {@link PollerSpec} based on the provided fixed delay period. + * The "fixed delay" means that periodic interval should be measured between the + * scheduled tasks actual completion times. + * @param period the fixed delay period to use. + * @param timeUnit the {@link TimeUnit} to use. + * @return the {@link PollerSpec} * @deprecated since 6.0 in favor of {@link #fixedDelay(Duration)} + * @see PeriodicTrigger */ @Deprecated(forRemoval = true) public static PollerSpec fixedDelay(long period, TimeUnit timeUnit) { return fixedDelay(Duration.of(period, timeUnit.toChronoUnit())); } + /** + * Create a {@link PollerSpec} based on the provided fixed delay period and initial delay. + * The "fixed delay" means that periodic interval should be measured between the + * scheduled tasks actual completion times. + * @param period the fixed delay period to use. + * @param initialDelay the initial delay to use. + * @return the {@link PollerSpec} + * @see PeriodicTrigger + */ public static PollerSpec fixedDelay(long period, long initialDelay) { return fixedDelay(Duration.ofMillis(period), Duration.ofMillis(initialDelay)); } /** + * Create a {@link PollerSpec} based on the provided fixed delay period + * and initial delay. + * The "fixed delay" means that periodic interval should be measured between the + * scheduled tasks actual completion times. + * @param period the fixed delay period to use. + * @param timeUnit the {@link TimeUnit} to use. + * @param initialDelay the initial delay to use. + * @return the {@link PollerSpec} * @deprecated since 6.0 in favor of {@link #fixedDelay(Duration, Duration)} + * @see PeriodicTrigger */ @Deprecated(forRemoval = true) public static PollerSpec fixedDelay(long period, TimeUnit timeUnit, long initialDelay) { @@ -114,15 +212,38 @@ public final class Pollers { if (initialDelay != null) { periodicTrigger.setInitialDelay(initialDelay); } - return new PollerSpec(periodicTrigger); + return trigger(periodicTrigger); } + /** + * Create a {@link PollerSpec} based on the provided cron expression. + * @param cronExpression the cron to use. + * @return the {@link PollerSpec} + * @see CronTrigger + */ public static PollerSpec cron(String cronExpression) { return cron(cronExpression, TimeZone.getDefault()); } + /** + * Create a {@link PollerSpec} based on the provided cron expression and {@link TimeZone}. + * @param cronExpression the cron to use. + * @param timeZone the {@link TimeZone} to use. + * @return the {@link PollerSpec} + * @see CronTrigger + */ public static PollerSpec cron(String cronExpression, TimeZone timeZone) { - return new PollerSpec(new CronTrigger(cronExpression, timeZone)); + return trigger(new CronTrigger(cronExpression, timeZone)); + } + + /** + * Create a {@link PollerSpec} based on the provided {@link Trigger}. + * @param trigger the {@link Trigger} to use. + * @return the {@link PollerSpec} + * @see Pollers#trigger(Trigger) + */ + public static PollerSpec trigger(Trigger trigger) { + return new PollerSpec(trigger); } private Pollers() {