001: /*******************************************************************************
002: * Copyright (c) 2000, 2006 IBM Corporation and others.
003: * All rights reserved. This program and the accompanying materials
004: * are made available under the terms of the Eclipse Public License v1.0
005: * which accompanies this distribution, and is available at
006: * http://www.eclipse.org/legal/epl-v10.html
007: *
008: * Contributors:
009: * IBM Corporation - initial API and implementation
010: *******************************************************************************/package org.eclipse.jdt.launching;
011:
012: import org.eclipse.core.resources.IResource;
013: import org.eclipse.core.runtime.CoreException;
014: import org.eclipse.core.runtime.IPath;
015: import org.eclipse.jdt.core.IClasspathEntry;
016: import org.eclipse.jdt.core.IJavaProject;
017:
018: /**
019: * Represents an entry on a runtime classpath. A runtime classpath entry
020: * may refer to one of the following:
021: * <ul>
022: * <li>A Java project (type <code>PROJECT</code>) - a project entry refers
023: * to all of the built classes in a project, and resolves to the output
024: * location(s) of the associated Java project.</li>
025: * <li>An archive (type <code>ARCHIVE</code>) - an archive refers to a jar, zip, or
026: * folder in the workspace or in the local file system containing class
027: * files. An archive may have attached source.</li>
028: * <li>A variable (type <code>VARIABLE</code>) - a variable refers to a
029: * classpath variable, which may refer to a jar.</li>
030: * <li>A library (type <code>CONTAINER</code>) - a container refers to classpath
031: * container variable which refers to a collection of archives derived
032: * dynamically, on a per project basis.</li>
033: * <li>A contributed classpath entry (type <code>OTHER</code>) - a contributed
034: * classpath entry is an extension contributed by a plug-in. The resolution
035: * of a contributed classpath entry is client defined. See
036: * <code>IRuntimeClasspathEntry2</code>.
037: * </ul>
038: * <p>
039: * Clients may implement this interface for contributed a classpath entry
040: * types (i.e. type <code>OTHER</code>). Note, contributed classpath entries
041: * are new in 3.0, and are only intended to be contributed by the Java debugger.
042: * </p>
043: * @since 2.0
044: * @see org.eclipse.jdt.launching.IRuntimeClasspathEntry2
045: */
046: public interface IRuntimeClasspathEntry {
047:
048: /**
049: * Type identifier for project entries.
050: */
051: public static final int PROJECT = 1;
052:
053: /**
054: * Type identifier for archive entries.
055: */
056: public static final int ARCHIVE = 2;
057:
058: /**
059: * Type identifier for variable entries.
060: */
061: public static final int VARIABLE = 3;
062:
063: /**
064: * Type identifier for container entries.
065: */
066: public static final int CONTAINER = 4;
067:
068: /**
069: * Type identifier for contributed entries.
070: * @since 3.0
071: */
072: public static final int OTHER = 5;
073:
074: /**
075: * Classpath property identifier for entries that appear on the
076: * bootstrap path by default.
077: */
078: public static final int STANDARD_CLASSES = 1;
079:
080: /**
081: * Classpath property identifier for entries that should appear on the
082: * bootstrap path explicitly.
083: */
084: public static final int BOOTSTRAP_CLASSES = 2;
085:
086: /**
087: * Classpath property identifier for entries that should appear on the
088: * user classpath.
089: */
090: public static final int USER_CLASSES = 3;
091:
092: /**
093: * Returns this classpath entry's type. The type of a runtime classpath entry is
094: * identified by one of the following constants:
095: * <ul>
096: * <li><code>PROJECT</code></li>
097: * <li><code>ARCHIVE</code></li>
098: * <li><code>VARIABLE</code></li>
099: * <li><code>CONTAINER</code></li>
100: * <li><code>OTHER</code></li>
101: * </ul>
102: * <p>
103: * Since 3.0, a type of <code>OTHER</code> may be returned.
104: * </p>
105: * @return this classpath entry's type
106: */
107: public int getType();
108:
109: /**
110: * Returns a memento for this classpath entry.
111: * <p>
112: * Since 3.0, the memento for a contributed classpath entry (i.e. of
113: * type <code>OTHER</code>), must be in the form of an XML document,
114: * with the following element structure:
115: * <pre>
116: * <runtimeClasspathEntry id="exampleId">
117: * <memento
118: * key1="value1"
119: * ...>
120: * </memento>
121: * </runtimeClasspathEntry>
122: * </pre>
123: * The <code>id</code> attribute is the unique identifier of the extension
124: * that contributed this runtime classpath entry type, via the extension
125: * point <code>org.eclipse.jdt.launching.runtimeClasspathEntries</code>.
126: * The <code>memento</code> element will be used to initialize a
127: * restored runtime classpath entry, via the method
128: * <code>IRuntimeClasspathEntry2.initializeFrom(Element memento)</code>. The
129: * attributes of the <code>memento</code> element are client defined.
130: * </p>
131: *
132: * @return a memento for this classpath entry
133: * @exception CoreException if an exception occurs generating a memento
134: */
135: public String getMemento() throws CoreException;
136:
137: /**
138: * Returns the path associated with this entry, or <code>null</code>
139: * if none. The format of the
140: * path returned depends on this entry's type:
141: * <ul>
142: * <li><code>PROJECT</code> - a workspace relative path to the associated
143: * project.</li>
144: * <li><code>ARCHIVE</code> - the absolute path of the associated archive,
145: * which may or may not be in the workspace.</li>
146: * <li><code>VARIABLE</code> - the path corresponding to the associated
147: * classpath variable entry.</li>
148: * <li><code>CONTAINER</code> - the path corresponding to the associated
149: * classpath container variable entry.</li>
150: * <li><code>OTHER</code> - the path returned is client defined.</li>
151: * </ul>
152: * <p>
153: * Since 3.0, this method may return <code>null</code>.
154: * </p>
155: * @return the path associated with this entry, or <code>null</code>
156: * @see org.eclipse.jdt.core.IClasspathEntry#getPath()
157: */
158: public IPath getPath();
159:
160: /**
161: * Returns the resource associated with this entry, or <code>null</code>
162: * if none. A project, archive, or folder entry may be associated
163: * with a resource.
164: *
165: * @return the resource associated with this entry, or <code>null</code>
166: */
167: public IResource getResource();
168:
169: /**
170: * Returns the path to the source archive associated with this
171: * entry, or <code>null</code> if this classpath entry has no
172: * source attachment.
173: * <p>
174: * Only archive and variable entries may have source attachments.
175: * For archive entries, the path (if present) locates a source
176: * archive. For variable entries, the path (if present) has
177: * an analogous form and meaning as the variable path, namely the first segment
178: * is the name of a classpath variable.
179: * </p>
180: *
181: * @return the path to the source archive, or <code>null</code> if none
182: */
183: public IPath getSourceAttachmentPath();
184:
185: /**
186: * Sets the path to the source archive associated with this
187: * entry, or <code>null</code> if this classpath entry has no
188: * source attachment.
189: * <p>
190: * Only archive and variable entries may have source attachments.
191: * For archive entries, the path refers to a source
192: * archive. For variable entries, the path has
193: * an analogous form and meaning as the variable path, namely the
194: * first segment is the name of a classpath variable.
195: * </p>
196: * <p>
197: * Note that an empty path (<code>Path.EMPTY</code>) is considered
198: * <code>null</code>.
199: * </p>
200: *
201: * @param path the path to the source archive, or <code>null</code> if none
202: */
203: public void setSourceAttachmentPath(IPath path);
204:
205: /**
206: * Returns the path within the source archive where package fragments
207: * are located. An empty path indicates that packages are located at
208: * the root of the source archive. Returns a non-<code>null</code> value
209: * if and only if <code>getSourceAttachmentPath</code> returns
210: * a non-<code>null</code> value.
211: *
212: * @return root path within the source archive, or <code>null</code> if
213: * not applicable
214: */
215: public IPath getSourceAttachmentRootPath();
216:
217: /**
218: * Sets the path within the source archive where package fragments
219: * are located. A root path indicates that packages are located at
220: * the root of the source archive. Only valid if a source attachment
221: * path is also specified.
222: * <p>
223: * Note that an empty path (<code>Path.EMPTY</code>) is considered
224: * <code>null</code>.
225: * </p>
226: *
227: * @param path root path within the source archive, or <code>null</code>
228: */
229: public void setSourceAttachmentRootPath(IPath path);
230:
231: /**
232: * Returns a constant indicating where this entry should appear on the
233: * runtime classpath by default.
234: * The value returned is one of the following:
235: * <ul>
236: * <li><code>STANDARD_CLASSES</code> - a standard entry does not need to appear
237: * on the runtime classpath</li>
238: * <li><code>BOOTSTRAP_CLASSES</code> - a bootstrap entry should appear on the
239: * boot path</li>
240: * <li><code>USER_CLASSES</code> - a user entry should appear on the path
241: * containing user or application classes</li>
242: * </ul>
243: *
244: * @return where this entry should appear on the runtime classpath
245: */
246: public int getClasspathProperty();
247:
248: /**
249: * Sets whether this entry should appear on the bootstrap classpath,
250: * the user classpath, or whether this entry is a standard bootstrap entry
251: * that does not need to appear on the classpath.
252: * The location is one of:
253: * <ul>
254: * <li><code>STANDARD_CLASSES</code> - a standard entry does not need to appear
255: * on the runtime classpath</li>
256: * <li><code>BOOTSTRAP_CLASSES</code> - a bootstrap entry should appear on the
257: * boot path</li>
258: * <li><code>USER_CLASSES</code> - a user entry should appear on the path
259: * conatining user or application classes</li>
260: * </ul>
261: *
262: * @param location a classpat property constant
263: */
264: public void setClasspathProperty(int location);
265:
266: /**
267: * Returns an absolute path in the local file system for this entry,
268: * or <code>null</code> if none, or if this entry is of type <code>CONTAINER</code>.
269: *
270: * @return an absolute path in the local file system for this entry,
271: * or <code>null</code> if none
272: */
273: public String getLocation();
274:
275: /**
276: * Returns an absolute path in the local file system for the source
277: * attachment associated with this entry entry, or <code>null</code> if none.
278: *
279: * @return an absolute path in the local file system for the source
280: * attachment associated with this entry entry, or <code>null</code> if none
281: */
282: public String getSourceAttachmentLocation();
283:
284: /**
285: * Returns a path relative to this entry's source attachment path for the
286: * root location containing source, or <code>null</code> if none.
287: *
288: * @return a path relative to this entry's source attachment path for the
289: * root location containing source, or <code>null</code> if none
290: */
291: public String getSourceAttachmentRootLocation();
292:
293: /**
294: * Returns the first segment of the path associated with this entry, or <code>null</code>
295: * if this entry is not of type <code>VARIABLE</code> or <code>CONTAINER</code>.
296: *
297: * @return the first segment of the path associated with this entry, or <code>null</code>
298: * if this entry is not of type <code>VARIABLE</code> or <code>CONTAINER</code>
299: */
300: public String getVariableName();
301:
302: /**
303: * Returns a classpath entry equivalent to this runtime classpath entry,
304: * or <code>null</code> if none.
305: * <p>
306: * Since 3.0, this method may return <code>null</code>.
307: * </p>
308: * @return a classpath entry equivalent to this runtime classpath entry,
309: * or <code>null</code>
310: * @since 2.1
311: */
312: public IClasspathEntry getClasspathEntry();
313:
314: /**
315: * Returns the Java project associated with this runtime classpath entry
316: * or <code>null</code> if none. Runtime classpath entries of type
317: * <code>CONTAINER</code> may be associated with a project for the
318: * purposes of resolving the entries in a container.
319: *
320: * @return the Java project associated with this runtime classpath entry
321: * or <code>null</code> if none
322: * @since 3.0
323: */
324: public IJavaProject getJavaProject();
325: }
|