Eclipse JDT Plug-in Developer Guide (Galileo) - ImportRewrite (Eclipse JDT API Specification)

Overview

Package

Class

Use

Tree

Deprecated

Index

Help

Eclipse JDT
Release 3.5

PREV CLASS NEXT CLASS

NO FRAMES

SUMMARY: NESTED | FIELD | CONSTR | METHOD

DETAIL: FIELD | CONSTR | METHOD

org.eclipse.jdt.core.dom.rewrite
Class ImportRewrite


java.lang.Object
  
org.eclipse.jdt.core.dom.rewrite.ImportRewrite

public final class ImportRewrite
extends Object
extends Object

The ImportRewrite helps updating imports following a import order and on-demand imports threshold as configured by a project.

The import rewrite is created on a compilation unit and collects references to types that are added or removed. When adding imports, e.g. using addImport(String), the import rewrite evaluates if the type can be imported and returns the a reference to the type that can be used in code. This reference is either unqualified if the import could be added, or fully qualified if the import failed due to a conflict with another element of the same name.

On rewriteImports(IProgressMonitor) the rewrite translates these descriptions into text edits that can then be applied to the original source. The rewrite infrastructure tries to generate minimal text changes and only works on the import statements. It is possible to combine the result of an import rewrite with the result of a ASTRewrite as long as no import statements are modified by the AST rewrite.

The options controlling the import order and on-demand thresholds are:

setImportOrder(String[]) specifies the import groups and their preferred order
setOnDemandImportThreshold(int) specifies the number of imports in a group needed for a on-demand import statement (star import)
setStaticOnDemandImportThreshold(int) specifies the number of static imports in a group needed for a on-demand import statement (star import)

This class is not intended to be subclassed.

Since:: 3.2

Nested Class Summary

static class ImportRewrite.ImportRewriteContext
          A ImportRewrite.ImportRewriteContext can optionally be used in e.g.

Method Summary

String addImport ( ITypeBinding binding)
          Adds a new import to the rewriter's record and returns a type reference that can be used in the code.

Type addImport ( ITypeBinding binding, AST ast)
          Adds a new import to the rewriter's record and returns a Type that can be used in the code.

Type addImport ( ITypeBinding binding, AST ast, ImportRewrite.ImportRewriteContext context)
          Adds a new import to the rewriter's record and returns a Type that can be used in the code.

String addImport ( ITypeBinding binding, ImportRewrite.ImportRewriteContext context)
          Adds a new import to the rewriter's record and returns a type reference that can be used in the code.

String addImport ( String qualifiedTypeName)
          Adds a new import to the rewriter's record and returns a type reference that can be used in the code.

String addImport ( String qualifiedTypeName, ImportRewrite.ImportRewriteContext context)
          Adds a new import to the rewriter's record and returns a type reference that can be used in the code.

Type addImportFromSignature ( String typeSig, AST ast)
          Adds a new import to the rewriter's record and returns a Type node that can be used in the code as a reference to the type.

Type addImportFromSignature ( String typeSig, AST ast, ImportRewrite.ImportRewriteContext context)
          Adds a new import to the rewriter's record and returns a Type node that can be used in the code as a reference to the type.

String addStaticImport ( IBinding binding)
          Adds a new static import to the rewriter's record and returns a reference that can be used in the code.

String addStaticImport ( IBinding binding, ImportRewrite.ImportRewriteContext context)
          Adds a new static import to the rewriter's record and returns a reference that can be used in the code.

String addStaticImport ( String declaringTypeName, String simpleName, boolean isField)
          Adds a new static import to the rewriter's record and returns a reference that can be used in the code.

String addStaticImport ( String declaringTypeName, String simpleName, boolean isField, ImportRewrite.ImportRewriteContext context)
          Adds a new static import to the rewriter's record and returns a reference that can be used in the code.

static ImportRewrite create ( CompilationUnit astRoot, boolean restoreExistingImports)
          Creates a ImportRewrite from a an AST ( CompilationUnit).

static ImportRewrite create ( ICompilationUnit cu, boolean restoreExistingImports)
          Creates a ImportRewrite from a ICompilationUnit.

String[] getAddedImports ()
          Returns all non-static imports that are recorded to be added.

String[] getAddedStaticImports ()
          Returns all static imports that are recorded to be added.

ICompilationUnit getCompilationUnit ()
          The compilation unit for which this import rewrite was created for.

String[] getCreatedImports ()
          Returns all new non-static imports created by the last invocation of rewriteImports(IProgressMonitor) or null if these methods have not been called yet.

String[] getCreatedStaticImports ()
          Returns all new static imports created by the last invocation of rewriteImports(IProgressMonitor) or null if these methods have not been called yet.

ImportRewrite.ImportRewriteContext getDefaultImportRewriteContext ()
          Returns the default rewrite context that only knows about the imported types.

String[] getRemovedImports ()
          Returns all non-static imports that are recorded to be removed.

String[] getRemovedStaticImports ()
          Returns all static imports that are recorded to be removed.

boolean hasRecordedChanges ()
          Returns true if imports have been recorded to be added or removed.

