org.eclipse.jdt.core.IJavaModel Maven / Gradle / Ivy

/*******************************************************************************
 * Copyright (c) 2000, 2011 IBM Corporation and others.
 * All rights reserved. This program and the accompanying materials
 * are made available under the terms of the Eclipse Public License v1.0
 * which accompanies this distribution, and is available at
 * http://www.eclipse.org/legal/epl-v10.html
 *
 * Contributors:
 *     IBM Corporation - initial API and implementation
 *******************************************************************************/
package org.eclipse.jdt.core;

import org.eclipse.core.resources.IResource;
import org.eclipse.core.resources.IWorkspace;
import org.eclipse.core.runtime.IPath;
import org.eclipse.core.runtime.IProgressMonitor;

/**
 * Represent the root Java element corresponding to the workspace.
 * Since there is only one such root element, it is commonly referred to as
 * the Java model element.
 * The Java model element needs to be opened before it can be navigated or manipulated.
 * The Java model element has no parent (it is the root of the Java element
 * hierarchy). Its children are IJavaProjects.
 * 
 * This interface provides methods for performing copy, move, rename, and
 * delete operations on multiple Java elements.
 * 
 * 
 * An instance of one of these handles can be created via
 * JavaCore.create(workspace.getRoot()).
 * 
 *
 * @see JavaCore#create(org.eclipse.core.resources.IWorkspaceRoot)
 * @noimplement This interface is not intended to be implemented by clients.
 */
