ISourceLookupParticipant


1   /*******************************************************************************
2    * Copyright (c) 2003, 2006 IBM Corporation and others.
3    * All rights reserved. This program and the accompanying materials
4    * are made available under the terms of the Eclipse Public License v1.0
5    * which accompanies this distribution, and is available at
6    * http://www.eclipse.org/legal/epl-v10.html
7    *
8    * Contributors:
9    *     IBM Corporation - initial API and implementation
10   *******************************************************************************/
11  package org.eclipse.debug.core.sourcelookup;
12  
13  import org.eclipse.core.runtime.CoreException;
14  
15  /**
16   * A source lookup participant participates in source lookup by searching an ordered
17   * list of source containers for source elements corresponding to a debug artifact.
18   * For example, a participant may be asked to find source corresponding to a stack
19   * frame or breakpoint. An implementation of a source lookup participant is debug
20   * model specific, since it must convert the debug model artifact (stack frame,
21   * breakpoint, etc.),  into a source name that can be recognized by a source container
22   * (<code>ISourceContainer</code>), to search for source elements. Source containers
23   * are generally debug model independent, whereas source lookup participants are
24   * debug model specific.  
25   * <p>
26   * Clients may implement this interface. An abstract implementation is
27   * provided by <code>AbstractSourceLookupParticipant</code>, which clients
28   * should subclass.
29   * </p>
30   * @since 3.0
31   */
32  public interface ISourceLookupParticipant {
33  
34      /**
35       * Notification this participant has been added to the specified
36       * source lookup director. 
37       *
38       * @param director the source lookup director that this participant
39       *  has been added to
40       */
41      public void init(ISourceLookupDirector director);
42      
43      /**
44       * Returns a collection of source elements corresponding to the given debug
45       * artifact (for example, a stack frame or breakpoint). Returns an empty
46       * collection if no source elements are found.
47       * This participant's source lookup director specifies if duplicate
48       * source elements should be searched for, via <code>isFindDuplicates()</code>.
49       * When <code>false</code> the returned collection should contain at most one
50       * source element.
51       * <p>
52       * If the given debug artifact is not recognized by this participant, an empty
53       * collection is returned. Otherwise, this participant generates a source name
54       * from the given artifact and performs a search for associated source elements
55       * in its source containers.
56       * </p>
57       * @param object the debug artifact for which source needs to be found (e.g., stack frame)
58       * @return a collection of source elements corresponding to the given
59       *  debug artifact, possibly empty
60       * @exception CoreException if an exception occurs while searching for source
61       */
62      public Object  [] findSourceElements(Object   object) throws CoreException;
63      
64      /**
65       * Returns the source file name associated with the given debug artifact that
66       * source needs to be found for, or <code>null</code> if none.
67       * 
68       * @param object the debug artifact for which source needs to be found (e.g., stack frame)
69       * @return the source file name associated with the given debug artifact,
70       *  or <code>null</code> if none.
71       * @throws CoreException if unable to determine a source file name 
72       */
73      public String   getSourceName(Object   object) throws CoreException;
74  
75      /**
76       * Disposes this source lookup participant. This method is called when
77       * the source lookup director associated with this participant is 
78       * disposed.
79       */
80      public void dispose();
81      
82      /**
83       * Notification that the source lookup containers in the given source
84       * lookup director have changed.
85       * 
86       * @param director source lookup director that is directing this
87       * participant
88       */
89      public void sourceContainersChanged(ISourceLookupDirector director);
90  }
91
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags