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
    Modifier and Type
    Field
    Description
    static final String
    CONFIGURATION_AREA_TYPE
    Constant which defines the type value used for the configuration area
    static final String
    CONFIGURATION_FILTER
    Constant which defines the filter string for acquiring the service which specifies the configuration location.
    static final String
    ECLIPSE_HOME_FILTER
    Constant which defines the filter string for acquiring the service which specifies the eclipse home location.
    static final String
    ECLIPSE_HOME_LOCATION_TYPE
    Constant which defines the type value used for the eclipse home location
    static final String
    INSTALL_AREA_TYPE
    Constant which defines the type value used for the install area
    static final String
    INSTALL_FILTER
    Constant which defines the filter string for acquiring the service which specifies the install location.
    static final String
    INSTANCE_AREA_TYPE
    Constant which defines the type value used for the instance area
    static final String
    INSTANCE_FILTER
    Constant which defines the filter string for acquiring the service which specifies the instance location.
    static final String
    SERVICE_PROPERTY_DEFAULT_URL
    Constant which defines the service property used for a location to represent its default url as a String (using URL.toExternalForm()), if the location has no default url this property will be missing.
    static final String
    SERVICE_PROPERTY_TYPE
    Constant which defines the service property used for a location to represent its type
    static final String
    SERVICE_PROPERTY_URL
    Constant which defines the service property used for a location to represent its url as a String (using URL.toExternalForm()), as long as the location is not set, this property will be missing, allowing consumers to track Locations that are (not) set yet.
    static final String
    USER_AREA_TYPE
    Constant which defines the type value used for the user area
    static final String
    USER_FILTER
    Constant which defines the filter string for acquiring the service which specifies the user location.

  • Method Summary

    Modifier and Type
    Method
    Description
    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 Details

    • ECLIPSE_HOME_LOCATION_TYPE

      static final String ECLIPSE_HOME_LOCATION_TYPE
      Constant which defines the type value used for the eclipse home location
      Since:
      3.18
      See Also:

    • USER_AREA_TYPE

      static final String USER_AREA_TYPE
      Constant which defines the type value used for the user area
      Since:
      3.18
      See Also:

    • CONFIGURATION_AREA_TYPE

      static final String CONFIGURATION_AREA_TYPE
      Constant which defines the type value used for the configuration area
      Since:
      3.18
      See Also:

    • INSTALL_AREA_TYPE

      static final String INSTALL_AREA_TYPE
      Constant which defines the type value used for the install area
      Since:
      3.18
      See Also:

    • INSTANCE_AREA_TYPE

      static final String INSTANCE_AREA_TYPE
      Constant which defines the type value used for the instance area
      Since:
      3.18
      See Also:

    • SERVICE_PROPERTY_TYPE

      static final String SERVICE_PROPERTY_TYPE
      Constant which defines the service property used for a location to represent its type
      Since:
      3.18
      See Also:

    • SERVICE_PROPERTY_URL

      static final String SERVICE_PROPERTY_URL
      Constant which defines the service property used for a location to represent its url as a String (using URL.toExternalForm()), as long as the location is not set, this property will be missing, allowing consumers to track Locations that are (not) set yet.
      Since:
      3.18
      See Also:

    • SERVICE_PROPERTY_DEFAULT_URL

      static final String SERVICE_PROPERTY_DEFAULT_URL
      Constant which defines the service property used for a location to represent its default url as a String (using URL.toExternalForm()), if the location has no default url this property will be missing.
      Since:
      3.18
      See Also:

    • 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 Details

    • 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