Java model

The Java model is the set of classes that model the objects associated with creating, editing, and building a Java program. The Java model classes are defined in org.eclipse.jdt.core.  These classes implement Java specific behavior for resources and further decompose Java resources into model elements.

Java elements

The package org.eclipse.jdt.core defines the classes that model the elements that compose a Java program. The JDT uses an in-memory object model to represent the structure of a Java program. This structure is derived from the project's class path. The model is hierarchical. Elements of a program can be decomposed into child elements.

Manipulating Java elements is similar to manipulating resource objects.  When you work with a Java element, you are actually working with a handle to some underlying model object.  You must use the exists() protocol to determine whether the element is actually present in the workspace. 

The following table summarizes the different kinds of Java elements.

Element Description
IJavaModel Represents the root Java element, corresponding to the workspace. The parent of all projects with the Java nature. It also gives you access to the projects without the java nature.
IJavaProject Represents a Java project in the workspace. (Child of IJavaModel)
IPackageFragmentRoot Represents a set of package fragments, and maps the fragments to an underlying resource which is either a folder, JAR, or ZIP file. (Child of IJavaProject)
IPackageFragment Represents the portion of the workspace that corresponds to an entire package, or a portion of the package. (Child of IPackageFragmentRoot )
ICompilationUnit Represents a Java source (.java) file. (Child of IPackageFragment )
IPackageDeclaration Represents a package declaration in a compilation unit. (Child of ICompilationUnit )
IImportContainer Represents the collection of package import declarations in a compilation unit. (Child of ICompilationUnit )
IImportDeclaration Represents a single package import declaration. (Child of IImportContainer )
IType Represents either a source type inside a compilation unit, or a binary type inside a class file.
IField Represents a field inside a type. (Child of IType )
IMethod Represents a method or constructor inside a type. (Child of IType )
IInitializer Represents a static or instance initializer inside a type. (Child of IType )
IClassFile Represents a compiled (binary) type.  (Child of IPackageFragment )
ITypeParameter Represents a type parameter.  (Not a child of any Java element, it is obtained using IType.getTypeParameter(String) or IMethod.getTypeParameter(String))
ILocalVariable Represents a local variable in a method or an initializer.  (Not a child of any Java element, it is obtained using ICodeAssist.codeSelect(int, int))
IAnnotation Represents a Java 5 annotation. (Not a child of any Java element, it is obtained using IAnnotatable.getAnnotation(String) or IAnnotatable.getAnnotations())
IAnnotatable Represents a type, a field, a method, a local variable, or a package declaration that can be annotated with one or several IAnnotations.

All Java elements support the IJavaElement interface.

Some of the elements are shown in the Packages view.  These elements implement the IOpenable interface, since they must be opened before they can be navigated. The figure below shows how these elements are represented in the Packages view.

Packages View showing elements implementing the IOpenable interface

The Java elements that implement IOpenable are created primarily from information found in the underlying resource files.  The same elements are represented generically in the resource navigator view.

Resource Navigator showing elements implementing the IOpenable interface

Since 3.3, IOpenables that are the root of ITypes implement ITypeRoot . These are ICompilationUnit and IClassFile.

Other elements correspond to the items that make up a Java compilation unit. The figure below shows a Java compilation unit and a content outliner that displays the source elements in the compilation unit.

An editor and a content outliner illustrating the relation between corresponding source elements

These elements implement the ISourceReference interface, since they can provide corresponding source code. (As these elements are selected in the content outliner, their corresponding source code is shown in the Java editor).

Java elements and their resources

Many of the Java elements correspond to generic resources in the workspace.  When you want to create Java elements from a generic resource the class JavaCore is the best starting point. The following code snippet shows how to get Java elements from their corresponding resources.

    
    private void createJavaElementsFrom(IProject myProject, IFolder myFolder, IFile myFile) {
        IJavaProject myJavaProject= JavaCore.create(myProject);
        if (myJavaProject == null)
            // the project is not configured for Java (has no Java nature)
            return;
            
        // get a package fragment or package fragment root
        IJavaElement myPackageFragment= JavaCore.create(myFolder);
        
        // get a .java (compilation unit), .class (class file), or
        // .jar (package fragment root)
        IJavaElement myJavaFile = JavaCore.create(myFile);
    }

Once you have a Java element, you can use the JDT API to traverse and query the model.  You may also query the non-Java resources contained in a Java element. 

    private void createJavaElementsFrom(IProject myProject, IFolder myFolder, IFile myFile) throws JavaModelException {
        ...
        // get the non Java resources contained in my project.
        Object[] nonJavaChildren = myJavaProject.getNonJavaResources();
        ...
    }

Java projects

When you create a Java project from a simple project, JavaCore will check to see if the project is configured with the Java nature.  The JDT plug-in uses a project nature to designate a project as having Java behavior.  This nature (org.eclipse.jdt.core.JavaCore#NATURE_ID ) is assigned to a project when the "New Java project" wizard creates a project.  If the Java nature is not configured on a project, JavaCore will return null when asked to create the project.

JavaCore is also used to maintain the Java class path, including locations for finding source code and libraries, and locations for generating output binary (.class) files.

What are the unique characteristics of Java projects? They record their classpath in a ".classpath" file and add the Java incremental project builder to the project's build spec.  Otherwise, they are just regular projects and can be configured with other natures (and other incremental builders) by plug-ins. Plug-ins that want to configure projects with Java behavior in addition to their own behavior typically use the NewJavaProjectWizardPage to assign the Java nature to the project in addition to their own custom natures or behavior.

IJavaModel can be considered the parent of all projects in the workspace that have the Java project nature (and therefore can be treated as an IJavaProject).