diff --git a/README-io.github.soc.md b/README-io.github.soc.md new file mode 100644 index 0000000..cbf022e --- /dev/null +++ b/README-io.github.soc.md @@ -0,0 +1,274 @@ +[![Maven Central](https://img.shields.io/maven-central/v/io.github.soc/directories.svg)](https://search.maven.org/#search|gav|1|g%3A%22io.github.soc%22%20AND%20a%3A%22directories%22) +[![API documentation](http://javadoc.io/badge/io.github.soc/directories.svg)](http://javadoc.io/doc/io.github.soc/directories) +![actively developed](https://img.shields.io/badge/maintenance-actively--developed-brightgreen.svg) +[![TravisCI status](https://img.shields.io/travis/dirs-dev/directories-jvm/master.svg?label=Linux%20build)](https://travis-ci.org/dirs-dev/directories-jvm) +[![AppVeyor status](https://img.shields.io/appveyor/ci/soc/directories-jvm/master.svg?label=Windows%20build)](https://ci.appveyor.com/project/soc/directories-jvm/branch/master) +[![License: MPL-2.0](https://img.shields.io/github/license/dirs-dev/directories-jvm.svg)](LICENSE) + +# Directories (legacy `soc.github.io` artefact) + +_Please refer to [README](README.md) for the documentation and artefact coordinates of the `dev.dirs` artefact, which is the new main branch of development._ + + +## Introduction + +- a tiny library (12kB) with a minimal API +- that provides the platform-specific, user-accessible locations +- for retrieving and storing configuration, cache and other data +- on Linux, Windows (≥ 7), macOS and BSD + +The library provides the location of these directories by leveraging the mechanisms defined by +- the [XDG base directory](https://standards.freedesktop.org/basedir-spec/basedir-spec-latest.html) and + the [XDG user directory](https://www.freedesktop.org/wiki/Software/xdg-user-dirs/) specifications on Linux +- the [Known Folder](https://msdn.microsoft.com/en-us/library/windows/desktop/dd378457.aspx) API on Windows +- the [Standard Directories](https://developer.apple.com/library/content/documentation/FileManagement/Conceptual/FileSystemProgrammingGuide/FileSystemOverview/FileSystemOverview.html#//apple_ref/doc/uid/TP40010672-CH2-SW6) + guidelines on macOS + +## Platforms + +This library is written in Java, and runs on the JVM (≥ 6). + +A version of this library implemented in Rust is provided by [directories-rs](https://github.com/dirs-dev/directories-rs). + +## Usage + +#### Dependency + +Add the library as a dependency to your project: + +##### Maven +```xml + + io.github.soc + directories + 12 + +``` +##### Gradle +```groovy +compile 'io.github.soc:directories:12' +``` + +##### SBT +```scala +"io.github.soc" % "directories" % "12" +``` + +The library itself is built against Java 6 to allow for the widest possible usage scenarios. +It can be used on any Java version >= 6. + +#### Example + +Library run by user Alice: + +```java +import io.github.soc.directories.ProjectDirectories; +import io.github.soc.directories.BaseDirectories; +import io.github.soc.directories.UserDirectories; + +ProjectDirectories myProjDirs = ProjectDirectories.from("com", "Foo Corp", "Bar App"); +myProjDirs.configDir; +// Lin: /home/alice/.config/barapp +// Mac: /Users/Alice/Library/Preferences/com.Foo-Corp.Bar-App +// Win: C:\Users\Alice\AppData\Roaming\Foo Corp\Bar App\config + +BaseDirectories baseDirs = BaseDirectories.get(); +baseDirs.executableDir; +// Lin: /home/alice/.local/bin +// Mac: null +// Win: null + +UserDirectories userDirs = UserDirectories.get(); +userDirs.audioDir; +// Lin: /home/alice/Music +// Mac: /Users/Alice/Music +// Win: C:\Users\Alice\Music +``` + +## Design Goals + +- The _directories_ library is designed to provide an accurate snapshot of the system's state at + the point of invocation of `BaseDirectories.get()`, `UserDirectories.get()` or + `ProjectDirectories.from()`. Subsequent changes to the state of the system are not reflected in + instances created prior to such a change. +- This library does not create directories or check for their existence. The library only provides + information on what the path to a certain directory _should_ be. How this information is used is + a decision that developers need to make based on the requirements of each individual application. +- This library is intentionally focused on providing information on user-writable directories only. + There is no discernible benefit in returning a path that points to a user-level, writable + directory on one operating system, but a system-level, read-only directory on another, that would + outweigh the confusion and unexpected failures such an approach would cause. + - `executableDir` is specified to provide the path to a user-writable directory for binaries.
+ As such a directory only commonly exists on Linux, it returns `null` on macOS and Windows. + - `fontDir` is specified to provide the path to a user-writable directory for fonts.
+ As such a directory only exists on Linux and macOS, it returns `null` Windows. + - `runtimeDir` is specified to provide the path to a directory for non-essential runtime data. + It is required that this directory is created when the user logs in, is only accessible by the + user itself, is deleted when the user logs out, and supports all filesystem features of the + operating system.
+ As such a directory only commonly exists on Linux, it returns `null` on macOS and Windows. + +## Features + +### `BaseDirectories` + +The intended use-case for `BaseDirectories` is to query the paths of user-invisible standard directories +that have been defined according to the conventions of the operating system the library is running on. + +If you want to compute the location of cache, config or data folders for your own application or project, use `ProjectDirectories` instead. + +| Field name | Value on Linux / BSD | Value on Windows | Value on macOS | +| --------------- | ---------------------------------------------------------------- | --------------------------------- | ----------------------------------- | +| `homeDir` | `$HOME` | `{FOLDERID_UserProfile}` | `$HOME` | +| `cacheDir` | `$XDG_CACHE_HOME` or `$HOME`/.cache | `{FOLDERID_LocalApplicationData}` | `$HOME`/Library/Caches | +| `configDir` | `$XDG_CONFIG_HOME` or `$HOME`/.config | `{FOLDERID_ApplicationData}` | `$HOME`/Library/Preferences | +| `dataDir` | `$XDG_DATA_HOME` or `$HOME`/.local/share | `{FOLDERID_ApplicationData}` | `$HOME`/Library/Application Support | +| `dataLocalDir` | `$XDG_DATA_HOME` or `$HOME`/.local/share | `{FOLDERID_LocalApplicationData}` | `$HOME`/Library/Application Support | +| `executableDir` | `$XDG_BIN_HOME` or `$XDG_DATA_HOME`/../bin or `$HOME`/.local/bin | `null` | `null` | +| `runtimeDir` | `$XDG_RUNTIME_DIR` or `null` | `null` | `null` | + +### `UserDirectories` + +The intended use-case for `UserDirectories` is to query the paths of user-facing standard directories +that have been defined according to the conventions of the operating system the library is running on. + +| Field name | Value on Linux / BSD | Value on Windows | Value on macOS | +| ------------- | ---------------------------------------------------- | ------------------------ | --------------------- | +| `homeDir` | `$HOME` | `{FOLDERID_UserProfile}` | `$HOME` | +| `audioDir` | `XDG_MUSIC_DIR` | `{FOLDERID_Music}` | `$HOME`/Music | +| `desktopDir` | `XDG_DESKTOP_DIR` | `{FOLDERID_Desktop}` | `$HOME`/Desktop | +| `documentDir` | `XDG_DOCUMENTS_DIR` | `{FOLDERID_Documents}` | `$HOME`/Documents | +| `downloadDir` | `XDG_DOWNLOAD_DIR` | `{FOLDERID_Downloads}` | `$HOME`/Downloads | +| `fontDir` | `$XDG_DATA_HOME`/fonts or `$HOME`/.local/share/fonts | `null` | `$HOME`/Library/Fonts | +| `pictureDir` | `XDG_PICTURES_DIR` | `{FOLDERID_Pictures}` | `$HOME`/Pictures | +| `publicDir` | `XDG_PUBLICSHARE_DIR` | `{FOLDERID_Public}` | `$HOME`/Public | +| `templateDir` | `XDG_TEMPLATES_DIR` | `{FOLDERID_Templates}` | `null` | +| `videoDir` | `XDG_VIDEOS_DIR` | `{FOLDERID_Videos}` | `$HOME`/Movies | + +### `ProjectDirectories` + +The intended use-case for `ProjectDirectories` is to compute the location of cache, config or data folders for your own application or project, +which are derived from the standard directories. + +| Field name | Value on Linux / BSD | Value on Windows | Value on macOS | +| -------------- | -------------------------------------------------------------------------- | -------------------------------------------------------- | ---------------------------------------------------- | +| `cacheDir` | `$XDG_CACHE_HOME`/`` or `$HOME`/.cache/`` | `{FOLDERID_LocalApplicationData}`/``/cache | `$HOME`/Library/Caches/`` | +| `configDir` | `$XDG_CONFIG_HOME`/`` or `$HOME`/.config/`` | `{FOLDERID_ApplicationData}`/``/config | `$HOME`/Library/Preferences/`` | +| `dataDir` | `$XDG_DATA_HOME`/`` or `$HOME`/.local/share/`` | `{FOLDERID_ApplicationData}`/``/data | `$HOME`/Library/Application Support/`` | +| `dataLocalDir` | `$XDG_DATA_HOME`/`` or `$HOME`/.local/share/`` | `{FOLDERID_LocalApplicationData}`/``/data | `$HOME`/Library/Application Support/`` | +| `runtimeDir` | `$XDG_RUNTIME_DIR`/`` | `null` | `null` | + +The specific value of `` is computed by the + + ProjectDirectories.from(String qualifier, + String organization, + String application) + +method and varies across operating systems. As an example, calling + + ProjectDirectories.from("org" /*qualifier*/, + "Baz Corp" /*organization*/, + "Foo Bar-App" /*application*/) + +results in the following values: + + +| Value on Linux | Value on Windows | Value on macOS | +| -------------- | ------------------------ | ---------------------------- | +| `"foobar-app"` | `"Baz Corp/Foo Bar-App"` | `"org.Baz-Corp.Foo-Bar-App"` | + +The `ProjectDirectories.fromPath` method allows the creation of `ProjectDirectories` instances directly from a project path. +This argument is used verbatim and is not adapted to operating system standards. +The use of `ProjectDirectories.fromPath` is strongly discouraged, as its results will not follow operating system standards on at least two of three platforms. + +## Versioning + +The version number of this library consists of a whole number, which is incremented with each release. +(Think semantic versioning without _minor_ and _patch_ versions.) + +## Changelog + +### 12 – current stable `soc.github.io:directories` release + +- Adjust library to deal with breaking changes in Java caused by CVE-2019-2958 (see JDK-8221858). Thanks @alexarchambault! +- Support Solaris. Thanks @tomasjura! +- Add reflect-config.json file for GraalVM native-image. Thanks @alexarchambault! + +### 11 + +- Throw RuntimeExceptions instead of catching IOExceptions and returning null if directory lookup on Windows fails. + This should make it easier to diagnose issues. +- Add Automatic-Module-Name to manifest file, enabling support for Java 9 modules. +- Some small cleanups. + +### 10 + +- Full Windows support: `downloadDir` and `publicDir` are now supported. +- Improved speed on Windows and Linux. +- Changed static fields in `BaseDirectories` and `UserDirectories` to instance fields. + Instances can be created with `BaseDirectories.get()` and `UserDirectories.get()`. + +### 9 + +- Windows: + - Fixed the implementation of `audioDir`, `desktopDir`, `documentDir`, `pictureDir` and `videoDir`. + - Clarified that `downloadDir` and `publicDir` return `null` on Windows, as the `SpecialFolder` enumeration lacks entries for these values. + +### 8 + +- Windows: + - Fixed incorrect `ProjectDirectories` paths for `cacheDir`, `configDir` and `dataDir`. +- Linux: + - Fixed incorrect `ProjectDirectories` paths for `cacheDir`, `configDir`, `dataDir` and `dataLocalDir` if XDG environment variables are set. + - Fixed incorrect `UserDirectories` paths for `fontDir` if XDG environment variables are set. + +### 7 + +- Split `BaseDirectories` into `BaseDirectories` (cache, config, ...) and `UserDirectories` (audio, + video, ...). +- Fields of `BaseDirectories` and `UserDirectories` are now public. +- Add substantial amounts of documentation. +- The fields of `UserDirectories` are now `null` if no values can be retrieved from `xdg-user-dirs`, + instead of falling back on hard-coded values. +- A user's home directory is now retrieved with `System.getProperty("user.home")` instead of + `System.getenv("HOME")`, improving reliability and portability. +- Changes to some values of `BaseDirectories` and `ProjectDirectories`: + +| Method | Old value | New Value | +| --------------------------------- | ------------------------------------------------------- | ------------------------------------------------------------ | +| `BaseDirectories.cacheDir` | `{SpecialFolder.LocalApplicationData}`/cache | `{SpecialFolder.LocalApplicationData}` | +| `ProjectDirectories#dataDir` | `{SpecialFolder.ApplicationData}`/`` | `{SpecialFolder.ApplicationData}`/``/data | +| `ProjectDirectories#dataLocalDir` | `{SpecialFolder.LocalApplicationData}`/`` | `{SpecialFolder.LocalApplicationData}`/``/data | + +### 6 + +- More consistent and intuitive naming scheme (all names are singular now): + +| Old name | New name | +| ----------------------- | --------------------- | +| `dataDir` | `dataLocalDir` | +| `dataRoamingDir` | `dataDir` | +| `executablesDir` | `executableDir` | +| `documentsDir` | `documentDir` | +| `downloadsDir` | `downloadDir` | +| `fontsDir` | `fontDir` | +| `musicDir` | `audioDir` | +| `picturesDir` | `pictureDir` | +| `templatesDir` | `templateDir` | +| `videosDir` | `videoDir` | + +- `ProjectDirectories` factory methods have been overhauled and replaced with a single `from(String qualifier, String organization, String project)` method. + +- Changes to the selection of local/roaming data directories: + - `dataDir` selects the roaming data directory on Windows (no change on Linux or macOS). + - `dataLocalDir` selects the local data directory on Windows (no change on Linux or macOS). + +- `ProjectDirectories` received a `runtimeDir` field. + +- `ProjectDirectories` field names dropped the `project` prefix. + +- Changes to the directory for executables: + - Support for `executableDir` has been dropped on macOS. + - The value of `executableDir` considers `$XDG_BIN_HOME` now, before falling back to `$XDG_DATA_HOME/../bin` and `$HOME/.local/bin`. + +### 5-1 – Unpublished beta releases diff --git a/README.md b/README.md index ef2dc0a..d59e7f0 100644 --- a/README.md +++ b/README.md @@ -1,5 +1,5 @@ -[![Maven Central](https://img.shields.io/maven-central/v/io.github.soc/directories.svg)](https://search.maven.org/#search|gav|1|g%3A%22io.github.soc%22%20AND%20a%3A%22directories%22) -[![API documentation](http://javadoc.io/badge/io.github.soc/directories.svg)](http://javadoc.io/doc/io.github.soc/directories) +[![Maven Central](https://img.shields.io/maven-central/v/dev.dirs/directories.svg)](https://search.maven.org/#search|gav|1|g%3A%22dev.dirs%22%20AND%20a%3A%22directories%22) +[![API documentation](http://javadoc.io/badge/dev.dirs/directories.svg)](http://javadoc.io/doc/dev.dirs/directories) ![actively developed](https://img.shields.io/badge/maintenance-actively--developed-brightgreen.svg) [![TravisCI status](https://img.shields.io/travis/dirs-dev/directories-jvm/master.svg?label=Linux%20build)](https://travis-ci.org/dirs-dev/directories-jvm) [![AppVeyor status](https://img.shields.io/appveyor/ci/soc/directories-jvm/master.svg?label=Windows%20build)](https://ci.appveyor.com/project/soc/directories-jvm/branch/master) @@ -25,7 +25,7 @@ The library provides the location of these directories by leveraging the mechani This library is written in Java, and runs on the JVM (≥ 6). -A version of this library implemented in Rust is provided by [directories-rs](https://github.com/soc/directories-rs). +A version of this library implemented in Rust is provided by [directories-rs](https://github.com/dirs-dev/directories-rs). ## Usage @@ -36,19 +36,19 @@ Add the library as a dependency to your project: ##### Maven ```xml - io.github.soc + dev.dirs directories - 12 + 20 ``` ##### Gradle ```groovy -compile 'io.github.soc:directories:12' +compile 'dev.dirs:directories:20' ``` ##### SBT ```scala -"io.github.soc" % "directories" % "12" +"dev.dirs" % "directories" % "20" ``` The library itself is built against Java 6 to allow for the widest possible usage scenarios. @@ -59,9 +59,9 @@ It can be used on any Java version >= 6. Library run by user Alice: ```java -import io.github.soc.directories.ProjectDirectories; -import io.github.soc.directories.BaseDirectories; -import io.github.soc.directories.UserDirectories; +import dev.dirs.ProjectDirectories; +import dev.dirs.BaseDirectories; +import dev.dirs.UserDirectories; ProjectDirectories myProjDirs = ProjectDirectories.from("com", "Foo Corp", "Bar App"); myProjDirs.configDir; @@ -114,14 +114,15 @@ that have been defined according to the conventions of the operating system the If you want to compute the location of cache, config or data folders for your own application or project, use `ProjectDirectories` instead. -| Field name | Value on Linux / BSD | Value on Windows | Value on macOS | +| Field name | Value on Linux / BSD / Solaris | Value on Windows | Value on macOS | | --------------- | ---------------------------------------------------------------- | --------------------------------- | ----------------------------------- | | `homeDir` | `$HOME` | `{FOLDERID_UserProfile}` | `$HOME` | | `cacheDir` | `$XDG_CACHE_HOME` or `$HOME`/.cache | `{FOLDERID_LocalApplicationData}` | `$HOME`/Library/Caches | -| `configDir` | `$XDG_CONFIG_HOME` or `$HOME`/.config | `{FOLDERID_ApplicationData}` | `$HOME`/Library/Preferences | +| `configDir` | `$XDG_CONFIG_HOME` or `$HOME`/.config | `{FOLDERID_ApplicationData}` | `$HOME`/Library/Application Support | | `dataDir` | `$XDG_DATA_HOME` or `$HOME`/.local/share | `{FOLDERID_ApplicationData}` | `$HOME`/Library/Application Support | | `dataLocalDir` | `$XDG_DATA_HOME` or `$HOME`/.local/share | `{FOLDERID_LocalApplicationData}` | `$HOME`/Library/Application Support | | `executableDir` | `$XDG_BIN_HOME` or `$XDG_DATA_HOME`/../bin or `$HOME`/.local/bin | `null` | `null` | +| `preferencesDir`| `$XDG_CONFIG_HOME` or `$HOME`/.config | `{FOLDERID_ApplicationData}` | `$HOME`/Library/Preferences | | `runtimeDir` | `$XDG_RUNTIME_DIR` or `null` | `null` | `null` | ### `UserDirectories` @@ -147,13 +148,14 @@ that have been defined according to the conventions of the operating system the The intended use-case for `ProjectDirectories` is to compute the location of cache, config or data folders for your own application or project, which are derived from the standard directories. -| Field name | Value on Linux / BSD | Value on Windows | Value on macOS | -| -------------- | -------------------------------------------------------------------------- | -------------------------------------------------------- | ---------------------------------------------------- | -| `cacheDir` | `$XDG_CACHE_HOME`/`` or `$HOME`/.cache/`` | `{FOLDERID_LocalApplicationData}`/``/cache | `$HOME`/Library/Caches/`` | -| `configDir` | `$XDG_CONFIG_HOME`/`` or `$HOME`/.config/`` | `{FOLDERID_ApplicationData}`/``/config | `$HOME`/Library/Preferences/`` | -| `dataDir` | `$XDG_DATA_HOME`/`` or `$HOME`/.local/share/`` | `{FOLDERID_ApplicationData}`/``/data | `$HOME`/Library/Application Support/`` | -| `dataLocalDir` | `$XDG_DATA_HOME`/`` or `$HOME`/.local/share/`` | `{FOLDERID_LocalApplicationData}`/``/data | `$HOME`/Library/Application Support/`` | -| `runtimeDir` | `$XDG_RUNTIME_DIR`/`` | `null` | `null` | +| Field name | Value on Linux / BSD | Value on Windows | Value on macOS | +| --------------- | -------------------------------------------------------------------------- | -------------------------------------------------------- | ---------------------------------------------------- | +| `cacheDir` | `$XDG_CACHE_HOME`/`` or `$HOME`/.cache/`` | `{FOLDERID_LocalApplicationData}`/``/cache | `$HOME`/Library/Caches/`` | +| `configDir` | `$XDG_CONFIG_HOME`/`` or `$HOME`/.config/`` | `{FOLDERID_ApplicationData}`/``/config | `$HOME`/Library/Application Support/`` | +| `dataDir` | `$XDG_DATA_HOME`/`` or `$HOME`/.local/share/`` | `{FOLDERID_ApplicationData}`/``/data | `$HOME`/Library/Application Support/`` | +| `dataLocalDir` | `$XDG_DATA_HOME`/`` or `$HOME`/.local/share/`` | `{FOLDERID_LocalApplicationData}`/``/data | `$HOME`/Library/Application Support/`` | +| `preferencesDir`| `$XDG_CONFIG_HOME`/`` or `$HOME`/.config/`` | `{FOLDERID_ApplicationData}`/``/config | `$HOME`/Library/Preferences/`` | +| `runtimeDir` | `$XDG_RUNTIME_DIR`/`` | `null` | `null` | The specific value of `` is computed by the @@ -185,7 +187,25 @@ The version number of this library consists of a whole number, which is incremen ## Changelog -### 12 – current stable version +### 20 – current stable `dev.dirs:directories` release + +- **BREAKING CHANGE** The behavior of `configDir` on macOS has been adjusted: + - The existing `BaseDirectories#configDir` has been changed to return the `Application Support` directory, + as suggested by Apple documentation. + - The newly added `BaseDirectories#preferencesDir` returns the `Preferences` directory now, + which – according to Apple documentation – shall only be used to store .plist files. + - The behavior of `configDir` on non-macOS platforms has not been changed. + – `preferencesDir` behaves identical to `configDir` on non-macOS platforms. + - The behavior of `ProjectDirectories` has been adjusted accordingly. + - If you have used `BaseDirectories#configDir` or `ProjectDirectories#configDir` to store files, + it may be necessary to write code that migrates the files to the new location. + (Alternative: change usages of `configDir` to `preferencesDir` to keep the old behavior.) + +### 19-13 – Reserved for bug fixes on `soc.github.io:directories` + +### 12 – current stable legacy `soc.github.io:directories` release + +_Please refer to [README-io.github.soc.md](README-io.github.soc.md) for the documentation and artefact coordinates._ - Adjust library to deal with breaking changes in Java caused by CVE-2019-2958 (see JDK-8221858). Thanks @alexarchambault! - Support Solaris. Thanks @tomasjura! @@ -267,3 +287,6 @@ The version number of this library consists of a whole number, which is incremen - Changes to the directory for executables: - Support for `executableDir` has been dropped on macOS. - The value of `executableDir` considers `$XDG_BIN_HOME` now, before falling back to `$XDG_DATA_HOME/../bin` and `$HOME/.local/bin`. + +### 5-1 – Unpublished beta releases + \ No newline at end of file diff --git a/build.sbt b/build.sbt index 1513e69..dea671f 100644 --- a/build.sbt +++ b/build.sbt @@ -1,11 +1,11 @@ lazy val root = (project in file(".")) .settings( name := "directories", - organization := "io.github.soc", + organization := "dev.dirs", managedScalaInstance := false, crossPaths := false, - version := "12", - homepage := Some(url("https://github.com/soc/directories-jvm")), + version := "20", + homepage := Some(url("https://github.com/dirs-dev/directories-jvm")), licenses := Seq("Mozilla Public License 2.0" -> url("https://opensource.org/licenses/MPL-2.0")), fork := true, // The javaHome setting can be removed if building against the latest installed version of Java is acceptable. @@ -25,14 +25,14 @@ lazy val root = (project in file(".")) packageOptions in (Compile, packageBin) += { import java.util.jar.{Attributes, Manifest} val manifest = new Manifest - manifest.getMainAttributes.put(new Attributes.Name("Automatic-Module-Name"), "io.github.soc.directories") + manifest.getMainAttributes.put(new Attributes.Name("Automatic-Module-Name"), "dev.dirs.directories") Package.JarManifest(manifest) }, pomIncludeRepository := { _ => false }, pomExtra := - git@github.com:soc/directories-jvm.git - scm:git:git@github.com:soc/directories-jvm.git + git@github.com:dirs-dev/directories-jvm.git + scm:git:git@github.com:dirs-dev/directories-jvm.git diff --git a/src/main/java/io/github/soc/directories/BaseDirectories.java b/src/main/java/dev/dirs/BaseDirectories.java similarity index 62% rename from src/main/java/io/github/soc/directories/BaseDirectories.java rename to src/main/java/dev/dirs/BaseDirectories.java index c36acdc..b6738cf 100644 --- a/src/main/java/io/github/soc/directories/BaseDirectories.java +++ b/src/main/java/dev/dirs/BaseDirectories.java @@ -1,6 +1,6 @@ -package io.github.soc.directories; +package dev.dirs; -import static io.github.soc.directories.Util.*; +import static dev.dirs.Util.*; /** {@code BaseDirectories} provides paths of user-invisible standard directories, following the conventions of the operating system the library is running on. *

@@ -73,7 +73,7 @@ public final class BaseDirectories { */ public final String cacheDir; - /** Returns the path to the user's config directory. + /** Returns the path to the user's configuration directory. *

* * @@ -88,8 +88,8 @@ public final class BaseDirectories { * * * - * - * + * + * * * * @@ -181,6 +181,33 @@ public final class BaseDirectories { */ public final String executableDir; + /** Returns the path to the user's preferences directory. + *

+ *
macOS{@code $HOME}/Library/Preferences/Users/Alice/Library/Preferences{@code $HOME}/Library/Application Support/Users/Alice/Library/Application Support
Windows
+ * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + *
PlatformValueExample
Linux/BSD{@code $XDG_CONFIG_HOME} or {@code $HOME}/.config/home/alice/.config
macOS{@code $HOME}/Library/Preferences/Users/Alice/Library/Preferences
Windows{@code {FOLDERID_RoamingAppData}}C:\Users\Alice\AppData\Roaming
+ */ + public final String preferencesDir; + /** Returns the path to the user's runtime directory. *

* @@ -224,32 +251,35 @@ private BaseDirectories() { case LIN: case BSD: case SOLARIS: - homeDir = System.getProperty("user.home"); - cacheDir = defaultIfNullOrEmpty(System.getenv("XDG_CACHE_HOME"), homeDir, "/.cache"); - configDir = defaultIfNullOrEmpty(System.getenv("XDG_CONFIG_HOME"), homeDir, "/.config"); - dataDir = defaultIfNullOrEmpty(System.getenv("XDG_DATA_HOME"), homeDir, "/.local/share"); - dataLocalDir = dataDir; - executableDir = linuxExecutableDir(homeDir, dataDir); - runtimeDir = linuxRuntimeDir(null); + homeDir = System.getProperty("user.home"); + cacheDir = defaultIfNullOrEmpty(System.getenv("XDG_CACHE_HOME"), homeDir, "/.cache"); + configDir = defaultIfNullOrEmpty(System.getenv("XDG_CONFIG_HOME"), homeDir, "/.config"); + dataDir = defaultIfNullOrEmpty(System.getenv("XDG_DATA_HOME"), homeDir, "/.local/share"); + dataLocalDir = dataDir; + executableDir = linuxExecutableDir(homeDir, dataDir); + preferencesDir = configDir; + runtimeDir = linuxRuntimeDir(null); break; case MAC: - homeDir = System.getProperty("user.home"); - cacheDir = homeDir + "/Library/Caches/"; - configDir = homeDir + "/Library/Preferences/"; - dataDir = homeDir + "/Library/Application Support/"; - dataLocalDir = dataDir; - executableDir = null; - runtimeDir = null; + homeDir = System.getProperty("user.home"); + cacheDir = homeDir + "/Library/Caches/"; + configDir = homeDir + "/Library/Application Support/"; + dataDir = configDir; + dataLocalDir = configDir; + executableDir = null; + preferencesDir = homeDir + "/Library/Preferences/"; + runtimeDir = null; break; case WIN: String[] winDirs = getWinDirs("5E6C858F-0E22-4760-9AFE-EA3317B67173", "3EB685DB-65F9-4CF6-A03A-E3EF65729F3D", "F1B32785-6FBA-4FCF-9D55-7B8E7F157091"); - homeDir = winDirs[0]; - dataDir = winDirs[1]; - dataLocalDir = winDirs[2]; - configDir = dataDir; - cacheDir = dataLocalDir; - executableDir = null; - runtimeDir = null; + homeDir = winDirs[0]; + dataDir = winDirs[1]; + dataLocalDir = winDirs[2]; + configDir = dataDir; + cacheDir = dataLocalDir; + executableDir = null; + preferencesDir = configDir; + runtimeDir = null; break; default: throw new UnsupportedOperatingSystemException("Base directories are not supported on " + operatingSystemName); @@ -259,13 +289,14 @@ private BaseDirectories() { @Override public String toString() { return "BaseDirectories (" + operatingSystemName + "):\n" + - " homeDir = '" + homeDir + "'\n" + - " cacheDir = '" + cacheDir + "'\n" + - " configDir = '" + configDir + "'\n" + - " dataDir = '" + dataDir + "'\n" + - " dataLocalDir = '" + dataLocalDir + "'\n" + - " executableDir = '" + executableDir + "'\n" + - " runtimeDir = '" + runtimeDir + "'\n"; + " homeDir = '" + homeDir + "'\n" + + " cacheDir = '" + cacheDir + "'\n" + + " configDir = '" + configDir + "'\n" + + " dataDir = '" + dataDir + "'\n" + + " dataLocalDir = '" + dataLocalDir + "'\n" + + " executableDir = '" + executableDir + "'\n" + + " preferencesDir = '" + preferencesDir + "'\n" + + " runtimeDir = '" + runtimeDir + "'\n"; } @Override @@ -275,19 +306,21 @@ public boolean equals(Object o) { BaseDirectories that = (BaseDirectories) o; - if (homeDir != null ? !homeDir .equals(that.homeDir) : that.homeDir != null) + if (homeDir != null ? !homeDir .equals(that.homeDir) : that.homeDir != null) + return false; + if (cacheDir != null ? !cacheDir .equals(that.cacheDir) : that.cacheDir != null) return false; - if (cacheDir != null ? !cacheDir .equals(that.cacheDir) : that.cacheDir != null) + if (configDir != null ? !configDir .equals(that.configDir) : that.configDir != null) return false; - if (configDir != null ? !configDir .equals(that.configDir) : that.configDir != null) + if (dataDir != null ? !dataDir .equals(that.dataDir) : that.dataDir != null) return false; - if (dataDir != null ? !dataDir .equals(that.dataDir) : that.dataDir != null) + if (dataLocalDir != null ? !dataLocalDir .equals(that.dataLocalDir) : that.dataLocalDir != null) return false; - if (dataLocalDir != null ? !dataLocalDir .equals(that.dataLocalDir) : that.dataLocalDir != null) + if (executableDir != null ? !executableDir .equals(that.executableDir) : that.executableDir != null) return false; - if (executableDir != null ? !executableDir.equals(that.executableDir) : that.executableDir != null) + if (preferencesDir != null ? !preferencesDir.equals(that.preferencesDir) : that.preferencesDir != null) return false; - if (runtimeDir != null ? !runtimeDir .equals(that.runtimeDir) : that.runtimeDir != null) + if (runtimeDir != null ? !runtimeDir .equals(that.runtimeDir) : that.runtimeDir != null) return false; return true; } @@ -295,13 +328,14 @@ public boolean equals(Object o) { @Override public int hashCode() { int result = 0; - result = 31 * result + (homeDir != null ? homeDir .hashCode() : 0); - result = 31 * result + (cacheDir != null ? cacheDir .hashCode() : 0); - result = 31 * result + (configDir != null ? configDir .hashCode() : 0); - result = 31 * result + (dataDir != null ? dataDir .hashCode() : 0); - result = 31 * result + (dataLocalDir != null ? dataLocalDir .hashCode() : 0); - result = 31 * result + (executableDir != null ? executableDir.hashCode() : 0); - result = 31 * result + (runtimeDir != null ? runtimeDir .hashCode() : 0); + result = 31 * result + (homeDir != null ? homeDir .hashCode() : 0); + result = 31 * result + (cacheDir != null ? cacheDir .hashCode() : 0); + result = 31 * result + (configDir != null ? configDir .hashCode() : 0); + result = 31 * result + (dataDir != null ? dataDir .hashCode() : 0); + result = 31 * result + (dataLocalDir != null ? dataLocalDir .hashCode() : 0); + result = 31 * result + (executableDir != null ? executableDir .hashCode() : 0); + result = 31 * result + (preferencesDir != null ? preferencesDir.hashCode() : 0); + result = 31 * result + (runtimeDir != null ? runtimeDir .hashCode() : 0); return result; } } diff --git a/src/main/java/io/github/soc/directories/ProjectDirectories.java b/src/main/java/dev/dirs/ProjectDirectories.java similarity index 70% rename from src/main/java/io/github/soc/directories/ProjectDirectories.java rename to src/main/java/dev/dirs/ProjectDirectories.java index 34b2d63..541756f 100644 --- a/src/main/java/io/github/soc/directories/ProjectDirectories.java +++ b/src/main/java/dev/dirs/ProjectDirectories.java @@ -1,6 +1,6 @@ -package io.github.soc.directories; +package dev.dirs; -import static io.github.soc.directories.Util.*; +import static dev.dirs.Util.*; /** {@code ProjectDirectories} computes the location of cache, config or data directories for a specific application, * which are derived from the standard directories and the name of the project/organization. @@ -25,6 +25,7 @@ private ProjectDirectories( final String configDir, final String dataDir, final String dataLocalDir, + final String preferencesDir, final String runtimeDir) { requireNonNull(projectPath); @@ -34,6 +35,7 @@ private ProjectDirectories( this.configDir = configDir; this.dataDir = dataDir; this.dataLocalDir = dataLocalDir; + this.preferencesDir = preferencesDir; this.runtimeDir = runtimeDir; } @@ -71,7 +73,7 @@ private ProjectDirectories( */ public final String cacheDir; - /** Returns the path to the project's config directory, + /** Returns the path to the project's configuration directory, * in which {@code } is the value of {@link ProjectDirectories#projectPath}. *

*
@@ -87,8 +89,8 @@ private ProjectDirectories( * * * - * - * + * + * * * * @@ -155,6 +157,34 @@ private ProjectDirectories( */ public final String dataLocalDir; + /** Returns the path to the project's preferences directory, + * in which {@code } is the value of {@link ProjectDirectories#projectPath}. + *

+ *
macOS{@code $HOME}/Library/Preferences/{@code }/Users/Alice/Library/Preferences/com.Foo-Corp.Bar-App{@code $HOME}/Library/Application Support/{@code }/Users/Alice/Library/Application Support/com.Foo-Corp.Bar-App
Windows
+ * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + *
PlatformValueExample
Linux/BSD{@code $XDG_CONFIG_HOME}/{@code } or {@code $HOME}/.config/{@code }/home/alice/.config/barapp
macOS{@code $HOME}/Library/Preferences/{@code }/Users/Alice/Library/Preferences/com.Foo-Corp.Bar-App
Windows{@code {FOLDERID_RoamingAppData}}\{@code }\configC:\Users\Alice\AppData\Roaming\Foo Corp\Bar App\config
+ */ + public final String preferencesDir; + /** Returns the path to the project's runtime directory. *

* @@ -198,38 +228,42 @@ public static ProjectDirectories fromPath(String path) { String configDir; String dataDir; String dataLocalDir; + String preferencesDir; String runtimeDir = null; switch (operatingSystem) { case LIN: case BSD: case SOLARIS: - homeDir = System.getProperty("user.home"); - cacheDir = defaultIfNullOrEmptyExtended(System.getenv("XDG_CACHE_HOME"), path, homeDir + "/.cache/", path); - configDir = defaultIfNullOrEmptyExtended(System.getenv("XDG_CONFIG_HOME"), path, homeDir + "/.config/", path); - dataDir = defaultIfNullOrEmptyExtended(System.getenv("XDG_DATA_HOME"), path, homeDir + "/.local/share/", path); - dataLocalDir = dataDir; - runtimeDir = linuxRuntimeDir(path); + homeDir = System.getProperty("user.home"); + cacheDir = defaultIfNullOrEmptyExtended(System.getenv("XDG_CACHE_HOME"), path, homeDir + "/.cache/", path); + configDir = defaultIfNullOrEmptyExtended(System.getenv("XDG_CONFIG_HOME"), path, homeDir + "/.config/", path); + dataDir = defaultIfNullOrEmptyExtended(System.getenv("XDG_DATA_HOME"), path, homeDir + "/.local/share/", path); + dataLocalDir = dataDir; + preferencesDir = configDir; + runtimeDir = linuxRuntimeDir(path); break; case MAC: - homeDir = System.getProperty("user.home"); - cacheDir = homeDir + "/Library/Caches/" + path; - configDir = homeDir + "/Library/Preferences/" + path; - dataDir = homeDir + "/Library/Application Support/" + path; - dataLocalDir = dataDir; + homeDir = System.getProperty("user.home"); + cacheDir = homeDir + "/Library/Caches/" + path; + configDir = homeDir + "/Library/Application Support/" + path; + dataDir = homeDir + "/Library/Application Support/" + path; + dataLocalDir = dataDir; + preferencesDir = homeDir + "/Library/Preferences/" + path; break; case WIN: String[] winDirs = getWinDirs("3EB685DB-65F9-4CF6-A03A-E3EF65729F3D", "F1B32785-6FBA-4FCF-9D55-7B8E7F157091"); String appDataRoaming = winDirs[0] + '\\' + path; String appDataLocal = winDirs[1] + '\\' + path; - dataDir = appDataRoaming + "\\data"; - dataLocalDir = appDataLocal + "\\data"; - configDir = appDataRoaming + "\\config"; - cacheDir = appDataLocal + "\\cache"; + dataDir = appDataRoaming + "\\data"; + dataLocalDir = appDataLocal + "\\data"; + configDir = appDataRoaming + "\\config"; + cacheDir = appDataLocal + "\\cache"; + preferencesDir = configDir; break; default: throw new UnsupportedOperatingSystemException("Project directories are not supported on " + operatingSystemName); } - return new ProjectDirectories(path, cacheDir, configDir, dataDir, dataLocalDir, runtimeDir); + return new ProjectDirectories(path, cacheDir, configDir, dataDir, dataLocalDir, preferencesDir, runtimeDir); } /** Creates a {@code ProjectDirectories} instance from values describing the project. @@ -253,7 +287,7 @@ public static ProjectDirectories fromPath(String path) { * {@code qualifier}, {@code organization} and {@code application} arguments. */ public static ProjectDirectories from(String qualifier, String organization, String application) { - if (Util.isNullOrEmpty(organization) && Util.isNullOrEmpty(application)) + if (isNullOrEmpty(organization) && isNullOrEmpty(application)) throw new UnsupportedOperationException("organization and application arguments cannot both be null/empty"); String path; switch (operatingSystem) { @@ -263,10 +297,10 @@ public static ProjectDirectories from(String qualifier, String organization, Str path = trimLowercaseReplaceWhitespace(application, "", true); break; case MAC: - path = Util.macOSApplicationPath(qualifier, organization, application); + path = macOSApplicationPath(qualifier, organization, application); break; case WIN: - path = Util.windowsApplicationPath(qualifier, organization, application); + path = windowsApplicationPath(qualifier, organization, application); break; default: throw new UnsupportedOperatingSystemException("Base directories are not supported on " + operatingSystemName); @@ -277,12 +311,13 @@ public static ProjectDirectories from(String qualifier, String organization, Str @Override public String toString() { return "ProjectDirectories (" + operatingSystemName + "):\n" + - " projectPath = '" + projectPath + "'\n" + - " cacheDir = '" + cacheDir + "'\n" + - " configDir = '" + configDir + "'\n" + - " dataDir = '" + dataDir + "'\n" + - " dataLocalDir = '" + dataLocalDir + "'\n" + - " runtimeDir = '" + runtimeDir + "'\n"; + " projectPath = '" + projectPath + "'\n" + + " cacheDir = '" + cacheDir + "'\n" + + " configDir = '" + configDir + "'\n" + + " dataDir = '" + dataDir + "'\n" + + " dataLocalDir = '" + dataLocalDir + "'\n" + + " preferencesDir = '" + preferencesDir + "'\n" + + " runtimeDir = '" + runtimeDir + "'\n"; } @Override @@ -293,15 +328,17 @@ public boolean equals(Object o) { ProjectDirectories that = (ProjectDirectories) o; if (!projectPath.equals(that.projectPath)) return false; - if (cacheDir != null ? !cacheDir .equals(that.cacheDir) : that.cacheDir != null) + if (cacheDir != null ? !cacheDir .equals(that.cacheDir) : that.cacheDir != null) + return false; + if (configDir != null ? !configDir .equals(that.configDir) : that.configDir != null) return false; - if (configDir != null ? !configDir .equals(that.configDir) : that.configDir != null) + if (dataDir != null ? !dataDir .equals(that.dataDir) : that.dataDir != null) return false; - if (dataDir != null ? !dataDir .equals(that.dataDir) : that.dataDir != null) + if (dataLocalDir != null ? !dataLocalDir .equals(that.dataLocalDir) : that.dataLocalDir != null) return false; - if (dataLocalDir != null ? !dataLocalDir.equals(that.dataLocalDir) : that.dataLocalDir != null) + if (preferencesDir != null ? !preferencesDir.equals(that.preferencesDir) : that.preferencesDir != null) return false; - if (runtimeDir != null ? !runtimeDir .equals(that.runtimeDir) : that.runtimeDir != null) + if (runtimeDir != null ? !runtimeDir .equals(that.runtimeDir) : that.runtimeDir != null) return false; return true; } @@ -309,11 +346,12 @@ public boolean equals(Object o) { @Override public int hashCode() { int result = projectPath.hashCode(); - result = 31 * result + (cacheDir != null ? cacheDir .hashCode() : 0); - result = 31 * result + (configDir != null ? configDir .hashCode() : 0); - result = 31 * result + (dataDir != null ? dataDir .hashCode() : 0); - result = 31 * result + (dataLocalDir != null ? dataLocalDir.hashCode() : 0); - result = 31 * result + (runtimeDir != null ? runtimeDir .hashCode() : 0); + result = 31 * result + (cacheDir != null ? cacheDir .hashCode() : 0); + result = 31 * result + (configDir != null ? configDir .hashCode() : 0); + result = 31 * result + (dataDir != null ? dataDir .hashCode() : 0); + result = 31 * result + (dataLocalDir != null ? dataLocalDir .hashCode() : 0); + result = 31 * result + (preferencesDir != null ? preferencesDir.hashCode() : 0); + result = 31 * result + (runtimeDir != null ? runtimeDir .hashCode() : 0); return result; } } diff --git a/src/main/java/io/github/soc/directories/UnsupportedOperatingSystemException.java b/src/main/java/dev/dirs/UnsupportedOperatingSystemException.java similarity index 87% rename from src/main/java/io/github/soc/directories/UnsupportedOperatingSystemException.java rename to src/main/java/dev/dirs/UnsupportedOperatingSystemException.java index 3f0b36c..0e54473 100644 --- a/src/main/java/io/github/soc/directories/UnsupportedOperatingSystemException.java +++ b/src/main/java/dev/dirs/UnsupportedOperatingSystemException.java @@ -1,4 +1,4 @@ -package io.github.soc.directories; +package dev.dirs; public class UnsupportedOperatingSystemException extends UnsupportedOperationException { diff --git a/src/main/java/io/github/soc/directories/UserDirectories.java b/src/main/java/dev/dirs/UserDirectories.java similarity index 99% rename from src/main/java/io/github/soc/directories/UserDirectories.java rename to src/main/java/dev/dirs/UserDirectories.java index 5d086e4..74e2f70 100644 --- a/src/main/java/io/github/soc/directories/UserDirectories.java +++ b/src/main/java/dev/dirs/UserDirectories.java @@ -1,6 +1,6 @@ -package io.github.soc.directories; +package dev.dirs; -import static io.github.soc.directories.Util.*; +import static dev.dirs.Util.*; /** {@code UserDirectories} provides paths of user-facing standard directories, following the conventions of the operating system the library is running on. * diff --git a/src/main/java/io/github/soc/directories/Util.java b/src/main/java/dev/dirs/Util.java similarity index 99% rename from src/main/java/io/github/soc/directories/Util.java rename to src/main/java/dev/dirs/Util.java index 4db3d5a..26044fc 100644 --- a/src/main/java/io/github/soc/directories/Util.java +++ b/src/main/java/dev/dirs/Util.java @@ -1,4 +1,4 @@ -package io.github.soc.directories; +package dev.dirs; import java.io.BufferedReader; import java.io.IOException; diff --git a/src/main/resources/META-INF/native-image/io.github.soc/directories/reflect-config.json b/src/main/resources/META-INF/native-image/dev.dirs/reflect-config.json similarity index 96% rename from src/main/resources/META-INF/native-image/io.github.soc/directories/reflect-config.json rename to src/main/resources/META-INF/native-image/dev.dirs/reflect-config.json index 9fefe81..61a585e 100644 --- a/src/main/resources/META-INF/native-image/io.github.soc/directories/reflect-config.json +++ b/src/main/resources/META-INF/native-image/dev.dirs/reflect-config.json @@ -1,20 +1,20 @@ -[ - { - "name" : "java.util.Base64", - "allDeclaredConstructors" : true, - "allPublicConstructors" : true, - "allDeclaredMethods" : true, - "allPublicMethods" : true, - "allDeclaredClasses" : true, - "allPublicClasses" : true - }, - { - "name" : "java.util.Base64$Encoder", - "allDeclaredConstructors" : true, - "allPublicConstructors" : true, - "allDeclaredMethods" : true, - "allPublicMethods" : true, - "allDeclaredClasses" : true, - "allPublicClasses" : true - } -] +[ + { + "name" : "java.util.Base64", + "allDeclaredConstructors" : true, + "allPublicConstructors" : true, + "allDeclaredMethods" : true, + "allPublicMethods" : true, + "allDeclaredClasses" : true, + "allPublicClasses" : true + }, + { + "name" : "java.util.Base64$Encoder", + "allDeclaredConstructors" : true, + "allPublicConstructors" : true, + "allDeclaredMethods" : true, + "allPublicMethods" : true, + "allDeclaredClasses" : true, + "allPublicClasses" : true + } +] diff --git a/src/test/java/io/github/soc/directories/DirectoriesTest.java b/src/test/java/dev/dirs/DirectoriesTest.java similarity index 94% rename from src/test/java/io/github/soc/directories/DirectoriesTest.java rename to src/test/java/dev/dirs/DirectoriesTest.java index b9ec7ee..4786808 100644 --- a/src/test/java/io/github/soc/directories/DirectoriesTest.java +++ b/src/test/java/dev/dirs/DirectoriesTest.java @@ -1,4 +1,4 @@ -package io.github.soc.directories; +package dev.dirs; import org.junit.Test; diff --git a/src/test/java/io/github/soc/directories/UtilTest.java b/src/test/java/dev/dirs/UtilTest.java similarity index 99% rename from src/test/java/io/github/soc/directories/UtilTest.java rename to src/test/java/dev/dirs/UtilTest.java index 76d7e98..70091f4 100644 --- a/src/test/java/io/github/soc/directories/UtilTest.java +++ b/src/test/java/dev/dirs/UtilTest.java @@ -1,4 +1,4 @@ -package io.github.soc.directories; +package dev.dirs; import org.junit.Test;