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