boolean removeImport ( String qualifiedName)
          Records to remove a import.

boolean removeStaticImport ( String qualifiedName)
          Records to remove a static import.

TextEdit rewriteImports ( IProgressMonitor monitor)
          Converts all modifications recorded by this rewriter into an object representing the corresponding text edits to the source code of the rewrite's compilation unit.

void setFilterImplicitImports (boolean filterImplicitImports)
          Specifies that implicit imports (types in default package, package java.lang or in the same package as the rewrite compilation unit should not be created except if necessary to resolve an on-demand import conflict.

void setImportOrder ( String[] order)
          Defines the import groups and order to be used by the ImportRewrite.

void setOnDemandImportThreshold (int threshold)
          Sets the on-demand import threshold for normal (non-static) imports.

void setStaticOnDemandImportThreshold (int threshold)
          Sets the on-demand import threshold for static imports.

Methods inherited from class java.lang. Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

create

public static 
ImportRewrite create(
ICompilationUnit cu,
                                   boolean restoreExistingImports)
                            throws 
JavaModelException

Creates a ImportRewrite from a ICompilationUnit. If restoreExistingImports is true, all existing imports are kept, and new imports will be inserted at best matching locations. If restoreExistingImports is false, the existing imports will be removed and only the newly added imports will be created.

Note that create(ICompilationUnit, boolean) is more efficient than this method if an AST for the compilation unit is already available.

Parameters:: cu - the compilation unit to create the imports for; restoreExistingImports - specifies if the existing imports should be kept or removed.
Returns:: the created import rewriter.
Throws:: JavaModelException - thrown when the compilation unit could not be accessed.

create

public static 
ImportRewrite create(
CompilationUnit astRoot,
                                   boolean restoreExistingImports)

Creates a ImportRewrite from a an AST ( CompilationUnit). The AST has to be created from a ICompilationUnit, that means ASTParser.setSource(ICompilationUnit) has been used when creating the AST. If restoreExistingImports is true, all existing imports are kept, and new imports will be inserted at best matching locations. If restoreExistingImports is false, the existing imports will be removed and only the newly added imports will be created.

Note that this method is more efficient than using create(ICompilationUnit, boolean) if an AST is already available.

Parameters:: astRoot - the AST root node to create the imports for; restoreExistingImports - specifies if the existing imports should be kept or removed.
Returns:: the created import rewriter.
Throws:: IllegalArgumentException - thrown when the passed AST is null or was not created from a compilation unit.

setImportOrder

public void setImportOrder(
String[] order)

Defines the import groups and order to be used by the ImportRewrite. Imports are added to the group matching their qualified name most. The empty group name groups all imports not matching any other group. Static imports are managed in separate groups. Static import group names are prefixed with a '#' character.

Parameters:: order - A list of strings defining the import groups. A group name must be a valid package name or empty. If can be prefixed by the '#' character for static import groups

setOnDemandImportThreshold

public void setOnDemandImportThreshold(int threshold)

Sets the on-demand import threshold for normal (non-static) imports. This threshold defines the number of imports that need to be in a group to use a on-demand (star) import declaration instead.

Parameters:: threshold - a positive number defining the on-demand import threshold for normal (non-static) imports.
Throws:: IllegalArgumentException - a IllegalArgumentException is thrown if the number is not positive.

setStaticOnDemandImportThreshold

public void setStaticOnDemandImportThreshold(int threshold)

Sets the on-demand import threshold for static imports. This threshold defines the number of imports that need to be in a group to use a on-demand (star) import declaration instead.

Parameters:: threshold - a positive number defining the on-demand import threshold for normal (non-static) imports.
Throws:: IllegalArgumentException - a IllegalArgumentException is thrown if the number is not positive.

getCompilationUnit

public 
ICompilationUnit getCompilationUnit()

The compilation unit for which this import rewrite was created for.

Returns:: the compilation unit for which this import rewrite was created for.

getDefaultImportRewriteContext

public 
ImportRewrite.ImportRewriteContext getDefaultImportRewriteContext()

Returns the default rewrite context that only knows about the imported types. Clients can write their own context and use the default context for the default behavior.

Returns:: the default import rewrite context.

setFilterImplicitImports

public void setFilterImplicitImports(boolean filterImplicitImports)

Specifies that implicit imports (types in default package, package java.lang or in the same package as the rewrite compilation unit should not be created except if necessary to resolve an on-demand import conflict. The filter is enabled by default.

Parameters:: filterImplicitImports - if set, implicit imports will be filtered.

addImportFromSignature

public 
Type addImportFromSignature(
String typeSig,
                                   
AST ast)

Adds a new import to the rewriter's record and returns a Type node that can be used in the code as a reference to the type. The type binding can be an array binding, type variable or wildcard. If the binding is a generic type, the type parameters are ignored. For parameterized types, also the type arguments are processed and imports added if necessary. Anonymous types inside type arguments are normalized to their base type, wildcard of wildcards are ignored.

No imports are added for types that are already known. If a import for a type is recorded to be removed, this record is discarded instead.