org.eclipse.jdt.core.IPackageFragment Maven / Gradle / Ivy
/*******************************************************************************
* 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.
*
* Package fragments elements need to be opened before they can be navigated or manipulated.
* The children are of type ICompilationUnit
(representing a source file) or
* IClassFile
(representing a binary class file).
* The children are listed in no particular order.
*
*
* @noimplement This interface is not intended to be implemented by clients.
*/
public interface IPackageFragment extends IParent, IJavaElement, IOpenable, ISourceManipulation {
/**
*
* The name of package fragment for the default package (value: the empty
* string, ""
).
*
*/
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.
*
* It is possible that a compilation unit with the same name already exists in this
* package fragment.
* The value of the force
parameter affects the resolution of
* such a conflict:
* -
true
- in this case the compilation is created with the new contents
* -
false
- in this case a JavaModelException
is thrown
*
*
* @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:
*
* - This Java element does not exist (ELEMENT_DOES_NOT_EXIST)
* - A
CoreException
occurred while creating an underlying resource
* - The name is not a valid compilation unit name (INVALID_NAME)
*
- The contents are
null
(INVALID_CONTENTS)
*
* @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, "Object.class"
).
* The ".class" suffix is required.
* This is a handle-only method. The class file may or may not be present.
*
* This method can handle ordinary class files or modular class files
* denoted by the name "module-info.class"
.
*
* @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, "Object.class"
).
* The ".class" suffix is required.
* This is a handle-only method. The class file may or may not be present.
*
* This method is not applicable to the files "module-info.class"
* as introduced in Java 9. For those please use {@link #getModularClassFile()}.
*
* @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 "module-info.class"
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.
*
* Note: it is possible that a package fragment contains only
* compilation units (in other words, its kind is K_SOURCE
), in
* which case this method returns an empty collection.
*
* Note: the returned list may contain ordinary class files as well as
* a modular class file (for "module-info.class").
*
* @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.
*
* Note: this list never includes a modular class file
* (see {@link #getModularClassFile()}).
*
* Note: it is possible that a package fragment contains only
* compilation units (in other words, its kind is K_SOURCE
), in
* which case this method returns an empty collection.
*
* @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".
*
* Note: it is possible that a package fragment contains only
* compilation units (in other words, its kind is K_SOURCE
), in
* which case this method returns an empty collection.
*
* @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, "Object.java"
).
* 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.
*
* Note: it is possible that a package fragment contains only
* class files (in other words, its kind is K_BINARY
), in which
* case this method returns an empty collection.
*
*
* @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.
*
* 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.
*
* Note: it is possible that a package fragment contains only
* class files (in other words, its kind is K_BINARY
), in which
* case this method returns an empty collection.
*
*
* @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
* "java.lang"
, or ""
(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 .class
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.
*
* 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).
*
* 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.
*
*
* @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 (IFile
s,
* IFolder
s, or IStorage
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();
}