KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > eclipse > debug > core > sourcelookup > ISourceContainer


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 import org.eclipse.core.runtime.IAdaptable;
15
16 /**
17  * A source container is a container of source code. A source container is
18  * capable of searching for source elements by name. For example, a source
19  * container may be a project or a directory capable of searching for files
20  * by name. A source container may be a composite container - i.e. contain
21  * other source containers.
22  * <p>
23  * When a source container is created and added to a source director, the
24  * source container's <code>dispose()</code> method is called when the
25  * source director is disposed. Clients creating source containers for other
26  * purposes must dispose of containers themselves.
27  * </p>
28  * <p>
29  * Clients may implement this interface.
30  * </p>
31  * @see ISourceLookupParticipant
32  * @see ISourceContainerType
33  * @since 3.0
34  */
35 public interface ISourceContainer extends IAdaptable {
36     
37     /**
38      * Notification this source container has been added to the given
39      * source lookup director.
40      *
41      * @param director the director this container has been added to
42      */
43     public void init(ISourceLookupDirector director);
44
45     /**
46      * Returns a collection of source elements in this container corresponding to the
47      * given name. Returns an empty collection if no source elements are found.
48      * This source container's source lookup director specifies if duplicate
49      * source elements should be searched for, via <code>isFindDuplicates()</code>.
50      * When <code>false</code> the returned collection should contain at most one
51      * source element. If this is a composite container, the containers contained
52      * by this container are also searched.
53      * <p>
54      * The format of the given name is implementation specific but generally conforms
55      * to the format of a file name. If a source container does not recognize the
56      * name format provided, an empty collection should be returned. A source container
57      * may or may not require names to be fully qualified (i.e. be qualified with directory
58      * names).
59      * </p>
60      * @param name the name of the source element to search for
61      * @return a collection of source elements corresponding to the given name
62      * @exception CoreException if an exception occurs while searching for source elements
63      */
64     public Object JavaDoc[] findSourceElements(String JavaDoc name) throws CoreException;
65
66     /**
67      * The name of this source container that can be used for presentation purposes.
68      * For example, the name of a project.
69      *
70      * @return the name of this source container
71      */
72     public String JavaDoc getName();
73
74     /**
75      * Returns the source containers this container is composed of. An empty
76      * collection is returned if this container is not a composite container.
77      * For example, a workspace source container may be composed of project source
78      * containers.
79      *
80      * @return the source containers this container is composed of, possibly
81      * an empty collection
82      * @exception CoreException if unable to retrieve source containers
83      */
84     public ISourceContainer[] getSourceContainers() throws CoreException;
85
86     /**
87      * Returns whether this container is a composite container. A composite
88      * container is composed of other source containers. For example, a workspace
89      * source container may be composed of project source containers.
90      *
91      * @return whether this container is a composite container
92      */
93     public boolean isComposite();
94     
95     /**
96      * Returns this container's type.
97      *
98      * @return this container's type
99      */
100     public ISourceContainerType getType();
101     
102     /**
103      * Disposes this source container. This method is called when the source
104      * director associated with this source container is disposed.
105      */
106     public void dispose();
107     
108 }
109
Popular Tags