Scheduler API (initial specification)

Author: dariol83

eu.dariolucia.reatmetric.api/src/main/java/eu/dariolucia/reatmetric/api/IReatmetricSystem.java

@@ -30,6 +30,8 @@
 import eu.dariolucia.reatmetric.api.model.ISystemModelProvisionService;
 import eu.dariolucia.reatmetric.api.parameters.IParameterDataProvisionService;
 import eu.dariolucia.reatmetric.api.rawdata.IRawDataProvisionService;
+import eu.dariolucia.reatmetric.api.scheduler.IScheduledActivityDataProvisionService;
+import eu.dariolucia.reatmetric.api.scheduler.IScheduler;
 import eu.dariolucia.reatmetric.api.transport.ITransportConnector;
 
 import java.util.List;
@@ -67,5 +69,9 @@ public interface IReatmetricSystem extends IDebugInfoProvider {
 
     IActivityExecutionService getActivityExecutionService() throws ReatmetricException;
 
+    IScheduler getScheduler() throws ReatmetricException;
+
+    IScheduledActivityDataProvisionService getScheduledActivityDataMonitorService() throws ReatmetricException;
+
     List<ITransportConnector> getTransportConnectors() throws ReatmetricException;
 }

eu.dariolucia.reatmetric.api/src/main/java/eu/dariolucia/reatmetric/api/processing/input/AbstractInputDataItem.java

@@ -16,6 +16,8 @@
 
 package eu.dariolucia.reatmetric.api.processing.input;
 