public interface IJavaModel extends IJavaElement, IOpenable, IParent {
/**
 * Returns whether this Java model contains an IJavaElement whose
 * resource is the given resource or a non-Java resource which is the given resource.
 * 
 * Note: no existency check is performed on the argument resource. If it is not accessible
 * (see IResource.isAccessible()) yet but would be located in Java model
 * range, then it will return true.
 * 

 * If the resource is accessible, it can be reached by navigating the Java model down using the
 * getChildren() and/or getNonJavaResources() methods.
 * 
 * @param resource the resource to check
 * @return true if the resource is accessible through the Java model
 * @since 2.1
 */
boolean contains(IResource resource);
/**
 * Copies the given elements to the specified container(s).
 * If one container is specified, all elements are copied to that
 * container. If more than one container is specified, the number of
 * elements and containers must match, and each element is copied to
 * its associated container.
 * 
 * Optionally, each copy can positioned before a sibling
 * element. If null is specified for a given sibling, the copy
 * is inserted as the last child of its associated container.
 * 
 * 
 * Optionally, each copy can be renamed. If
 * null is specified for the new name, the copy
 * is not renamed.
 * 
 * 
 * Optionally, any existing child in the destination container with
 * the same name can be replaced by specifying true for
 * force. Otherwise an exception is thrown in the event that a name
 * collision occurs.
 * 
 *
 * @param elements the elements to copy
 * @param containers the container, or list of containers
 * @param siblings the list of siblings element any of which may be
 *   null; or null
 * @param renamings the list of new names any of which may be
 *   null; or null
 * @param replace true if any existing child in a target container
 *   with the target name should be replaced, and false to throw an
 *   exception in the event of a name collision
 * @param monitor a progress monitor
 * @exception JavaModelException if an element could not be copied. Reasons include:
 * 
 *  There is no element to process (NO_ELEMENTS_TO_PROCESS). The given elements is null or empty
 *  A specified element, container, or sibling does not exist (ELEMENT_DOES_NOT_EXIST)
 *  A CoreException occurred while updating an underlying resource
 *  A container is of an incompatible type (INVALID_DESTINATION)
 *  A sibling is not a child of it associated container (INVALID_SIBLING)
 *  A new name is invalid (INVALID_NAME)
 *  A child in its associated container already exists with the same
 * 		name and replace has been specified as false (NAME_COLLISION)
 *  A container or element is read-only (READ_ONLY) 
 * 
 * @see org.eclipse.jdt.core.IJavaModelStatusConstants#INVALID_DESTINATION
 */
void copy(IJavaElement[] elements, IJavaElement[] containers, IJavaElement[] siblings, String[] renamings, boolean replace, IProgressMonitor monitor) throws JavaModelException;
/**
 * Deletes the given elements, forcing the operation if necessary and specified.
 *
 * @param elements the elements to delete
 * @param force a flag controlling whether underlying resources that are not
 *    in sync with the local file system will be tolerated
 * @param monitor a progress monitor
 * @exception JavaModelException if an element could not be deleted. Reasons include:
 * 
 *  There is no element to process (NO_ELEMENTS_TO_PROCESS). The given elements is null or empty
 *  A specified element does not exist (ELEMENT_DOES_NOT_EXIST)
 *  A CoreException occurred while updating an underlying resource
 *  An element is read-only (READ_ONLY) 
 * 
 */
void delete(IJavaElement[] elements, boolean force, IProgressMonitor monitor) throws JavaModelException;
/**
 * Returns the Java project with the given name. The given name must be a valid
 * path segment as defined by {@link IPath#isValidSegment(String)}.
 * This is a handle-only method.
 * The project may or may not exist.
 *
 * @param name the name of the Java project
 * @return the Java project with the given name
 */
IJavaProject getJavaProject(String name);
/**
 * Returns the Java projects in this Java model, or an empty array if there
 * are none.
 *
 * @return the Java projects in this Java model, or an empty array if there
 * are none
 * @exception JavaModelException if this request fails.
 */
IJavaProject[] getJavaProjects() throws JavaModelException;
/**
 * Returns an array of non-Java resources (that is, non-Java projects) in
 * the workspace.
 * 
 * Non-Java projects include all projects that are closed (even if they have the
 * Java nature).
 * 
 *
 * @return an array of non-Java projects (IProjects) contained
 *              in the workspace.
 * @throws JavaModelException if this element does not exist or if an
 *		exception occurs while accessing its corresponding resource
 * @since 2.1
 */
Object[] getNonJavaResources() throws JavaModelException;
/**
 * Returns the workspace associated with this Java model.
 *
 * @return the workspace associated with this Java model
 */
IWorkspace getWorkspace();
/**
 * Moves the given elements to the specified container(s).
 * If one container is specified, all elements are moved to that
 * container. If more than one container is specified, the number of
 * elements and containers must match, and each element is moved to
 * its associated container.
 * 
 * Optionally, each element can positioned before a sibling
 * element. If null is specified for sibling, the element
 * is inserted as the last child of its associated container.
 * 
 * 
 * Optionally, each element can be renamed. If
 * null is specified for the new name, the element
 * is not renamed.
 * 
 * 
 * Optionally, any existing child in the destination container with
 * the same name can be replaced by specifying true for
 * force. Otherwise an exception is thrown in the event that a name
 * collision occurs.
 * 
 *
 * @param elements the elements to move
 * @param containers the container, or list of containers
 * @param siblings the list of siblings element any of which may be
 *   null; or null
 * @param renamings the list of new names any of which may be
 *   null; or null
 * @param replace true if any existing child in a target container
 *   with the target name should be replaced, and false to throw an
 *   exception in the event of a name collision
 * @param monitor a progress monitor
 * @exception JavaModelException if an element could not be moved. Reasons include:
 * 
 *  There is no element to process (NO_ELEMENTS_TO_PROCESS). The given elements is null or empty
 *  A specified element, container, or sibling does not exist (ELEMENT_DOES_NOT_EXIST)
 *  A CoreException occurred while updating an underlying resource
 *  A container is of an incompatible type (INVALID_DESTINATION)
 *  A sibling is not a child of it associated container (INVALID_SIBLING)
 *  A new name is invalid (INVALID_NAME)
 *  A child in its associated container already exists with the same
 * 		name and replace has been specified as false (NAME_COLLISION)
 *  A container or element is read-only (READ_ONLY) 
 * 
 *
 * @exception IllegalArgumentException any element or container is null
 * @see org.eclipse.jdt.core.IJavaModelStatusConstants#INVALID_DESTINATION
 */
void move(IJavaElement[] elements, IJavaElement[] containers, IJavaElement[] siblings, String[] renamings, boolean replace, IProgressMonitor monitor) throws JavaModelException;

/**
 * Triggers an update of the JavaModel with respect to the referenced external archives.
 * This operation will issue a JavaModel delta describing the discovered changes, in term
 * of Java element package fragment roots added, removed or changed.
 * Note that a collection of elements can be passed so as to narrow the set of archives
 * to refresh (passing null along is equivalent to refreshing the entire mode).
 * The elements can be:
 * 
 *  package fragment roots corresponding to external archives
 * 
 Java projects, which referenced external archives will be refreshed
 * 
 Java model, all referenced external archives will be refreshed.
 * 
 *  In case an archive is used by multiple projects, the delta issued will account for
 * all of them. This means that even if a project was not part of the elements scope, it
 * may still be notified of changes if it is referencing a library comprised in the scope.
 * 

 * Since 3.7, a project refresh automatically triggers a refresh of external archives.
 * Hence, this method doesn't need to be explicitly called after a project refresh.
 * 

 * @param elementsScope - a collection of elements defining the scope of the refresh
 * @param monitor - a progress monitor used to report progress
 * @exception JavaModelException in one of the corresponding situation:
 * 

 *     an exception occurs while accessing project resources 
 * 
 *
 * @see IJavaElementDelta
 * @since 2.0
 */
void refreshExternalArchives(IJavaElement[] elementsScope, IProgressMonitor monitor) throws JavaModelException;

/**
 * Renames the given elements as specified.
 * If one container is specified, all elements are renamed within that
 * container. If more than one container is specified, the number of
 * elements and containers must match, and each element is renamed within
 * its associated container.
 *
 * @param elements the elements to rename
 * @param destinations the container, or list of containers
 * @param names the list of new names
 * @param replace true if an existing child in a target container
 *   with the target name should be replaced, and false to throw an
 *   exception in the event of a name collision
 * @param monitor a progress monitor
 * @exception JavaModelException if an element could not be renamed. Reasons include:
 * 
 *  There is no element to process (NO_ELEMENTS_TO_PROCESS). The given elements is null or empty
 *  A specified element does not exist (ELEMENT_DOES_NOT_EXIST)
 *  A CoreException occurred while updating an underlying resource
 * 
 A new name is invalid (INVALID_NAME)
 * 
 A child already exists with the same name and replace has been specified as false (NAME_COLLISION)
 * 
 An element is read-only (READ_ONLY)
 * 
 */
void rename(IJavaElement[] elements, IJavaElement[] destinations, String[] names, boolean replace, IProgressMonitor monitor) throws JavaModelException;

}