Awesome
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.)
- Choose the latest version on the MvnRepository.
- From the tabs of dependency management tools, select the one you are using.
- Copy the snippet and add it to the dependency list of your project file (
pom.xml
,build.gradle
, etc.).
Without a dependency management tool
- Choose the latest version on the release page.
- Download the
appdirs-(version).jar
file. - You may also need to download
jna-(version).jar
andjna-platform-(version).jar
. - 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.