/*******************************************************************************
 * Copyright (c) 2000, 2004 IBM Corporation and others.
 * All rights reserved. This program and the accompanying materials 
 * are made available under the terms of the Common Public License v1.0
 * which accompanies this distribution, and is available at
 * http://www.eclipse.org/legal/cpl-v10.html
 * 
 * Contributors:
 *     IBM Corporation - initial API and implementation
 *******************************************************************************/
package org.eclipse.debug.core.sourcelookup;

import org.eclipse.core.runtime.CoreException;
import org.eclipse.debug.core.ILaunchConfiguration;

/**
 * A source lookup director directs the source lookup process
 * among a set of participants and source containers.
 * <p>
 * Clients may implement this interface. An astract implementation
 * is provided by <code>AbstractSourceLookupDirector</code>, which
 * clients should subclass.
 * </p>
 * @since 3.0
 */
public interface ISourceLookupDirector extends IPersistableSourceLocator2 {
	
	/**
	 * Returns the launch configuration associated with this source 
	 * lookup director, or <code>null</code> if none.
	 * 
	 * @return the launch configuration associated with this source 
	 * lookup director, or <code>null</code> if none
	 */
	public ILaunchConfiguration getLaunchConfiguration();
	
	/**
	 * Returns the source lookup participants currently registered with
	 * this director, possibly an empty collection.
	 * 
	 * @return the source lookup participants currently registered with
	 * this director, possibly an empty collection
	 */
	public ISourceLookupParticipant[] getParticipants();
	
	/**
	 * Returns the source containers currently registered with this 
	 * director, possibly an empty collection.
	 * 
	 * @return the source containers currently registered with this 
	 * director, possibly an empty collection
	 */
	public ISourceContainer[] getSourceContainers();
	
	/**
	 * Sets the source containers this source lookup director
	 * should search when looking for source, possibly an empty collection.
	 * 
	 * @param containers the source containers this source lookup director
	 * should search when looking for source, possibly an empty collection
	 */
	public void setSourceContainers(ISourceContainer[] containers);	
	
	/**
	 * Returns whether to search exhaustively for all source elements
	 * with the same name in all registered source containers, or
	 * whether to stop searching when the first source element matching
	 * the required name is found.
	 * 
	 * @return whether to search exhaustively for all source elements
	 * with the same name
	 */
	public boolean isFindDuplicates();
	
	/**
	 * Sets whether to search exhaustively for all source elements
	 * with the same name in all registered source containers, or
	 * whether to stop searching when the first source element matching
	 * the required name is found.
	 * 
	 * @param findDuplicates whether to search exhaustively for all source elements
	 * with the same name
	 */
	public void setFindDuplicates(boolean findDuplicates);	
	
	/**
	 * Notifies this source lookup director that it should initialize
	 * its set of source lookup participants.
	 */
	public void initializeParticipants();
	
	/**
	 * Returns whether this source director supports the given type
	 * of source location. 
	 * 
	 * @param type source container type
	 * @return whether this source director supports the given type
	 * of source location
	 */
	public boolean supportsSourceContainerType(ISourceContainerType type);
	
	/**
	 * Clears any source lookup results associated with the given
	 * debug artifact, such that a subsequent lookup will force a new search
	 * to be performed.
	 *  
	 * @param element debug artifact to clear source lookup results for
	 */
	public void clearSourceElements(Object element);
	
	/**
	 * Adds the given source lookup participants to this director.
	 * 
	 * @param participants participants to add
	 */
	public void addParticipants(ISourceLookupParticipant[] participants);
	
	/**
	 * Removes the given source lookup participants from this director.
	 * 
	 * @param participants participants to remove
	 */
	public void removeParticipants(ISourceLookupParticipant[] participants);
	
	/**
	 * Returns the identifier of this type of source locator.
	 * 
	 * @return the identifier of this type of source locator
	 */
	public String getId();
	
	/**
	 * Returns the source path computer to use with this source lookup
	 * director, possibly <code>null</code>. By default, the source path 
	 * computer returned is the one associated with this director's launch
	 * configuration's type. However, the source path computer can be specified
	 * programmatically by calling <code>setSourcePathComputer(...)</code>.
	 * 
	 * @return the source path computer to use with this source lookup
	 *  director, possibly <code>null</code>
	 */
	public ISourcePathComputer getSourcePathComputer();
	
	/**
	 * Sets the source path computer for this source lookup director.
	 * This method can be used to override the default source path computer
	 * for a launch configuration type. When <code>null</code> is specified
	 * the default source path computer will be used (i.e. the one assocaited
	 * with this director's launch configuration's type).
	 *  
	 * @param computer source path computer or <code>null</code>
	 */
	public void setSourcePathComputer(ISourcePathComputer computer);
	
	/**
	 * Returns a collection of source elements corresponding to the given debug
	 * artifact (for example, a stack frame or breakpoint). Returns an empty
	 * collection if no source elements are found.
	 * This participant's source lookup director specifies if duplicate
	 * source elements should be searched for, via <code>isFindDuplicates()</code>.
	 * When <code>false</code> the returned collection should contain at most one
	 * source element.
	 * 
	 * @param object the debug artifact for which source needs to be found (e.g., stack frame)
	 * @return a collection of source elements corresponding to the given
	 *  debug artifact, possibly empty
	 * @exception CoreException if an exception occurrs while searching for source
	 */
	public Object[] findSourceElements(Object object) throws CoreException;	
	
	/**
	 * Returns a source element that corresponds to the given debug artifact, or
	 * <code>null</code> if a source element could not be located. This is a
	 * generalization of <code>getSourceElement(IStackFrame)</code> to allow
	 * source to be found for other types of elements.
	 *
	 * @param element the debug artifact for which to locate source
	 * @return an object representing a source element. 
	 */
	 public Object getSourceElement(Object element);	
	
}