KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > eclipse > jdt > launching > IRuntimeClasspathEntry


1 /*******************************************************************************
2  * Copyright (c) 2000, 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.jdt.launching;
12
13
14 import org.eclipse.core.resources.IResource;
15 import org.eclipse.core.runtime.CoreException;
16 import org.eclipse.core.runtime.IPath;
17 import org.eclipse.jdt.core.IClasspathEntry;
18 import org.eclipse.jdt.core.IJavaProject;
19
20 /**
21  * Represents an entry on a runtime classpath. A runtime classpath entry
22  * may refer to one of the following:
23  * <ul>
24  * <li>A Java project (type <code>PROJECT</code>) - a project entry refers
25  * to all of the built classes in a project, and resolves to the output
26  * location(s) of the associated Java project.</li>
27  * <li>An archive (type <code>ARCHIVE</code>) - an archive refers to a jar, zip, or
28  * folder in the workspace or in the local file system containing class
29  * files. An archive may have attached source.</li>
30  * <li>A variable (type <code>VARIABLE</code>) - a variable refers to a
31  * classpath variable, which may refer to a jar.</li>
32  * <li>A library (type <code>CONTAINER</code>) - a container refers to classpath
33  * container variable which refers to a collection of archives derived
34  * dynamically, on a per project basis.</li>
35  * <li>A contributed classpath entry (type <code>OTHER</code>) - a contributed
36  * classpath entry is an extension contributed by a plug-in. The resolution
37  * of a contributed classpath entry is client defined. See
38  * <code>IRuntimeClasspathEntry2</code>.
39  * </ul>
40  * <p>
41  * Clients may implement this interface for contributed a classpath entry
42  * types (i.e. type <code>OTHER</code>). Note, contributed classpath entries
43  * are new in 3.0, and are only intended to be contributed by the Java debugger.
44  * </p>
45  * @since 2.0
46  * @see org.eclipse.jdt.launching.IRuntimeClasspathEntry2
47  */
48 public interface IRuntimeClasspathEntry {
49     
50     /**
51      * Type identifier for project entries.
52      */
53     public static final int PROJECT = 1;
54     
55     /**
56      * Type identifier for archive entries.
57      */
58     public static final int ARCHIVE = 2;
59         
60     /**
61      * Type identifier for variable entries.
62      */
63     public static final int VARIABLE = 3;
64     
65     /**
66      * Type identifier for container entries.
67      */
68     public static final int CONTAINER = 4;
69     
70     /**
71      * Type identifier for contributed entries.
72      * @since 3.0
73      */
74     public static final int OTHER = 5;
75
76     /**
77      * Classpath property identifier for entries that appear on the
78      * bootstrap path by default.
79      */
80     public static final int STANDARD_CLASSES = 1;
81     
82     /**
83      * Classpath property identifier for entries that should appear on the
84      * bootstrap path explicitly.
85      */
86     public static final int BOOTSTRAP_CLASSES = 2;
87         
88     /**
89      * Classpath property identifier for entries that should appear on the
90      * user classpath.
91      */
92     public static final int USER_CLASSES = 3;
93     
94     /**
95      * Returns this classpath entry's type. The type of a runtime classpath entry is
96      * identified by one of the following constants:
97      * <ul>
98      * <li><code>PROJECT</code></li>
99      * <li><code>ARCHIVE</code></li>
100      * <li><code>VARIABLE</code></li>
101      * <li><code>CONTAINER</code></li>
102      * <li><code>OTHER</code></li>
103      * </ul>
104      * <p>
105      * Since 3.0, a type of <code>OTHER</code> may be returned.
106      * </p>
107      * @return this classpath entry's type
108      */
109     public int getType();
110     
111     /**
112      * Returns a memento for this classpath entry.
113      * <p>
114      * Since 3.0, the memento for a contributed classpath entry (i.e. of
115      * type <code>OTHER</code>), must be in the form of an XML document,
116      * with the following element structure:
117      * <pre>
118      * <runtimeClasspathEntry id="exampleId">
119      * <memento
120      * key1="value1"
121      * ...>
122      * </memento>
123      * </runtimeClasspathEntry>
124      * </pre>
125      * The <code>id</code> attribute is the unique identifier of the extension
126      * that contributed this runtime classpath entry type, via the extension
127      * point <code>org.eclipse.jdt.launching.runtimeClasspathEntries</code>.
128      * The <code>memento</code> element will be used to initialize a
129      * restored runtime classpath entry, via the method
130      * <code>IRuntimeClasspathEntry2.initializeFrom(Element memento)</code>. The
131      * attributes of the <code>memento</code> element are client defined.
132      * </p>
133      *
134      * @return a memento for this classpath entry
135      * @exception CoreException if an exception occurs generating a memento
136      */
137     public String JavaDoc getMemento() throws CoreException;
138     
139     /**
140      * Returns the path associated with this entry, or <code>null</code>
141      * if none. The format of the
142      * path returned depends on this entry's type:
143      * <ul>
144      * <li><code>PROJECT</code> - a workspace relative path to the associated
145      * project.</li>
146      * <li><code>ARCHIVE</code> - the absolute path of the associated archive,
147      * which may or may not be in the workspace.</li>
148      * <li><code>VARIABLE</code> - the path corresponding to the associated
149      * classpath variable entry.</li>
150      * <li><code>CONTAINER</code> - the path corresponding to the associated
151      * classpath container variable entry.</li>
152      * <li><code>OTHER</code> - the path returned is client defined.</li>
153      * </ul>
154      * <p>
155      * Since 3.0, this method may return <code>null</code>.
156      * </p>
157      * @return the path associated with this entry, or <code>null</code>
158      * @see org.eclipse.jdt.core.IClasspathEntry#getPath()
159      */
160     public IPath getPath();
161         
162     /**
163      * Returns the resource associated with this entry, or <code>null</code>
164      * if none. A project, archive, or folder entry may be associated
165      * with a resource.
166      *
167      * @return the resource associated with this entry, or <code>null</code>
168      */
169     public IResource getResource();
170     
171     /**
172      * Returns the path to the source archive associated with this
173      * entry, or <code>null</code> if this classpath entry has no
174      * source attachment.
175      * <p>
176      * Only archive and variable entries may have source attachments.
177      * For archive entries, the path (if present) locates a source
178      * archive. For variable entries, the path (if present) has
179      * an analogous form and meaning as the variable path, namely the first segment
180      * is the name of a classpath variable.
181      * </p>
182      *
183      * @return the path to the source archive, or <code>null</code> if none
184      */
185     public IPath getSourceAttachmentPath();
186
187     /**
188      * Sets the path to the source archive associated with this
189      * entry, or <code>null</code> if this classpath entry has no
190      * source attachment.
191      * <p>
192      * Only archive and variable entries may have source attachments.
193      * For archive entries, the path refers to a source
194      * archive. For variable entries, the path has
195      * an analogous form and meaning as the variable path, namely the
196      * first segment is the name of a classpath variable.
197      * </p>
198      * <p>
199      * Note that an empty path (<code>Path.EMPTY</code>) is considered
200      * <code>null</code>.
201      * </p>
202      *
203      * @param path the path to the source archive, or <code>null</code> if none
204      */
205     public void setSourceAttachmentPath(IPath path);
206     
207     /**
208      * Returns the path within the source archive where package fragments
209      * are located. An empty path indicates that packages are located at
210      * the root of the source archive. Returns a non-<code>null</code> value
211      * if and only if <code>getSourceAttachmentPath</code> returns
212      * a non-<code>null</code> value.
213      *
214      * @return root path within the source archive, or <code>null</code> if
215      * not applicable
216      */
217     public IPath getSourceAttachmentRootPath();
218     
219     /**
220      * Sets the path within the source archive where package fragments
221      * are located. A root path indicates that packages are located at
222      * the root of the source archive. Only valid if a source attachment
223      * path is also specified.
224      * <p>
225      * Note that an empty path (<code>Path.EMPTY</code>) is considered
226      * <code>null</code>.
227      * </p>
228      *
229      * @param path root path within the source archive, or <code>null</code>
230      */
231     public void setSourceAttachmentRootPath(IPath path);
232     
233     /**
234      * Returns a constant indicating where this entry should appear on the
235      * runtime classpath by default.
236      * The value returned is one of the following:
237      * <ul>
238      * <li><code>STANDARD_CLASSES</code> - a standard entry does not need to appear
239      * on the runtime classpath</li>
240      * <li><code>BOOTSTRAP_CLASSES</code> - a bootstrap entry should appear on the
241      * boot path</li>
242      * <li><code>USER_CLASSES</code> - a user entry should appear on the path
243      * containing user or application classes</li>
244      * </ul>
245      *
246      * @return where this entry should appear on the runtime classpath
247      */
248     public int getClasspathProperty();
249     
250     /**
251      * Sets whether this entry should appear on the bootstrap classpath,
252      * the user classpath, or whether this entry is a standard bootstrap entry
253      * that does not need to appear on the classpath.
254      * The location is one of:
255      * <ul>
256      * <li><code>STANDARD_CLASSES</code> - a standard entry does not need to appear
257      * on the runtime classpath</li>
258      * <li><code>BOOTSTRAP_CLASSES</code> - a bootstrap entry should appear on the
259      * boot path</li>
260      * <li><code>USER_CLASSES</code> - a user entry should appear on the path
261      * conatining user or application classes</li>
262      * </ul>
263      *
264      * @param location a classpat property constant
265      */
266     public void setClasspathProperty(int location);
267     
268     /**
269      * Returns an absolute path in the local file system for this entry,
270      * or <code>null</code> if none, or if this entry is of type <code>CONTAINER</code>.
271      *
272      * @return an absolute path in the local file system for this entry,
273      * or <code>null</code> if none
274      */
275     public String JavaDoc getLocation();
276         
277     /**
278      * Returns an absolute path in the local file system for the source
279      * attachment associated with this entry entry, or <code>null</code> if none.
280      *
281      * @return an absolute path in the local file system for the source
282      * attachment associated with this entry entry, or <code>null</code> if none
283      */
284     public String JavaDoc getSourceAttachmentLocation();
285     
286     /**
287      * Returns a path relative to this entry's source attachment path for the
288      * root location containing source, or <code>null</code> if none.
289      *
290      * @return a path relative to this entry's source attachment path for the
291      * root location containing source, or <code>null</code> if none
292      */
293     public String JavaDoc getSourceAttachmentRootLocation();
294     
295     /**
296      * Returns the first segment of the path associated with this entry, or <code>null</code>
297      * if this entry is not of type <code>VARIABLE</code> or <code>CONTAINER</code>.
298      *
299      * @return the first segment of the path associated with this entry, or <code>null</code>
300      * if this entry is not of type <code>VARIABLE</code> or <code>CONTAINER</code>
301      */
302     public String JavaDoc getVariableName();
303     
304     /**
305      * Returns a classpath entry equivalent to this runtime classpath entry,
306      * or <code>null</code> if none.
307      * <p>
308      * Since 3.0, this method may return <code>null</code>.
309      * </p>
310      * @return a classpath entry equivalent to this runtime classpath entry,
311      * or <code>null</code>
312      * @since 2.1
313      */
314     public IClasspathEntry getClasspathEntry();
315     
316     /**
317      * Returns the Java project associated with this runtime classpath entry
318      * or <code>null</code> if none. Runtime classpath entries of type
319      * <code>CONTAINER</code> may be associated with a project for the
320      * purposes of resolving the entries in a container.
321      *
322      * @return the Java project associated with this runtime classpath entry
323      * or <code>null</code> if none
324      * @since 3.0
325      */
326     public IJavaProject getJavaProject();
327 }
328
Popular Tags