Package dev.dirs

Class ProjectDirectories

  • public final class ProjectDirectories
extends java.lang.Object
    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.

    Examples

    All examples on this page are computed with a user named Alice, and a ProjectDirectories instance created with the following information: 
    ProjectDirectories.from("com", "Foo Corp", "Bar App")

    Example of configDir value in different operating systems:

    • Linux/BSD: /home/alice/.config/barapp
    • macOS: /Users/Alice/Library/Preferences/com.Foo-Corp.Bar-App
    • Windows: C:\Users\Alice\AppData\Roaming\Foo Corp\Bar App

    • Field Summary

      Fields 
      Modifier and Type Field Description
      java.lang.String cacheDir
      Returns the path to the project's cache directory, in which <project_path> is the value of projectPath.
      java.lang.String configDir
      Returns the path to the project's configuration directory, in which <project_path> is the value of projectPath.
      java.lang.String dataDir
      Returns the path to the project's data directory, in which <project_path> is the value of projectPath.
      java.lang.String dataLocalDir
      Returns the path to the project's local data directory, in which <project_path> is the value of projectPath.
      java.lang.String preferenceDir
      Returns the path to the project's preference directory, in which <project_path> is the value of projectPath.
      java.lang.String projectPath
      Returns the project path fragment used to compute the project's cache/config/data directories.
      java.lang.String runtimeDir
      Returns the path to the project's runtime directory.

    • Method Summary

      All Methods Static Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      boolean equals​(java.lang.Object o)  
      static ProjectDirectories from​(java.lang.String qualifier, java.lang.String organization, java.lang.String application)
      Creates a ProjectDirectories instance from values describing the project.
      static ProjectDirectories fromPath​(java.lang.String path)
      Creates a ProjectDirectories instance directly from a path.
      int hashCode()  
      java.lang.String toString()  

      • Methods inherited from class java.lang.Object

        clone, finalize, getClass, notify, notifyAll, wait, wait, wait

    • Field Detail

      • projectPath

        public final java.lang.String projectPath
        Returns the project path fragment used to compute the project's cache/config/data directories.

        The value is derived from the arguments provided to the from(java.lang.String, java.lang.String, java.lang.String) call and is platform-dependent.

      • cacheDir

        public final java.lang.String cacheDir
        Returns the path to the project's cache directory, in which <project_path> is the value of projectPath.

        Platform Value Example
        Linux/BSD $XDG_CACHE_HOME/<project_path> or $HOME/.cache/<project_path> /home/alice/.cache/barapp
        macOS $HOME/Library/Caches/<project_path> /Users/Alice/Library/Caches/com.Foo-Corp.Bar-App
        Windows {FOLDERID_LocalAppData}\<project_path>\cache C:\Users\Alice\AppData\Local\Foo Corp\Bar App\cache

      • configDir

        public final java.lang.String configDir
        Returns the path to the project's configuration directory, in which <project_path> is the value of projectPath.

        Platform Value Example
        Linux/BSD $XDG_CONFIG_HOME/<project_path> or $HOME/.config/<project_path> /home/alice/.config/barapp
        macOS $HOME/Library/Application Support/<project_path> /Users/Alice/Library/Application Support/com.Foo-Corp.Bar-App
        Windows {FOLDERID_RoamingAppData}\<project_path>\config C:\Users\Alice\AppData\Roaming\Foo Corp\Bar App\config

      • dataDir

        public final java.lang.String dataDir
        Returns the path to the project's data directory, in which <project_path> is the value of projectPath.

        Platform Value Example
        Linux/BSD $XDG_DATA_HOME/<project_path> or $HOME/.local/share/<project_path> /home/alice/.local/share/barapp
        macOS $HOME/Library/Application Support/<project_path> /Users/Alice/Library/Application Support/com.Foo-Corp.Bar-App
        Windows {FOLDERID_RoamingAppData}\<project_path>\data C:\Users\Alice\AppData\Roaming\Foo Corp\Bar App\data

      • dataLocalDir

        public final java.lang.String dataLocalDir
        Returns the path to the project's local data directory, in which <project_path> is the value of projectPath.

        Platform Value Example
        Linux/BSD $XDG_DATA_HOME/<project_path> or $HOME/.local/share/<project_path> /home/alice/.local/share/barapp
        macOS $HOME/Library/Application Support/<project_path> /Users/Alice/Library/Application Support/com.Foo-Corp.Bar-App
        Windows {FOLDERID_LocalAppData}\<project_path>\data C:\Users\Alice\AppData\Local\Foo Corp\Bar App\data

      • preferenceDir

        public final java.lang.String preferenceDir
        Returns the path to the project's preference directory, in which <project_path> is the value of projectPath.

        Platform Value Example
        Linux/BSD $XDG_CONFIG_HOME/<project_path> or $HOME/.config/<project_path> /home/alice/.config/barapp
        macOS $HOME/Library/Preferences/<project_path> /Users/Alice/Library/Preferences/com.Foo-Corp.Bar-App
        Windows {FOLDERID_RoamingAppData}\<project_path>\config C:\Users\Alice\AppData\Roaming\Foo Corp\Bar App\config

      • runtimeDir

        public final java.lang.String runtimeDir
        Returns the path to the project's runtime directory.

        Platform Value Example
        Linux/BSD $XDG_RUNTIME_DIR /run/user/1001/barapp
        macOS – null
        Windows – null

    • Method Detail

      • fromPath

        public static ProjectDirectories fromPath​(java.lang.String path)
        Creates a ProjectDirectories instance directly from a path.

        The argument is used verbatim and is not adapted to operating system standards. The use of fromPath(java.lang.String) is strongly discouraged, as its results will not follow operating system standards on at least two of three platforms.

        Parameters:
        path - A string used verbatim as the path fragment to derive the directory field values.
        Returns:
        A new ProjectDirectories instance, whose directory field values are directly derived from the path argument.

      • from

        public static ProjectDirectories from​(java.lang.String qualifier,
                                      java.lang.String organization,
                                      java.lang.String application)
        Creates a ProjectDirectories instance from values describing the project.

        The use of from(java.lang.String, java.lang.String, java.lang.String) – instead of fromPath(java.lang.String) – is strongly encouraged, as its results will follow operating system standards on Linux, macOS and Windows.

        Parameters:
        qualifier - The reverse domain name notation of the application, excluding the organization or application name itself.
        An empty string can be passed if no qualifier should be used (only affects macOS).
        Example values: "com.example", "org", "uk.co", "io", ""
        organization - The name of the organization that develops this application, or for which the application is developed.
        An empty string can be passed if no organization should be used (only affects macOS and Windows).
        Example values: "Foo Corp", "Alice and Bob Inc", ""
        application - The name of the application itself.
        Example values: "Bar App", "ExampleProgram", "Unicorn-Programme"
        Returns:
        An instance of ProjectDirectories, whose directory field values are based on the qualifier, organization and application arguments.

      • toString

        public java.lang.String toString()
        Overrides:
        toString in class java.lang.Object

      • equals

        public boolean equals​(java.lang.Object o)
        Overrides:
        equals in class java.lang.Object

      • hashCode

        public int hashCode()
        Overrides:
        hashCode in class java.lang.Object