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. Since there
  19  * is only one such root element, it is commonly referred to as <em>the</em>
  20  * Java model element. The Java model element needs to be opened before it can
  21  * be navigated or manipulated. The Java model element has no parent (it is the
  22  * root of the Java element hierarchy). Its children are
  23  * <code>IJavaProject</code>s.
  24  * <p>
  25  * This interface provides methods for performing copy, move, rename, and delete
  26  * operations on multiple Java elements.
  27  * </p>
  28  * <p>
  29  * This interface is not intended to be implemented by clients. An instance of
  30  * 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>
  39          * whose resource is the given resource or a non-Java resource which is the
  40          * given resource.
  41          * <p>
  42          * Note: no existency check is performed on the argument resource. If it is
  43          * not accessible (see <code>IResource.isAccessible()</code>) yet but
  44          * would be located in Java model range, then it will return
  45          * <code>true</code>.
  46          * </p>
  47          * <p>
  48          * If the resource is accessible, it can be reached by navigating the Java
  49          * model down using the <code>getChildren()</code> and/or
  50          * <code>getNonJavaResources()</code> methods.
  51          * </p>
  52          *
  53          * @param resource
  54          *            the resource to check
  55          * @return true if the resource is accessible through the Java model
  56          * @since 2.1
  57          */
  58         boolean contains(IResource resource);
  59
  60         /**
  61          * Copies the given elements to the specified container(s). If one container
  62          * is specified, all elements are copied to that container. If more than one
  63          * container is specified, the number of elements and containers must match,
  64          * and each element is copied to its associated container.
  65          * <p>
  66          * Optionally, each copy can positioned before a sibling element. If
  67          * <code>null</code> is specified for a given sibling, the copy is
  68          * inserted as the last child of its associated container.
  69          * </p>
  70          * <p>
  71          * Optionally, each copy can be renamed. If <code>null</code> is specified
  72          * for the new name, the copy is not renamed.
  73          * </p>
  74          * <p>
  75          * Optionally, any existing child in the destination container with the same
  76          * name can be replaced by specifying <code>true</code> for force.
  77          * Otherwise an exception is thrown in the event that a name collision
  78          * occurs.
  79          * </p>
  80          *
  81          * @param elements
  82          *            the elements to copy
  83          * @param containers
  84          *            the container, or list of containers
  85          * @param siblings
  86          *            the list of siblings element any of which may be
  87          *            <code>null</code>; or <code>null</code>
  88          * @param renamings
  89          *            the list of new names any of which may be <code>null</code>;
  90          *            or <code>null</code>
  91          * @param replace
  92          *            <code>true</code> if any existing child in a target
  93          *            container with the target name should be replaced, and
  94          *            <code>false</code> to throw an exception in the event of a
  95          *            name collision
  96          * @param monitor
  97          *            a progress monitor
  98          * @exception JavaModelException
  99          *                if an element could not be copied. Reasons include:
 100          *                <ul>
 101          *                <li> There is no element to process
 102          *                (NO_ELEMENTS_TO_PROCESS). The given elements is null or
 103          *                empty</li>
 104          *                <li> A specified element, container, or sibling does not
 105          *                exist (ELEMENT_DOES_NOT_EXIST)</li>
 106          *                <li> A <code>CoreException</code> occurred while
 107          *                updating an underlying resource</li>
 108          *                <li> A container is of an incompatible type (<code>INVALID_DESTINATION</code>)</li>
 109          *                <li> A sibling is not a child of it associated container (<code>INVALID_SIBLING</code>)</li>
 110          *                <li> A new name is invalid (<code>INVALID_NAME</code>)</li>
 111          *                <li> A child in its associated container already exists
 112          *                with the same name and <code>replace</code> has been
 113          *                specified as <code>false</code> (<code>NAME_COLLISION</code>)</li>
 114          *                <li> A container or element is read-only (<code>READ_ONLY</code>)
 115          *                </li>
 116          *                </ul>
 117          */
 118         void copy(IJavaElement[] elements, IJavaElement[] containers,
 119                         IJavaElement[] siblings, String[] renamings, boolean replace,
 120                         IProgressMonitor monitor) throws JavaModelException;
 121
 122         /**
 123          * Deletes the given elements, forcing the operation if necessary and
 124          * specified.
 125          *
 126          * @param elements
 127          *            the elements to delete
 128          * @param force
 129          *            a flag controlling whether underlying resources that are not
 130          *            in sync with the local file system will be tolerated
 131          * @param monitor
 132          *            a progress monitor
 133          * @exception JavaModelException
 134          *                if an element could not be deleted. Reasons include:
 135          *                <ul>
 136          *                <li> There is no element to process
 137          *                (NO_ELEMENTS_TO_PROCESS). The given elements is null or
 138          *                empty</li>
 139          *                <li> A specified element does not exist
 140          *                (ELEMENT_DOES_NOT_EXIST)</li>
 141          *                <li> A <code>CoreException</code> occurred while
 142          *                updating an underlying resource</li>
 143          *                <li> An element is read-only (<code>READ_ONLY</code>)
 144          *                </li>
 145          *                </ul>
 146          */
 147         void delete(IJavaElement[] elements, boolean force, IProgressMonitor monitor)
 148                         throws JavaModelException;
 149
 150         /**
 151          * Returns the Java project with the given name. This is a handle-only
 152          * method. The project may or may not exist.
 153          *
 154          * @return the Java project with the given name
 155          */
 156         IJavaProject getJavaProject(String name);
 157
 158         /**
 159          * Returns the Java projects in this Java model, or an empty array if there
 160          * are none.
 161          *
 162          * @return the Java projects in this Java model, or an empty array if there
 163          *         are none
 164          * @exception JavaModelException
 165          *                if this request fails.
 166          */
 167         IJavaProject[] getJavaProjects() throws JavaModelException;
 168
 169         /**
 170          * Returns an array of non-Java resources (that is, non-Java projects) in
 171          * the workspace.
 172          * <p>
 173          * Non-Java projects include all projects that are closed (even if they have
 174          * the Java nature).
 175          * </p>
 176          *
 177          * @return an array of non-Java projects contained in the workspace.
 178          * @throws JavaModelException
 179          *             if this element does not exist or if an exception occurs
 180          *             while accessing its corresponding resource
 181          * @since 2.1
 182          */
 183         // Object[] getNonJavaResources() throws JavaModelException;
 184         /**
 185          * Returns the workspace associated with this Java model.
 186          *
 187          * @return the workspace associated with this Java model
 188          */
 189         IWorkspace getWorkspace();
 190
 191         /**
 192          * Moves the given elements to the specified container(s). If one container
 193          * is specified, all elements are moved to that container. If more than one
 194          * container is specified, the number of elements and containers must match,
 195          * and each element is moved to its associated container.
 196          * <p>
 197          * Optionally, each element can positioned before a sibling element. If
 198          * <code>null</code> is specified for sibling, the element is inserted as
 199          * the last child of its associated container.
 200          * </p>
 201          * <p>
 202          * Optionally, each element can be renamed. If <code>null</code> is
 203          * specified for the new name, the element is not renamed.
 204          * </p>
 205          * <p>
 206          * Optionally, any existing child in the destination container with the same
 207          * name can be replaced by specifying <code>true</code> for force.
 208          * Otherwise an exception is thrown in the event that a name collision
 209          * occurs.
 210          * </p>
 211          *
 212          * @param elements
 213          *            the elements to move
 214          * @param containers
 215          *            the container, or list of containers
 216          * @param siblings
 217          *            the list of siblings element any of which may be
 218          *            <code>null</code>; or <code>null</code>
 219          * @param renamings
 220          *            the list of new names any of which may be <code>null</code>;
 221          *            or <code>null</code>
 222          * @param replace
 223          *            <code>true</code> if any existing child in a target
 224          *            container with the target name should be replaced, and
 225          *            <code>false</code> to throw an exception in the event of a
 226          *            name collision
 227          * @param monitor
 228          *            a progress monitor
 229          * @exception JavaModelException
 230          *                if an element could not be moved. Reasons include:
 231          *                <ul>
 232          *                <li> There is no element to process
 233          *                (NO_ELEMENTS_TO_PROCESS). The given elements is null or
 234          *                empty</li>
 235          *                <li> A specified element, container, or sibling does not
 236          *                exist (ELEMENT_DOES_NOT_EXIST)</li>
 237          *                <li> A <code>CoreException</code> occurred while
 238          *                updating an underlying resource</li>
 239          *                <li> A container is of an incompatible type (<code>INVALID_DESTINATION</code>)</li>
 240          *                <li> A sibling is not a child of it associated container (<code>INVALID_SIBLING</code>)</li>
 241          *                <li> A new name is invalid (<code>INVALID_NAME</code>)</li>
 242          *                <li> A child in its associated container already exists
 243          *                with the same name and <code>replace</code> has been
 244          *                specified as <code>false</code> (<code>NAME_COLLISION</code>)</li>
 245          *                <li> A container or element is read-only (<code>READ_ONLY</code>)
 246          *                </li>
 247          *                </ul>
 248          *
 249          * @exception IllegalArgumentException
 250          *                any element or container is <code>null</code>
 251          */
 252         void move(IJavaElement[] elements, IJavaElement[] containers,
 253                         IJavaElement[] siblings, String[] renamings, boolean replace,
 254                         IProgressMonitor monitor) throws JavaModelException;
 255
 256         /**
 257          * Triggers an update of the JavaModel with respect to the referenced
 258          * external archives. This operation will issue a JavaModel delta describing
 259          * the discovered changes, in term of Java element package fragment roots
 260          * added, removed or changed. Note that a collection of elements can be
 261          * passed so as to narrow the set of archives to refresh (passing
 262          * <code>null</code> along is equivalent to refreshing the entire mode).
 263          * The elements can be:
 264          * <ul>
 265          * <li> package fragment roots corresponding to external archives
 266          * <li> Java projects, which referenced external archives will be refreshed
 267          * <li> Java model, all referenced external archives will be refreshed.
 268          * </ul>
 269          * <p>
 270          * In case an archive is used by multiple projects, the delta issued will
 271          * account for all of them. This means that even if a project was not part
 272          * of the elements scope, it may still be notified of changes if it is
 273          * referencing a library comprised in the scope.
 274          * <p>
 275          *
 276          * @param elementsScope -
 277          *            a collection of elements defining the scope of the refresh
 278          * @param monitor -
 279          *            a progress monitor used to report progress
 280          * @exception JavaModelException
 281          *                in one of the corresponding situation:
 282          *                <ul>
 283          *                <li> an exception occurs while accessing project resources
 284          *                </li>
 285          *                </ul>
 286          *
 287          * @see IJavaElementDelta
 288          * @since 2.0
 289          */
 290         // void refreshExternalArchives(IJavaElement[] elementsScope,
 291         // IProgressMonitor monitor) throws JavaModelException;
 292         /**
 293          * Renames the given elements as specified. If one container is specified,
 294          * all elements are renamed within that container. If more than one
 295          * container is specified, the number of elements and containers must match,
 296          * and each element is renamed within its associated container.
 297          *
 298          * @param elements
 299          *            the elements to rename
 300          * @param destinations
 301          *            the container, or list of containers
 302          * @param names
 303          *            the list of new names
 304          * @param replace
 305          *            <code>true</code> if an existing child in a target container
 306          *            with the target name should be replaced, and
 307          *            <code>false</code> to throw an exception in the event of a
 308          *            name collision
 309          * @param monitor
 310          *            a progress monitor
 311          * @exception JavaModelException
 312          *                if an element could not be renamed. Reasons include:
 313          *                <ul>
 314          *                <li> There is no element to process
 315          *                (NO_ELEMENTS_TO_PROCESS). The given elements is null or
 316          *                empty</li>
 317          *                <li> A specified element does not exist
 318          *                (ELEMENT_DOES_NOT_EXIST)</li>
 319          *                <li> A <code>CoreException</code> occurred while
 320          *                updating an underlying resource
 321          *                <li> A new name is invalid (<code>INVALID_NAME</code>)
 322          *                <li> A child already exists with the same name and
 323          *                <code>replace</code> has been specified as
 324          *                <code>false</code> (<code>NAME_COLLISION</code>)
 325          *                <li> An element is read-only (<code>READ_ONLY</code>)
 326          *                </ul>
 327          */
 328         void rename(IJavaElement[] elements, IJavaElement[] destinations,
 329                         String[] names, boolean replace, IProgressMonitor monitor)
 330                         throws JavaModelException;
 331
 332 }