| /******************************************************************************* |
| * Copyright (c) 2000, 2006 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.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 abstract 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 associated |
| * 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 occurs 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); |
| |
| } |