Merge pull request #36 from cryptomator/feature/quick-access-api

Feature: Quick Access API

src/main/java/module-info.java

@@ -1,3 +1,4 @@
+import org.cryptomator.integrations.quickaccess.QuickAccessService;
 import org.cryptomator.integrations.mount.MountService;
 import org.cryptomator.integrations.revealpath.RevealPathService;
 import org.cryptomator.integrations.tray.TrayMenuController;
@@ -18,6 +19,7 @@
  exports org.cryptomator.integrations.revealpath;
  exports org.cryptomator.integrations.tray;
  exports org.cryptomator.integrations.uiappearance;
+ exports org.cryptomator.integrations.quickaccess;
 
  uses AutoStartProvider;
  uses KeychainAccessProvider;
@@ -26,4 +28,5 @@
  uses TrayIntegrationProvider;
  uses TrayMenuController;
  uses UiAppearanceProvider;
+ uses QuickAccessService;
 }

src/main/java/org/cryptomator/integrations/quickaccess/QuickAccessService.java

@@ -0,0 +1,55 @@
+package org.cryptomator.integrations.quickaccess;
+
+import org.cryptomator.integrations.common.IntegrationsLoader;
+import org.jetbrains.annotations.Blocking;
+import org.jetbrains.annotations.NotNull;
+
+import java.nio.file.Path;
+import java.util.stream.Stream;
+
+/**
+ * Service adding a system path link to a quick access area of the OS or an application (e.g. file manager).
+ *
+ * @apiNote On purpose this service does not define, what an "link to a quick access area" is. The defintion depends on the OS. For example, the quick access area can be the home screen/desktop and the link would be an icon leading to the linked path.
+ */
+@FunctionalInterface
+public interface QuickAccessService {
+
+ /**
+ * Creates an entry in the quick access area.
+ *
+ * @param target The filesystem path the quick access entry points to
+ * @param displayName The display name of the quick access entry
+ * @return a {@link QuickAccessEntry }, used to remove the entry again
+ * @throws QuickAccessServiceException if adding an entry to the quick access area fails
+ * @apiNote It depends on the service implementation wether the display name is used or not.
+ */
+ @Blocking
+ QuickAccessEntry add(@NotNull Path target, @NotNull String displayName) throws QuickAccessServiceException;
+
+ /**
+ * An entry of the quick access area, created by a service implementation.
+ */
+ @FunctionalInterface
+ interface QuickAccessEntry {
+
+ /**
+ * Removes this entry from the quick access area.
+ *
+ * @throws QuickAccessServiceException if removal fails.
+ * @implSpec Service implementations should make this function <em>idempotent</em>, i.e. after the method is called once and succeeded, consecutive calls should not change anything or throw an error.
+ */
+ @Blocking
+ void remove() throws QuickAccessServiceException;
+
+ }
+
+ /**
+ * Loads all supported service providers.
+ *
+ * @return Stream of supported {@link QuickAccessService} implementations (may be empty)
+ */
+ static Stream<QuickAccessService> get() {
+ return IntegrationsLoader.loadAll(QuickAccessService.class);
+ }
+}

src/main/java/org/cryptomator/integrations/quickaccess/QuickAccessServiceException.java

@@ -0,0 +1,12 @@
+package org.cryptomator.integrations.quickaccess;
+
+public class QuickAccessServiceException extends Exception {
+
+ public QuickAccessServiceException(String message) {
+ super(message);
+ }
+
+ public QuickAccessServiceException(String message, Throwable t) {
+ super(message, t);
+ }
+}