Add getUserDownloadsDir()

Fixes #80

README.md

@@ -48,9 +48,10 @@ Currently, __AppDirs__ has the following methods.
 - getUserConfigDir
 - getUserCacheDir
 - getUserLogDir
+- getUserDownloadsDir (since 1.2.2)
 - getSiteDataDir
 - getSiteConfigDir
-- getSharedDir
+- getSharedDir (since 1.1.0)
 
 Here is a test program and the output on some platforms.
 
@@ -72,6 +73,8 @@ public class AppDirTest {
       + appDirs.getUserCacheDir("myapp", "1.2.3", "harawata"));
     System.out.println("User log dir: "
       + appDirs.getUserLogDir("myapp", "1.2.3", "harawata"));
+    System.out.println("User downloads dir: "
+      + appDirs.getUserDownloadsDir("myapp", "1.2.3", "harawata"));
     System.out.println("Site data dir: "
       + appDirs.getSiteDataDir("myapp", "1.2.3", "harawata"));
     System.out.println("Site data dir (multi path): "
@@ -95,6 +98,7 @@ User config dir: /Users/ave/Library/Preferences/myapp/1.2.3
 User config dir (roaming): /Users/ave/Library/Preferences/myapp/1.2.3
 User cache dir: /Users/ave/Library/Caches/myapp/1.2.3
 User log dir: /Users/ave/Library/Logs/myapp/1.2.3
+User downloads dir: /Users/ave/Downloads/myapp/1.2.3
 Site data dir: /Library/Application Support/myapp/1.2.3
 Site data dir (multi path): /Library/Application Support/myapp/1.2.3
 Site config dir: /Library/Preferences/myapp/1.2.3
@@ -112,6 +116,7 @@ User config dir: C:\Users\ave\AppData\Local\harawata\myapp\1.2.3
 User config dir (roaming): C:\Users\ave\AppData\Roaming\harawata\myapp\1.2.3
 User cache dir: C:\Users\ave\AppData\Local\harawata\myapp\Cache\1.2.3
 User log dir: C:\Users\ave\AppData\Local\harawata\myapp\Logs\1.2.3
+User downloads dir: C:\Users\ave\Downloads\harawata\myapp\1.2.3
 Site data dir: C:\ProgramData\harawata\myapp\1.2.3
 Site data dir (multi path): C:\ProgramData\harawata\myapp\1.2.3
 Site config dir: C:\ProgramData\harawata\myapp\1.2.3
@@ -121,6 +126,7 @@ Shared dir: C:\ProgramData\harawata\myapp\1.2.3
 - Internally calls [SHGetFolderPath](http://msdn.microsoft.com/en-us/library/bb762181%28VS.85%29.aspx) via [Java Native Access (JNA)](https://github.com/twall/jna).
  - Returns CSIDL_LOCAL_APPDATA or CSIDL_APPDATA for user directories.
  - Returns CSIDL_COMMON_APPDATA for site directories.
+ - Returns KNOWNFOLDERID `374DE290-123F-4565-9164-39C4925E467B` for user downloads directory. Not supported on pre-Vista OSes.
 - _multiPath_ parameter has no effect on Windows.
 
 ### Output on Linux (username = ave, with no XDG environment variables defined)
@@ -131,6 +137,7 @@ User config dir: /home/ave/.config/myapp/1.2.3
 User config dir (roaming): /home/ave/.config/myapp/1.2.3
 User cache dir: /home/ave/.cache/myapp/1.2.3
 User log dir: /home/ave/.cache/myapp/logs/1.2.3
+User downloads dir: /home/ave/Downloads/myapp/1.2.3
 Site data dir: /usr/local/share/myapp/1.2.3
 Site data dir (multi path): /usr/local/share/myapp/1.2.3:/usr/share/myapp/1.2.3
 Site config dir: /etc/xdg/myapp/1.2.3
@@ -144,6 +151,7 @@ Shared dir: /srv/myapp/1.2.3
  - Returns XDG_CACHE_HOME for user cache directory.
  - Returns XDG_DATA_DIRS for site data directory.
  - Returns XDG_CONFIG_DIRS for site config directory.
+ - Returns XDG_DOWNLOAD_DIR for user downloads directory.
 - _appAuthor_ parameter is not used on Unix/Linux.
 - _roaming_ parameter has no effect on Unix/Linux.
 

src/main/java/net/harawata/appdirs/AppDirs.java

@@ -53,6 +53,9 @@ public abstract String getSiteConfigDir(String appName, String appVersion,
   public abstract String getUserLogDir(String appName, String appVersion,
       String appAuthor);
 
+  public abstract String getUserDownloadsDir(String appName, String appVersion,
+      String appAuthor);
+
   public abstract String getSharedDir(String appName, String appVersion,
       String appAuthor);
 

src/main/java/net/harawata/appdirs/impl/MacOSXAppDirs.java

@@ -52,6 +52,12 @@ public String getUserLogDir(String appName, String appVersion,
     return buildPath(home(), "/Library/Logs", appName, appVersion);
   }
 
+  @Override
+  public String getUserDownloadsDir(String appName, String appVersion,
+      String appAuthor) {
+    return buildPath(home(), "/Downloads", appName, appVersion);
+  }
+
   @Override
   public String getSharedDir(String appName, String appVersion,
       String appAuthor) {

src/main/java/net/harawata/appdirs/impl/ShellFolderResolver.java

@@ -51,6 +51,8 @@ private GUID convertFolderIdToGuid(FolderId folderId) {
       return KnownFolders.FOLDERID_LocalAppData;
     case COMMON_APPDATA:
       return KnownFolders.FOLDERID_ProgramData;
+    case DOWNLOADS:
+      return KnownFolders.FOLDERID_Downloads;
     default:
       throw new AppDirsException(
           "Unknown folder ID " + folderId + " was specified.");

src/main/java/net/harawata/appdirs/impl/UnixAppDirs.java

@@ -29,6 +29,8 @@ public class UnixAppDirs extends AppDirs {
 
   public static final String XDG_DATA_HOME = "XDG_DATA_HOME";
 
+  public static final String XDG_DOWNLOAD_DIR = "XDG_DOWNLOAD_DIR";
+
   protected final Map<String, String> sysEnv;
 
   public String getUserDataDir(String appName, String appVersion,
@@ -98,6 +100,13 @@ public String getUserLogDir(String appName, String appVersion,
     return buildPath(dir, appName, "/logs", appVersion);
   }
 
+  @Override
+  public String getUserDownloadsDir(String appName, String appVersion,
+      String appAuthor) {
+    String dir = getOrDefault(XDG_DOWNLOAD_DIR, buildPath(home(), "/Downloads"));
+    return buildPath(dir, appName, appVersion);
+  }
+
   @Override
   public String getSharedDir(String appName, String appVersion,
       String appAuthor) {

src/main/java/net/harawata/appdirs/impl/WindowsAppDirs.java

@@ -20,7 +20,7 @@ public class WindowsAppDirs extends AppDirs {
   private WindowsFolderResolver folderResolver;
 
   public enum FolderId {
-    APPDATA, LOCAL_APPDATA, COMMON_APPDATA;
+    APPDATA, LOCAL_APPDATA, COMMON_APPDATA, DOWNLOADS;
   }
 
   public WindowsAppDirs(WindowsFolderResolver folderResolver) {
@@ -61,6 +61,12 @@ public String getUserLogDir(String appName, String appVersion,
         appVersion);
   }
 
+  @Override
+  public String getUserDownloadsDir(String appName, String appVersion,
+      String appAuthor) {
+    return buildPath(getDownloads(), appAuthor, appName, appVersion);
+  }
+
   @Override
   public String getSharedDir(String appName, String appVersion,
       String appAuthor) {
@@ -78,4 +84,8 @@ protected String getLocalAppData() {
   protected String getCommonAppData() {
     return folderResolver.resolveFolder(FolderId.COMMON_APPDATA);
   }
+
+  protected String getDownloads() {
+    return folderResolver.resolveFolder(FolderId.DOWNLOADS);
+  }
 }

src/test/java/net/harawata/appdirs/impl/MacOSXAppDirTest.java

@@ -104,6 +104,18 @@ public void testGetUserLogDir() {
         appDirs.getUserLogDir("myapp", "1.2.3", "harawata"));
   }
 
+  @Test
+  public void testGetUserDownloadsDir() {
+    assertEquals("/Users/somebody/Downloads",
+        appDirs.getUserDownloadsDir(null, null, null));
+    assertEquals("/Users/somebody/Downloads/myapp",
+        appDirs.getUserDownloadsDir("myapp", null, null));
+    assertEquals("/Users/somebody/Downloads/myapp/1.2.3",
+        appDirs.getUserDownloadsDir("myapp", "1.2.3", null));
+    assertEquals("/Users/somebody/Downloads/myapp/1.2.3",
+        appDirs.getUserDownloadsDir("myapp", "1.2.3", "harawata"));
+  }
+
   @Test
   public void testSiteDataDir() {
     assertEquals("/Library/Application Support",

src/test/java/net/harawata/appdirs/impl/MockWindowsFolderResolver.java

@@ -26,6 +26,8 @@ public String resolveFolder(FolderId folderId) {
       return "C:\\Documents and Settings\\harawata\\Local Settings\\Application Data";
     case COMMON_APPDATA:
       return "C:\\Documents and Settings\\All Users\\Application Data";
+    case DOWNLOADS:
+      return "C:\\Users\\ave\\Downloads";
     default:
       throw new AppDirsException(
           "Unknown folder ID " + folderId + " was specified.");

src/test/java/net/harawata/appdirs/impl/UnixAppDirTest.java

@@ -107,6 +107,19 @@ public void testGetUserLogDir() {
         appDirs.getUserLogDir("myapp", "1.2.3", "harawata"));
   }
 
+  @Test
+  public void testGetUserDownloadsDir() {
+    AppDirs appDirs = getAppDirs();
+    assertEquals("/home/somebody/Downloads",
+        appDirs.getUserDownloadsDir(null, null, null));
+    assertEquals("/home/somebody/Downloads/myapp",
+        appDirs.getUserDownloadsDir("myapp", null, null));
+    assertEquals("/home/somebody/Downloads/myapp/1.2.3",
+        appDirs.getUserDownloadsDir("myapp", "1.2.3", null));
+    assertEquals("/home/somebody/Downloads/myapp/1.2.3",
+        appDirs.getUserDownloadsDir("myapp", "1.2.3", "harawata"));
+  }
+
   @Test
   public void testSiteDataDir() {
     AppDirs appDirs = getAppDirs();

src/test/java/net/harawata/appdirs/impl/WindowsAppDirTest.java

@@ -122,6 +122,21 @@ public void testGetUserLogDir() {
         appDirs.getUserLogDir("myapp", "1.2.3", "harawata"));
   }
 
+  @Test
+  public void testGetUserDownloadsDir() {
+    assertEquals("C:\\Users\\ave\\Downloads",
+        appDirs.getUserDownloadsDir(null, null, null));
+    assertEquals(
+        "C:\\Users\\ave\\Downloads\\myapp",
+        appDirs.getUserDownloadsDir("myapp", null, null));
+    assertEquals(
+        "C:\\Users\\ave\\Downloads\\myapp\\1.2.3",
+        appDirs.getUserDownloadsDir("myapp", "1.2.3", null));
+    assertEquals(
+        "C:\\Users\\ave\\Downloads\\harawata\\myapp\\1.2.3",
+        appDirs.getUserDownloadsDir("myapp", "1.2.3", "harawata"));
+  }
+
   @Test
   public void testSiteDataDir() {
     assertEquals("C:\\Documents and Settings\\All Users\\Application Data",
@@ -175,7 +190,7 @@ public void testSiteConfigDir() {
   }
 
   @Test
-  public void testgetSharedDir() {
+  public void testGetSharedDir() {
     assertEquals("C:\\Documents and Settings\\All Users\\Application Data",
         appDirs.getSharedDir(null, null, null));
     assertEquals(