0001: /*******************************************************************************
0002: * Copyright (c) 2000, 2007 IBM Corporation and others.
0003: * All rights reserved. This program and the accompanying materials
0004: * are made available under the terms of the Eclipse Public License v1.0
0005: * which accompanies this distribution, and is available at
0006: * http://www.eclipse.org/legal/epl-v10.html
0007: *
0008: * Contributors:
0009: * IBM Corporation - initial API and implementation
0010: * IBM Corporation - added getOption(String, boolean), getOptions(boolean) and setOptions(Map)
0011: * IBM Corporation - deprecated getPackageFragmentRoots(IClasspathEntry) and
0012: * added findPackageFragmentRoots(IClasspathEntry)
0013: * IBM Corporation - added isOnClasspath(IResource)
0014: * IBM Corporation - added setOption(String, String)
0015: * IBM Corporation - added forceClasspathReload(IProgressMonitor)
0016: *******************************************************************************/package org.eclipse.jdt.core;
0017:
0018: import java.util.Map;
0019:
0020: import org.eclipse.core.resources.IProject;
0021: import org.eclipse.core.resources.IResource;
0022: import org.eclipse.core.runtime.IProgressMonitor;
0023: import org.eclipse.core.runtime.IPath;
0024:
0025: import org.eclipse.jdt.core.eval.IEvaluationContext;
0026:
0027: /**
0028: * A Java project represents a view of a project resource in terms of Java
0029: * elements such as package fragments, types, methods and fields.
0030: * A project may contain several package roots, which contain package fragments.
0031: * A package root corresponds to an underlying folder or JAR.
0032: * <p>
0033: * Each Java project has a classpath, defining which folders contain source code and
0034: * where required libraries are located. Each Java project also has an output location,
0035: * defining where the builder writes <code>.class</code> files. A project that
0036: * references packages in another project can access the packages by including
0037: * the required project in a classpath entry. The Java model will present the
0038: * source elements in the required project; when building, the compiler will use
0039: * the corresponding generated class files from the required project's output
0040: * location(s)). The classpath format is a sequence of classpath entries
0041: * describing the location and contents of package fragment roots.
0042: * </p>
0043: * Java project elements need to be opened before they can be navigated or manipulated.
0044: * The children of a Java project are the package fragment roots that are
0045: * defined by the classpath and contained in this project (in other words, it
0046: * does not include package fragment roots for other projects).
0047: * </p>
0048: * <p>
0049: * This interface is not intended to be implemented by clients. An instance
0050: * of one of these handles can be created via
0051: * <code>JavaCore.create(project)</code>.
0052: * </p>
0053: *
0054: * @see JavaCore#create(org.eclipse.core.resources.IProject)
0055: * @see IClasspathEntry
0056: */
0057: public interface IJavaProject extends IParent, IJavaElement, IOpenable {
0058:
0059: /**
0060: * Decodes the classpath entry that has been encoded in the given string
0061: * in the context of this project.
0062: * Returns null if the encoded entry is malformed.
0063: *
0064: * @param encodedEntry the encoded classpath entry
0065: * @return the decoded classpath entry, or <code>null</code> if unable to decode it
0066: * @since 3.2
0067: */
0068: IClasspathEntry decodeClasspathEntry(String encodedEntry);
0069:
0070: /**
0071: * Encodes the given classpath entry into a string in the context of this project.
0072: *
0073: * @param classpathEntry the classpath entry to encode
0074: * @return the encoded classpath entry
0075: * @since 3.2
0076: */
0077: String encodeClasspathEntry(IClasspathEntry classpathEntry);
0078:
0079: /**
0080: * Returns the <code>IJavaElement</code> corresponding to the given
0081: * classpath-relative path, or <code>null</code> if no such
0082: * <code>IJavaElement</code> is found. The result is one of an
0083: * <code>ICompilationUnit</code>, <code>IClassFile</code>, or
0084: * <code>IPackageFragment</code>.
0085: * <p>
0086: * When looking for a package fragment, there might be several potential
0087: * matches; only one of them is returned.
0088: *
0089: * <p>For example, the path "java/lang/Object.java", would result in the
0090: * <code>ICompilationUnit</code> or <code>IClassFile</code> corresponding to
0091: * "java.lang.Object". The path "java/lang" would result in the
0092: * <code>IPackageFragment</code> for "java.lang".
0093: * @param path the given classpath-relative path
0094: * @exception JavaModelException if the given path is <code>null</code>
0095: * or absolute
0096: * @return the <code>IJavaElement</code> corresponding to the given
0097: * classpath-relative path, or <code>null</code> if no such
0098: * <code>IJavaElement</code> is found
0099: */
0100: IJavaElement findElement(IPath path) throws JavaModelException;
0101:
0102: /**
0103: * Returns the <code>IJavaElement</code> corresponding to the given
0104: * classpath-relative path, or <code>null</code> if no such
0105: * <code>IJavaElement</code> is found. The result is one of an
0106: * <code>ICompilationUnit</code>, <code>IClassFile</code>, or
0107: * <code>IPackageFragment</code>. If it is an <code>ICompilationUnit</code>,
0108: * its owner is the given owner.
0109: * <p>
0110: * When looking for a package fragment, there might be several potential
0111: * matches; only one of them is returned.
0112: *
0113: * <p>For example, the path "java/lang/Object.java", would result in the
0114: * <code>ICompilationUnit</code> or <code>IClassFile</code> corresponding to
0115: * "java.lang.Object". The path "java/lang" would result in the
0116: * <code>IPackageFragment</code> for "java.lang".
0117: * @param path the given classpath-relative path
0118: * @param owner the owner of the returned compilation unit, ignored if it is
0119: * not a compilation unit.
0120: * @exception JavaModelException if the given path is <code>null</code>
0121: * or absolute
0122: * @return the <code>IJavaElement</code> corresponding to the given
0123: * classpath-relative path, or <code>null</code> if no such
0124: * <code>IJavaElement</code> is found
0125: * @since 3.0
0126: */
0127: IJavaElement findElement(IPath path, WorkingCopyOwner owner)
0128: throws JavaModelException;
0129:
0130: /**
0131: * Returns the first existing package fragment on this project's classpath
0132: * whose path matches the given (absolute) path, or <code>null</code> if none
0133: * exist.
0134: * The path can be:
0135: * - internal to the workbench: "/Project/src"
0136: * - external to the workbench: "c:/jdk/classes.zip/java/lang"
0137: * @param path the given absolute path
0138: * @exception JavaModelException if this project does not exist or if an
0139: * exception occurs while accessing its corresponding resource
0140: * @return the first existing package fragment on this project's classpath
0141: * whose path matches the given (absolute) path, or <code>null</code> if none
0142: * exist
0143: */
0144: IPackageFragment findPackageFragment(IPath path)
0145: throws JavaModelException;
0146:
0147: /**
0148: * Returns the existing package fragment root on this project's classpath
0149: * whose path matches the given (absolute) path, or <code>null</code> if
0150: * one does not exist.
0151: * The path can be:
0152: * - internal to the workbench: "/Compiler/src"
0153: * - external to the workbench: "c:/jdk/classes.zip"
0154: * @param path the given absolute path
0155: * @exception JavaModelException if this project does not exist or if an
0156: * exception occurs while accessing its corresponding resource
0157: * @return the existing package fragment root on this project's classpath
0158: * whose path matches the given (absolute) path, or <code>null</code> if
0159: * one does not exist
0160: */
0161: IPackageFragmentRoot findPackageFragmentRoot(IPath path)
0162: throws JavaModelException;
0163:
0164: /**
0165: * Returns the existing package fragment roots identified by the given entry.
0166: * Note that a classpath entry that refers to another project may
0167: * have more than one root (if that project has more than on root
0168: * containing source), and classpath entries within the current
0169: * project identify a single root.
0170: * <p>
0171: * If the classpath entry denotes a variable, it will be resolved and return
0172: * the roots of the target entry (empty if not resolvable).
0173: * <p>
0174: * If the classpath entry denotes a container, it will be resolved and return
0175: * the roots corresponding to the set of container entries (empty if not resolvable).
0176: *
0177: * @param entry the given entry
0178: * @return the existing package fragment roots identified by the given entry
0179: * @see IClasspathContainer
0180: * @since 2.1
0181: */
0182: IPackageFragmentRoot[] findPackageFragmentRoots(
0183: IClasspathEntry entry);
0184:
0185: /**
0186: * Returns the first type found following this project's classpath
0187: * with the given fully qualified name or <code>null</code> if none is found.
0188: * The fully qualified name is a dot-separated name. For example,
0189: * a class B defined as a member type of a class A in package x.y should have a
0190: * the fully qualified name "x.y.A.B".
0191: *
0192: * Note that in order to be found, a type name (or its toplevel enclosing
0193: * type name) must match its corresponding compilation unit name. As a
0194: * consequence, secondary types cannot be found using this functionality.
0195: * To find secondary types use {@link #findType(String, IProgressMonitor)} instead.
0196: *
0197: * @param fullyQualifiedName the given fully qualified name
0198: * @exception JavaModelException if this project does not exist or if an
0199: * exception occurs while accessing its corresponding resource
0200: * @return the first type found following this project's classpath
0201: * with the given fully qualified name or <code>null</code> if none is found
0202: * @see IType#getFullyQualifiedName(char)
0203: * @since 2.0
0204: */
0205: IType findType(String fullyQualifiedName) throws JavaModelException;
0206:
0207: /**
0208: * Same functionality as {@link #findType(String)} but also look for secondary
0209: * types if given name does not match a compilation unit name.
0210: *
0211: * @param fullyQualifiedName the given fully qualified name
0212: * @param progressMonitor the progress monitor to report progress to,
0213: * or <code>null</code> if no progress monitor is provided
0214: * @exception JavaModelException if this project does not exist or if an
0215: * exception occurs while accessing its corresponding resource
0216: * @return the first type found following this project's classpath
0217: * with the given fully qualified name or <code>null</code> if none is found
0218: * @see IType#getFullyQualifiedName(char)
0219: * @since 3.2
0220: */
0221: IType findType(String fullyQualifiedName,
0222: IProgressMonitor progressMonitor) throws JavaModelException;
0223:
0224: /**
0225: * Returns the first type found following this project's classpath
0226: * with the given fully qualified name or <code>null</code> if none is found.
0227: * The fully qualified name is a dot-separated name. For example,
0228: * a class B defined as a member type of a class A in package x.y should have a
0229: * the fully qualified name "x.y.A.B".
0230: * If the returned type is part of a compilation unit, its owner is the given
0231: * owner.
0232: *
0233: * Note that in order to be found, a type name (or its toplevel enclosing
0234: * type name) must match its corresponding compilation unit name. As a
0235: * consequence, secondary types cannot be found using this functionality.
0236: * To find secondary types use {@link #findType(String, WorkingCopyOwner, IProgressMonitor)}
0237: * instead.
0238: *
0239: * @param fullyQualifiedName the given fully qualified name
0240: * @param owner the owner of the returned type's compilation unit
0241: * @exception JavaModelException if this project does not exist or if an
0242: * exception occurs while accessing its corresponding resource
0243: * @return the first type found following this project's classpath
0244: * with the given fully qualified name or <code>null</code> if none is found
0245: * @see IType#getFullyQualifiedName(char)
0246: * @since 3.0
0247: */
0248: IType findType(String fullyQualifiedName, WorkingCopyOwner owner)
0249: throws JavaModelException;
0250:
0251: /**
0252: * Same functionality as {@link #findType(String, WorkingCopyOwner)}
0253: * but also look for secondary types if given name does not match
0254: * a compilation unit name.
0255: *
0256: * @param fullyQualifiedName the given fully qualified name
0257: * @param owner the owner of the returned type's compilation unit
0258: * @param progressMonitor the progress monitor to report progress to,
0259: * or <code>null</code> if no progress monitor is provided
0260: * @exception JavaModelException if this project does not exist or if an
0261: * exception occurs while accessing its corresponding resource
0262: * @return the first type found following this project's classpath
0263: * with the given fully qualified name or <code>null</code> if none is found
0264: * @see IType#getFullyQualifiedName(char)
0265: * @since 3.2
0266: */
0267: IType findType(String fullyQualifiedName, WorkingCopyOwner owner,
0268: IProgressMonitor progressMonitor) throws JavaModelException;
0269:
0270: /**
0271: * Returns the first type found following this project's classpath
0272: * with the given package name and type qualified name
0273: * or <code>null</code> if none is found.
0274: * The package name is a dot-separated name.
0275: * The type qualified name is also a dot-separated name. For example,
0276: * a class B defined as a member type of a class A should have the
0277: * type qualified name "A.B".
0278: *
0279: * Note that in order to be found, a type name (or its toplevel enclosing
0280: * type name) must match its corresponding compilation unit name. As a
0281: * consequence, secondary types cannot be found using this functionality.
0282: * To find secondary types use {@link #findType(String, String, IProgressMonitor)}
0283: * instead.
0284: *
0285: * @param packageName the given package name
0286: * @param typeQualifiedName the given type qualified name
0287: * @exception JavaModelException if this project does not exist or if an
0288: * exception occurs while accessing its corresponding resource
0289: * @return the first type found following this project's classpath
0290: * with the given package name and type qualified name
0291: * or <code>null</code> if none is found
0292: * @see IType#getTypeQualifiedName(char)
0293: * @since 2.0
0294: */
0295: IType findType(String packageName, String typeQualifiedName)
0296: throws JavaModelException;
0297:
0298: /**
0299: * Same functionality as {@link #findType(String, String)} but also look for
0300: * secondary types if given name does not match a compilation unit name.
0301: *
0302: * @param packageName the given package name
0303: * @param typeQualifiedName the given type qualified name
0304: * @param progressMonitor the progress monitor to report progress to,
0305: * or <code>null</code> if no progress monitor is provided
0306: * @exception JavaModelException if this project does not exist or if an
0307: * exception occurs while accessing its corresponding resource
0308: * @return the first type found following this project's classpath
0309: * with the given fully qualified name or <code>null</code> if none is found
0310: * @see IType#getFullyQualifiedName(char)
0311: * @since 3.2
0312: */
0313: IType findType(String packageName, String typeQualifiedName,
0314: IProgressMonitor progressMonitor) throws JavaModelException;
0315:
0316: /**
0317: * Returns the first type found following this project's classpath
0318: * with the given package name and type qualified name
0319: * or <code>null</code> if none is found.
0320: * The package name is a dot-separated name.
0321: * The type qualified name is also a dot-separated name. For example,
0322: * a class B defined as a member type of a class A should have the
0323: * type qualified name "A.B".
0324: * If the returned type is part of a compilation unit, its owner is the given
0325: * owner.
0326: *
0327: * Note that in order to be found, a type name (or its toplevel enclosing
0328: * type name) must match its corresponding compilation unit name. As a
0329: * consequence, secondary types cannot be found using this functionality.
0330: * To find secondary types use {@link #findType(String, String, WorkingCopyOwner, IProgressMonitor)}
0331: * instead.
0332: *
0333: * @param packageName the given package name
0334: * @param typeQualifiedName the given type qualified name
0335: * @param owner the owner of the returned type's compilation unit
0336: * @exception JavaModelException if this project does not exist or if an
0337: * exception occurs while accessing its corresponding resource
0338: * @return the first type found following this project's classpath
0339: * with the given package name and type qualified name
0340: * or <code>null</code> if none is found
0341: * @see IType#getTypeQualifiedName(char)
0342: * @since 3.0
0343: */
0344: IType findType(String packageName, String typeQualifiedName,
0345: WorkingCopyOwner owner) throws JavaModelException;
0346:
0347: /**
0348: * Same functionality as {@link #findType(String, String, WorkingCopyOwner)}
0349: * but also look for secondary types if given name does not match a compilation unit name.
0350: *
0351: * @param packageName the given package name
0352: * @param typeQualifiedName the given type qualified name
0353: * @param owner the owner of the returned type's compilation unit
0354: * @param progressMonitor the progress monitor to report progress to,
0355: * or <code>null</code> if no progress monitor is provided
0356: * @exception JavaModelException if this project does not exist or if an
0357: * exception occurs while accessing its corresponding resource
0358: * @return the first type found following this project's classpath
0359: * with the given fully qualified name or <code>null</code> if none is found
0360: * @see IType#getFullyQualifiedName(char)
0361: * @since 3.2
0362: */
0363: IType findType(String packageName, String typeQualifiedName,
0364: WorkingCopyOwner owner, IProgressMonitor progressMonitor)
0365: throws JavaModelException;
0366:
0367: /**
0368: * Returns all of the existing package fragment roots that exist
0369: * on the classpath, in the order they are defined by the classpath.
0370: *
0371: * @return all of the existing package fragment roots that exist
0372: * on the classpath
0373: * @exception JavaModelException if this element does not exist or if an
0374: * exception occurs while accessing its corresponding resource
0375: */
0376: IPackageFragmentRoot[] getAllPackageFragmentRoots()
0377: throws JavaModelException;
0378:
0379: /**
0380: * Returns an array of non-Java resources directly contained in this project.
0381: * It does not transitively answer non-Java resources contained in folders;
0382: * these would have to be explicitly iterated over.
0383: * <p>
0384: * Non-Java resources includes other files and folders located in the
0385: * project not accounted for by any of it source or binary package fragment
0386: * roots. If the project is a source folder itself, resources excluded from the
0387: * corresponding source classpath entry by one or more exclusion patterns
0388: * are considered non-Java resources and will appear in the result
0389: * (possibly in a folder)
0390: * </p>
0391: *
0392: * @return an array of non-Java resources (<code>IFile</code>s and/or
0393: * <code>IFolder</code>s) directly contained in this project
0394: * @exception JavaModelException if this element does not exist or if an
0395: * exception occurs while accessing its corresponding resource
0396: */
0397: Object[] getNonJavaResources() throws JavaModelException;
0398:
0399: /**
0400: * Helper method for returning one option value only. Equivalent to <code>(String)this.getOptions(inheritJavaCoreOptions).get(optionName)</code>
0401: * Note that it may answer <code>null</code> if this option does not exist, or if there is no custom value for it.
0402: * <p>
0403: * For a complete description of the configurable options, see <code>JavaCore#getDefaultOptions</code>.
0404: * </p>
0405: *
0406: * @param optionName the name of an option
0407: * @param inheritJavaCoreOptions - boolean indicating whether JavaCore options should be inherited as well
0408: * @return the String value of a given option
0409: * @see JavaCore#getDefaultOptions()
0410: * @since 2.1
0411: */
0412: String getOption(String optionName, boolean inheritJavaCoreOptions);
0413:
0414: /**
0415: * Returns the table of the current custom options for this project. Projects remember their custom options,
0416: * in other words, only the options different from the the JavaCore global options for the workspace.
0417: * A boolean argument allows to directly merge the project options with global ones from <code>JavaCore</code>.
0418: * <p>
0419: * For a complete description of the configurable options, see <code>JavaCore#getDefaultOptions</code>.
0420: * </p>
0421: *
0422: * @param inheritJavaCoreOptions - boolean indicating whether JavaCore options should be inherited as well
0423: * @return table of current settings of all options
0424: * (key type: <code>String</code>; value type: <code>String</code>)
0425: * @see JavaCore#getDefaultOptions()
0426: * @since 2.1
0427: */
0428: Map getOptions(boolean inheritJavaCoreOptions);
0429:
0430: /**
0431: * Returns the default output location for this project as a workspace-
0432: * relative absolute path.
0433: * <p>
0434: * The default output location is where class files are ordinarily generated
0435: * (and resource files, copied). Each source classpath entry can also
0436: * specify an output location for the generated class files (and copied
0437: * resource files) corresponding to compilation units under that source
0438: * folder. This makes it possible to arrange generated class files for
0439: * different source folders in different output folders, and not
0440: * necessarily the default output folder. This means that the generated
0441: * class files for the project may end up scattered across several folders,
0442: * rather than all in the default output folder (which is more standard).
0443: * </p>
0444: *
0445: * @return the workspace-relative absolute path of the default output folder
0446: * @exception JavaModelException if this element does not exist
0447: * @see #setOutputLocation(org.eclipse.core.runtime.IPath, IProgressMonitor)
0448: * @see IClasspathEntry#getOutputLocation()
0449: */
0450: IPath getOutputLocation() throws JavaModelException;
0451:
0452: /**
0453: * Returns a package fragment root for the JAR at the specified file system path.
0454: * This is a handle-only method. The underlying <code>java.io.File</code>
0455: * may or may not exist. No resource is associated with this local JAR
0456: * package fragment root.
0457: *
0458: * @param jarPath the jars's file system path
0459: * @return a package fragment root for the JAR at the specified file system path
0460: */
0461: IPackageFragmentRoot getPackageFragmentRoot(String jarPath);
0462:
0463: /**
0464: * Returns a package fragment root for the given resource, which
0465: * must either be a folder representing the top of a package hierarchy,
0466: * or a <code>.jar</code> or <code>.zip</code> file.
0467: * This is a handle-only method. The underlying resource may or may not exist.
0468: *
0469: * @param resource the given resource
0470: * @return a package fragment root for the given resource, which
0471: * must either be a folder representing the top of a package hierarchy,
0472: * or a <code>.jar</code> or <code>.zip</code> file
0473: */
0474: IPackageFragmentRoot getPackageFragmentRoot(IResource resource);
0475:
0476: /**
0477: * Returns all of the package fragment roots contained in this
0478: * project, identified on this project's resolved classpath. The result
0479: * does not include package fragment roots in other projects referenced
0480: * on this project's classpath.
0481: *
0482: * <p>NOTE: This is equivalent to <code>getChildren()</code>.
0483: *
0484: * @return all of the package fragment roots contained in this
0485: * project, identified on this project's resolved classpath
0486: * @exception JavaModelException if this element does not exist or if an
0487: * exception occurs while accessing its corresponding resource
0488: */
0489: IPackageFragmentRoot[] getPackageFragmentRoots()
0490: throws JavaModelException;
0491:
0492: /**
0493: * Returns the existing package fragment roots identified by the given entry.
0494: * Note that a classpath entry that refers to another project may
0495: * have more than one root (if that project has more than on root
0496: * containing source), and classpath entries within the current
0497: * project identify a single root.
0498: * <p>
0499: * If the classpath entry denotes a variable, it will be resolved and return
0500: * the roots of the target entry (empty if not resolvable).
0501: * <p>
0502: * If the classpath entry denotes a container, it will be resolved and return
0503: * the roots corresponding to the set of container entries (empty if not resolvable).
0504: *
0505: * @param entry the given entry
0506: * @return the existing package fragment roots identified by the given entry
0507: * @see IClasspathContainer
0508: * @deprecated Use {@link IJavaProject#findPackageFragmentRoots(IClasspathEntry)} instead
0509: */
0510: IPackageFragmentRoot[] getPackageFragmentRoots(IClasspathEntry entry);
0511:
0512: /**
0513: * Returns all package fragments in all package fragment roots contained
0514: * in this project. This is a convenience method.
0515: *
0516: * Note that the package fragment roots corresponds to the resolved
0517: * classpath of the project.
0518: *
0519: * @return all package fragments in all package fragment roots contained
0520: * in this project
0521: * @exception JavaModelException if this element does not exist or if an
0522: * exception occurs while accessing its corresponding resource
0523: */
0524: IPackageFragment[] getPackageFragments() throws JavaModelException;
0525:
0526: /**
0527: * Returns the <code>IProject</code> on which this <code>IJavaProject</code>
0528: * was created. This is handle-only method.
0529: *
0530: * @return the <code>IProject</code> on which this <code>IJavaProject</code>
0531: * was created
0532: */
0533: IProject getProject();
0534:
0535: /**
0536: * Returns the raw classpath for the project, as a list of classpath
0537: * entries. This corresponds to the exact set of entries which were assigned
0538: * using <code>setRawClasspath</code>, in particular such a classpath may
0539: * contain classpath variable and classpath container entries. Classpath
0540: * variable and classpath container entries can be resolved using the
0541: * helper method <code>getResolvedClasspath</code>; classpath variable
0542: * entries also can be resolved individually using
0543: * <code>JavaCore#getClasspathVariable</code>).
0544: * <p>
0545: * Both classpath containers and classpath variables provides a level of
0546: * indirection that can make the <code>.classpath</code> file stable across
0547: * workspaces.
0548: * As an example, classpath variables allow a classpath to no longer refer
0549: * directly to external JARs located in some user specific location.
0550: * The classpath can simply refer to some variables defining the proper
0551: * locations of these external JARs. Similarly, classpath containers
0552: * allows classpath entries to be computed dynamically by the plug-in that
0553: * defines that kind of classpath container.
0554: * </p>
0555: * <p>
0556: * Note that in case the project isn't yet opened, the classpath will
0557: * be read directly from the associated <tt>.classpath</tt> file.
0558: * </p>
0559: *
0560: * @return the raw classpath for the project, as a list of classpath entries
0561: * @exception JavaModelException if this element does not exist or if an
0562: * exception occurs while accessing its corresponding resource
0563: * @see IClasspathEntry
0564: */
0565: IClasspathEntry[] getRawClasspath() throws JavaModelException;
0566:
0567: /**
0568: * Returns the names of the projects that are directly required by this
0569: * project. A project is required if it is in its classpath.
0570: * <p>
0571: * The project names are returned in the order they appear on the classpath.
0572: *
0573: * @return the names of the projects that are directly required by this
0574: * project in classpath order
0575: * @exception JavaModelException if this element does not exist or if an
0576: * exception occurs while accessing its corresponding resource
0577: */
0578: String[] getRequiredProjectNames() throws JavaModelException;
0579:
0580: /**
0581: * This is a helper method returning the resolved classpath for the project
0582: * as a list of simple (non-variable, non-container) classpath entries.
0583: * All classpath variable and classpath container entries in the project's
0584: * raw classpath will be replaced by the simple classpath entries they
0585: * resolve to.
0586: * <p>
0587: * The resulting resolved classpath is accurate for the given point in time.
0588: * If the project's raw classpath is later modified, or if classpath
0589: * variables are changed, the resolved classpath can become out of date.
0590: * Because of this, hanging on resolved classpath is not recommended.
0591: * </p>
0592: *
0593: * @param ignoreUnresolvedEntry indicates how to handle unresolvable
0594: * variables and containers; <code>true</code> indicates that missing
0595: * variables and unresolvable classpath containers should be silently
0596: * ignored, and that the resulting list should consist only of the
0597: * entries that could be successfully resolved; <code>false</code> indicates
0598: * that a <code>JavaModelException</code> should be thrown for the first
0599: * unresolved variable or container
0600: * @return the resolved classpath for the project as a list of simple
0601: * classpath entries, where all classpath variable and container entries
0602: * have been resolved and substituted with their final target entries
0603: * @exception JavaModelException in one of the corresponding situation:
0604: * <ul>
0605: * <li>this element does not exist</li>
0606: * <li>an exception occurs while accessing its corresponding resource</li>
0607: * <li>a classpath variable or classpath container was not resolvable
0608: * and <code>ignoreUnresolvedEntry</code> is <code>false</code>.</li>
0609: * </ul>
0610: * @see IClasspathEntry
0611: */
0612: IClasspathEntry[] getResolvedClasspath(boolean ignoreUnresolvedEntry)
0613: throws JavaModelException;
0614:
0615: /**
0616: * Returns whether this project has been built at least once and thus whether it has a build state.
0617: * @return true if this project has been built at least once, false otherwise
0618: */
0619: boolean hasBuildState();
0620:
0621: /**
0622: * Returns whether setting this project's classpath to the given classpath entries
0623: * would result in a cycle.
0624: *
0625: * If the set of entries contains some variables, those are resolved in order to determine
0626: * cycles.
0627: *
0628: * @param entries the given classpath entries
0629: * @return true if the given classpath entries would result in a cycle, false otherwise
0630: */
0631: boolean hasClasspathCycle(IClasspathEntry[] entries);
0632:
0633: /**
0634: * Returns whether the given element is on the classpath of this project,
0635: * that is, referenced from a classpath entry and not explicitly excluded
0636: * using an exclusion pattern.
0637: *
0638: * @param element the given element
0639: * @return <code>true</code> if the given element is on the classpath of
0640: * this project, <code>false</code> otherwise
0641: * @see IClasspathEntry#getInclusionPatterns()
0642: * @see IClasspathEntry#getExclusionPatterns()
0643: * @since 2.0
0644: */
0645: boolean isOnClasspath(IJavaElement element);
0646:
0647: /**
0648: * Returns whether the given resource is on the classpath of this project,
0649: * that is, referenced from a classpath entry and not explicitly excluded
0650: * using an exclusion pattern.
0651: *
0652: * @param resource the given resource
0653: * @return <code>true</code> if the given resource is on the classpath of
0654: * this project, <code>false</code> otherwise
0655: * @see IClasspathEntry#getInclusionPatterns()
0656: * @see IClasspathEntry#getExclusionPatterns()
0657: * @since 2.1
0658: */
0659: boolean isOnClasspath(IResource resource);
0660:
0661: /**
0662: * Creates a new evaluation context.
0663: * @return a new evaluation context.
0664: */
0665: IEvaluationContext newEvaluationContext();
0666:
0667: /**
0668: * Creates and returns a type hierarchy for all types in the given
0669: * region, considering subtypes within that region.
0670: *
0671: * @param monitor the given progress monitor
0672: * @param region the given region
0673: * @exception JavaModelException if this element does not exist or if an
0674: * exception occurs while accessing its corresponding resource
0675: * @exception IllegalArgumentException if region is <code>null</code>
0676: * @return a type hierarchy for all types in the given
0677: * region, considering subtypes within that region
0678: */
0679: ITypeHierarchy newTypeHierarchy(IRegion region,
0680: IProgressMonitor monitor) throws JavaModelException;
0681:
0682: /**
0683: * Creates and returns a type hierarchy for all types in the given
0684: * region, considering subtypes within that region and considering types in the
0685: * working copies with the given owner.
0686: * In other words, the owner's working copies will take
0687: * precedence over their original compilation units in the workspace.
0688: * <p>
0689: * Note that if a working copy is empty, it will be as if the original compilation
0690: * unit had been deleted.
0691: * <p>
0692: *
0693: * @param monitor the given progress monitor
0694: * @param region the given region
0695: * @param owner the owner of working copies that take precedence over their original compilation units
0696: * @exception JavaModelException if this element does not exist or if an
0697: * exception occurs while accessing its corresponding resource
0698: * @exception IllegalArgumentException if region is <code>null</code>
0699: * @return a type hierarchy for all types in the given
0700: * region, considering subtypes within that region
0701: * @since 3.0
0702: */
0703: ITypeHierarchy newTypeHierarchy(IRegion region,
0704: WorkingCopyOwner owner, IProgressMonitor monitor)
0705: throws JavaModelException;
0706:
0707: /**
0708: * Creates and returns a type hierarchy for the given type considering
0709: * subtypes in the specified region.
0710: *
0711: * @param type the given type
0712: * @param region the given region
0713: * @param monitor the given monitor
0714: *
0715: * @exception JavaModelException if this element does not exist or if an
0716: * exception occurs while accessing its corresponding resource
0717: *
0718: * @exception IllegalArgumentException if type or region is <code>null</code>
0719: * @return a type hierarchy for the given type considering
0720: * subtypes in the specified region
0721: */
0722: ITypeHierarchy newTypeHierarchy(IType type, IRegion region,
0723: IProgressMonitor monitor) throws JavaModelException;
0724:
0725: /**
0726: * Creates and returns a type hierarchy for the given type considering
0727: * subtypes in the specified region and considering types in the
0728: * working copies with the given owner.
0729: * In other words, the owner's working copies will take
0730: * precedence over their original compilation units in the workspace.
0731: * <p>
0732: * Note that if a working copy is empty, it will be as if the original compilation
0733: * unit had been deleted.
0734: * <p>
0735: *
0736: * @param type the given type
0737: * @param region the given region
0738: * @param monitor the given monitor
0739: * @param owner the owner of working copies that take precedence over their original compilation units
0740: *
0741: * @exception JavaModelException if this element does not exist or if an
0742: * exception occurs while accessing its corresponding resource
0743: *
0744: * @exception IllegalArgumentException if type or region is <code>null</code>
0745: * @return a type hierarchy for the given type considering
0746: * subtypes in the specified region
0747: * @since 3.0
0748: */
0749: ITypeHierarchy newTypeHierarchy(IType type, IRegion region,
0750: WorkingCopyOwner owner, IProgressMonitor monitor)
0751: throws JavaModelException;
0752:
0753: /**
0754: * Returns the default output location for the project as defined by its <code>.classpath</code> file from disk, or <code>null</code>
0755: * if unable to read the file.
0756: * <p>
0757: * This output location may differ from the in-memory one returned by <code>getOutputLocation</code>, in case the
0758: * automatic reconciliation mechanism has not been performed yet. Usually, any change to the <code>.classpath</code> file
0759: * is automatically noticed and reconciled at the next resource change notification event.
0760: * However, if the file is modified within an operation, where this change needs to be taken into account before the
0761: * operation ends, then the output location from disk can be read using this method, and further assigned to the project
0762: * using <code>setRawClasspath(...)</code>.
0763: * <p>
0764: * The default output location is where class files are ordinarily generated
0765: * (and resource files, copied). Each source classpath entry can also
0766: * specify an output location for the generated class files (and copied
0767: * resource files) corresponding to compilation units under that source
0768: * folder. This makes it possible to arrange generated class files for
0769: * different source folders in different output folders, and not
0770: * necessarily the default output folder. This means that the generated
0771: * class files for the project may end up scattered across several folders,
0772: * rather than all in the default output folder (which is more standard).
0773: * <p>
0774: * In order to manually force a project classpath refresh, one can simply assign the project classpath using the result of this
0775: * method, as follows:
0776: * <code>proj.setRawClasspath(proj.readRawClasspath(), proj.readOutputLocation(), monitor)</code>
0777: * (note that the <code>readRawClasspath/readOutputLocation</code> methods could return <code>null</code>).
0778: * <p>
0779: * @return the workspace-relative absolute path of the default output folder
0780: * @see #getOutputLocation()
0781: * @since 3.0
0782: */
0783: IPath readOutputLocation();
0784:
0785: /**
0786: * Returns the raw classpath for the project as defined by its
0787: * <code>.classpath</code> file from disk, or <code>null</code>
0788: * if unable to read the file.
0789: * <p>
0790: * This classpath may differ from the in-memory classpath returned by
0791: * <code>getRawClasspath</code>, in case the automatic reconciliation
0792: * mechanism has not been performed yet. Usually, any change to the
0793: * <code>.classpath</code> file is automatically noticed and reconciled at
0794: * the next resource change notification event. However, if the file is
0795: * modified within an operation, where this change needs to be taken into
0796: * account before the operation ends, then the classpath from disk can be
0797: * read using this method, and further assigned to the project using
0798: * <code>setRawClasspath(...)</code>.
0799: * </p>
0800: * <p>
0801: * Classpath variable and classpath container entries can be resolved using
0802: * the helper method <code>getResolvedClasspath</code>; classpath variable
0803: * entries also can be resolved individually using
0804: * <code>JavaCore#getClasspathVariable</code>).
0805: * </p>
0806: * <p>
0807: * Note that no check is performed whether the project has the Java nature
0808: * set, allowing an existing <code>.classpath</code> file to be considered
0809: * independantly (unlike <code>getRawClasspath</code> which requires the
0810: * Java nature to be associated with the project).
0811: * </p>
0812: * <p>
0813: * In order to manually force a project classpath refresh, one can simply
0814: * assign the project classpath using the result of this method, as follows:
0815: * <code>proj.setRawClasspath(proj.readRawClasspath(), proj.readOutputLocation(), monitor)</code>
0816: * (note that the <code>readRawClasspath/readOutputLocation</code> methods
0817: * could return <code>null</code>).
0818: * </p>
0819: *
0820: * @return the raw classpath from disk for the project, as a list of
0821: * classpath entries
0822: * @see #getRawClasspath()
0823: * @see IClasspathEntry
0824: * @since 3.0
0825: */
0826: IClasspathEntry[] readRawClasspath();
0827:
0828: /**
0829: * Helper method for setting one option value only.
0830: *<p>
0831: * Equivalent to:
0832: * <pre>
0833: * Map options = this.getOptions(false);
0834: * map.put(optionName, optionValue);
0835: * this.setOptions(map)
0836: * </pre>
0837: * <p>
0838: * For a complete description of the configurable options, see <code>JavaCore#getDefaultOptions</code>.
0839: * </p>
0840: *
0841: * @param optionName the name of an option
0842: * @param optionValue the value of the option to set. If <code>null</code>, then the option
0843: * is removed from project preferences.
0844: * @throws NullPointerException if <code>optionName</code> is <code>null</code>
0845: * (see {@link org.osgi.service.prefs.Preferences#put(String, String)}).
0846: * @see JavaCore#getDefaultOptions()
0847: * @since 3.0
0848: */
0849: void setOption(String optionName, String optionValue);
0850:
0851: /**
0852: * Sets the project custom options. All and only the options explicitly included in the given table
0853: * are remembered; all previous option settings are forgotten, including ones not explicitly
0854: * mentioned.
0855: * <p>
0856: * For a complete description of the configurable options, see <code>JavaCore#getDefaultOptions</code>.
0857: * </p>
0858: *
0859: * @param newOptions the new options (key type: <code>String</code>; value type: <code>String</code>),
0860: * or <code>null</code> to flush all custom options (clients will automatically get the global JavaCore options).
0861: * @see JavaCore#getDefaultOptions()
0862: * @since 2.1
0863: */
0864: void setOptions(Map newOptions);
0865:
0866: /**
0867: * Sets the default output location of this project to the location
0868: * described by the given workspace-relative absolute path.
0869: * <p>
0870: * The default output location is where class files are ordinarily generated
0871: * (and resource files, copied). Each source classpath entries can also
0872: * specify an output location for the generated class files (and copied
0873: * resource files) corresponding to compilation units under that source
0874: * folder. This makes it possible to arrange that generated class files for
0875: * different source folders to end up in different output folders, and not
0876: * necessarily the default output folder. This means that the generated
0877: * class files for the project may end up scattered across several folders,
0878: * rather than all in the default output folder (which is more standard).
0879: * </p>
0880: *
0881: * @param path the workspace-relative absolute path of the default output
0882: * folder
0883: * @param monitor the progress monitor
0884: *
0885: * @exception JavaModelException if the classpath could not be set. Reasons include:
0886: * <ul>
0887: * <li> This Java element does not exist (ELEMENT_DOES_NOT_EXIST)</li>
0888: * <li> The path refers to a location not contained in this project (<code>PATH_OUTSIDE_PROJECT</code>)
0889: * <li> The path is not an absolute path (<code>RELATIVE_PATH</code>)
0890: * <li> The path is nested inside a package fragment root of this project (<code>INVALID_PATH</code>)
0891: * <li> The output location is being modified during resource change event notification (CORE_EXCEPTION)
0892: * </ul>
0893: * @see #getOutputLocation()
0894: * @see IClasspathEntry#getOutputLocation()
0895: */
0896: void setOutputLocation(IPath path, IProgressMonitor monitor)
0897: throws JavaModelException;
0898:
0899: /**
0900: * Sets both the classpath of this project and its default output
0901: * location at once. The classpath is defined using a list of classpath
0902: * entries. In particular such a classpath may contain classpath variable entries.
0903: * Classpath variable entries can be resolved individually ({@link JavaCore#getClasspathVariable(String)}),
0904: * or the full classpath can be resolved at once using the helper method {@link #getResolvedClasspath(boolean)}.
0905: * <p>
0906: * A classpath variable provides an indirection level for better sharing a classpath. As an example, it allows
0907: * a classpath to no longer refer directly to external JARs located in some user specific location. The classpath
0908: * can simply refer to some variables defining the proper locations of these external JARs.
0909: * </p><p>
0910: * If it is specified that this operation cannot modify resources, the .classpath file will not be written to disk
0911: * and no error marker will be generated. To synchronize the .classpath with the in-memory classpath,
0912: * one can use <code>setRawClasspath(readRawClasspath(), true, monitor)</code>.
0913: * </p><p>
0914: * Setting the classpath to <code>null</code> specifies a default classpath
0915: * (the project root). Setting the classpath to an empty array specifies an
0916: * empty classpath.
0917: * </p><p>
0918: * If a cycle is detected while setting this classpath (and if resources can be modified), an error marker will be added
0919: * to the project closing the cycle.
0920: * To avoid this problem, use {@link #hasClasspathCycle(IClasspathEntry[])}
0921: * before setting the classpath.
0922: * <p>
0923: * This operation acquires a lock on the workspace's root.
0924: *
0925: * @param entries a list of classpath entries
0926: * @param outputLocation the default output location
0927: * @param canModifyResources whether resources should be written to disk if needed
0928: * @param monitor the given progress monitor
0929: * @exception JavaModelException if the classpath could not be set. Reasons include:
0930: * <ul>
0931: * <li> This Java element does not exist (ELEMENT_DOES_NOT_EXIST)</li>
0932: * <li> The classpath is being modified during resource change event notification (CORE_EXCEPTION)
0933: * <li> The classpath failed the validation check as defined by {@link JavaConventions#validateClasspath(IJavaProject, IClasspathEntry[], IPath)}
0934: * </ul>
0935: * @see IClasspathEntry
0936: * @since 3.2
0937: */
0938: void setRawClasspath(IClasspathEntry[] entries,
0939: IPath outputLocation, boolean canModifyResources,
0940: IProgressMonitor monitor) throws JavaModelException;
0941:
0942: /**
0943: * Sets the classpath of this project using a list of classpath entries. In particular such a classpath may contain
0944: * classpath variable entries. Classpath variable entries can be resolved individually ({@link JavaCore#getClasspathVariable(String)}),
0945: * or the full classpath can be resolved at once using the helper method {@link #getResolvedClasspath(boolean)}.
0946: * <p>
0947: * A classpath variable provides an indirection level for better sharing a classpath. As an example, it allows
0948: * a classpath to no longer refer directly to external JARs located in some user specific location. The classpath
0949: * can simply refer to some variables defining the proper locations of these external JARs.
0950: * </p><p>
0951: * If it is specified that this operation cannot modify resources, the .classpath file will not be written to disk
0952: * and no error marker will be generated. To synchronize the .classpath with the in-memory classpath,
0953: * one can use <code>setRawClasspath(readRawClasspath(), true, monitor)</code>.
0954: * </p><p>
0955: * Setting the classpath to <code>null</code> specifies a default classpath
0956: * (the project root). Setting the classpath to an empty array specifies an
0957: * empty classpath.
0958: * </p><p>
0959: * If a cycle is detected while setting this classpath (and if resources can be modified), an error marker will be added
0960: * to the project closing the cycle.
0961: * To avoid this problem, use {@link #hasClasspathCycle(IClasspathEntry[])}
0962: * before setting the classpath.
0963: * <p>
0964: * This operation acquires a lock on the workspace's root.
0965: *
0966: * @param entries a list of classpath entries
0967: * @param canModifyResources whether resources should be written to disk if needed
0968: * @param monitor the given progress monitor
0969: * @exception JavaModelException if the classpath could not be set. Reasons include:
0970: * <ul>
0971: * <li> This Java element does not exist (ELEMENT_DOES_NOT_EXIST)</li>
0972: * <li> The classpath is being modified during resource change event notification (CORE_EXCEPTION)
0973: * <li> The classpath failed the validation check as defined by {@link JavaConventions#validateClasspath(IJavaProject, IClasspathEntry[], IPath)}
0974: * </ul>
0975: * @see IClasspathEntry
0976: * @since 3.2
0977: */
0978: void setRawClasspath(IClasspathEntry[] entries,
0979: boolean canModifyResources, IProgressMonitor monitor)
0980: throws JavaModelException;
0981:
0982: /**
0983: * Sets the classpath of this project using a list of classpath entries. In particular such a classpath may contain
0984: * classpath variable entries. Classpath variable entries can be resolved individually ({@link JavaCore#getClasspathVariable(String)}),
0985: * or the full classpath can be resolved at once using the helper method {@link #getResolvedClasspath(boolean)}.
0986: * <p>
0987: * A classpath variable provides an indirection level for better sharing a classpath. As an example, it allows
0988: * a classpath to no longer refer directly to external JARs located in some user specific location. The classpath
0989: * can simply refer to some variables defining the proper locations of these external JARs.
0990: * <p>
0991: * Setting the classpath to <code>null</code> specifies a default classpath
0992: * (the project root). Setting the classpath to an empty array specifies an
0993: * empty classpath.
0994: * <p>
0995: * If a cycle is detected while setting this classpath, an error marker will be added
0996: * to the project closing the cycle.
0997: * To avoid this problem, use {@link #hasClasspathCycle(IClasspathEntry[])}
0998: * before setting the classpath.
0999: * <p>
1000: * This operation acquires a lock on the workspace's root.
1001: *
1002: * @param entries a list of classpath entries
1003: * @param monitor the given progress monitor
1004: * @exception JavaModelException if the classpath could not be set. Reasons include:
1005: * <ul>
1006: * <li> This Java element does not exist (ELEMENT_DOES_NOT_EXIST)</li>
1007: * <li> The classpath is being modified during resource change event notification (CORE_EXCEPTION)
1008: * <li> The classpath failed the validation check as defined by {@link JavaConventions#validateClasspath(IJavaProject, IClasspathEntry[], IPath)}
1009: * </ul>
1010: * @see IClasspathEntry
1011: */
1012: void setRawClasspath(IClasspathEntry[] entries,
1013: IProgressMonitor monitor) throws JavaModelException;
1014:
1015: /**
1016: * Sets the both the classpath of this project and its default output
1017: * location at once. The classpath is defined using a list of classpath
1018: * entries. In particular, such a classpath may contain classpath variable
1019: * entries. Classpath variable entries can be resolved individually (see
1020: * ({@link JavaCore#getClasspathVariable(String)}), or the full classpath can be
1021: * resolved at once using the helper method
1022: * {@link #getResolvedClasspath(boolean)}.
1023: * <p>
1024: * A classpath variable provides an indirection level for better sharing a
1025: * classpath. As an example, it allows a classpath to no longer refer
1026: * directly to external JARs located in some user specific location. The
1027: * classpath can simply refer to some variables defining the proper
1028: * locations of these external JARs.
1029: * </p>
1030: * <p>
1031: * Setting the classpath to <code>null</code> specifies a default classpath
1032: * (the project root). Setting the classpath to an empty array specifies an
1033: * empty classpath.
1034: * </p>
1035: * <p>
1036: * If a cycle is detected while setting this classpath, an error marker will
1037: * be added to the project closing the cycle. To avoid this problem, use
1038: * {@link #hasClasspathCycle(IClasspathEntry[])} before setting
1039: * the classpath.
1040: * </p>
1041: * <p>
1042: * This operation acquires a lock on the workspace's root.
1043: * </p>
1044: *
1045: * @param entries a list of classpath entries
1046: * @param monitor the progress monitor
1047: * @param outputLocation the default output location
1048: * @exception JavaModelException if the classpath could not be set. Reasons
1049: * include:
1050: * <ul>
1051: * <li> This Java element does not exist (ELEMENT_DOES_NOT_EXIST)</li>
1052: * <li> Two or more entries specify source roots with the same or overlapping paths (NAME_COLLISION)
1053: * <li> A entry of kind <code>CPE_PROJECT</code> refers to this project (INVALID_PATH)
1054: * <li>This Java element does not exist (ELEMENT_DOES_NOT_EXIST)</li>
1055: * <li>The output location path refers to a location not contained in this project (<code>PATH_OUTSIDE_PROJECT</code>)
1056: * <li>The output location path is not an absolute path (<code>RELATIVE_PATH</code>)
1057: * <li>The output location path is nested inside a package fragment root of this project (<code>INVALID_PATH</code>)
1058: * <li> The classpath is being modified during resource change event notification (CORE_EXCEPTION)
1059: * </ul>
1060: * @see IClasspathEntry
1061: * @since 2.0
1062: */
1063: void setRawClasspath(IClasspathEntry[] entries,
1064: IPath outputLocation, IProgressMonitor monitor)
1065: throws JavaModelException;
1066: }
|