Package org.eclipse.osgi.service.datalocation

## Interface Location

    public interface Location

A Location represents a URL which may have a default value, may be read only, may or may not have a current value and may be cascaded on to a parent location.

This interface is not intended to be implemented by clients.

Since:
  3.0
Restriction:
  This interface is not intended to be implemented by clients.

### Field Summary

Fields
`static String` `CONFIGURATION_FILTER` Constant which defines the filter string for acquiring the service which specifies the configuration location.
`static String` `ECLIPSE_HOME_FILTER` Constant which defines the filter string for acquiring the service which specifies the eclipse home location.
`static String` `INSTALL_FILTER` Constant which defines the filter string for acquiring the service which specifies the install location.
`static String` `INSTANCE_FILTER` Constant which defines the filter string for acquiring the service which specifies the instance location.
`static String` `USER_FILTER` Constant which defines the filter string for acquiring the service which specifies the user location.

### Method Summary

All Methods Instance Methods Abstract Methods Deprecated Methods
`boolean` `allowsDefault()` Returns `true` if this location allows a default value to be assigned and `false` otherwise.
`Location` `createLocation​(Location parent, URL defaultValue, boolean readonly)` Constructs a new location.
`URL` `getDataArea​(String path)` Returns a URL to the specified path within this location.
`URL` `getDefault()` Returns the default value of this location if any.
`Location` `getParentLocation()` Returns the parent of this location or `null` if none is available.
`URL` `getURL()` Returns the actual `URL` of this location.
`boolean` `isLocked()` Returns `true` if this location is locked and `false` otherwise.
`boolean` `isReadOnly()` Returns `true` if this location represents a read only location and `false` otherwise.
`boolean` `isSet()` Returns `true` if this location has a value and `false` otherwise.
`boolean` `lock()` Attempts to lock this location with a canonical locking mechanism and return `true` if the lock could be acquired.
`void` `release()` Releases the lock on this location.
`boolean` `set​(URL value, boolean lock)` Sets and optionally locks the location's value to the given `URL`.
`boolean` `set​(URL value, boolean lock, String lockFilePath)` Sets and optionally locks the location's value to the given `URL` using the given lock file.
`boolean` `setURL​(URL value, boolean lock)` Deprecated. use `set(URL, boolean)` instead.

### Field Detail

#### INSTANCE_FILTER

    static final String INSTANCE_FILTER

Constant which defines the filter string for acquiring the service which specifies the instance location.

Since:
  3.2

#### INSTALL_FILTER

    static final String INSTALL_FILTER

Constant which defines the filter string for acquiring the service which specifies the install location.

Since:
  3.2

#### CONFIGURATION_FILTER

    static final String CONFIGURATION_FILTER

Constant which defines the filter string for acquiring the service which specifies the configuration location.

Since:
  3.2

#### USER_FILTER

    static final String USER_FILTER

Constant which defines the filter string for acquiring the service which specifies the user location.

Since:
  3.2

#### ECLIPSE_HOME_FILTER

    static final String ECLIPSE_HOME_FILTER

Constant which defines the filter string for acquiring the service which specifies the eclipse home location.

Since:
  3.4

### Method Detail

#### allowsDefault

    boolean allowsDefault()

Returns `true` if this location allows a default value to be assigned and `false` otherwise.

Returns:
  whether or not this location can have a default value assigned

#### getDefault

    URL getDefault()

Returns the default value of this location if any. If no default is available then `null` is returned. Note that even locations which allow defaults may still return `null`.

Returns:
  the default value for this location or `null`

#### getParentLocation

    Location getParentLocation()

Returns the parent of this location or `null` if none is available.

Returns:
  the parent of this location or `null`

#### getURL

    URL getURL()

Returns the actual `URL` of this location. If the location's value has been set, that value is returned. If the value is not set and the location allows defaults, the value is set to the default and returned. In all other cases `null` is returned.

Returns:
  the URL for this location or `null` if none

#### isSet

    boolean isSet()

Returns `true` if this location has a value and `false` otherwise.

