Source code: javax/ide/model/java/JavaModel.java
1 /*
2 * @(#)JavaModel.java
3 */
4
5 package javax.ide.model.java;
6
7 import javax.ide.model.java.declaration.ClassD;
8 import javax.ide.model.java.declaration.PackageD;
9 import javax.ide.model.java.declaration.TypeD;
10 import javax.ide.model.java.source.util.TreeLocator;
11 import javax.ide.model.java.source.util.TreeResolver;
12 import javax.ide.model.java.source.write.TreeManager;
13
14 /**
15 * The JavaModel is the central point of access to all source
16 * compilation unit facilities. Read and write access to parse trees
17 * is provided through the TreeManager interface. The ability to
18 * resolve source references to declarations is provided through the
19 * TreeResolver interface. The ability to fetch the source for a
20 * declaration is provided through the TreeLocator interface. Finally,
21 * declaration loading is provided through the JavaModel interface
22 * itself. Typically, a JavaModel will have an underlying classpath
23 * and sourcepath that define its search path. <p/>
24 *
25 * @author Andy Yu
26 */
27 public interface JavaModel
28 extends TreeManager, TreeResolver, TreeLocator
29 {
30 /**
31 * Fetches a ClassD for the given fully qualified name in source format,
32 * null if none. The name may denote a primitive type,
33 * <code>void</code> return type, array type, or class type. <p/>
34 *
35 * If multiple sources of class information are available, the most
36 * up-to-date one should be returned. For example, suppose we have
37 * both a class file C.class and a source file C.java that both
38 * provide class information for a class C. If C.class has a more
39 * recent timestamp than C.java, then a ClassD built from C.class
40 * should be returned. <p/>
41 *
42 * Although implementations are not required to return the same
43 * instance each time, they are encouraged to do so as it will
44 * dramatically improve performance. <p/>
45 *
46 * Note: TypeD's, except for TypeVariableD's, can be uniquely identified
47 * by their source names. <p/>
48 *
49 * @see TypeD#getSourceName()
50 *
51 * @param sourceName The fully qualified name in source format, e.g.
52 * "java.lang.Object", "java.util.Map.Entry[]".
53 *
54 * @return A ClassD for the given fully qualified name, null if none can
55 * be found.
56 */
57 public ClassD getClass(String sourceName);
58
59 /**
60 * Fetches a TypeD for the given array type of the specified component
61 * type an dimensions. <p/>
62 *
63 * @param componentType The array component type.
64 * @param dims The requested array dimension.
65 *
66 * @return A TypeD for the type requested. If dims is zero or
67 * componentType is null, then componentType is returned as is.
68 *
69 * @throws IllegalArgumentException if dims < 0.
70 */
71 public TypeD getArrayType(TypeD componentType, int dims);
72
73 /**
74 * Fetches a PackageD for the given fully-qualified name. <p/>
75 *
76 * Although implementations are not required to return the same
77 * instance each time, they are encouraged to do so as it will
78 * dramatically improve performance. <p/>
79 *
80 * @param sourceName The fully qualified package name. "" for the
81 * root package.
82 *
83 * @return A PackageD for the requested package.
84 */
85 public PackageD getPackage(String sourceName);
86 }