| /******************************************************************************* |
| * Copyright (c) 2000, 2017 IBM Corporation and others. |
| * |
| * This program and the accompanying materials |
| * are made available under the terms of the Eclipse Public License 2.0 |
| * which accompanies this distribution, and is available at |
| * https://www.eclipse.org/legal/epl-2.0/ |
| * |
| * SPDX-License-Identifier: EPL-2.0 |
| * |
| * Contributors: |
| * IBM Corporation - initial API and implementation |
| *******************************************************************************/ |
| package org.eclipse.jdt.core; |
| |
| import org.eclipse.core.runtime.IProgressMonitor; |
| |
| /** |
| * A package fragment is a portion of the workspace corresponding to an entire package, |
| * or to a portion thereof. The distinction between a package fragment and a package |
| * is that a package with some name is the union of all package fragments in the class path |
| * which have the same name. |
| * <p> |
| * Package fragments elements need to be opened before they can be navigated or manipulated. |
| * The children are of type <code>ICompilationUnit</code> (representing a source file) or |
| * <code>IClassFile</code> (representing a binary class file). |
| * The children are listed in no particular order. |
| * </p> |
| * |
| * @noimplement This interface is not intended to be implemented by clients. |
| */ |
| public interface IPackageFragment extends IParent, IJavaElement, IOpenable, ISourceManipulation { |
| |
| /** |
| * <p> |
| * The name of package fragment for the default package (value: the empty |
| * string, <code>""</code>). |
| * </p> |
| */ |
| public static final String DEFAULT_PACKAGE_NAME = ""; //$NON-NLS-1$ |
| /** |
| * Returns whether this fragment contains at least one Java resource. |
| * @return true if this fragment contains at least one Java resource, false otherwise |
| * @exception JavaModelException if this element does not exist or if an |
| * exception occurs while accessing its corresponding resource. |
| */ |
| boolean containsJavaResources() throws JavaModelException; |
| /** |
| * Creates and returns a compilation unit in this package fragment |
| * with the specified name and contents. No verification is performed |
| * on the contents. |
| * |
| * <p>It is possible that a compilation unit with the same name already exists in this |
| * package fragment. |
| * The value of the <code>force</code> parameter affects the resolution of |
| * such a conflict:<ul> |
| * <li> <code>true</code> - in this case the compilation is created with the new contents</li> |
| * <li> <code>false</code> - in this case a <code>JavaModelException</code> is thrown</li> |
| * </ul> |
| * |
| * @param contents the given contents |
| * @param force specify how to handle conflict is the same name already exists |
| * @param monitor the given progress monitor |
| * @param name the given name |
| * @exception JavaModelException if the element could not be created. Reasons include: |
| * <ul> |
| * <li> This Java element does not exist (ELEMENT_DOES_NOT_EXIST)</li> |
| * <li> A <code>CoreException</code> occurred while creating an underlying resource |
| * <li> The name is not a valid compilation unit name (INVALID_NAME) |
| * <li> The contents are <code>null</code> (INVALID_CONTENTS) |
| * </ul> |
| * @return a compilation unit in this package fragment |
| * with the specified name and contents |
| */ |
| ICompilationUnit createCompilationUnit(String name, String contents, boolean force, IProgressMonitor monitor) throws JavaModelException; |
| /** |
| * Returns the class file with the specified name |
| * in this package (for example, <code>"Object.class"</code>). |
| * The ".class" suffix is required. |
| * This is a handle-only method. The class file may or may not be present. |
| * <p> |
| * This method can handle ordinary class files or modular class files |
| * denoted by the name <code>"module-info.class"</code>. |
| * </p> |
| * @param name the given name |
| * @return the class file with the specified name in this package |
| */ |
| IClassFile getClassFile(String name); |
| /** |
| * Returns the class file with the specified name |
| * in this package (for example, <code>"Object.class"</code>). |
| * The ".class" suffix is required. |
| * This is a handle-only method. The class file may or may not be present. |
| * <p> |
| * This method is not applicable to the files <code>"module-info.class"</code> |
| * as introduced in Java 9. For those please use {@link #getModularClassFile()}. |
| * </p> |
| * @param name the given name |
| * @return the class file with the specified name in this package |
| * @since 3.14 |
| */ |
| IOrdinaryClassFile getOrdinaryClassFile(String name); |
| |
| /** |
| * Returns the class file for <code>"module-info.class"</code> in this package. |
| * This is a handle-only method. The class file may or may not be present. |
| * If the class file is present, then it is guaranteed to contain an {@link IModuleDescription}. |
| * |
| * @since 3.14 |
| * @return the class file representing "module-info.class" in this package. |
| */ |
| IModularClassFile getModularClassFile(); |
| |
| /** |
| * Returns all of the class files in this package fragment. |
| * |
| * <p>Note: it is possible that a package fragment contains only |
| * compilation units (in other words, its kind is <code>K_SOURCE</code>), in |
| * which case this method returns an empty collection.</p> |
| * |
| * <p>Note: the returned list may contain ordinary class files as well as |
| * a modular class file (for "module-info.class").</p> |
| * |
| * @exception JavaModelException if this element does not exist or if an |
| * exception occurs while accessing its corresponding resource. |
| * @return all of the class files in this package fragment |
| * @since 3.14 |
| */ |
| IClassFile[] getAllClassFiles() throws JavaModelException; |
| |
| /** |
| * Returns all of the ordinary class files in this package fragment. |
| * |
| * <p>Note: this list never includes a modular class file |
| * (see {@link #getModularClassFile()}).</p> |
| * |
| * <p>Note: it is possible that a package fragment contains only |
| * compilation units (in other words, its kind is <code>K_SOURCE</code>), in |
| * which case this method returns an empty collection.</p> |
| * |
| * @exception JavaModelException if this element does not exist or if an |
| * exception occurs while accessing its corresponding resource. |
| * @return all of the ordinary class files in this package fragment |
| * @deprecated Clients are advised to specifically use either {@link #getOrdinaryClassFiles()} |
| * or {@link #getAllClassFiles()} to express their intent. |
| */ |
| @Deprecated |
| IClassFile[] getClassFiles() throws JavaModelException; |
| /** |
| * Returns all of the ordinary class files in this package fragment, |
| * i.e., not including the modular class file "module-info.class". |
| * |
| * <p>Note: it is possible that a package fragment contains only |
| * compilation units (in other words, its kind is <code>K_SOURCE</code>), in |
| * which case this method returns an empty collection.</p> |
| * |
| * @exception JavaModelException if this element does not exist or if an |
| * exception occurs while accessing its corresponding resource. |
| * @return all of the ordinary class files in this package fragment |
| * @since 3.14 |
| */ |
| IOrdinaryClassFile[] getOrdinaryClassFiles() throws JavaModelException; |
| |
| /** |
| * Returns the compilation unit with the specified name |
| * in this package (for example, <code>"Object.java"</code>). |
| * The name has to be a valid compilation unit name. |
| * This is a handle-only method. The compilation unit may or may not be present. |
| * |
| * @param name the given name |
| * @return the compilation unit with the specified name in this package |
| * @see JavaConventions#validateCompilationUnitName(String name, String sourceLevel, String complianceLevel) |
| */ |
| ICompilationUnit getCompilationUnit(String name); |
| /** |
| * Returns all of the compilation units in this package fragment. |
| * |
| * <p>Note: it is possible that a package fragment contains only |
| * class files (in other words, its kind is <code>K_BINARY</code>), in which |
| * case this method returns an empty collection. |
| * </p> |
| * |
| * @exception JavaModelException if this element does not exist or if an |
| * exception occurs while accessing its corresponding resource. |
| * @return all of the compilation units in this package fragment |
| */ |
| ICompilationUnit[] getCompilationUnits() throws JavaModelException; |
| /** |
| * Returns all of the compilation units in this package fragment that are |
| * in working copy mode and that have the given owner. |
| * <p> |
| * Only existing working copies are returned. So a compilation unit handle that has no |
| * corresponding resource on disk will be included if and only if is in working copy mode. |
| * </p> |
| * <p>Note: it is possible that a package fragment contains only |
| * class files (in other words, its kind is <code>K_BINARY</code>), in which |
| * case this method returns an empty collection. |
| * </p> |
| * |
| * @param owner the owner of the returned compilation units |
| * @exception JavaModelException if this element does not exist or if an |
| * exception occurs while accessing its corresponding resource. |
| * @return all of the compilation units in this package fragment |
| * @since 3.0 |
| */ |
| ICompilationUnit[] getCompilationUnits(WorkingCopyOwner owner) throws JavaModelException; |
| /** |
| * Returns the dot-separated package name of this fragment, for example |
| * <code>"java.lang"</code>, or <code>""</code> (the empty string), |
| * for the default package. |
| * |
| * @return the dot-separated package name of this fragment |
| */ |
| @Override |
| String getElementName(); |
| /** |
| * Returns this package fragment's root kind encoded as an integer. |
| * A package fragment can contain source files (i.e. files with one of |
| * the {@link JavaCore#getJavaLikeExtensions() Java-like extensions}), |
| * or <code>.class</code> files. This is a convenience method. |
| * |
| * @exception JavaModelException if this element does not exist or if an |
| * exception occurs while accessing its corresponding resource. |
| * @return this package fragment's root kind encoded as an integer |
| * @see IPackageFragmentRoot#K_SOURCE |
| * @see IPackageFragmentRoot#K_BINARY |
| */ |
| int getKind() throws JavaModelException; |
| /** |
| * Returns an array of non-Java resources contained in this package fragment. |
| * <p> |
| * Non-Java resources includes other files and folders located in the same |
| * directory as the compilation units or class files for this package |
| * fragment. Source files excluded from this package by virtue of |
| * inclusion/exclusion patterns on the corresponding source classpath entry |
| * are considered non-Java resources and will appear in the result |
| * (possibly in a folder). |
| * </p><p> |
| * Since 3.3, if this package fragment is inside an archive, the non-Java resources |
| * are a tree of {@link IJarEntryResource}s. One can navigate this tree using |
| * the {@link IJarEntryResource#getChildren()} and |
| * {@link IJarEntryResource#getParent()} methods. |
| * </p> |
| * |
| * @exception JavaModelException if this element does not exist or if an |
| * exception occurs while accessing its corresponding resource. |
| * @return an array of non-Java resources (<code>IFile</code>s, |
| * <code>IFolder</code>s, or <code>IStorage</code>s if the |
| * package fragment is in an archive) contained in this package |
| * fragment |
| * @see IClasspathEntry#getInclusionPatterns() |
| * @see IClasspathEntry#getExclusionPatterns() |
| */ |
| Object[] getNonJavaResources() throws JavaModelException; |
| /** |
| * Returns whether this package fragment's name is |
| * a prefix of other package fragments in this package fragment's |
| * root. |
| * |
| * @exception JavaModelException if this element does not exist or if an |
| * exception occurs while accessing its corresponding resource. |
| * @return true if this package fragment's name is a prefix of other package fragments in this package fragment's root, false otherwise |
| */ |
| boolean hasSubpackages() throws JavaModelException; |
| /** |
| * Returns whether this package fragment is a default package. |
| * This is a handle-only method. |
| * |
| * @return true if this package fragment is a default package |
| */ |
| boolean isDefaultPackage(); |
| } |