/*******************************************************************************
 * 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.
 * <p>
 * This interface is not intended to be implemented by clients.
 * </p>
 * 
 * @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 <code>true</code> if this location allows a default value to be assigned
	 * and <code>false</code> 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
	 * <code>null</code> is returned. Note that even locations which allow defaults may still
	 * return <code>null</code>.
	 * 
	 * @return the default value for this location or <code>null</code>
	 */
	public URL getDefault();

	/**
	 * Returns the parent of this location or <code>null</code> if none is available.
	 * 
	 * @return the parent of this location or <code>null</code>
	 */
	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 <code>null</code>
	 * is returned.
	 * 
	 * @return the URL for this location or <code>null</code> if none
	 */
	public URL getURL();

	/**
	 * Returns <code>true</code> if this location has a value and <code>false</code>
	 * otherwise.
	 * 
	 * @return boolean value indicating whether or not the value is set
	 */
	public boolean isSet();

	/**
	 * Returns <code>true</code> if this location represents a read only location and
	 * <code>false</code> 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, <code>false</code>
	 * 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, <code>false</code>
	 * 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, <code>false</code>
	 * 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 <code>null</code>
	 * 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
	 * <code>true</code> if the lock could be acquired.  Not all locations can be 
	 * locked.
	 * <p>
	 * Locking a location is advisory only.  That is, it does not prevent other applications from 
	 * modifying the same location
	 * </p>
	 * @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 <code>true</code> if this location is locked and <code>false</code>
	 * 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 <code>null</code> value is allowed.
	 * @param defaultValue the default value of the location. A <code>null</code> 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.
	 * <p>
	 * 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.
	 * </p>
	 * <p>
	 * Clients should check if the location is read only before writing anything
	 * to the returned data area.  An <code>IOException</code> 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.
	 * </p>
	 * 
	 * @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;
}