net.sourceforge.phpeclipse/src/net/sourceforge/phpdt/core/IJavaModel.java

   1 /*******************************************************************************
   2  * Copyright (c) 2000, 2001, 2002 International Business Machines Corp. and others.
   3  * All rights reserved. This program and the accompanying materials
   4  * are made available under the terms of the Common Public License v0.5
   5  * which accompanies this distribution, and is available at
   6  * http://www.eclipse.org/legal/cpl-v05.html
   7  *
   8  * Contributors:
   9  *     IBM Corporation - initial API and implementation
  10  ******************************************************************************/
  11 package net.sourceforge.phpdt.core;
  12
  13 import org.eclipse.core.resources.IWorkspace;
  14 import org.eclipse.core.runtime.IProgressMonitor;
  15
  16 /**
  17  * Represent the root Java element corresponding to the workspace.
  18  * Since there is only one such root element, it is commonly referred to as
  19  * <em>the</em> Java model element.
  20  * The Java model element needs to be opened before it can be navigated or manipulated.
  21  * The Java model element has no parent (it is the root of the Java element
  22  * hierarchy). Its children are <code>IJavaProject</code>s.
  23  * <p>
  24  * This interface provides methods for performing copy, move, rename, and
  25  * delete operations on multiple Java elements.
  26  * </p>
  27  * <p>
  28  * This interface is not intended to be implemented by clients. An instance
  29  * of one of these handles can be created via
  30  * <code>JavaCore.create(workspace.getRoot())</code>.
  31  * </p>
  32  *
  33  * @see JavaCore#create(org.eclipse.core.resources.IWorkspaceRoot)
  34  */
  35 public interface IJavaModel extends IJavaElement, IOpenable, IParent {
  36 /**
  37  * Copies the given elements to the specified container(s).
  38  * If one container is specified, all elements are copied to that
  39  * container. If more than one container is specified, the number of
  40  * elements and containers must match, and each element is copied to
  41  * its associated container.
  42  * <p>
  43  * Optionally, each copy can positioned before a sibling
  44  * element. If <code>null</code> is specified for a given sibling, the copy
  45  * is inserted as the last child of its associated container.
  46  * </p>
  47  * <p>
  48  * Optionally, each copy can be renamed. If
  49  * <code>null</code> is specified for the new name, the copy
  50  * is not renamed.
  51  * </p>
  52  * <p>
  53  * Optionally, any existing child in the destination container with
  54  * the same name can be replaced by specifying <code>true</code> for
  55  * force. Otherwise an exception is thrown in the event that a name
  56  * collision occurs.
  57  * </p>
  58  *
  59  * @param elements the elements to copy
  60  * @param containers the container, or list of containers
  61  * @param siblings the list of siblings element any of which may be
  62  *   <code>null</code>; or <code>null</code>
  63  * @param renamings the list of new names any of which may be
  64  *   <code>null</code>; or <code>null</code>
  65  * @param replace <code>true</code> if any existing child in a target container
  66  *   with the target name should be replaced, and <code>false</code> to throw an
  67  *   exception in the event of a name collision
  68  * @param monitor a progress monitor
  69  * @exception JavaModelException if an element could not be copied. Reasons include:
  70  * <ul>
  71  * <li> A specified element, container, or sibling does not exist (ELEMENT_DOES_NOT_EXIST)</li>
  72  * <li> A <code>CoreException</code> occurred while updating an underlying resource
  73  * <li> A container is of an incompatible type (<code>INVALID_DESTINATION</code>)
  74  * <li> A sibling is not a child of it associated container (<code>INVALID_SIBLING</code>)
  75  * <li> A new name is invalid (<code>INVALID_NAME</code>)
  76  * <li> A child in its associated container already exists with the same
  77  *              name and <code>replace</code> has been specified as <code>false</code> (<code>NAME_COLLISION</code>)
  78  * <li> A container or element is read-only (<code>READ_ONLY</code>)
  79  * </ul>
  80  */
  81 void copy(IJavaElement[] elements, IJavaElement[] containers, IJavaElement[] siblings, String[] renamings, boolean replace, IProgressMonitor monitor) throws JavaModelException;
  82 /**
  83  * Deletes the given elements, forcing the operation if necessary and specified.
  84  *
  85  * @param elements the elements to delete
  86  * @param force a flag controlling whether underlying resources that are not
  87  *    in sync with the local file system will be tolerated
  88  * @param monitor a progress monitor
  89  * @exception JavaModelException if an element could not be deleted. Reasons include:
  90  * <ul>
  91  * <li> A specified element does not exist (ELEMENT_DOES_NOT_EXIST)</li>
  92  * <li> A <code>CoreException</code> occurred while updating an underlying resource
  93  * <li> An element is read-only (<code>READ_ONLY</code>)
  94  * </ul>
  95  */
  96 void delete(IJavaElement[] elements, boolean force, IProgressMonitor monitor) throws JavaModelException;
  97 /**
  98  * Returns the Java project with the given name. This is a handle-only method.
  99  * The project may or may not exist.
 100  *
 101  * @return the Java project with the given name
 102  */
 103 IJavaProject getJavaProject(String name);
 104 /**
 105  * Returns the Java projects in this Java model, or an empty array if there
 106  * are none.
 107  *
 108  * @return the Java projects in this Java model, or an empty array if there
 109  * are none
 110  * @exception JavaModelException if this request fails.
 111  */
 112 IJavaProject[] getJavaProjects() throws JavaModelException;
 113 /**
 114  * Returns the workspace associated with this Java model.
 115  *
 116  * @return the workspace associated with this Java model
 117  */
 118 IWorkspace getWorkspace();
 119 /**
 120  * Moves the given elements to the specified container(s).
 121  * If one container is specified, all elements are moved to that
 122  * container. If more than one container is specified, the number of
 123  * elements and containers must match, and each element is moved to
 124  * its associated container.
 125  * <p>
 126  * Optionally, each element can positioned before a sibling
 127  * element. If <code>null</code> is specified for sibling, the element
 128  * is inserted as the last child of its associated container.
 129  * </p>
 130  * <p>
 131  * Optionally, each element can be renamed. If
 132  * <code>null</code> is specified for the new name, the element
 133  * is not renamed.
 134  * </p>
 135  * <p>
 136  * Optionally, any existing child in the destination container with
 137  * the same name can be replaced by specifying <code>true</code> for
 138  * force. Otherwise an exception is thrown in the event that a name
 139  * collision occurs.
 140  * </p>
 141  *
 142  * @param elements the elements to move
 143  * @param containers the container, or list of containers
 144  * @param siblings the list of siblings element any of which may be
 145  *   <code>null</code>; or <code>null</code>
 146  * @param renamings the list of new names any of which may be
 147  *   <code>null</code>; or <code>null</code>
 148  * @param replace <code>true</code> if any existing child in a target container
 149  *   with the target name should be replaced, and <code>false</code> to throw an
 150  *   exception in the event of a name collision
 151  * @param monitor a progress monitor
 152  * @exception JavaModelException if an element could not be moved. Reasons include:
 153  * <ul>
 154  * <li> A specified element, container, or sibling does not exist (ELEMENT_DOES_NOT_EXIST)</li>
 155  * <li> A <code>CoreException</code> occurred while updating an underlying resource
 156  * <li> A container is of an incompatible type (<code>INVALID_DESTINATION</code>)
 157  * <li> A sibling is not a child of it associated container (<code>INVALID_SIBLING</code>)
 158  * <li> A new name is invalid (<code>INVALID_NAME</code>)
 159  * <li> A child in its associated container already exists with the same
 160  *              name and <code>replace</code> has been specified as <code>false</code> (<code>NAME_COLLISION</code>)
 161  * <li> A container or element is read-only (<code>READ_ONLY</code>)
 162  * </ul>
 163  *
 164  * @exception IllegalArgumentException any element or container is <code>null</code>
 165  */
 166 void move(IJavaElement[] elements, IJavaElement[] containers, IJavaElement[] siblings, String[] renamings, boolean replace, IProgressMonitor monitor) throws JavaModelException;
 167
 168 /**
 169  * Triggers an update of the JavaModel with respect to the referenced external archives.
 170  * This operation will issue a JavaModel delta describing the discovered changes, in term
 171  * of Java element package fragment roots added, removed or changed.
 172  * Note that a collection of elements can be passed so as to narrow the set of archives
 173  * to refresh (passing <code>null</code> along is equivalent to refreshing the entire mode).
 174  * The elements can be:
 175  * <ul>
 176  * <li> package fragment roots corresponding to external archives
 177  * <li> Java projects, which referenced external archives will be refreshed
 178  * <li> Java model, all referenced external archives will be refreshed.
 179  * </ul>
 180  * <p> In case an archive is used by multiple projects, the delta issued will account for
 181  * all of them. This means that even if a project was not part of the elements scope, it
 182  * may still be notified of changes if it is referencing a library comprised in the scope.
 183  * <p>
 184  * @param elementsScope - a collection of elements defining the scope of the refresh
 185  * @param monitor - a progress monitor used to report progress
 186  * @exception JavaModelException in one of the corresponding situation:
 187  * <ul>
 188  *    <li> an exception occurs while accessing project resources </li>
 189  * </ul>
 190  *
 191  * @see IJavaElementDelta
 192  * @since 2.0
 193  */
 194 void refreshExternalArchives(IJavaElement[] elementsScope, IProgressMonitor monitor) throws JavaModelException;
 195
 196 /**
 197  * Renames the given elements as specified.
 198  * If one container is specified, all elements are renamed within that
 199  * container. If more than one container is specified, the number of
 200  * elements and containers must match, and each element is renamed within
 201  * its associated container.
 202  *
 203  * @param elements the elements to rename
 204  * @param destinations the container, or list of containers
 205  * @param names the list of new names
 206  * @param replace <code>true</code> if an existing child in a target container
 207  *   with the target name should be replaced, and <code>false</code> to throw an
 208  *   exception in the event of a name collision
 209  * @param monitor a progress monitor
 210  * @exception JavaModelException if an element could not be renamed. Reasons include:
 211  * <ul>
 212  * <li> A specified element does not exist (ELEMENT_DOES_NOT_EXIST)</li>
 213  * <li> A <code>CoreException</code> occurred while updating an underlying resource
 214  * <li> A new name is invalid (<code>INVALID_NAME</code>)
 215  * <li> A child already exists with the same name and <code>replace</code> has been specified as <code>false</code> (<code>NAME_COLLISION</code>)
 216  * <li> An element is read-only (<code>READ_ONLY</code>)
 217  * </ul>
 218  */
 219 void rename(IJavaElement[] elements, IJavaElement[] destinations, String[] names, boolean replace, IProgressMonitor monitor) throws JavaModelException;
 220
 221 }