131d36f9bbe001da7072ff71b4f0e135ee94be24
[phpeclipse.git] / net.sourceforge.phpeclipse / src / net / sourceforge / phpdt / core / IPackageFragment.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.runtime.IProgressMonitor;
14
15 /**
16  * A package fragment is a portion of the workspace corresponding to an entire package,
17  * or to a portion thereof. The distinction between a package fragment and a package
18  * is that a package with some name is the union of all package fragments in the class path
19  * which have the same name.
20  * <p>
21  * Package fragments elements need to be opened before they can be navigated or manipulated.
22  * The children are of type <code>ICompilationUnit</code> (representing a source file) or 
23  * <code>IClassFile</code> (representing a binary class file).
24  * The children are listed in no particular order.
25  * </p>
26  * <p>
27  * This interface is not intended to be implemented by clients.
28  * </p>
29  */
30 public interface IPackageFragment extends IParent, IJavaElement, IOpenable { 
31 //ISourceManipulation {
32
33         /**     
34          * <p>
35          * The name of package fragment for the default package (value: the empty 
36          * string, <code>""</code>).
37          * </p>
38         */
39         public static final String DEFAULT_PACKAGE_NAME = ""; //$NON-NLS-1$
40         /**
41          * Returns whether this fragment contains at least one Java resource.
42          * @return true if this fragment contains at least one Java resource, false otherwise
43          */
44 //      boolean containsJavaResources() throws JavaModelException;
45         /**
46          * Creates and returns a compilation unit in this package fragment 
47          * with the specified name and contents. No verification is performed
48          * on the contents.
49          *
50          * <p>It is possible that a compilation unit with the same name already exists in this 
51          * package fragment.
52          * The value of the <code>force</code> parameter effects the resolution of
53          * such a conflict:<ul>
54          * <li> <code>true</code> - in this case the compilation is created with the new contents</li>
55          * <li> <code>false</code> - in this case a <code>JavaModelException</code> is thrown</li>
56          * </ul>
57          *
58          * @param contents the given contents
59          * @param force specify how to handle conflict is the same name already exists
60          * @param monitor the given progress monitor
61          * @param name the given name
62          * @exception JavaModelException if the element could not be created. Reasons include:
63          * <ul>
64          * <li> This Java element does not exist (ELEMENT_DOES_NOT_EXIST)</li>
65          * <li> A <code>CoreException</code> occurred while creating an underlying resource
66          * <li> The name is not a valid compilation unit name (INVALID_NAME)
67          * <li> The contents are <code>null</code> (INVALID_CONTENTS)
68          * </ul>
69          * @return a compilation unit in this package fragment 
70          * with the specified name and contents
71          */
72         ICompilationUnit createCompilationUnit(String name, String contents, boolean force, IProgressMonitor monitor) throws JavaModelException;
73         /**
74          * Returns the class file with the specified name
75          * in this package (for example, <code>"Object.class"</code>).
76          * The ".class" suffix is required.
77          * This is a handle-only method.  The class file may or may not be present.
78          * @param name the given name
79          * @return the class file with the specified name in this package
80          */
81 //      IClassFile getClassFile(String name);
82         /**
83          * Returns all of the class files in this package fragment.
84          *
85          * <p>Note: it is possible that a package fragment contains only
86          * compilation units (in other words, its kind is <code>K_SOURCE</code>), in
87          * which case this method returns an empty collection.
88          *
89          * @exception JavaModelException if this element does not exist or if an
90          *              exception occurs while accessing its corresponding resource.
91          * @return all of the class files in this package fragment
92          */
93 //      IClassFile[] getClassFiles() throws JavaModelException;
94         /**
95          * Returns the compilation unit with the specified name
96          * in this package (for example, <code>"Object.java"</code>).
97          * The name has to be a valid compilation unit name.
98          * This is a handle-only method.  The compilation unit may or may not be present.
99          * @see JavaConventions#validateCompilationUnitName
100          * @param name the given name
101          * @return the compilation unit with the specified name in this package
102          */
103         ICompilationUnit getCompilationUnit(String name);
104         /**
105          * Returns all of the compilation units in this package fragment.
106          *
107          * <p>Note: it is possible that a package fragment contains only
108          * class files (in other words, its kind is <code>K_BINARY</code>), in which
109          * case this method returns an empty collection.
110          *
111          * @exception JavaModelException if this element does not exist or if an
112          *              exception occurs while accessing its corresponding resource.
113          * @return all of the compilation units in this package fragment
114          */
115 //      ICompilationUnit[] getCompilationUnits() throws JavaModelException;
116         /**
117          * Returns the dot-separated package name of this fragment, for example
118          * <code>"java.lang"</code>, or <code>""</code> (the empty string),
119          * for the default package.
120          * 
121          * @return the dot-separated package name of this fragment
122          */
123         String getElementName();
124         /**
125          * Returns this package fragment's root kind encoded as an integer.
126          * A package fragment can contain <code>.java</code> source files,
127          * or <code>.class</code> files. This is a convenience method.
128          *
129          * @see IPackageFragmentRoot#K_SOURCE
130          * @see IPackageFragmentRoot#K_BINARY
131          *
132          * @exception JavaModelException if this element does not exist or if an
133          *              exception occurs while accessing its corresponding resource.
134          * @return this package fragment's root kind encoded as an integer
135          */
136 //      int getKind() throws JavaModelException;
137         /**
138          * Returns an array of non-Java resources contained in this package fragment.
139          * <p>
140          * Non-Java resources includes other files and folders located in the same
141          * directory as the compilation units or class files for this package 
142          * fragment. Source files excluded from this package by one or more
143          * exclusion patterns on the corresponding source classpath entry are
144          * considered non-Java resources and will appear in the result
145          * (possibly in a folder).
146          * </p>
147          * 
148          * @return an array of non-Java resources contained in this package fragment
149          * @see IClasspathEntry#getExclusionPatterns
150          */
151 //      Object[] getNonJavaResources() throws JavaModelException;
152         /**
153          * Returns whether this package fragment's name is
154          * a prefix of other package fragments in this package fragment's
155          * root.
156          *
157          * @exception JavaModelException if this element does not exist or if an
158          *              exception occurs while accessing its corresponding resource.
159          * @return true if this package fragment's name is a prefix of other package fragments in this package fragment's root, false otherwise
160          */
161 //      boolean hasSubpackages() throws JavaModelException;
162         /**
163          * Returns whether this package fragment is a default package.
164          * This is a handle-only method.
165          * 
166          * @return true if this package fragment is a default package
167          */
168         boolean isDefaultPackage();
169 }