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
Modifier and TypeFieldDescriptionstatic final String
Constant which defines the type value used for the configuration areastatic final String
Constant which defines the filter string for acquiring the service which specifies the configuration location.static final String
Constant which defines the filter string for acquiring the service which specifies the eclipse home location.static final String
Constant which defines the type value used for the eclipse home locationstatic final String
Constant which defines the type value used for the install areastatic final String
Constant which defines the filter string for acquiring the service which specifies the install location.static final String
Constant which defines the type value used for the instance areastatic final String
Constant which defines the filter string for acquiring the service which specifies the instance location.static final String
Constant which defines the service property used for a location to represent its default url as aString
(usingURL.toExternalForm()
), if the location has no default url this property will be missing.static final String
Constant which defines the service property used for a location to represent its typestatic final String
Constant which defines the service property used for a location to represent its url as aString
(usingURL.toExternalForm()
), as long as the location is not set, this property will be missing, allowing consumers to trackLocation
s that are (not) set yet.static final String
Constant which defines the type value used for the user areastatic final String
Constant which defines the filter string for acquiring the service which specifies the user location. -
Method Summary
Modifier and TypeMethodDescriptionboolean
Returnstrue
if this location allows a default value to be assigned andfalse
otherwise.createLocation
(Location parent, URL defaultValue, boolean readonly) Constructs a new location.getDataArea
(String path) Returns a URL to the specified path within this location.Returns the default value of this location if any.Returns the parent of this location ornull
if none is available.getURL()
Returns the actualURL
of this location.boolean
isLocked()
Returnstrue
if this location is locked andfalse
otherwise.boolean
Returnstrue
if this location represents a read only location andfalse
otherwise.boolean
isSet()
Returnstrue
if this location has a value andfalse
otherwise.boolean
lock()
Attempts to lock this location with a canonical locking mechanism and returntrue
if the lock could be acquired.void
release()
Releases the lock on this location.boolean
Sets and optionally locks the location's value to the givenURL
.boolean
Sets and optionally locks the location's value to the givenURL
using the given lock file.boolean
Deprecated.
-
Field Details
-
ECLIPSE_HOME_LOCATION_TYPE
Constant which defines the type value used for the eclipse home location- Since:
- 3.18
- See Also:
-
USER_AREA_TYPE
Constant which defines the type value used for the user area- Since:
- 3.18
- See Also:
-
CONFIGURATION_AREA_TYPE
Constant which defines the type value used for the configuration area- Since:
- 3.18
- See Also:
-
INSTALL_AREA_TYPE
Constant which defines the type value used for the install area- Since:
- 3.18
- See Also:
-
INSTANCE_AREA_TYPE
Constant which defines the type value used for the instance area- Since:
- 3.18
- See Also:
-
SERVICE_PROPERTY_TYPE
Constant which defines the service property used for a location to represent its type -
SERVICE_PROPERTY_URL
Constant which defines the service property used for a location to represent its url as aString
(usingURL.toExternalForm()
), as long as the location is not set, this property will be missing, allowing consumers to trackLocation
s that are (not) set yet.- Since:
- 3.18
- See Also:
-
SERVICE_PROPERTY_DEFAULT_URL
Constant which defines the service property used for a location to represent its default url as aString
(usingURL.toExternalForm()
), if the location has no default url this property will be missing.- Since:
- 3.18
- See Also:
-
INSTANCE_FILTER
Constant which defines the filter string for acquiring the service which specifies the instance location.- Since:
- 3.2
-
INSTALL_FILTER
Constant which defines the filter string for acquiring the service which specifies the install location.- Since:
- 3.2
-
CONFIGURATION_FILTER
Constant which defines the filter string for acquiring the service which specifies the configuration location.- Since:
- 3.2
-
USER_FILTER
Constant which defines the filter string for acquiring the service which specifies the user location.- Since:
- 3.2
-
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()Returnstrue
if this location allows a default value to be assigned andfalse
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 thennull
is returned. Note that even locations which allow defaults may still returnnull
.- Returns:
- the default value for this location or
null
-
getParentLocation
Location getParentLocation()Returns the parent of this location ornull
if none is available.- Returns:
- the parent of this location or
null
-
getURL
URL getURL()Returns the actualURL
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 casesnull
is returned.- Returns:
- the URL for this location or
null
if none
-
isSet
boolean isSet()Returnstrue
if this location has a value andfalse
otherwise.- Returns:
- boolean value indicating whether or not the value is set
-
isReadOnly
boolean isReadOnly()Returnstrue
if this location represents a read only location andfalse
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
Deprecated.useset(URL, boolean)
instead.Sets and optionally locks the location's value to the givenURL
. If the location already has a value an exception is thrown. If locking is requested and fails,false
is returned and theURL
of this location is not set.- Parameters:
value
- the value of this locationlock
- 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
Sets and optionally locks the location's value to the givenURL
. If the location already has a value an exception is thrown. If locking is requested and fails,false
is returned and theURL
of this location is not set.- Parameters:
value
- the value of this locationlock
- 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 setIOException
- if there was an unexpected problem while acquiring the lock- Since:
- 3.4
-
set
Sets and optionally locks the location's value to the givenURL
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 theURL
of this location is not set.- Parameters:
value
- the value of this locationlock
- whether or not to lock this locationlockFilePath
- 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 anull
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 setIOException
- if there was an unexpected problem while acquiring the lock- Since:
- 3.5
-
lock
Attempts to lock this location with a canonical locking mechanism and returntrue
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
Returnstrue
if this location is locked andfalse
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
Constructs a new location.- Parameters:
parent
- the parent location. Anull
value is allowed.defaultValue
- the default value of the location. Anull
value is allowed.readonly
- true if the location is read-only.- Returns:
- a new location.
- Since:
- 3.4
-
getDataArea
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
-
set(URL, boolean)
instead.