Scheduled tasks (#2301)

Signed-off-by: Daniel Kec <daniel.kec@oracle.com>

bom/pom.xml

@@ -713,6 +713,18 @@
                 <version>${helidon.version}</version>
             </dependency>
 
+            <!-- Scheduling -->
+            <dependency>
+                <groupId>io.helidon.scheduling</groupId>
+                <artifactId>helidon-scheduling</artifactId>
+                <version>${helidon.version}</version>
+            </dependency>
+            <dependency>
+                <groupId>io.helidon.microprofile.scheduling</groupId>
+                <artifactId>helidon-microprofile-scheduling</artifactId>
+                <version>${helidon.version}</version>
+            </dependency>
+
             <!-- integrations -->
             <dependency>
                 <groupId>io.helidon.integrations.db</groupId>

common/common/src/main/java/io/helidon/common/FeatureCatalog.java

@@ -146,6 +146,13 @@ final class FeatureCatalog {
               "Jersey",
               "WebServer integration with Jersey",
               "WebServer", "Jersey");
+        add("io.helidon.scheduling",
+                FeatureDescriptor.builder()
+                        .flavor(HelidonFlavor.SE)
+                        .name("Scheduling")
+                        .description("Scheduling of periodical tasks")
+                        .path("Scheduling")
+                        .nativeSupported(true));
         add("io.helidon.webserver.tyrus",
             FeatureDescriptor.builder()
                     .flavor(HelidonFlavor.SE)
@@ -326,6 +333,16 @@ final class FeatureCatalog {
                     .experimental(true)
         );
 
+        add("io.helidon.microprofile.scheduling",
+            FeatureDescriptor.builder()
+                    .name("Scheduling")
+                    .description("Task scheduling")
+                    .path("Scheduling")
+                    .flavor(HelidonFlavor.MP)
+                    .nativeSupported(true)
+                    .experimental(true)
+        );
+
         /*
          * Common modules
          */

dependencies/pom.xml

@@ -44,6 +44,7 @@
         <version.lib.brave-opentracing>0.35.0</version.lib.brave-opentracing>
         <version.lib.cdi-api>2.0.2</version.lib.cdi-api>
         <version.lib.commons-logging>1.2</version.lib.commons-logging>
+        <version.lib.cron-utils>9.1.0</version.lib.cron-utils>
         <version.lib.dropwizard.metrics>4.1.2</version.lib.dropwizard.metrics>
         <version.lib.eclipselink>2.7.5</version.lib.eclipselink>
         <version.lib.el-api>3.0.3</version.lib.el-api>
@@ -1027,6 +1028,12 @@
                 <artifactId>neo4j-java-driver</artifactId>
                 <version>${version.lib.neo4j}</version>
             </dependency>
+            <!-- Cron utils -->
+            <dependency>
+                <groupId>com.cronutils</groupId>
+                <artifactId>cron-utils</artifactId>
+                <version>${version.lib.cron-utils}</version>
+            </dependency>
             <!-- END OF Section 1: direct third party dependencies -->
 
             <!-- Section 2: third party dependencies used by examples -->

docs/mp/aot/01_introduction.adoc

@@ -1,6 +1,6 @@
 ///////////////////////////////////////////////////////////////////////////////
 
-    Copyright (c) 2020 Oracle and/or its affiliates.
+    Copyright (c) 2021 Oracle and/or its affiliates.
 
     Licensed under the Apache License, Version 2.0 (the "License");
     you may not use this file except in compliance with the License.
@@ -95,5 +95,6 @@ for native image.
 |❓ |gRPC Client |gRPC Client |Not yet tested.
 |✅ |{nbsp} |Metrics |{nbsp}
 |✅ |Metrics |Metrics |{nbsp}
+|✅ |Scheduling |Scheduling |{nbsp}
 |===
 

docs/mp/scheduling/01_introduction.adoc

@@ -0,0 +1,102 @@
+///////////////////////////////////////////////////////////////////////////////
+
+    Copyright (c) 2021 Oracle and/or its affiliates.
+
+    Licensed under the Apache License, Version 2.0 (the "License");
+    you may not use this file except in compliance with the License.
+    You may obtain a copy of the License at
+
+        http://www.apache.org/licenses/LICENSE-2.0
+
+    Unless required by applicable law or agreed to in writing, software
+    distributed under the License is distributed on an "AS IS" BASIS,
+    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+    See the License for the specific language governing permissions and
+    limitations under the License.
+
+///////////////////////////////////////////////////////////////////////////////
+
+= Overview
+:toc:
+:toc-placement: preamble
+:description: Scheduling in Helidon MP
+:keywords: helidon, mp, scheduling
+:h1Prefix: MP
+
+== Scheduling
+For scheduling tasks in Helidon you can choose from @Scheduled or @FixedRate annotations by required complexity of invocation interval. All you need is define method with one of the annotations in application scoped bean.
+
+[source,xml]
+.Dependency for Scheduling feature
+----
+<dependency>
+    <groupId>io.helidon.microprofile.scheduling</groupId>
+    <artifactId>helidon-microprofile-scheduling</artifactId>
+</dependency>
+----
+
+
+=== Fixed rate
+For simple fixed rate invocation interval is @FixedRate the easiest way for scheduling
+task invocation.
+
+[source,java]
+.Example of scheduling with fixed rate
+----
+@FixedRate(initialDelay = 5, value = 10, timeUnit = TimeUnit.MINUTES)
+public void methodName() {
+    System.out.println("Every 10 minutes, first invocation 5 minutes after start");
+}
+----
+
+All values defined with the annotation can be overridden from the config.
+
+[source,yaml]
+.Overiding annotated values from config
+----
+fully.quallified.ClassName.methodName:
+  schedule:
+    initial-delay: 5
+    delay: 15
+    time-unit: HOURS
+----
+
+Metadata like human-readable interval description or configured values are available through
+FixedRateInvocation injected as method parameter.
+
+[source,java]
+.Example with ivocation metadata
+----
+@FixedRate(initialDelay = 5, value = 10, timeUnit = TimeUnit.MINUTES)
+public void methodName(FixedRateInvocation inv) {
+    System.out.println("Method invoked " + inv.description());
+}
+----
+
+=== Cron expression
+
+For more complicated interval definition, cron expression can be leveraged with
+@Schedule annotation.
+
+[source,java]
+.Example of scheduling with cron expression
+----
+@Scheduled("0 15 8 ? * *")
+public void methodName() {
+    System.out.println("Executer every day at 8:15");
+}
+----
+
+include::../../shared/scheduling/01_cron.adoc[lines=19..]
+
+Metadata like human-readable interval description or configured values are available through
+CronInvocation injected as method parameter.
+
+[source,java]
+.Example with ivocation metadata
+----
+@Scheduled("0 15 8 ? * *")
+public void methodName(CronInvocation inv) {
+    System.out.println("Method invoked " + inv.description());
+}
+----

docs/se/aot/01_introduction.adoc

@@ -107,5 +107,6 @@ for native image.
 |✅ |{nbsp} |Metrics |{nbsp}
 |✅ |gRPC Client |gRPC Client |Since GraalVM 21.0.0
 |✅ |{nbsp} |Metrics |{nbsp}
+|✅ |Scheduling |Scheduling |{nbsp}
 |===
 

docs/se/scheduling/01_introduction.adoc

@@ -0,0 +1,91 @@
+///////////////////////////////////////////////////////////////////////////////
+
+    Copyright (c) 2021 Oracle and/or its affiliates.
+
+    Licensed under the Apache License, Version 2.0 (the "License");
+    you may not use this file except in compliance with the License.
+    You may obtain a copy of the License at
+
+        http://www.apache.org/licenses/LICENSE-2.0
+
+    Unless required by applicable law or agreed to in writing, software
+    distributed under the License is distributed on an "AS IS" BASIS,
+    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+    See the License for the specific language governing permissions and
+    limitations under the License.
+
+///////////////////////////////////////////////////////////////////////////////
+
+= Overview
+:toc:
+:toc-placement: preamble
+:description: Scheduling in Helidon SE
+:keywords: helidon, se, scheduling
+:h1Prefix: SE
+
+== Scheduling
+For scheduling periodic tasks it is possible to choose fixed rate setup or Cron expression.
+
+[source,xml]
+.Dependency for Scheduling feature
+----
+<dependency>
+    <groupId>io.helidon.scheduling</groupId>
+    <artifactId>helidon-scheduling</artifactId>
+</dependency>
+----
+
+
+=== Fixed rate
+For simple fixed rate invocation use .
+
+[source,java]
+.Example of scheduling with fixed rate use `Scheduling.fixedRateBuilder()` builder.
+----
+Scheduling.fixedRateBuilder()
+        .delay(10)
+        .initialDelay(5)
+        .timeUnit(TimeUnit.MINUTES)
+        .task(inv -> System.out.println("Every 10 minutes, first invocation 5 minutes after start"))
+        .build();
+----
+
+Metadata like human-readable interval description or configured values are available through
+FixedRateInvocation provided as task parameter.
+
+[source,java]
+.Example with ivocation metadata
+----
+Scheduling.fixedRateBuilder()
+        .delay(10)
+        .task(inv -> System.out.println("Method invoked " + inv.description()))
+        .build();
+----
+
+=== Cron expression
+
+For more complicated interval definition, cron expression can be leveraged with
+`Scheduling.cronBuilder()` builder.
+
+[source,java]
+.Example of scheduling with cron expression
+----
+Scheduling.cronBuilder()
+    .expression("0 15 8 ? * *")
+    .task(inv -> System.out.println("Executer every day at 8:15"))
+    .build();
+----
+
+include::../../shared/scheduling/01_cron.adoc[lines=19..]
+
+Metadata like human-readable interval description or configured values are available through
+CronInvocation provided as task parameter.
+
+[source,java]
+.Example with ivocation metadata
+----
+Scheduling.cronBuilder()
+    .expression("0 15 8 ? * *")
+    .task(inv -> System.out.println("Method invoked " + inv.description()))
+    .build();
+----

docs/shared/scheduling/01_cron.adoc

@@ -0,0 +1,61 @@
+///////////////////////////////////////////////////////////////////////////////
+
+    Copyright (c) 2021 Oracle and/or its affiliates.
+
+    Licensed under the Apache License, Version 2.0 (the "License");
+    you may not use this file except in compliance with the License.
+    You may obtain a copy of the License at
+
+        http://www.apache.org/licenses/LICENSE-2.0
+
+    Unless required by applicable law or agreed to in writing, software
+    distributed under the License is distributed on an "AS IS" BASIS,
+    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+    See the License for the specific language governing permissions and
+    limitations under the License.
+
+///////////////////////////////////////////////////////////////////////////////
+=== Cron expression
+[source]
+.Cron expression format
+----
+<seconds> <minutes> <hours> <day-of-month> <month> <day-of-week> <year>
+----
+
+.Cron expression fields
+[width="90%",cols="^3,20,^2,90,^3",frame="topbot",options="header"]
+|=======================================================================================================================
+| Order | Name          | Supported values  | Supported field format                                        | Optional
+| 1     | seconds       | 0-59              | CONST, LIST, RANGE, WILDCARD, INCREMENT                       | false
+| 2     | minutes       | 0-59              | CONST, LIST, RANGE, WILDCARD, INCREMENT                       | false
+| 3     | hours         | 0-23              | CONST, LIST, RANGE, WILDCARD, INCREMENT                       | false
+| 4     | day-of-month  | 1-31              | CONST, LIST, RANGE, WILDCARD, INCREMENT, ANY, LAST, WEEKDAY   | false
+| 5     | month         | 1-12 or JAN-DEC   | CONST, LIST, RANGE, WILDCARD, INCREMENT                       | false
+| 6     | day-of-week   | 1-7 or SUN-SAT    | CONST, LIST, RANGE, WILDCARD, INCREMENT, ANY, NTH, LAST       | false
+| 7     | year          | 1970-2099         | CONST, LIST, RANGE, WILDCARD, INCREMENT                       | true
+|=======================================================================================================================
+
+.Field formats
+[width="90%",cols="3,25,^2,90",frame="topbot",options="header"]
+|=======================================================================================================================
+| Name      | Regex format          | Example   | Description
+| CONST     | \d+                   | 12        | exact value
+| LIST      | \d+,\d+(,\d+)*        | 1,2,3,4   | list of constants
+| RANGE     | \d+-\d+               | 15-30     | range of values from-to
+| WILDCARD  | \*                    | *         | all values withing the field
+| INCREMENT | \d+\/\d+              | 0/5       | inital number / increments, 2/5 means 2,7,9,11,16,...
+| ANY       | \?                    | ?         | any day(apply only to day-of-week and day-of-month)
+| NTH       | \#                    | 1#3       | nth day of the month, 2#3 means third monday of the month
+| LAST      | \d*L(\+\d+\|\-\d+)?   | 3L-3      | last day of the month in day-of-month or last nth day in the day-of-week
+| WEEKDAY   | \#                    | 1#3       | nearest weekday of the nth day of month, 1W is the first monday of the week
+|=======================================================================================================================
+
+.Examples
+[width="90%",cols="3,10",frame="topbot",options="header"]
+|=======================================================================================================================
+| Cron expression       | Description
+| * * * * * ?           | Every second
+| 0/2 * * * * ? *       | Every 2 seconds
+| 0 45 9 ? * *          | Every day at 9:45
+| 0 15 8 ? * MON-FRI    | Every workday at 8:15
+|=======================================================================================================================

docs/sitegen.yaml

@@ -1,5 +1,5 @@
 #
-# Copyright (c) 2018, 2021 Oracle and/or its affiliates.
+# Copyright (c) 2018, 2021, Oracle and/or its affiliates.
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.
@@ -185,6 +185,14 @@ backend:
               items:
                 - includes:
                     - "se/security/*.adoc"
+            - title: "Scheduling"
+              pathprefix: "/se/scheduling"
+              glyph:
+                type: "icon"
+                value: "access_alarm"
+              items:
+                - includes:
+                    - "se/scheduling/*.adoc"
             - title: "Tracing"
               pathprefix: "/se/tracing"
               glyph:
@@ -383,6 +391,14 @@ backend:
               items:
                 - includes:
                     - "mp/security/*.adoc"
+            - title: "Scheduling"
+              pathprefix: "/mp/scheduling"
+              glyph:
+                type: "icon"
+                value: "access_alarm"
+              items:
+                - includes:
+                    - "mp/scheduling/*.adoc"
             - title: "Tracing"
               pathprefix: "/mp/tracing"
               glyph:

microprofile/pom.xml

@@ -54,5 +54,6 @@
         <module>messaging</module>
         <module>cors</module>
         <module>graphql</module>
+        <module>scheduling</module>
     </modules>
 </project>