001: /*******************************************************************************
002: * Copyright (c) 2000, 2006 IBM Corporation and others.
003: * All rights reserved. This program and the accompanying materials
004: * are made available under the terms of the Eclipse Public License v1.0
005: * which accompanies this distribution, and is available at
006: * http://www.eclipse.org/legal/epl-v10.html
007: *
008: * Contributors:
009: * IBM Corporation - initial API and implementation
010: *******************************************************************************/package org.eclipse.jdt.core;
011:
012: import org.eclipse.core.resources.IResource;
013: import org.eclipse.core.resources.IWorkspace;
014: import org.eclipse.core.runtime.IProgressMonitor;
015:
016: /**
017: * Represent the root Java element corresponding to the workspace.
018: * Since there is only one such root element, it is commonly referred to as
019: * <em>the</em> Java model element.
020: * The Java model element needs to be opened before it can be navigated or manipulated.
021: * The Java model element has no parent (it is the root of the Java element
022: * hierarchy). Its children are <code>IJavaProject</code>s.
023: * <p>
024: * This interface provides methods for performing copy, move, rename, and
025: * delete operations on multiple Java elements.
026: * </p>
027: * <p>
028: * This interface is not intended to be implemented by clients. An instance
029: * of one of these handles can be created via
030: * <code>JavaCore.create(workspace.getRoot())</code>.
031: * </p>
032: *
033: * @see JavaCore#create(org.eclipse.core.resources.IWorkspaceRoot)
034: */
035: public interface IJavaModel extends IJavaElement, IOpenable, IParent {
036: /**
037: * Returns whether this Java model contains an <code>IJavaElement</code> whose
038: * resource is the given resource or a non-Java resource which is the given resource.
039: * <p>
040: * Note: no existency check is performed on the argument resource. If it is not accessible
041: * (see <code>IResource.isAccessible()</code>) yet but would be located in Java model
042: * range, then it will return <code>true</code>.
043: * </p><p>
044: * If the resource is accessible, it can be reached by navigating the Java model down using the
045: * <code>getChildren()</code> and/or <code>getNonJavaResources()</code> methods.
046: * </p>
047: * @param resource the resource to check
048: * @return true if the resource is accessible through the Java model
049: * @since 2.1
050: */
051: boolean contains(IResource resource);
052:
053: /**
054: * Copies the given elements to the specified container(s).
055: * If one container is specified, all elements are copied to that
056: * container. If more than one container is specified, the number of
057: * elements and containers must match, and each element is copied to
058: * its associated container.
059: * <p>
060: * Optionally, each copy can positioned before a sibling
061: * element. If <code>null</code> is specified for a given sibling, the copy
062: * is inserted as the last child of its associated container.
063: * </p>
064: * <p>
065: * Optionally, each copy can be renamed. If
066: * <code>null</code> is specified for the new name, the copy
067: * is not renamed.
068: * </p>
069: * <p>
070: * Optionally, any existing child in the destination container with
071: * the same name can be replaced by specifying <code>true</code> for
072: * force. Otherwise an exception is thrown in the event that a name
073: * collision occurs.
074: * </p>
075: *
076: * @param elements the elements to copy
077: * @param containers the container, or list of containers
078: * @param siblings the list of siblings element any of which may be
079: * <code>null</code>; or <code>null</code>
080: * @param renamings the list of new names any of which may be
081: * <code>null</code>; or <code>null</code>
082: * @param replace <code>true</code> if any existing child in a target container
083: * with the target name should be replaced, and <code>false</code> to throw an
084: * exception in the event of a name collision
085: * @param monitor a progress monitor
086: * @exception JavaModelException if an element could not be copied. Reasons include:
087: * <ul>
088: * <li> There is no element to process (NO_ELEMENTS_TO_PROCESS). The given elements is null or empty</li>
089: * <li> A specified element, container, or sibling does not exist (ELEMENT_DOES_NOT_EXIST)</li>
090: * <li> A <code>CoreException</code> occurred while updating an underlying resource</li>
091: * <li> A container is of an incompatible type (<code>INVALID_DESTINATION</code>)</li>
092: * <li> A sibling is not a child of it associated container (<code>INVALID_SIBLING</code>)</li>
093: * <li> A new name is invalid (<code>INVALID_NAME</code>)</li>
094: * <li> A child in its associated container already exists with the same
095: * name and <code>replace</code> has been specified as <code>false</code> (<code>NAME_COLLISION</code>)</li>
096: * <li> A container or element is read-only (<code>READ_ONLY</code>) </li>
097: * </ul>
098: */
099: void copy(IJavaElement[] elements, IJavaElement[] containers,
100: IJavaElement[] siblings, String[] renamings,
101: boolean replace, IProgressMonitor monitor)
102: throws JavaModelException;
103:
104: /**
105: * Deletes the given elements, forcing the operation if necessary and specified.
106: *
107: * @param elements the elements to delete
108: * @param force a flag controlling whether underlying resources that are not
109: * in sync with the local file system will be tolerated
110: * @param monitor a progress monitor
111: * @exception JavaModelException if an element could not be deleted. Reasons include:
112: * <ul>
113: * <li> There is no element to process (NO_ELEMENTS_TO_PROCESS). The given elements is null or empty</li>
114: * <li> A specified element does not exist (ELEMENT_DOES_NOT_EXIST)</li>
115: * <li> A <code>CoreException</code> occurred while updating an underlying resource</li>
116: * <li> An element is read-only (<code>READ_ONLY</code>) </li>
117: * </ul>
118: */
119: void delete(IJavaElement[] elements, boolean force,
120: IProgressMonitor monitor) throws JavaModelException;
121:
122: /**
123: * Returns the Java project with the given name. This is a handle-only method.
124: * The project may or may not exist.
125: *
126: * @param name the name of the Java project
127: * @return the Java project with the given name
128: */
129: IJavaProject getJavaProject(String name);
130:
131: /**
132: * Returns the Java projects in this Java model, or an empty array if there
133: * are none.
134: *
135: * @return the Java projects in this Java model, or an empty array if there
136: * are none
137: * @exception JavaModelException if this request fails.
138: */
139: IJavaProject[] getJavaProjects() throws JavaModelException;
140:
141: /**
142: * Returns an array of non-Java resources (that is, non-Java projects) in
143: * the workspace.
144: * <p>
145: * Non-Java projects include all projects that are closed (even if they have the
146: * Java nature).
147: * </p>
148: *
149: * @return an array of non-Java projects (<code>IProject</code>s) contained
150: * in the workspace.
151: * @throws JavaModelException if this element does not exist or if an
152: * exception occurs while accessing its corresponding resource
153: * @since 2.1
154: */
155: Object[] getNonJavaResources() throws JavaModelException;
156:
157: /**
158: * Returns the workspace associated with this Java model.
159: *
160: * @return the workspace associated with this Java model
161: */
162: IWorkspace getWorkspace();
163:
164: /**
165: * Moves the given elements to the specified container(s).
166: * If one container is specified, all elements are moved to that
167: * container. If more than one container is specified, the number of
168: * elements and containers must match, and each element is moved to
169: * its associated container.
170: * <p>
171: * Optionally, each element can positioned before a sibling
172: * element. If <code>null</code> is specified for sibling, the element
173: * is inserted as the last child of its associated container.
174: * </p>
175: * <p>
176: * Optionally, each element can be renamed. If
177: * <code>null</code> is specified for the new name, the element
178: * is not renamed.
179: * </p>
180: * <p>
181: * Optionally, any existing child in the destination container with
182: * the same name can be replaced by specifying <code>true</code> for
183: * force. Otherwise an exception is thrown in the event that a name
184: * collision occurs.
185: * </p>
186: *
187: * @param elements the elements to move
188: * @param containers the container, or list of containers
189: * @param siblings the list of siblings element any of which may be
190: * <code>null</code>; or <code>null</code>
191: * @param renamings the list of new names any of which may be
192: * <code>null</code>; or <code>null</code>
193: * @param replace <code>true</code> if any existing child in a target container
194: * with the target name should be replaced, and <code>false</code> to throw an
195: * exception in the event of a name collision
196: * @param monitor a progress monitor
197: * @exception JavaModelException if an element could not be moved. Reasons include:
198: * <ul>
199: * <li> There is no element to process (NO_ELEMENTS_TO_PROCESS). The given elements is null or empty</li>
200: * <li> A specified element, container, or sibling does not exist (ELEMENT_DOES_NOT_EXIST)</li>
201: * <li> A <code>CoreException</code> occurred while updating an underlying resource</li>
202: * <li> A container is of an incompatible type (<code>INVALID_DESTINATION</code>)</li>
203: * <li> A sibling is not a child of it associated container (<code>INVALID_SIBLING</code>)</li>
204: * <li> A new name is invalid (<code>INVALID_NAME</code>)</li>
205: * <li> A child in its associated container already exists with the same
206: * name and <code>replace</code> has been specified as <code>false</code> (<code>NAME_COLLISION</code>)</li>
207: * <li> A container or element is read-only (<code>READ_ONLY</code>) </li>
208: * </ul>
209: *
210: * @exception IllegalArgumentException any element or container is <code>null</code>
211: */
212: void move(IJavaElement[] elements, IJavaElement[] containers,
213: IJavaElement[] siblings, String[] renamings,
214: boolean replace, IProgressMonitor monitor)
215: throws JavaModelException;
216:
217: /**
218: * Triggers an update of the JavaModel with respect to the referenced external archives.
219: * This operation will issue a JavaModel delta describing the discovered changes, in term
220: * of Java element package fragment roots added, removed or changed.
221: * Note that a collection of elements can be passed so as to narrow the set of archives
222: * to refresh (passing <code>null</code> along is equivalent to refreshing the entire mode).
223: * The elements can be:
224: * <ul>
225: * <li> package fragment roots corresponding to external archives
226: * <li> Java projects, which referenced external archives will be refreshed
227: * <li> Java model, all referenced external archives will be refreshed.
228: * </ul>
229: * <p> In case an archive is used by multiple projects, the delta issued will account for
230: * all of them. This means that even if a project was not part of the elements scope, it
231: * may still be notified of changes if it is referencing a library comprised in the scope.
232: * <p>
233: * @param elementsScope - a collection of elements defining the scope of the refresh
234: * @param monitor - a progress monitor used to report progress
235: * @exception JavaModelException in one of the corresponding situation:
236: * <ul>
237: * <li> an exception occurs while accessing project resources </li>
238: * </ul>
239: *
240: * @see IJavaElementDelta
241: * @since 2.0
242: */
243: void refreshExternalArchives(IJavaElement[] elementsScope,
244: IProgressMonitor monitor) throws JavaModelException;
245:
246: /**
247: * Renames the given elements as specified.
248: * If one container is specified, all elements are renamed within that
249: * container. If more than one container is specified, the number of
250: * elements and containers must match, and each element is renamed within
251: * its associated container.
252: *
253: * @param elements the elements to rename
254: * @param destinations the container, or list of containers
255: * @param names the list of new names
256: * @param replace <code>true</code> if an existing child in a target container
257: * with the target name should be replaced, and <code>false</code> to throw an
258: * exception in the event of a name collision
259: * @param monitor a progress monitor
260: * @exception JavaModelException if an element could not be renamed. Reasons include:
261: * <ul>
262: * <li> There is no element to process (NO_ELEMENTS_TO_PROCESS). The given elements is null or empty</li>
263: * <li> A specified element does not exist (ELEMENT_DOES_NOT_EXIST)</li>
264: * <li> A <code>CoreException</code> occurred while updating an underlying resource
265: * <li> A new name is invalid (<code>INVALID_NAME</code>)
266: * <li> A child already exists with the same name and <code>replace</code> has been specified as <code>false</code> (<code>NAME_COLLISION</code>)
267: * <li> An element is read-only (<code>READ_ONLY</code>)
268: * </ul>
269: */
270: void rename(IJavaElement[] elements, IJavaElement[] destinations,
271: String[] names, boolean replace, IProgressMonitor monitor)
272: throws JavaModelException;
273:
274: }
|