-public abstract class AbstractInputDataItem {
+import java.io.Serializable;
+
+public abstract class AbstractInputDataItem implements Serializable {
     // Marker class
 }

eu.dariolucia.reatmetric.api/src/main/java/eu/dariolucia/reatmetric/api/scheduler/AbstractSchedulingTrigger.java

@@ -1,5 +1,7 @@
 package eu.dariolucia.reatmetric.api.scheduler;
 
-public abstract class AbstractSchedulingTrigger {
+import java.io.Serializable;
+
+public abstract class AbstractSchedulingTrigger implements Serializable {
 
 }

eu.dariolucia.reatmetric.api/src/main/java/eu/dariolucia/reatmetric/api/scheduler/IScheduler.java

@@ -2,14 +2,31 @@
 
 import eu.dariolucia.reatmetric.api.common.IUniqueId;
 import eu.dariolucia.reatmetric.api.scheduler.exceptions.SchedulingException;
+import eu.dariolucia.reatmetric.api.scheduler.input.SchedulingRequest;
 
 import java.time.Instant;
 import java.util.List;
 
-public interface IScheduler {
+/**
+ * Interface implemented by a ReatMetric scheduler, allowing the change in the scheduler state as well as
+ * the capability to create, update and remove scheduled activities.
+ */
+public interface IScheduler extends IScheduledActivityDataProvisionService {
 
+    void initialise() throws SchedulingException;
+
+    /**
+     * Subscribe the provided subscriber to the scheduler, to know the current scheduler state.
+     *
+     * @param subscriber the subscriber
+     */
     void subscribe(ISchedulerSubscriber subscriber);
 
+    /**
+     * Unsubscribe the provided subscriber.
+     *
+     * @param subscriber the subscriber
+     */
     void unsubscribe(ISchedulerSubscriber subscriber);
 
     void enable() throws SchedulingException;
@@ -22,6 +39,26 @@ public interface IScheduler {
 
     List<ScheduledActivityData> schedule(List<SchedulingRequest> request, CreationConflictStrategy conflictStrategy) throws SchedulingException;
 
+    /**
+     * Return the list of the activities currently in the state {@link SchedulingState#SCHEDULED}.
+     *
+     * @return the list of the activities currently in the state {@link SchedulingState#SCHEDULED}
+     * @throws SchedulingException in case of issues when executing the method
+     */
+    List<ScheduledActivityData> getCurrentScheduledActivities() throws SchedulingException;
+
+    /**
+     * Update the scheduled activity indicated by originalId with the new data coming from the provided {@link SchedulingRequest}.
+     *
+     * The scheduled activity can be updated only if it is in the {@link SchedulingState#SCHEDULED} state.
+     *
+     * @param originalId the original scheduled activity to update
+     * @param newRequest the new request
+     * @param conflictStrategy the creation conflict strategy to be used in case of resource conflict
+     * @return the updated scheduled activity data
+     * @throws SchedulingException in case the conflict strategy does not allow proper resolution or in case the scheduled activity is not
+     * in the expected state
+     */
     ScheduledActivityData update(IUniqueId originalId, SchedulingRequest newRequest, CreationConflictStrategy conflictStrategy) throws SchedulingException;
 
     boolean remove(IUniqueId scheduledId) throws SchedulingException;
@@ -33,7 +70,7 @@ public interface IScheduler {
      * and adds the new scheduling requests. This is effectively the operation needed to replace schedule increments belonging to
      * a given source.
      *
-     * If a merge is requested, method {@link IScheduler#schedule(List, CreationConflictStrategy)} should be used.
+     * If a merge is instead requested, method {@link IScheduler#schedule(List, CreationConflictStrategy)} should be used.
      *
      * @param startTime the start of the schedule increment
      * @param endTime the end of the schedule increments
@@ -42,7 +79,7 @@ public interface IScheduler {
      * @param conflictStrategy the conflict strategy to use with respect to resources
      * @return the list of scheduled operations
      */
-    List<ScheduledActivityData> reload(Instant startTime, Instant endTime, List<SchedulingRequest> requests, String source, CreationConflictStrategy conflictStrategy);
+    List<ScheduledActivityData> load(Instant startTime, Instant endTime, List<SchedulingRequest> requests, String source, CreationConflictStrategy conflictStrategy);
 
 
 

eu.dariolucia.reatmetric.api/src/main/java/eu/dariolucia/reatmetric/api/scheduler/ISchedulerFactory.java

@@ -0,0 +1,42 @@
+/*
+ * Copyright (c)  2020 Dario Lucia (https://www.dariolucia.eu)
+ *
+ * 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.
+ */
+
+package eu.dariolucia.reatmetric.api.scheduler;
+
+import eu.dariolucia.reatmetric.api.archive.IArchive;
+import eu.dariolucia.reatmetric.api.archive.exceptions.ArchiveException;
+import eu.dariolucia.reatmetric.api.scheduler.exceptions.SchedulingException;
+
+/**
+ * This interface is the service interface representing the scheduling service in a ReatMetric system. It contains
+ * a single factory method that can be used to instantiate an implementation of the {@link IScheduler} interface.
+ */
+public interface ISchedulerFactory {
+
+    /**
+     * Return an implementation of the {@link IScheduler} interface supplied by the provider of the service. The
+     * archive argument allows the implementation to restore the current status from the archive.
+     *
+     * The returned {@link IScheduler} object is not required to be a different new object: {@link ISchedulerFactory}
+     * implementations are allowed to cache objects or use a singleton-based design.
+     *
+     * @param archive the archive system, can be null: in such case, nothing is restored
+     * @return an implementation of {@link IScheduler} interface
+     * @throws SchedulingException in case of problems arising from the construction of the specific {@link IScheduler} object
+     */
+    IScheduler buildScheduler(IArchive archive) throws SchedulingException;
+
+}

eu.dariolucia.reatmetric.api/src/main/java/eu/dariolucia/reatmetric/api/scheduler/ISchedulerSubscriber.java

@@ -1,7 +1,15 @@
 package eu.dariolucia.reatmetric.api.scheduler;
 
+/**
+ * Interface subscriber for the scheduler state.
+ */
 public interface ISchedulerSubscriber {
 
+    /**
+     * Report the enablement status of the scheduler when it changes.
+     *
+     * @param enabled true if the scheduler is enabled
+     */
     void schedulerEnablementChanged(boolean enabled);
 
 }

eu.dariolucia.reatmetric.api/src/main/java/eu/dariolucia/reatmetric/api/scheduler/ScheduledActivityData.java

@@ -5,6 +5,7 @@
 import eu.dariolucia.reatmetric.api.processing.input.ActivityRequest;
 
 import java.time.Instant;
+import java.util.Collection;
 import java.util.Set;
 
 public final class ScheduledActivityData extends AbstractDataItem {
@@ -27,11 +28,36 @@ public final class ScheduledActivityData extends AbstractDataItem {
 
     private final SchedulingState state;
 
-    public ScheduledActivityData(IUniqueId internalId, Instant generationTime, ActivityRequest request, IUniqueId activityOccurrence, Set<String> resources, String source, long externalId, AbstractSchedulingTrigger trigger, Instant latestInvocationTime, ConflictStrategy conflictStrategy, SchedulingState state, Object extension) {
+    /**
+     *
+     * @param internalId
+     * @param generationTime
+     * @param request
+     * @param activityOccurrence
+     * @param resources the resources required by this activity: not null, each string can contain any characters except whitespaces
+     * @param source
+     * @param externalId
+     * @param trigger
+     * @param latestInvocationTime
+     * @param conflictStrategy
+     * @param state
+     * @param extension
+     */
+    public ScheduledActivityData(IUniqueId internalId, Instant generationTime, ActivityRequest request, IUniqueId activityOccurrence, Collection<String> resources, String source, long externalId, AbstractSchedulingTrigger trigger, Instant latestInvocationTime, ConflictStrategy conflictStrategy, SchedulingState state, Object extension) {
         super(internalId, generationTime, extension);
+        if(resources == null) {
+            throw new NullPointerException("Resources cannot be null");
+        }
+        for(String res : resources) {
+            if(res.isBlank()) {
+                throw new IllegalArgumentException("Resource '" + res + "' is blank");
+            } else if(res.indexOf(' ') != -1) {
+                throw new IllegalArgumentException("Resource '" + res + "' contains whitespaces (forbidden)");
+            }
+        }
         this.request = request;
         this.activityOccurrence = activityOccurrence;
-        this.resources = resources;
+        this.resources = Set.copyOf(resources);
         this.source = source;
         this.externalId = externalId;
         this.trigger = trigger;

eu.dariolucia.reatmetric.api/src/main/java/eu/dariolucia/reatmetric/api/scheduler/SchedulingRequest.java

@@ -0,0 +1,65 @@
+package eu.dariolucia.reatmetric.api.scheduler.input;
+
+import eu.dariolucia.reatmetric.api.processing.input.AbstractInputDataItem;
+import eu.dariolucia.reatmetric.api.processing.input.ActivityRequest;
+import eu.dariolucia.reatmetric.api.scheduler.AbstractSchedulingTrigger;
+import eu.dariolucia.reatmetric.api.scheduler.ConflictStrategy;
+
+import java.time.Instant;
+import java.util.Set;
+
+public final class SchedulingRequest extends AbstractInputDataItem {
+
+    private final ActivityRequest request;
+
+    private final Set<String> resources;
+
+    private final String source;
+
+    private final long externalId;
+
+    private final AbstractSchedulingTrigger trigger;
+
+    private final Instant latestInvocationTime;
+
+    private final ConflictStrategy conflictStrategy;
+
+    public SchedulingRequest(ActivityRequest request, Set<String> resources, String source, long externalId, AbstractSchedulingTrigger trigger, Instant latestInvocationTime, ConflictStrategy conflictStrategy) {
+        this.request = request;
+        this.resources = resources;
+        this.source = source;
+        this.externalId = externalId;
+        this.trigger = trigger;
+        this.latestInvocationTime = latestInvocationTime;
+        this.conflictStrategy = conflictStrategy;
+    }
+
+    public ActivityRequest getRequest() {
+        return request;
+    }
+
+    public Set<String> getResources() {
+        return resources;
+    }
+
+    public String getSource() {
+        return source;
+    }
+
+    public long getExternalId() {
+        return externalId;
+    }
+
+    public AbstractSchedulingTrigger getTrigger() {
+        return trigger;
+    }
+
+    public Instant getLatestInvocationTime() {
+        return latestInvocationTime;
+    }
+
+    public ConflictStrategy getConflictStrategy() {
+        return conflictStrategy;
+    }
+}
+

eu.dariolucia.reatmetric.api/src/main/java/eu/dariolucia/reatmetric/api/scheduler/input/SchedulingRequest.java

@@ -20,6 +20,9 @@
     exports eu.dariolucia.reatmetric.api.processing.exceptions;
     exports eu.dariolucia.reatmetric.api.processing.input;
     exports eu.dariolucia.reatmetric.api.processing.scripting;
+    exports eu.dariolucia.reatmetric.api.scheduler;
+    exports eu.dariolucia.reatmetric.api.scheduler.exceptions;
+    exports eu.dariolucia.reatmetric.api.scheduler.input;
     exports eu.dariolucia.reatmetric.api.transport;
     exports eu.dariolucia.reatmetric.api.transport.exceptions;
 }