Skip to content

Latest commit

 

History

History
164 lines (136 loc) · 7.35 KB

README.md

File metadata and controls

164 lines (136 loc) · 7.35 KB
Raw

AppDirs

Overview

AppDirs is a small java library which provides a path to the platform dependent special folder/directory.

For example, here are the common paths of the folder/directory that is used to store application specific user data on each platform.

On Mac OS X : /Users/<Account>/Library/Application Support/<AppName>
On Windows XP : C:\Documents and Settings\<Account>\Application Data\Local Settings\<AppAuthor>\<AppName>
On Windows 7 : C:\Users\<Account>\AppData\<AppAuthor>\<AppName>
On Unix/Linux : /home/<account>/.local/share/<AppName>

With AppDirs, you can get the path depending on the runtime platform with the following code.

AppDirs appDirs = AppDirsFactory.getInstance();
appDirs.getUserDataDir("<AppName>", null, "<AppAuthor>");

AppDirs is loosely based on a python module with the same name.
Please use the issue tracker for bug reports or suggestions.

Requirements

AppDirs requires Java SE 6 or later and Java Native Access (JNA) as its dependency.

Quickstart

With a dependency management tool (Maven, Gradle, etc.)

  1. Choose the latest version on the MvnRepository.
  2. From the tabs of dependency management tools, select the one you are using.
  3. Copy the snippet and add it to the dependency list of your project file (pom.xml, build.gradle, etc.).

Without a dependency management tool

  1. Choose the latest version on the release page.
  2. Download the appdirs-(version).jar file.
  3. You may also need to download jna-(version).jar and jna-platform-(version).jar.
  4. Put all .jar files into the classpath of your application.

Supported directories

Currently, AppDirs has the following methods.

  • getUserDataDir
  • getUserConfigDir
  • getUserCacheDir
  • getUserLogDir
  • getUserDownloadsDir (since 1.2.2)
  • getSiteDataDir
  • getSiteConfigDir
  • getSharedDir (since 1.1.0)

Here is a test program and the output on some platforms.

import net.harawata.appdirs.AppDirs;
import net.harawata.appdirs.AppDirsFactory;

public class AppDirTest {
  public static void main(String[] args) {
    AppDirs appDirs = AppDirsFactory.getInstance();
    System.out.println("User data dir: " + appDirs.getUserDataDir("myapp", "1.2.3", "harawata"));
    System.out.println("User data dir (roaming): "
      + appDirs.getUserDataDir("myapp", "1.2.3", "harawata", true));
    System.out.println("User config dir: "
      + appDirs.getUserConfigDir("myapp", "1.2.3", "harawata"));
    System.out.println("User config dir (roaming): "
      + appDirs.getUserConfigDir("myapp", "1.2.3", "harawata", true));
    System.out.println("User cache dir: "
      + 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): "
      + appDirs.getSiteDataDir("myapp", "1.2.3", "harawata", true));
    System.out.println("Site config dir: "
      + appDirs.getSiteConfigDir("myapp", "1.2.3", "harawata"));
    System.out.println("Site config dir (multi path): "
      + appDirs.getSiteConfigDir("myapp", "1.2.3", "harawata", true));
    System.out.println("Shared dir: "
      + appDirs.getSharedDir("myapp", "1.2.3", "harawata"));
  }
}

Output on Mac OS X (username = ave)

User data dir: /Users/ave/Library/Application Support/myapp/1.2.3
User data dir (roaming): /Users/ave/Library/Application Support/myapp/1.2.3
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
Site config dir (multi path): /Library/Preferences/myapp/1.2.3
Shared dir: /Users/Shared/Library/Application Support/myapp/1.2.3
  • appAuthor parameter is not used on Mac OS X.
  • roaming and multiPath parameters have no effect on Mac OS X.

Output on Windows 7 (username = ave)

User data dir: C:\Users\ave\AppData\Local\harawata\myapp\1.2.3
User data dir (roaming): C:\Users\ave\AppData\Roaming\harawata\myapp\1.2.3
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
Site config dir (multi path): C:\ProgramData\harawata\myapp\1.2.3
Shared dir: C:\ProgramData\harawata\myapp\1.2.3
  • Internally calls SHGetFolderPath via Java Native Access (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)

User data dir: /home/ave/.local/share/myapp/1.2.3
User data dir (roaming): /home/ave/.local/share/myapp/1.2.3
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
Site config dir (multi path): /etc/xdg/myapp/1.2.3
Shared dir: /srv/myapp/1.2.3
  • AppDirs respects XDG Base Directory Specification if variables are defined.
  • Returns XDG_DATA_HOME for user data directory.
  • Returns XDG_CONFIG_HOME for user config directory.
  • 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.

Bug report, feature request, question

Please create an issue on the tracker.

License

AppDirs is released under Apache Software License 2.0.