org.eclipse.jdt/org.eclipse.jdt.core/3.20.0 : org/eclipse/jdt/core/IPackageFragment.java

IPackageFragment
http://www.eclipse.org/jdt: Java Development Tools Core (Eclipse Foundation)
Eclipse Public License - v 2.0
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
/*******************************************************************************
 * 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./**
 * 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 {

	
The name of package fragment for the default package (value: the empty
string, "").

/**
	 * <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.
Throws: JavaModelException – if this element does not exist or if an
	exception occurs while accessing its corresponding resource.
Returns: true if this fragment contains at least one Java resource, false otherwise/**
	 * 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

Params: contents – the given contents
force – specify how to handle conflict is the same name already exists
monitor – the given progress monitor
name – the given name
Throws: 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)
Returns: a compilation unit in this package fragment
with the specified name and contents/**
	 * 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, "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".

Params: name – the given name
Returns: the class file with the specified name in this package/**
	 * 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, "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 getModularClassFile(). 
Params: name – the given name
Returns: the class file with the specified name in this package
Since: 3.14/**
	 * 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 "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 IModuleDescription. 
Since: 3.14
Returns: the class file representing "module-info.class" in this package./**
	 * 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.
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").
Throws: JavaModelException – if this element does not exist or if an
	exception occurs while accessing its corresponding resource.
Returns: all of the class files in this package fragment
Since: 3.14/**
	 * 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.
Note: this list never includes a modular class file (see 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.
Throws: JavaModelException – if this element does not exist or if an
	exception occurs while accessing its corresponding resource.
Returns: all of the ordinary class files in this package fragment
Deprecated: Clients are advised to specifically use either getOrdinaryClassFiles() or getAllClassFiles() to express their intent./**
	 * 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".
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.
Throws: JavaModelException – if this element does not exist or if an
	exception occurs while accessing its corresponding resource.
Returns: all of the ordinary class files in this package fragment
Since: 3.14/**
	 * 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, "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.
Params: name – the given name
See Also: JavaConventions.validateCompilationUnitName(String name, String sourceLevel, String complianceLevel)
Returns: the compilation unit with the specified name in this package/**
	 * 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.
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.

Throws: JavaModelException – if this element does not exist or if an
	exception occurs while accessing its corresponding resource.
Returns: all of the compilation units in this package fragment/**
	 * 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.

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.

Params: owner – the owner of the returned compilation units
Throws: JavaModelException – if this element does not exist or if an
	exception occurs while accessing its corresponding resource.
Returns: all of the compilation units in this package fragment
Since: 3.0/**
	 * 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
"java.lang", or "" (the empty string),
for the default package.
Returns: the dot-separated package name of this fragment/**
	 * 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 Java-like extensions), or .class files. This is a convenience method.
Throws: JavaModelException – if this element does not exist or if an
	exception occurs while accessing its corresponding resource.
See Also: IPackageFragmentRoot.K_SOURCE
IPackageFragmentRoot.K_BINARY
Returns: this package fragment's root kind encoded as an integer/**
	 * 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.

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 IJarEntryResources. One can navigate this tree using the IJarEntryResource.getChildren() and IJarEntryResource.getParent() methods. 
Throws: JavaModelException – if this element does not exist or if an
	exception occurs while accessing its corresponding resource.
See Also: IClasspathEntry.getInclusionPatterns()
IClasspathEntry.getExclusionPatterns()
Returns: an array of non-Java resources (IFiles,
             IFolders, or IStorages if the
             package fragment is in an archive) contained in this package
             fragment/**
	 * 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.
Throws: JavaModelException – if this element does not exist or if an
	exception occurs while accessing its corresponding resource.
Returns: true if this package fragment's name is a prefix of other package fragments in this package fragment's root, false otherwise/**
	 * 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.
Returns: true if this package fragment is a default package/**
	 * 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();
}
Throws:	JavaModelException – if this element does not exist or if an exception occurs while accessing its corresponding resource.
Returns:	true if this fragment contains at least one Java resource, false otherwise
Params:	contents – the given contents force – specify how to handle conflict is the same name already exists monitor – the given progress monitor name – the given name
Throws:	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)
Returns:	a compilation unit in this package fragment with the specified name and contents
Params:	name – the given name
Returns:	the class file with the specified name in this package
Since:	3.14
Returns:	the class file representing "module-info.class" in this package.
Params:	name – the given name
See Also:	JavaConventions.validateCompilationUnitName(String name, String sourceLevel, String complianceLevel)
Returns:	the compilation unit with the specified name in this package
Params:	owner – the owner of the returned compilation units
Throws:	JavaModelException – if this element does not exist or if an exception occurs while accessing its corresponding resource.
Returns:	all of the compilation units in this package fragment
Since:	3.0
/

org.eclipse.jdt/ org.eclipse.jdt.core/ 3.20.0/ org/eclipse/jdt/core/IPackageFragment.java
