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