/*******************************************************************************
* Copyright (c) 2000, 2009 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.runtime.IProgressMonitor;
/**
* Common protocol for Java elements that support source code manipulations such
* as copy, move, rename, and delete.
*
* @noimplement This interface is not intended to be implemented by clients.
*/
public interface ISourceManipulation {
/**
* Copies this element to the given container.
*
* @param container the container
* @param sibling the sibling element before which the copy should be inserted,
* or <code>null</code> if the copy should be inserted as the last child of
* the container
* @param rename the new name for the element, or <code>null</code> if the copy
* retains the name of this element
* @param replace <code>true</code> if any existing child in the container with
* the target name should be replaced, and <code>false</code> to throw an
* exception in the event of a name collision
* @param monitor a progress monitor
* @exception JavaModelException if this element could not be copied. Reasons include:
* <ul>
* <li> This Java element, container element, or sibling does not exist (ELEMENT_DOES_NOT_EXIST)</li>
* <li> A <code>CoreException</code> occurred while updating an underlying resource
* <li> The container is of an incompatible type (INVALID_DESTINATION)
* <li> The sibling is not a child of the given container (INVALID_SIBLING)
* <li> The new name is invalid (INVALID_NAME)
* <li> A child in the container already exists with the same name (NAME_COLLISION)
* and <code>replace</code> has been specified as <code>false</code>
* <li> The container or this element is read-only (READ_ONLY)
* </ul>
*
* @exception IllegalArgumentException if container is <code>null</code>
* @see org.eclipse.jdt.core.IJavaModelStatusConstants#INVALID_DESTINATION
*/
void copy(IJavaElement container, IJavaElement sibling, String rename, boolean replace, IProgressMonitor monitor) throws JavaModelException;
/**
* Deletes this element, forcing if specified and necessary.
*
* @param force a flag controlling whether underlying resources that are not
* in sync with the local file system will be tolerated (same as the force flag
* in IResource operations).
* @param monitor a progress monitor
* @exception JavaModelException if this element could not be deleted. Reasons include:
* <ul>
* <li> This Java element does not exist (ELEMENT_DOES_NOT_EXIST)</li>
* <li> A <code>CoreException</code> occurred while updating an underlying resource (CORE_EXCEPTION)</li>
* <li> This element is read-only (READ_ONLY)</li>
* </ul>
*/
void delete(boolean force, IProgressMonitor monitor) throws JavaModelException;
/**
* Moves this element to the given container.
*
* @param container the container
* @param sibling the sibling element before which the element should be inserted,
* or <code>null</code> if the element should be inserted as the last child of
* the container
* @param rename the new name for the element, or <code>null</code> if the
* element retains its name
* @param replace <code>true</code> if any existing child in the container with
* the target name should be replaced, and <code>false</code> to throw an
* exception in the event of a name collision
* @param monitor a progress monitor
* @exception JavaModelException if this element could not be moved. Reasons include:
* <ul>
* <li> This Java element, container element, or sibling does not exist (ELEMENT_DOES_NOT_EXIST)</li>
* <li> A <code>CoreException</code> occurred while updating an underlying resource
* <li> The container is of an incompatible type (INVALID_DESTINATION)
* <li> The sibling is not a child of the given container (INVALID_SIBLING)
* <li> The new name is invalid (INVALID_NAME)
* <li> A child in the container already exists with the same name (NAME_COLLISION)
* and <code>replace</code> has been specified as <code>false</code>
* <li> The container or this element is read-only (READ_ONLY)
* </ul>
*
* @exception IllegalArgumentException if container is <code>null</code>
* @see org.eclipse.jdt.core.IJavaModelStatusConstants#INVALID_DESTINATION
*/
void move(IJavaElement container, IJavaElement sibling, String rename, boolean replace, IProgressMonitor monitor) throws JavaModelException;
/**
* Renames this element to the given name.
*
* @param name the new name for the element
* @param replace <code>true</code> if any existing element with the target name
* should be replaced, and <code>false</code> to throw an exception in the
* event of a name collision
* @param monitor a progress monitor
* @exception JavaModelException if this element could not be renamed. Reasons include:
* <ul>
* <li> This Java element does not exist (ELEMENT_DOES_NOT_EXIST)</li>
* <li> A <code>CoreException</code> occurred while updating an underlying resource
* <li> The new name is invalid (INVALID_NAME)
* <li> A child in the container already exists with the same name (NAME_COLLISION)
* and <code>replace</code> has been specified as <code>false</code>
* <li> This element is read-only (READ_ONLY)
* </ul>
*/
void rename(String name, boolean replace, IProgressMonitor monitor) throws JavaModelException;
}