org.eclipse.osgi.service.datalocation.Location Maven / Gradle / Ivy
The newest version!
/*******************************************************************************
* Copyright (c) 2004, 2010 IBM Corporation and others.
* All rights reserved. This program and the accompanying materials
* are made available under the terms of the Eclipse Public License v1.0
* which accompanies this distribution, and is available at
* http://www.eclipse.org/legal/epl-v10.html
*
* Contributors:
* IBM Corporation - initial API and implementation
*******************************************************************************/
package org.eclipse.osgi.service.datalocation;
import java.io.IOException;
import java.net.URL;
/**
* 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
* @noimplement This interface is not intended to be implemented by clients.
*/
public interface Location {
/**
* Constant which defines the filter string for acquiring the service which
* specifies the instance location.
*
* @since 3.2
*/
public static final String INSTANCE_FILTER = "(&(objectClass=" + Location.class.getName() + ")(type=osgi.instance.area))"; //$NON-NLS-1$ //$NON-NLS-2$
/**
* Constant which defines the filter string for acquiring the service which
* specifies the install location.
*
* @since 3.2
*/
public static final String INSTALL_FILTER = "(&(objectClass=" + Location.class.getName() + ")(type=osgi.install.area))"; //$NON-NLS-1$ //$NON-NLS-2$
/**
* Constant which defines the filter string for acquiring the service which
* specifies the configuration location.
*
* @since 3.2
*/
public static final String CONFIGURATION_FILTER = "(&(objectClass=" + Location.class.getName() + ")(type=osgi.configuration.area))"; //$NON-NLS-1$ //$NON-NLS-2$
/**
* Constant which defines the filter string for acquiring the service which
* specifies the user location.
*
* @since 3.2
*/
public static final String USER_FILTER = "(&(objectClass=" + Location.class.getName() + ")(type=osgi.user.area))"; //$NON-NLS-1$ //$NON-NLS-2$
/**
* Constant which defines the filter string for acquiring the service which
* specifies the eclipse home location.
*
* @since 3.4
*/
public static final String ECLIPSE_HOME_FILTER = "(&(objectClass=" + Location.class.getName() + ")(type=eclipse.home.location))"; //$NON-NLS-1$ //$NON-NLS-2$
/**
* Returns true if this location allows a default value to be assigned
* and false otherwise.
*
* @return whether or not this location can have a default value assigned
*/
public boolean allowsDefault();
/**
* 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.
*
* @return the default value for this location or null
*/
public URL getDefault();
/**
* Returns the parent of this location or null if none is available.
*
* @return the parent of this location or null
*/
public Location getParentLocation();
/**
* Returns the actual {@link 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.
*
* @return the URL for this location or null if none
*/
public URL getURL();
/**
* Returns true if this location has a value and false
* otherwise.
*
* @return boolean value indicating whether or not the value is set
*/
public boolean isSet();
/**
* 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.
*
* @return boolean value indicating whether the location is read only
*/
public boolean isReadOnly();
/**
* Sets and optionally locks the location's value to the given {@link URL}. If the location
* already has a value an exception is thrown. If locking is requested and fails, false
* is returned and the {@link URL} of this location is not set.
*
* @param value the value of this location
* @param lock whether or not to lock this location
* @return whether or not the location was successfully set and, if requested, locked.
* @throws IllegalStateException if the location's value is already set
* @deprecated use {@link #set(URL, boolean)} instead.
*/
public boolean setURL(URL value, boolean lock) throws IllegalStateException;
/**
* Sets and optionally locks the location's value to the given {@link URL}. If the location
* already has a value an exception is thrown. If locking is requested and fails, false
* is returned and the {@link URL} of this location is not set.
*
* @param value the value of this location
* @param lock whether or not to lock this location
* @return whether or not the location was successfully set and, if requested, locked.
* @throws IllegalStateException if the location's value is already set
* @throws IOException if there was an unexpected problem while acquiring the lock
* @since 3.4
*/
public boolean set(URL value, boolean lock) throws IllegalStateException, IOException;
/**
* Sets and optionally locks the location's value to the given {@link 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 {@link URL} of this location is not set.
*
* @param value the value of this location
* @param lock whether or not to lock this location
* @param 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.
* @return whether or not the location was successfully set and, if requested, locked.
* @throws IllegalStateException if the location's value is already set
* @throws IOException if there was an unexpected problem while acquiring the lock
* @since 3.5
*/
public boolean set(URL value, boolean lock, String lockFilePath) throws IllegalStateException, 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
*
* @return true if the lock could be acquired; otherwise false is returned
*
* @exception IOException if there was an unexpected problem while acquiring the lock
*/
public boolean lock() throws IOException;
/**
* Releases the lock on this location. If the location is not already locked, no action
* is taken.
*/
public void release();
/**
* Returns true if this location is locked and false
* otherwise.
* @return boolean value indicating whether or not this location is locked
* @throws IOException if there was an unexpected problem reading the lock
* @since 3.4
*/
public boolean isLocked() throws IOException;
/**
* Constructs a new location.
* @param parent the parent location. A null value is allowed.
* @param defaultValue the default value of the location. A null value is allowed.
* @param readonly true if the location is read-only.
* @return a new location.
* @since 3.4
*/
public Location createLocation(Location parent, URL defaultValue, boolean readonly);
/**
* 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.
*
*
* @param path the name of the path to get from this location
* @return the URL to the data area with the specified path.
* @throws IOException if the location URL is not already set
* @since 3.6
*/
public URL getDataArea(String path) throws IOException;
}
© 2015 - 2024 Weber Informatics LLC | Privacy Policy