Returns:
  boolean value indicating whether or not the value is set

#### isReadOnly

    boolean isReadOnly()

Returns `true` if this location represents a read only location and `false` otherwise. The read only character of a location is not in enforced in any way but rather expresses the intention of the location's creator.

Returns:
  boolean value indicating whether the location is read only

#### setURL

    boolean setURL​(URL value,
                   boolean lock)
            throws IllegalStateException

Deprecated.
use `set(URL, boolean)` instead.
Sets and optionally locks the location's value to the given `URL`. If the location already has a value an exception is thrown. If locking is requested and fails, `false` is returned and the `URL` of this location is not set.

Parameters:
  `value` - the value of this location
  `lock` - whether or not to lock this location
Returns:
  whether or not the location was successfully set and, if requested, locked.
Throws:
  `IllegalStateException` - if the location's value is already set

#### set

    boolean set​(URL value,
                boolean lock)
         throws IllegalStateException,
                IOException

Sets and optionally locks the location's value to the given `URL`. If the location already has a value an exception is thrown. If locking is requested and fails, `false` is returned and the `URL` of this location is not set.

Parameters:
  `value` - the value of this location
  `lock` - whether or not to lock this location
Returns:
  whether or not the location was successfully set and, if requested, locked.
Throws:
  `IllegalStateException` - if the location's value is already set
  `IOException` - if there was an unexpected problem while acquiring the lock
Since:
  3.4

#### set

    boolean set​(URL value,
                boolean lock,
                String lockFilePath)
         throws IllegalStateException,
                IOException

Sets and optionally locks the location's value to the given `URL` using the given lock file. If the location already has a value an exception is thrown. If locking is requested and fails, `false` is returned and the `URL` of this location is not set.

Parameters:
  `value` - the value of this location
  `lock` - whether or not to lock this location
  `lockFilePath` - the path to the lock file. This path will be used to establish locks on this location. The path may be an absolute path or it may be relative to the given URL. If a `null` value is used then a default lock path will be used for this location.
Returns:
  whether or not the location was successfully set and, if requested, locked.
Throws:
  `IllegalStateException` - if the location's value is already set
  `IOException` - if there was an unexpected problem while acquiring the lock
Since:
  3.5

#### lock

    boolean lock()
          throws IOException

Attempts to lock this location with a canonical locking mechanism and return `true` if the lock could be acquired. Not all locations can be locked.

Locking a location is advisory only. That is, it does not prevent other applications from modifying the same location

Returns:
  true if the lock could be acquired; otherwise false is returned
Throws:
  `IOException` - if there was an unexpected problem while acquiring the lock

#### release

    void release()

Releases the lock on this location. If the location is not already locked, no action is taken.

#### isLocked

    boolean isLocked()
              throws IOException

Returns `true` if this location is locked and `false` otherwise.

Returns:
  boolean value indicating whether or not this location is locked
Throws:
  `IOException` - if there was an unexpected problem reading the lock
Since:
  3.4

#### createLocation

    Location createLocation​(Location parent,
                            URL defaultValue,
                            boolean readonly)

Constructs a new location.

Parameters:
  `parent` - the parent location. A `null` value is allowed.
  `defaultValue` - the default value of the location. A `null` value is allowed.
  `readonly` - true if the location is read-only.
Returns:
  a new location.
Since:
  3.4

#### getDataArea

    URL getDataArea​(String path)
             throws IOException

Returns a URL to the specified path within this location. The path of the returned URL may not exist yet. It is the responsibility of the client to create the content of the data area returned if it does not exist.

This method can be used to obtain a private area within the given location. For example use the symbolic name of a bundle to obtain a data area specific to that bundle.

Clients should check if the location is read only before writing anything to the returned data area. An `IOException` will be thrown if this method is called and the location URL has not been set and there is no default value for this location.

Parameters:
  `path` - the name of the path to get from this location
Returns:
  the URL to the data area with the specified path.
Throws:
  `IOException` - if the location URL is not already set
Since:
  3.6