Section 26.11.  Data Areas

26.11. Data Areas Applications often need to read or store data. Depending on the use case, this data may be stored in one of many locations. Consider preferences as an example. Typical products use at least some preferences. The preferences themselves may or may not be defined in the product's plug-ins. For example, if you are reusing plug-ins from different products, it is more convenient to manage the preferences outside the plug-in. In addition, applications often allow users to change preference values or use preferences to store recently opened files, recent chat partners, and so on. These values might be stored uniquely for each user or shared among users. In scenarios where applications operate on distinct datasets, some of the preferences may even relate to the particular data and should be stored or associated with that data. Preferences are just one example, but they illustrate the various scopes and lifecycles that applications have for the data they read and write. Eclipse defines four data areas that capture these characteristics and allows application writers to properly control the scope of their data: Install The install area is where Eclipse itself is installed. The install area is generally read-only. The data in the install area is available to all instances of all configurations of Eclipse running on the install. See also Platform.getInstallLocation() and osgi.install.area. Configuration The configuration area is where the running configuration of Eclipse is defined. Configuration areas are generally writable. The data in a configuration area is available to all instances of the configuration. Chapter 25, "The Last Mile," contains additional detail on the configuration area. See also Platform.getConfigurationLocation() and osgi.configuration.area. Instance The instance area is the default location for user-defined data (e.g., a workspace). The instance area is typically writable. Applications may allow multiple sessions to have concurrent access to the instance area, but must take care to prevent lost updates, etc. See also Platform.getInstanceLocation() and osgi.instance.area. Note The Eclipse IDE's workspace is an example of the use of instance locations. The Resources plug-in implementers chose to make the default location for projects be in the instance area defined by the Runtime. Eclipse IDE users commonly think they are setting the Resource's workspace location, but actually they are setting the Runtime's instance location. User The user area is where Eclipse manages data specific to a user, but independent of the configuration or instance. The user area is typically based on the Java user.home system property and the initial value of the osgi.user.area system property. See also Platform.getUserLocation() and osgi.user.area. In addition to these Eclipse wide areas, the Runtime defines two locations specifically for each installed plug-in: State location This is a location within the instance area's metadata. See Plugin.getStateLocation(). Data location This is a location within the configuration's metadata. See Bundle.getDataFile(). Each of these locations is controlled by setting the system properties described before Eclipse starts (e.g., in the config.ini). Locations are URLs. For simplicity, file paths are also accepted and automatically converted to file: URLs. For better control and convenience, there are also a number of predefined symbolic locations that can be used. Note that not all combinations of location type and symbolic value are valid. Table 26-1 details which combinations are possible. Table 26-1. Location Compatibilities Location/Value Supports default? File/URL @none @noDefault @user.home @user.dir Install No Yes No No Yes Yes Configuration Yes Yes Yes[*] Yes[*] Yes Yes Instance Yes Yes Yes Yes Yes Yes (default) User Yes Yes Yes Yes Yes Yes [*] Indicates that this setup is technically possible, but pragmatically quite difficult to manage. In particular, without a configuration location, the Eclipse Runtime may only get as far as starting the OSGi framework. @none Indicates that the corresponding location should never be set either explicitly or to its default value. For example, an RCP-style application that has no instance data may use osgi.instance.area=@none to prevent extraneous files being written to disk. @none must not be followed by any path segments. @noDefault Forces a location to be undefined or explicitly defined (i.e., Eclipse does not automatically compute a default value). This is useful when you want to allow for data in the corresponding location, but the Eclipse default value is not appropriate. @noDefault must not be followed by any path segments. @user.home Directs Eclipse to compute a location value relative to the user's home directory. @user.home can be followed by path segments. In all cases, the string "@user.home" is replaced with the value of the Java user.home system property. For example, setting osgi.instance.area=@user.home/myWorkspace results in a value of file:/users/fred/myWorkspace @user.dir Directs Eclipse to compute a location value relative to the current working directory. @user.dir can be followed by path segments. In all cases, the string "@user.dir" is replaced with the value of the Java user.dir system property. For example, setting osgi.instance.area=@user.dir/myWorkspace results in a value of file:/usr/local/eclipse/myWorkspace Since the default case is for all locations to be set, valid, and writable, some plug-ins may fail in other setups, even if they are listed as possible. For example, it is unreasonable to expect a plug-in focused on instance data, such as the Resources plug-in, to do much if the instance area is not defined. It is up to plug-in developers to choose the setups they support and design their functions accordingly. Note that each of the locations can be statically marked as read-only by setting the corresponding property osgi.AAA.area.readonly=true, where "AAA" is one of the area names.