IJavaModel


1   /*******************************************************************************
2    * Copyright (c) 2000, 2006 IBM Corporation and others.
3    * All rights reserved. This program and the accompanying materials
4    * are made available under the terms of the Eclipse Public License v1.0
5    * which accompanies this distribution, and is available at
6    * http://www.eclipse.org/legal/epl-v10.html
7    *
8    * Contributors:
9    *     IBM Corporation - initial API and implementation
10   *******************************************************************************/
11  package org.eclipse.jdt.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  * @param name the name of the Java project
121  * @return the Java project with the given name
122  */
123 IJavaProject getJavaProject(String   name);
124 /**
125  * Returns the Java projects in this Java model, or an empty array if there
126  * are none.
127  *
128  * @return the Java projects in this Java model, or an empty array if there
129  * are none
130  * @exception JavaModelException if this request fails.
131  */
132 IJavaProject[] getJavaProjects() throws JavaModelException;
133 /**
134  * Returns an array of non-Java resources (that is, non-Java projects) in
135  * the workspace.
136  * <p>
137  * Non-Java projects include all projects that are closed (even if they have the
138  * Java nature).
139  * </p>
140  * 
141  * @return an array of non-Java projects (<code>IProject</code>s) contained 
142  *              in the workspace.
143  * @throws JavaModelException if this element does not exist or if an
144  *      exception occurs while accessing its corresponding resource
145  * @since 2.1
146  */
147 Object  [] getNonJavaResources() throws JavaModelException;
148 /**
149  * Returns the workspace associated with this Java model.
150  * 
151  * @return the workspace associated with this Java model
152  */
153 IWorkspace getWorkspace();
154 /**
155  * Moves the given elements to the specified container(s).
156  * If one container is specified, all elements are moved to that
157  * container. If more than one container is specified, the number of
158  * elements and containers must match, and each element is moved to
159  * its associated container.
160  * <p>
161  * Optionally, each element can positioned before a sibling
162  * element. If <code>null</code> is specified for sibling, the element
163  * is inserted as the last child of its associated container.
164  * </p>
165  * <p>
166  * Optionally, each element can be renamed. If 
167  * <code>null</code> is specified for the new name, the element
168  * is not renamed. 
169  * </p>
170  * <p>
171  * Optionally, any existing child in the destination container with
172  * the same name can be replaced by specifying <code>true</code> for
173  * force. Otherwise an exception is thrown in the event that a name
174  * collision occurs.
175  * </p>
176  *
177  * @param elements the elements to move
178  * @param containers the container, or list of containers
179  * @param siblings the list of siblings element any of which may be
180  *   <code>null</code>; or <code>null</code>
181  * @param renamings the list of new names any of which may be
182  *   <code>null</code>; or <code>null</code>
183  * @param replace <code>true</code> if any existing child in a target container
184  *   with the target name should be replaced, and <code>false</code> to throw an
185  *   exception in the event of a name collision
186  * @param monitor a progress monitor
187  * @exception JavaModelException if an element could not be moved. Reasons include:
188  * <ul>
189  * <li> There is no element to process (NO_ELEMENTS_TO_PROCESS). The given elements is null or empty</li>
190  * <li> A specified element, container, or sibling does not exist (ELEMENT_DOES_NOT_EXIST)</li>
191  * <li> A <code>CoreException</code> occurred while updating an underlying resource</li>
192  * <li> A container is of an incompatible type (<code>INVALID_DESTINATION</code>)</li>
193  * <li> A sibling is not a child of it associated container (<code>INVALID_SIBLING</code>)</li>
194  * <li> A new name is invalid (<code>INVALID_NAME</code>)</li>
195  * <li> A child in its associated container already exists with the same
196  *      name and <code>replace</code> has been specified as <code>false</code> (<code>NAME_COLLISION</code>)</li>
197  * <li> A container or element is read-only (<code>READ_ONLY</code>) </li>
198  * </ul>
199  *
200  * @exception IllegalArgumentException any element or container is <code>null</code>
201  */
202 void move(IJavaElement[] elements, IJavaElement[] containers, IJavaElement[] siblings, String  [] renamings, boolean replace, IProgressMonitor monitor) throws JavaModelException;
203 
204 /**
205  * Triggers an update of the JavaModel with respect to the referenced external archives.
206  * This operation will issue a JavaModel delta describing the discovered changes, in term
207  * of Java element package fragment roots added, removed or changed.
208  * Note that a collection of elements can be passed so as to narrow the set of archives
209  * to refresh (passing <code>null</code> along is equivalent to refreshing the entire mode). 
210  * The elements can be:
211  * <ul>
212  * <li> package fragment roots corresponding to external archives
213  * <li> Java projects, which referenced external archives will be refreshed
214  * <li> Java model, all referenced external archives will be refreshed.
215  * </ul>
216  * <p> In case an archive is used by multiple projects, the delta issued will account for
217  * all of them. This means that even if a project was not part of the elements scope, it
218  * may still be notified of changes if it is referencing a library comprised in the scope.
219  * <p>
220  * @param elementsScope - a collection of elements defining the scope of the refresh
221  * @param monitor - a progress monitor used to report progress
222  * @exception JavaModelException in one of the corresponding situation:
223  * <ul>
224  *    <li> an exception occurs while accessing project resources </li>
225  * </ul>
226  * 
227  * @see IJavaElementDelta
228  * @since 2.0
229  */
230 void refreshExternalArchives(IJavaElement[] elementsScope, IProgressMonitor monitor) throws JavaModelException;
231 
232 /**
233  * Renames the given elements as specified.
234  * If one container is specified, all elements are renamed within that
235  * container. If more than one container is specified, the number of
236  * elements and containers must match, and each element is renamed within
237  * its associated container.
238  *
239  * @param elements the elements to rename
240  * @param destinations the container, or list of containers
241  * @param names the list of new names
242  * @param replace <code>true</code> if an existing child in a target container
243  *   with the target name should be replaced, and <code>false</code> to throw an
244  *   exception in the event of a name collision
245  * @param monitor a progress monitor
246  * @exception JavaModelException if an element could not be renamed. Reasons include:
247  * <ul>
248  * <li> There is no element to process (NO_ELEMENTS_TO_PROCESS). The given elements is null or empty</li>
249  * <li> A specified element does not exist (ELEMENT_DOES_NOT_EXIST)</li>
250  * <li> A <code>CoreException</code> occurred while updating an underlying resource
251  * <li> A new name is invalid (<code>INVALID_NAME</code>)
252  * <li> A child already exists with the same name and <code>replace</code> has been specified as <code>false</code> (<code>NAME_COLLISION</code>)
253  * <li> An element is read-only (<code>READ_ONLY</code>) 
254  * </ul>
255  */
256 void rename(IJavaElement[] elements, IJavaElement[] destinations, String  [] names, boolean replace, IProgressMonitor monitor) throws JavaModelException;
257 
258 }
259
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags