/*******************************************************************************
* Copyright (c) 2000, 2003 IBM Corporation and others.
* All rights reserved. This program and the accompanying materials
* are made available under the terms of the Common Public License v1.0
* which accompanies this distribution, and is available at
* http://www.eclipse.org/legal/cpl-v10.html
*
* Contributors:
* IBM Corporation - initial API and implementation
* IBM Corporation - specified that a source archive or a source folder can be attached to a binary
* package fragment root.
* IBM Corporation - added root manipulation APIs: copy, delete, move
* IBM Corporation - added DESTINATION_PROJECT_CLASSPATH
* IBM Corporation - added OTHER_REFERRING_PROJECTS_CLASSPATH
* IBM Corporation - added NO_RESOURCE_MODIFICATION
* IBM Corporation - added REPLACE
* IBM Corporation - added ORIGINATING_PROJECT_CLASSPATH
*******************************************************************************/
package net.sourceforge.phpdt.core;
/**
* A package fragment root contains a set of package fragments.
* It corresponds to an underlying resource which is either a folder,
* JAR, or zip. In the case of a folder, all descendant folders represent
* package fragments. For a given child folder representing a package fragment,
* the corresponding package name is composed of the folder names between the folder
* for this root and the child folder representing the package, separated by '.'.
* In the case of a JAR or zip, the contents of the archive dictates
* the set of package fragments in an analogous manner.
* Package fragment roots need to be opened before they can be navigated or manipulated.
* The children are of type IPackageFragment
, and are in no particular order.
*
* This interface is not intended to be implemented by clients. *
*/ public interface IPackageFragmentRoot extends IParent, IJavaElement, IOpenable { /** * Kind constant for a source path root. Indicates this root * only contains source files. */ int K_SOURCE = 1; /** * Kind constant for a binary path root. Indicates this * root only contains binary files. */ int K_BINARY = 2; /** * Empty root path */ String DEFAULT_PACKAGEROOT_PATH = ""; //$NON-NLS-1$ /** * Update model flag constant (bit mask value 1) indicating that the operation * is to not copy/move/delete the package fragment root resource. * @since 2.1 */ int NO_RESOURCE_MODIFICATION = 1; /** * Update model flag constant (bit mask value 2) indicating that the operation * is to update the classpath of the originating project. * @since 2.1 */ int ORIGINATING_PROJECT_CLASSPATH = 2; /** * Update model flag constant (bit mask value 4) indicating that the operation * is to update the classpath of all referring projects except the originating project. * @since 2.1 */ int OTHER_REFERRING_PROJECTS_CLASSPATH = 4; /** * Update model flag constant (bit mask value 8) indicating that the operation * is to update the classpath of the destination project. * @since 2.1 */ int DESTINATION_PROJECT_CLASSPATH = 8; /** * Update model flag constant (bit mask value 16) indicating that the operation * is to replace the resource and the destination project's classpath entry. * @since 2.1 */ int REPLACE = 16; /** * Attaches the source archive identified by the given absolute path to this * binary package fragment root.rootPath
specifies the location
* of the root within the archive or folder (empty specifies the default root
* and null
specifies the root path should be detected).
* Once a source archive or folder is attached to the package fragment root,
* the getSource
and getSourceRange
* methods become operational for binary types/members.
* To detach a source archive or folder from a package fragment root, specify
* null
as the source path.
*
* @param sourcePath the given absolute path to the source archive or folder
* @param rootPath specifies the location of the root within the archive
* (empty specifies the default root and null
specifies
* automatic detection of the root path)
* @param monitor the given progress monitor
* @exception JavaModelException if this operation fails. Reasons include:
* CoreException
occurred while updating a server property
* IResource.copy(IPath, int, IProgressMonitor)
* but excluding nested source folders.
*
* If NO_RESOURCE_MODIFICATION
is specified in
* updateModelFlags
or if this package fragment root is external,
* this operation doesn't copy the resource. updateResourceFlags
* is then ignored.
*
* If DESTINATION_PROJECT_CLASSPATH
is specified in
* updateModelFlags
, updates the classpath of the
* destination's project (if it is a Java project). If a non-null
* sibling is specified, a copy of this root's classpath entry is inserted before the
* sibling on the destination project's raw classpath. If null
is
* specified, the classpath entry is added at the end of the raw classpath.
*
* If REPLACE
is specified in updateModelFlags
,
* overwrites the resource at the destination path if any.
* If the same classpath entry already exists on the destination project's raw
* classpath, then the sibling is ignored and the new classpath entry replaces the
* existing one.
*
* If no flags is specified in updateModelFlags
(using
* IResource.NONE
), the default behavior applies: the
* resource is copied (if this package fragment root is not external) and the
* classpath is not updated.
*
IResource.FORCE
and IResource.SHALLOW
)
* @param updateModelFlags bit-wise or of update resource flag constants
* (DESTINATION_PROJECT_CLASSPATH
and
* NO_RESOURCE_MODIFICATION
)
* @param sibling the classpath entry before which a copy of the classpath
* entry should be inserted or null
if the classpath entry should
* be inserted at the end
* @param monitor a progress monitor
*
* @exception JavaModelException if this root could not be copied. Reasons
* include:
* CoreException
occurred while copying the
* resource or updating a classpathupdateModelFlags
* has been specified as DESTINATION_PROJECT_CLASSPATH
* (INVALID_DESTINATION)updateModelFlags
* has not been specified as REPLACE
force
flag, see IFolder.create
.
*
* @param name the given dot-separated package name
* @param force a flag controlling how to deal with resources that
* are not in sync with the local file system
* @param monitor the given progress monitor
* @exception JavaModelException if the element could not be created. Reasons include:
* CoreException
occurred while creating an underlying resource
* IResource.delete(int, IProgressMonitor)
but excluding nested
* source folders.
*
* If NO_RESOURCE_MODIFICATION
is specified in
* updateModelFlags
or if this package fragment root is external,
* this operation doesn't delete the resource. updateResourceFlags
* is then ignored.
*
* If ORIGINATING_PROJECT_CLASSPATH
is specified in
* updateModelFlags
, update the raw classpath of this package
* fragment root's project by removing the corresponding classpath entry.
*
* If OTHER_REFERRING_PROJECTS_CLASSPATH
is specified in
* updateModelFlags
, update the raw classpaths of all other Java
* projects referring to this root's resource by removing the corresponding classpath
* entries.
*
* If no flags is specified in updateModelFlags
(using
* IResource.NONE
), the default behavior applies: the
* resource is deleted (if this package fragment root is not external) and no
* classpaths are updated.
*
IResource.FORCE
and IResource.KEEP_HISTORY
)
* @param updateModelFlags bit-wise or of update resource flag constants
* (ORIGINATING_PROJECT_CLASSPATH
,
* OTHER_REFERRING_PROJECTS_CLASSPATH
and
* NO_RESOURCE_MODIFICATION
)
* @param monitor a progress monitor
*
* @exception JavaModelException if this root could not be deleted. Reasons
* include:
* CoreException
occurred while deleting the resource
* or updating a classpath
* .java
source files,
* or .class
files, but not both.
* If the underlying folder or archive contains other kinds of files, they are ignored.
* In particular, .class
files are ignored under a source package fragment root,
* and .java
files are ignored under a binary package fragment root.
*
* @see IPackageFragmentRoot#K_SOURCE
* @see IPackageFragmentRoot#K_BINARY
*
* @exception JavaModelException if this element does not exist or if an
* exception occurs while accessing its corresponding resource.
* @return this package fragment root's kind encoded as an integer
*/
int getKind() throws JavaModelException;
/**
* Returns an array of non-Java resources contained in this package fragment root.
* * Non-Java resources includes other files and folders located in the same * directories as the compilation units or class files under this package * fragment root. Resources excluded from this package fragment root * by one or more exclusion patterns on the corresponding source classpath * entry are considered non-Java resources and will appear in the result * (possibly in a folder). Thus when a nested source folder is excluded, it will appear * in the non-Java resources of the outer folder. *
* @return an array of non-Java resources contained in this package fragment root * @see IClasspathEntry#getExclusionPatterns */ // Object[] getNonJavaResources() throws JavaModelException; /** * Returns the package fragment with the given package name. * An empty string indicates the default package. * This is a handle-only operation. The package fragment * may or may not exist. * * @param packageName the given package name * @return the package fragment with the given package name */ IPackageFragment getPackageFragment(String packageName); /** * Returns the first raw classpath entry that corresponds to this package * fragment root. * A raw classpath entry corresponds to a package fragment root if once resolved * this entry's path is equal to the root's path. * * @exception JavaModelException if this element does not exist or if an * exception occurs while accessing its corresponding resource. * @return the first raw classpath entry that corresponds to this package fragment root * @since 2.0 */ // IClasspathEntry getRawClasspathEntry() throws JavaModelException; /** * Returns the absolute path to the source archive attached to * this package fragment root's binary archive. * * @return the absolute path to the corresponding source archive, * ornull
if this package fragment root's binary archive
* has no corresponding source archive, or if this package fragment root
* is not a binary archive
* @exception JavaModelException if this operation fails
*/
// IPath getSourceAttachmentPath() throws JavaModelException;
/**
* Returns the path within this package fragment root's source archive.
* An empty path indicates that packages are located at the root of the
* source archive.
*
* @return the path within the corresponding source archive,
* or null
if this package fragment root's binary archive
* has no corresponding source archive, or if this package fragment root
* is not a binary archive
* @exception JavaModelException if this operation fails
*/
// IPath getSourceAttachmentRootPath() throws JavaModelException;
/**
* Returns whether this package fragment root's underlying
* resource is a binary archive (a JAR or zip file).
*
* @return true if this package fragment root's underlying resource is a binary archive, false otherwise
*/
public boolean isArchive();
/**
* Returns whether this package fragment root is external
* to the workbench (that is, a local file), and has no
* underlying resource.
*
* @return true if this package fragment root is external
* to the workbench (that is, a local file), and has no
* underlying resource, false otherwise
*/
boolean isExternal();
/**
* Moves the resource of this package fragment root to the destination path
* as specified by IResource.move(IPath,int,IProgressMonitor)
* but excluding nested source folders.
*
* If NO_RESOURCE_MODIFICATION
is specified in
* updateModelFlags
or if this package fragment root is external,
* this operation doesn't move the resource. updateResourceFlags
* is then ignored.
*
* If DESTINATION_PROJECT_CLASSPATH
is specified in
* updateModelFlags
, updates the classpath of the
* destination's project (if it is a Java project). If a non-null
* sibling is specified, a copy of this root's classpath entry is inserted before the
* sibling on the destination project's raw classpath. If null
is
* specified, the classpath entry is added at the end of the raw classpath.
*
* If ORIGINATING_PROJECT_CLASSPATH
is specified in
* updateModelFlags
, update the raw classpath of this package
* fragment root's project by removing the corresponding classpath entry.
*
* If OTHER_REFERRING_PROJECTS_CLASSPATH
is specified in
* updateModelFlags
, update the raw classpaths of all other Java
* projects referring to this root's resource by removing the corresponding classpath
* entries.
*
* If REPLACE
is specified in updateModelFlags
,
* overwrites the resource at the destination path if any.
* If the same classpath entry already exists on the destination project's raw
* classpath, then the sibling is ignored and the new classpath entry replaces the
* existing one.
*
* If no flags is specified in updateModelFlags
(using
* IResource.NONE
), the default behavior applies: the
* resource is moved (if this package fragment root is not external) and no
* classpaths are updated.
*
IResource.FORCE
, IResource.KEEP_HISTORY
* and IResource.SHALLOW
)
* @param updateModelFlags bit-wise or of update resource flag constants
* (DESTINATION_PROJECT_CLASSPATH
,
* ORIGINATING_PROJECT_CLASSPATH
,
* OTHER_REFERRING_PROJECTS_CLASSPATH
and
* NO_RESOURCE_MODIFICATION
)
* @param sibling the classpath entry before which a copy of the classpath
* entry should be inserted or null
if the classpath entry should
* be inserted at the end
* @param monitor a progress monitor
*
* @exception JavaModelException if this root could not be moved. Reasons
* include:
* CoreException
occurred while copying the
* resource or updating a classpathupdateModelFlags
* has been specified as DESTINATION_PROJECT_CLASSPATH
* (INVALID_DESTINATION)updateModelFlags
* has not been specified as REPLACE