Introduce support for OS-specific standard cache directories (#676)

This cleans up the home directories of users and helps making sure that
Coursier's cache is not accidentically backed up by applications or OS
functionality.

The precedence is as follows:

- existing $COURSIER_CACHE environment variable
- existing coursier.cache Java property
- existing operating system specific standards:
  - Linux:   $XDG_CACHE_HOME/coursier, with fallback to ~/.cache/coursier
  - Windows: {SpecialFolder.LocalApplicationData}/cache/Coursier
  - macOS:   $HOME/Library/Caches/Coursier
- existing ~/.coursier/
- fallback to operating system specific standard directory else.

See discussion in https://github.com/coursier/coursier/pull/676#issuecomment-338974822

paths/src/main/java/coursier/CachePath.java

@@ -85,18 +85,7 @@ public class CachePath {
     }
 
     public static File defaultCacheDirectory() {
-
-        // cache this method result so that it's only ever computed once?
-
-        String path = System.getenv("COURSIER_CACHE");
-
-        if (path == null)
-          path = System.getProperty("coursier.cache");
-
-        if (path == null)
-            path = System.getProperty("user.home") + "/.coursier/cache/v1"; // shouldn't have put a "v1" component here...
-
-        return new File(path).getAbsoluteFile();
+        return new File(CoursierPaths.cacheDirectory(), "v1");
     }
 
     private static ConcurrentHashMap<File, Object> processStructureLocks = new ConcurrentHashMap<File, Object>();

paths/src/main/java/coursier/CoursierPaths.java

@@ -0,0 +1,72 @@
+package coursier;
+
+import java.io.File;
+
+import io.github.soc.directories.ProjectDirectories;
+
+/**
+ * Computes Coursier's directories according to the standard
+ * defined by operating system Coursier is running on.
+ *
+ * @implNote If more paths e. g. for configuration or application data is required,
+ * use {@link #coursierDirectories} and do not roll your own logic.
+ */
+public final class CoursierPaths {
+    private CoursierPaths() {
+        throw new Error();
+    }
+
+    private static ProjectDirectories coursierDirectories;
+
+    private static volatile File cacheDirectory0 = null;
+
+    private static final Object lock = new Object();
+
+    // TODO After switching to nio, that logic can be unit tested with mock filesystems.
+
+    private static File computeCacheDirectory() {
+        String path = System.getenv("COURSIER_CACHE");
+
+        if (path == null)
+            path = System.getProperty("coursier.cache");
+
+        String xdgPath = coursierDirectories.projectCacheDir;
+        File xdgDir = new File(xdgPath);
+
+        if (path == null) {
+            if (xdgDir.isDirectory())
+              path = xdgPath;
+        }
+
+        if (path == null) {
+            File coursierDotFile = new File(System.getProperty("user.home") + "/.coursier");
+            if (coursierDotFile.isDirectory())
+                path = System.getProperty("user.home") + "/.coursier/cache/";
+        }
+
+        if (path == null) {
+            path = xdgPath;
+            xdgDir.mkdirs();
+        }
+
+        File coursierCacheDirectory = new File(path).getAbsoluteFile();
+
+        if (coursierCacheDirectory.getName().equals("v1"))
+            coursierCacheDirectory = coursierCacheDirectory.getParentFile();
+
+        return coursierCacheDirectory;
+    }
+
+    public static File cacheDirectory() {
+
+        if (cacheDirectory0 == null)
+            synchronized (lock) {
+                if (cacheDirectory0 == null) {
+                    coursierDirectories = ProjectDirectories.fromProjectName("Coursier");
+                    cacheDirectory0 = computeCacheDirectory();
+                }
+            }
+
+        return cacheDirectory0;
+    }
+}