Merge branch 'develop' into feature/1690-invalid-config-handling

See: https://github.com/cryptomator/cryptomator/pull/1691#discussion_r650773723

src/main/java/org/cryptomator/common/mountpoint/MountPointChooser.java

@@ -34,11 +34,13 @@ import java.util.SortedSet;
  * this volume, even if {@code #prepare(Volume, Path)} fails.</i>
  *
  * <p>If {@code #chooseMountPoint(Volume)} yields no result, the next MPC is executed
- * <i>without</i> first calling the {@code #prepare(Volume, Path)} method of the current MPC.
+ * <i>without</i> calling the {@code #prepare(Volume, Path)} method of the current MPC first.
  * This is repeated until<br>
  * <ul>
  *     <li><b>either</b> a mountpoint is returned by {@code #chooseMountPoint(Volume)}
  *     and {@code #prepare(Volume, Path)} succeeds or fails, ending the entire operation</li>
+ *     <li><b>or</b> {@code #chooseMountPoint(Volume)} throws an exception,
+ *     ending the entire operation</li>
  *     <li><b>or</b> no MPC remains and an {@link InvalidMountPointException} is thrown.</li>
  * </ul>
  * If the {@code #prepare(Volume, Path)} method of a MPC fails, the entire
@@ -72,12 +74,13 @@ public interface MountPointChooser {
 	 * Developers should override this method to find or extract a mountpoint for
 	 * the volume <b>without</b> preparing it. Preparation should be done by
 	 * {@link #prepare(Volume, Path)} instead.
-	 * Exceptions in this method should be handled gracefully and result in returning
-	 * {@link Optional#empty()} instead of throwing an exception.
+	 * The Mountpoint-Choosing-Operation will fail if an exception occurs.
+	 * Consequently developers should try to restrict throwing exceptions to those cases where
+	 * aborting the entire operation is sensible. Failure to choose a suitable path should
+	 * be indicated by returning {@link Optional#empty()} instead.
 	 *
 	 * @param caller The Volume that is calling the method to choose a mountpoint
-	 * @return the chosen path or {@link Optional#empty()} if an exception occurred
-	 * or no mountpoint could be found.
+	 * @return the chosen path or {@link Optional#empty()} if no mountpoint could be found.
 	 * @see #isApplicable(Volume)
 	 * @see #prepare(Volume, Path)
 	 */

src/main/java/org/cryptomator/common/settings/InvalidSetting.java

@@ -0,0 +1,54 @@
+package org.cryptomator.common.settings;
+
+import java.net.URI;
+import java.util.Objects;
+import java.util.ResourceBundle;
+
+public enum InvalidSetting {
+
+	;
+
+	private final static String DEFAULT_TRACKER = "https://github.com/cryptomator/cryptomator/issues/";
+	private final static ResourceBundle BUNDLE = ResourceBundle.getBundle("i18n.strings");
+	private final static String UNKNOWN_KEY_FORMAT = "<Unknown key: %s>";
+
+	private final URI issue;
+	private final String resourceKey;
+
+	InvalidSetting(URI issue, String resourceKey) {
+		this.issue = issue;
+		this.resourceKey = Objects.requireNonNull(resourceKey);
+	}
+
+	InvalidSetting(int issueId, String resourceKey) {
+		this(onDefaultTracker(issueId), Objects.requireNonNull(resourceKey));
+	}
+
+	/**
+	 * Returns the corresponding issue URI of this setting.<br>
+	 * The issue URI usually resolves to a page on the
+	 * <a href="https://github.com/cryptomator/cryptomator/issues">Cryptomator Bugtracker.</a>
+	 *
+	 * @return the issue URI or {@code null} if none is provided.
+	 */
+	public URI getIssueURI() {
+		return this.issue;
+	}
+
+	/**
+	 * Returns a (preferably localized) message, that helps the user understand the
+	 * issue in their configuration and how to fix it.
+	 *
+	 * @return the non-null description of the issue.
+	 */
+	public String getMessage() {
+		if (!BUNDLE.containsKey(this.resourceKey)) {
+			return UNKNOWN_KEY_FORMAT.formatted(this.resourceKey);
+		}
+		return BUNDLE.getString(this.resourceKey);
+	}
+
+	private static URI onDefaultTracker(int id) {
+		return URI.create(DEFAULT_TRACKER + id);
+	}
+}

src/main/java/org/cryptomator/common/settings/InvalidSettingException.java

@@ -0,0 +1,41 @@
+package org.cryptomator.common.settings;
+
+
+public class InvalidSettingException extends RuntimeException {
+
+	private final InvalidSetting reason;
+	private final String additionalMessage;
+
+	public InvalidSettingException(InvalidSetting reason) {
+		this(reason, null, null);
+	}
+
+	public InvalidSettingException(InvalidSetting reason, String additionalMessage) {
+		this(reason, additionalMessage, null);
+	}
+
+	public InvalidSettingException(InvalidSetting reason, Throwable cause) {
+		this(reason, null, cause);
+	}
+
+	public InvalidSettingException(InvalidSetting reason, String additionalMessage, Throwable cause) {
+		super(composeMessage(reason, additionalMessage), cause);
+		this.reason = reason;
+		this.additionalMessage = additionalMessage;
+	}
+
+	public InvalidSetting getReason() {
+		return this.reason;
+	}
+
+	public String getAdditionalMessage() {
+		return this.additionalMessage;
+	}
+
+	private static String composeMessage(InvalidSetting reason, String additionalMessage) {
+		if (additionalMessage == null) {
+			return reason.getMessage();
+		}
+		return reason.getMessage() + "Additionally: " + additionalMessage;
+	}
+}