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
9 * IBM Corporation - initial API and implementation
10 *******************************************************************************/
11 package net.sourceforge.phpdt.core;
13 import org.eclipse.core.resources.IResource;
14 import org.eclipse.core.resources.IWorkspace;
15 import org.eclipse.core.runtime.IProgressMonitor;
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.
25 * This interface provides methods for performing copy, move, rename, and delete
26 * operations on multiple Java elements.
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>.
34 * @see JavaCore#create(org.eclipse.core.resources.IWorkspaceRoot)
36 public interface IJavaModel extends IJavaElement, IOpenable, IParent {
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
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
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.
54 * the resource to check
55 * @return true if the resource is accessible through the Java model
58 boolean contains(IResource resource);
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.
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.
71 * Optionally, each copy can be renamed. If <code>null</code> is specified
72 * for the new name, the copy is not renamed.
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
82 * the elements to copy
84 * the container, or list of containers
86 * the list of siblings element any of which may be
87 * <code>null</code>; or <code>null</code>
89 * the list of new names any of which may be <code>null</code>;
90 * or <code>null</code>
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
98 * @exception JavaModelException
99 * if an element could not be copied. Reasons include:
101 * <li> There is no element to process
102 * (NO_ELEMENTS_TO_PROCESS). The given elements is null or
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>)
118 void copy(IJavaElement[] elements, IJavaElement[] containers,
119 IJavaElement[] siblings, String[] renamings, boolean replace,
120 IProgressMonitor monitor) throws JavaModelException;
123 * Deletes the given elements, forcing the operation if necessary and
127 * the elements to delete
129 * a flag controlling whether underlying resources that are not
130 * in sync with the local file system will be tolerated
133 * @exception JavaModelException
134 * if an element could not be deleted. Reasons include:
136 * <li> There is no element to process
137 * (NO_ELEMENTS_TO_PROCESS). The given elements is null or
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>)
147 void delete(IJavaElement[] elements, boolean force, IProgressMonitor monitor)
148 throws JavaModelException;
151 * Returns the Java project with the given name. This is a handle-only
152 * method. The project may or may not exist.
154 * @return the Java project with the given name
156 IJavaProject getJavaProject(String name);
159 * Returns the Java projects in this Java model, or an empty array if there
162 * @return the Java projects in this Java model, or an empty array if there
164 * @exception JavaModelException
165 * if this request fails.
167 IJavaProject[] getJavaProjects() throws JavaModelException;
170 * Returns an array of non-Java resources (that is, non-Java projects) in
173 * Non-Java projects include all projects that are closed (even if they have
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
183 // Object[] getNonJavaResources() throws JavaModelException;
185 * Returns the workspace associated with this Java model.
187 * @return the workspace associated with this Java model
189 IWorkspace getWorkspace();
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.
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.
202 * Optionally, each element can be renamed. If <code>null</code> is
203 * specified for the new name, the element is not renamed.
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
213 * the elements to move
215 * the container, or list of containers
217 * the list of siblings element any of which may be
218 * <code>null</code>; or <code>null</code>
220 * the list of new names any of which may be <code>null</code>;
221 * or <code>null</code>
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
229 * @exception JavaModelException
230 * if an element could not be moved. Reasons include:
232 * <li> There is no element to process
233 * (NO_ELEMENTS_TO_PROCESS). The given elements is null or
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>)
249 * @exception IllegalArgumentException
250 * any element or container is <code>null</code>
252 void move(IJavaElement[] elements, IJavaElement[] containers,
253 IJavaElement[] siblings, String[] renamings, boolean replace,
254 IProgressMonitor monitor) throws JavaModelException;
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:
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.
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.
276 * @param elementsScope -
277 * a collection of elements defining the scope of the refresh
279 * a progress monitor used to report progress
280 * @exception JavaModelException
281 * in one of the corresponding situation:
283 * <li> an exception occurs while accessing project resources
287 * @see IJavaElementDelta
290 // void refreshExternalArchives(IJavaElement[] elementsScope,
291 // IProgressMonitor monitor) throws JavaModelException;
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.
299 * the elements to rename
300 * @param destinations
301 * the container, or list of containers
303 * the list of new names
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
311 * @exception JavaModelException
312 * if an element could not be renamed. Reasons include:
314 * <li> There is no element to process
315 * (NO_ELEMENTS_TO_PROCESS). The given elements is null or
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>)
328 void rename(IJavaElement[] elements, IJavaElement[] destinations,
329 String[] names, boolean replace, IProgressMonitor monitor)
330 throws JavaModelException;