/*******************************************************************************
 * Copyright (c) 2011 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.pde.core.target;

import org.eclipse.core.runtime.*;

/**
 * Describes a location in a target that provides bundles and features. Abstracts
 * the storage and provisioning of bundles. May contain a combination of 
 * executable and source bundles.
 * <p>
 * Clients are allowed to provide their own implementations. For the target definition
 * to be persisted correctly, clients must provide a factory through the 
 * <code>org.eclipse.pde.core.targetLocations</code> extension point.
 * </p><p>
 * To display an implementation in the PDE UI, clients may do the following:
 * </p><p>
 * - Implement <code>ITargetLocationWizard</code> and contribute to the <code>org.eclipse.pde.ui.targetLocationProvisioners</code>
 * extension point.
 * </p><p>
 * - Have their target location adapt to <code>org.eclipse.jface.viewers.ILabelProvider</code>
 * to provide text and icon labels in the target definition wizard and editor.
 * </p><p>
 * - Have their target location adapt to <code>org.eclipse.jface.viewers.ITreeContentProvider</code>
 * to provide children items in the target definition wizard and editor. The children must adapt to
 * <code>ILabelProvider</code> to get text and icon labels in the tree.
 * </p><p>
 * - Have their target location adapt to <code>org.eclipse.pde.ui.target.ITargetLocationEditor</code>
 * to open an edit wizard when the edit button is pressed on the target definition wizard and editor.
 * </p><p>
 * - Have their target location adapt to <code>org.eclipse.pde.ui.target.ITargetLocationUpdater</code>
 * to run an update job on the location when the update button is pressed on the target definition
 * wizard and editor.
 * </p>
 * 
 * @since 3.8
 */
public interface ITargetLocation extends IAdaptable {

	/**
	 * Resolves all contents of this location in the context of the specified
	 * target. Returns a status describing the resolution.
	 * <p>
	 * If resolution is successful an OK status is returned. If a problem
	 * occurs while resolving a non-OK status will be returned. If the 
	 * progress monitor is cancelled a CANCEL status will be returned. The
	 * returned status can be accessed later using {@link #getStatus()}.
	 * </p><p>
	 * This location will be considered resolved even if a problem occurs
	 * while resolving. See {@link #isResolved()}
	 * 
	 * @param definition target being resolved for
	 * @param monitor progress monitor or <code>null</code>
	 * @return resolution status
	 */
	public IStatus resolve(ITargetDefinition definition, IProgressMonitor monitor);

	/**
	 * Returns whether this location has resolved all of its contents. If there
	 * was a problem during the resolution the location will still be considered
	 * resolved, see {@link #getStatus()}.
	 * 
	 * @see #resolve(ITargetDefinition, IProgressMonitor)
	 * @return whether this location has resolved all of its contents
	 */
	public boolean isResolved();

	/**
	 * Returns the status of the last bundle resolution or <code>null</code> if 
	 * this location has not been resolved. If there was a problem during the 
	 * resolution, the status returned by {@link #resolve(ITargetDefinition, IProgressMonitor)}
	 * will be returned.
	 * 	 
	 * @return resolution status or <code>null</code>
	 */
	public IStatus getStatus();

	/**
	 * Returns a string that identifies the implementation of this target location.
	 * For target definitions to be persisted correctly, this must match the type
	 * in a contributed <code>org.eclipse.pde.core.targetLocations</code> extension.
	 * 
	 * @return string identifier for the type of target location.
	 */
	public String getType();

	/**
	 * Returns a path in the local file system to the root of the target location.
	 * <p>
	 * The current target platform framework requires a local file location but this
	 * requirement may be removed in the future.  This method should not be referenced.
	 * </p>
	 * 
	 * @param resolve whether to resolve variables in the path
	 * @return home location
	 * @exception CoreException if unable to resolve the location
	 * @noreference This method is not intended to be referenced by clients.
	 */
	public String getLocation(boolean resolve) throws CoreException;

	/**
	 * Returns the bundles in this location or <code>null</code> if this location is not resolved
	 * <p>
	 * Some of the returned bundles may have non-OK statuses.  These bundles may be missing some
	 * information (location, version, source target).  To get a bundle's status call
	 * {@link TargetBundle#getStatus()}.  You can also use {@link #getStatus()} to
	 * get the complete set of problems.
	 * </p>
	 * @return resolved bundles or <code>null</code>
	 */
	public TargetBundle[] getBundles();

	/**
	 * Returns all features available in this location or <code>null</code> if this location is
	 * not resolved.
	 * <p>
	 * This method may return no features, even if the location has multiple bundles.  For all
	 * returned features, the bundles that the features reference should be returned in the list
	 * returned by {@link #getBundles()}
	 * </p>
	 * @return features or <code>null</code>
	 */
	public TargetFeature[] getFeatures();

	/**
	 * Returns VM Arguments that are specified in the bundle location or <code>null</code> if none.
	 * 
	 * @return list of VM Arguments or <code>null</code> if none available
	 */
	public String[] getVMArguments();

	/**
	 * Returns an XML String that stores information about this location so that it can be instantiated 
	 * later using a {@link ITargetLocationFactory}.
	 * 
	 * @return an XML string storing all location information
	 */
	public String serialize();
}