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

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