Merge pull request #75 from itsallcode/storage-api

Extract Storage into plugin api

README.md

@@ -2,8 +2,8 @@
 A time recording tool
 
 [![Build](https://github.com/itsallcode/white-rabbit/workflows/Build/badge.svg)](https://github.com/itsallcode/white-rabbit/actions?query=workflow%3ABuild)
-[![Quality Gate Status](https://sonarcloud.io/api/project_badges/measure?project=white-rabbit&metric=alert_status)](https://sonarcloud.io/dashboard?id=white-rabbit)
-[![Coverage](https://sonarcloud.io/api/project_badges/measure?project=white-rabbit&metric=coverage)](https://sonarcloud.io/dashboard?id=white-rabbit)
+[![Quality Gate Status](https://sonarcloud.io/api/project_badges/measure?project=org.itsallcode.whiterabbit%3Awhite-rabbit&metric=alert_status)](https://sonarcloud.io/dashboard?id=org.itsallcode.whiterabbit%3Awhite-rabbit)
+[![Coverage](https://sonarcloud.io/api/project_badges/measure?project=org.itsallcode.whiterabbit%3Awhite-rabbit&metric=coverage)](https://sonarcloud.io/dashboard?id=org.itsallcode.whiterabbit%3Awhite-rabbit)
 
 * [Features](#features)
 * [Usage](#usage)

api/src/main/java/org/itsallcode/whiterabbit/api/Plugin.java

@@ -1,14 +1,64 @@
 package org.itsallcode.whiterabbit.api;
 
+import org.itsallcode.whiterabbit.api.features.MonthDataStorage;
+import org.itsallcode.whiterabbit.api.features.PluginFeature;
+import org.itsallcode.whiterabbit.api.features.ProjectReportExporter;
+
+/**
+ * Implement this interface to create a plugin for WhiteRabbit. Register your
+ * plugin by adding file
+ * {@code META-INF/services/org.itsallcode.whiterabbit.api.Plugin} containing
+ * the full qualified class name to the jar.
+ * 
+ * Available features:
+ * <ul>
+ * <li>{@link ProjectReportExporter}</li>
+ * <li>{@link MonthDataStorage}</li>
+ * </ul>
+ */
 public interface Plugin
 {
+    /**
+     * Called once when loading the plugin.
+     * 
+     * @param config
+     *            the configuration of the plugin.
+     */
     void init(PluginConfiguration config);
 
+    /**
+     * The ID of this plugin. IDs must be unique for all plugins. The ID is used
+     * as prefix for {@link PluginConfiguration#getMandatoryValue(String)}.
+     * 
+     * @return the ID of this plugin.
+     */
     String getId();
 
-    void close();
+    /**
+     * Check if this plugin supports the given feature.
+     * 
+     * @param featureType
+     *            the feature type.
+     * @return <code>true</code> if this plugin supports the given feature, else
+     *         <code>false</code>.
+     */
+    boolean supports(Class<? extends PluginFeature> featureType);
 
-    boolean supports(Class<?> featureType);
+    /**
+     * Get an instance of the given feature type.
+     * 
+     * @param featureType
+     *            the feature type.
+     * @param <T>
+     *            the type of the feature.
+     * @return the instance of the given feature. May return <code>null</code>
+     *         or throw an exception if the feature is not supported.
+     */
+    <T extends PluginFeature> T getFeature(Class<T> featureType);
 
-    <T> T getFeature(Class<T> featureType);
+    /**
+     * Called before closing the plugin. The plugin should cleanup any resources
+     * in this method.
+     */
+    void close();
 }

api/src/main/java/org/itsallcode/whiterabbit/api/PluginConfiguration.java

@@ -1,6 +1,21 @@
 package org.itsallcode.whiterabbit.api;
 
+/**
+ * The configuration of a {@link Plugin} that allows retrieving configuration
+ * values from the WhiteRabbit properties file
+ * {@code ~/.whiterabbit.properties}.
+ */
 public interface PluginConfiguration
 {
-    String getMandatoryValue(String string);
+    /**
+     * Get property {@code pluginId.propertyName} from the config file. Throws
+     * an exception if the property is not available.
+     * 
+     * @param propertyName
+     *            the property name to get.
+     * @return the value of the property.
+     * @throws RuntimeException
+     *             if the property is not available in the config file.
+     */
+    String getMandatoryValue(String propertyName);
 }

api/src/main/java/org/itsallcode/whiterabbit/api/features/MonthDataStorage.java

@@ -0,0 +1,71 @@
+package org.itsallcode.whiterabbit.api.features;
+
+import java.time.YearMonth;
+import java.util.List;
+import java.util.Optional;
+
+import org.itsallcode.whiterabbit.api.model.ActivityData;
+import org.itsallcode.whiterabbit.api.model.DayData;
+import org.itsallcode.whiterabbit.api.model.MonthData;
+
+/**
+ * {@link PluginFeature} that provides a storage backend for month data. This
+ * class may keep the data on the local disk or on a backend server.
+ * {@link YearMonth} is used as key for loading and storing entries.
+ */
+public interface MonthDataStorage extends PluginFeature
+{
+    /**
+     * @param month
+     *            the month for which to load the data.
+     * @return the data for the given month.
+     */
+    Optional<MonthData> load(YearMonth month);
+
+    /**
+     * Store the data for a given month.
+     * 
+     * @param month
+     *            the month.
+     * @param data
+     *            the data to store.
+     */
+    void store(YearMonth month, MonthData data);
+
+    /**
+     * @return all months for that data is available in the store.
+     */
+    List<YearMonth> getAvailableDataMonths();
+
+    /**
+     * @return all available data.
+     */
+    List<MonthData> loadAll();
+
+    /**
+     * @return the model factory that can be used to create instances of the
+     *         model.
+     */
+    ModelFactory getModelFactory();
+
+    /**
+     * A {@link ModelFactory} allows creating new instances of the data model.
+     */
+    public interface ModelFactory
+    {
+        /**
+         * @return a new {@link MonthData} instance.
+         */
+        MonthData createMonthData();
+
+        /**
+         * @return a new {@link DayData} instance.
+         */
+        DayData createDayData();
+
+        /**
+         * @return a new {@link ActivityData} instance.
+         */
+        ActivityData createActivityData();
+    }
+}

api/src/main/java/org/itsallcode/whiterabbit/api/features/PluginFeature.java

@@ -0,0 +1,11 @@
+package org.itsallcode.whiterabbit.api.features;
+
+import org.itsallcode.whiterabbit.api.Plugin;
+
+/**
+ * Super interface for all features supported by a {@link Plugin}.
+ */
+public interface PluginFeature
+{
+
+}

api/src/main/java/org/itsallcode/whiterabbit/api/features/ProgressMonitor.java

@@ -0,0 +1,41 @@
+package org.itsallcode.whiterabbit.api.features;
+
+/**
+ * A progress monitor passed to a {@link PluginFeature} that allows reporting
+ * the progress of process.
+ */
+public interface ProgressMonitor
+{
+    /**
+     * Call this method repeatedly to check, if the user wants to cancel the
+     * process. Abort the process if this returns <code>true</code>.
+     * 
+     * @return <code>true</code> if the user has cancelled the process.
+     */
+    boolean isCanceled();
+
+    /**
+     * Notifies that the main task is beginning.
+     * 
+     * @param name
+     *            the name of the current task shown to the user.
+     * @param totalWork
+     *            the total number of work units that will be done by the task.
+     */
+    void beginTask(String name, int totalWork);
+
+    /**
+     * @param name
+     *            the name of the current task shown to the user.
+     */
+    void setTaskName(String name);
+
+    /**
+     * Notifies that a given number of work unit of the main task has been
+     * completed.
+     * 
+     * @param work
+     *            the number of work units just completed.
+     */
+    void worked(int work);
+}

api/src/main/java/org/itsallcode/whiterabbit/api/features/ProjectReportExporter.java

@@ -0,0 +1,20 @@
+package org.itsallcode.whiterabbit.api.features;
+
+import org.itsallcode.whiterabbit.api.model.ProjectReport;
+
+/**
+ * A {@link PluginFeature} that allows exporting a monthly {@link ProjectReport}
+ * to another system.
+ */
+public interface ProjectReportExporter extends PluginFeature
+{
+    /**
+     * Start the export.
+     * 
+     * @param report
+     *            the report to export.
+     * @param progressMonitor
+     *            a progress monitor for reporting the export progress.
+     */
+    void export(ProjectReport report, ProgressMonitor progressMonitor);
+}

api/src/main/java/org/itsallcode/whiterabbit/api/model/ActivityData.java

@@ -0,0 +1,24 @@
+package org.itsallcode.whiterabbit.api.model;
+
+import java.time.Duration;
+
+/**
+ * Model for a project activity on a given {@link DayData day} including project
+ * id, duration and comment.
+ */
+public interface ActivityData
+{
+    String getProjectId();
+
+    void setProjectId(String id);
+
+    Duration getDuration();
+
+    boolean isRemainder();
+
+    void setDuration(Duration duration);
+
+    String getComment();
+
+    void setComment(String comment);
+}

api/src/main/java/org/itsallcode/whiterabbit/api/model/DayData.java

@@ -0,0 +1,45 @@
+package org.itsallcode.whiterabbit.api.model;
+
+import java.time.Duration;
+import java.time.LocalDate;
+import java.time.LocalTime;
+import java.util.List;
+
+/**
+ * Model class representing a day with date, time for begin and end of work,
+ * activities etc.
+ */
+public interface DayData
+{
+    LocalDate getDate();
+
+    DayType getType();
+
+    LocalTime getBegin();
+
+    LocalTime getEnd();
+
+    Duration getInterruption();
+
+    Duration getWorkingHours();
+
+    String getComment();
+
+    void setDate(LocalDate date);
+
+    void setType(DayType type);
+
+    void setBegin(LocalTime begin);
+
+    void setEnd(LocalTime end);
+
+    void setWorkingHours(Duration workingHours);
+
+    void setComment(String comment);
+
+    void setInterruption(Duration interruption);
+
+    List<ActivityData> getActivities();
+
+    void setActivities(List<ActivityData> activities);
+}

api/src/main/java/org/itsallcode/whiterabbit/api/model/DayType.java

@@ -1,5 +1,8 @@
 package org.itsallcode.whiterabbit.api.model;
 
+/**
+ * The type of a {@link DayData day}.
+ */
 public enum DayType
 {
     HOLIDAY(false), VACATION(false), FLEX_TIME(true), SICK(false), WORK(true), WEEKEND(false);
@@ -11,6 +14,9 @@ public enum DayType
         this.workDay = workDay;
     }
 
+    /**
+     * @return <code>true</code> if you need to work on a day of this type.
+     */
     public boolean isWorkDay()
     {
         return workDay;

api/src/main/java/org/itsallcode/whiterabbit/api/model/MonthData.java

@@ -0,0 +1,27 @@
+package org.itsallcode.whiterabbit.api.model;
+
+import java.time.Duration;
+import java.time.Month;
+import java.util.List;
+
+/**
+ * Model class for data of a single month containing year, month, day data etc.
+ */
+public interface MonthData
+{
+    int getYear();
+
+    void setYear(int year);
+
+    Month getMonth();
+
+    void setMonth(Month month);
+
+    Duration getOvertimePreviousMonth();
+
+    void setOvertimePreviousMonth(Duration overtimePreviousMonth);
+
+    List<DayData> getDays();
+
+    void setDays(List<DayData> days);
+}