Eclipse Platform
Release 3.1

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

Method Summary
 boolean allowsDefault()
          Returns true if this location allows a default value to be assigned and false otherwise.
 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 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 setURL(URL value, boolean lock)
          Sets and optionally locks the location's value to the given URL.
 

Method Detail

allowsDefault

public 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

public 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

public Location getParentLocation()
Returns the parent of this location or null if none is available.

Returns:
the parent of this location or null

getURL

public 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

public 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

public 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

public boolean setURL(URL value,
                      boolean lock)
               throws IllegalStateException
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

lock

public 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

Throws:
IOException - if there was an unexpected problem while acquiring the lock

release

public void release()
Releases the lock on this location. If the location is not already locked, no action is taken.


Eclipse Platform
Release 3.1

Guidelines for using Eclipse APIs.

Copyright (c) IBM Corp. and others 2000, 2005. All rights reserved.