Package org.aspectj.org.eclipse.jdt.core.dom.rewrite

Class ImportRewrite

java.lang.Object

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

public final class ImportRewrite
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

Nested Classes

Modifier and Type	Class	Description
static class	ImportRewrite.ImportRewriteContext	A ImportRewrite.ImportRewriteContext can optionally be used in e.g.
static enum	ImportRewrite.TypeLocation	Used to determine how a type will be used, so that unwanted annotations can be filtered, which is in particular relevant for avoiding redundant null annotations in the scope of @NonNullByDefault.

Method Summary

Modifier and Type	Method	Description
Annotation	addAnnotation(IAnnotationBinding annotation, AST ast, ImportRewrite.ImportRewriteContext context)	Adds the necessary imports for the given annotation binding to the rewriter's record and returns an Annotation 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.
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.
Type	addImport(ITypeBinding binding, AST ast, ImportRewrite.ImportRewriteContext context, ImportRewrite.TypeLocation location)	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.
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(String declaringTypeName, String simpleName, boolean isField)	Adds a new static import to the rewriter's record and returns a name - single member name if import is successful, else qualified name.
String	addStaticImport(String declaringTypeName, String simpleName, boolean isField, ImportRewrite.ImportRewriteContext context)	Adds a new static import to the rewriter's record and returns a name - single member name if import is successful, else qualified name.
String	addStaticImport(IBinding binding)	Adds a new static import to the rewriter's record and returns a name - single member name if import is successful, else qualified name.
String	addStaticImport(IBinding binding, ImportRewrite.ImportRewriteContext context)	Adds a new static import to the rewriter's record and returns a name - single member name if import is successful, else qualified name.
static ImportRewrite	create(CompilationUnit astRoot, boolean restoreExistingImports)	Creates an ImportRewrite from an AST (CompilationUnit).
static ImportRewrite	create(ICompilationUnit cu, boolean restoreExistingImports)	Creates an ImportRewrite from an 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.
final org.eclipse.text.edits.TextEdit	rewriteImports(org.eclipse.core.runtime.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 (for types in java.lang, types in the same package as the rewrite compilation unit, and types in the compilation unit's main type) 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.
void	setUseContextToFilterImplicitImports(boolean useContextToFilterImplicitImports)	Sets whether a context should be used to properly filter implicit imports.

Methods inherited from class java.lang.Object

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

Method Details

create

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

Creates an ImportRewrite from an 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(CompilationUnit, 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 an ImportRewrite from an AST (CompilationUnit). The AST has to be created from an 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 (for types in java.lang, types in the same package as the rewrite compilation unit, and types in the compilation unit's main type) should not be created, except if necessary to resolve an on-demand import conflict.

The filter is enabled by default.

Note: setUseContextToFilterImplicitImports(boolean) can be used to filter implicit imports when a context is used.

Parameters:

filterImplicitImports - if true, implicit imports will be filtered

See Also:

• setUseContextToFilterImplicitImports(boolean)

setUseContextToFilterImplicitImports

public void setUseContextToFilterImplicitImports(boolean useContextToFilterImplicitImports)

Sets whether a context should be used to properly filter implicit imports.

By default, the option is disabled to preserve pre-3.6 behavior.

When this option is set, the context passed to the addImport*(...) methods is used to determine whether an import can be filtered because the type is implicitly visible. Note that too many imports may be kept if this option is set and addImport*(...) methods are called without a context.

Parameters:

useContextToFilterImplicitImports - the given setting

Since:

3.6

See Also:

• setFilterImplicitImports(boolean)

addAnnotation

public Annotation addAnnotation(IAnnotationBinding annotation,
 AST ast,
 ImportRewrite.ImportRewriteContext context)

Adds the necessary imports for the given annotation binding to the rewriter's record and returns an Annotation that can be used in the code.

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

The content of the compilation unit itself is actually not modified in any way by this method; rather, the rewriter just records newly added imports.

Parameters:

annotation - the annotation to be added

ast - the AST to create the returned annotation for

context - an optional context that knows about types visible in the current scope or null to use the default context (only using the available imports)

Returns:

an annotation node. The returned annotation contains unqualified type names where an import could be added or was already known. Type names are fully qualified if an import conflict prevented an import.

Since:

3.10

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.

The content of the compilation unit itself is actually not modified in any way by this method; rather, the rewriter just records that a new import has been added.

Parameters:

typeSig - the signature of the type to be added.

ast - the AST to create the returned type for.

Returns:

a type node for the given type signature. Type names are simple names if an import could be used, or else qualified names if an import conflict prevented an import.

addImportFromSignature

public 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. 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.

The content of the compilation unit itself is actually not modified in any way by this method; rather, the rewriter just records that a new import has been added.

Parameters:

typeSig - the signature of the type to be added.

ast - the AST to create the returned type for.

context - an optional context that knows about types visible in the current scope or null to use the default context only using the available imports.

Returns:

a type node for the given type signature. Type names are simple names if an import could be used, or else qualified names if an import conflict prevented an import.

addImport

public 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. 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. Type annotations 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.

The content of the compilation unit itself is actually not modified in any way by this method; rather, the rewriter just records that a new import has been added.

Parameters:

binding - the signature of the type to be added.

Returns:

a type reference for the given type binding. Type names are simple names if an import could be used, or else qualified names if an import conflict prevented an import.

addImport

public 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. 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. Type annotations 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.

The content of the compilation unit itself is actually not modified in any way by this method; rather, the rewriter just records that a new import has been added.

Parameters:

binding - the signature of the type to be added.

context - an optional context that knows about types visible in the current scope or null to use the default context only using the available imports.

Returns:

a type reference for the given type binding. Type names are simple names if an import could be used, or else qualified names if an import conflict prevented an import.

addImport

public 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. 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. If type annotations or type arguments are present at any point, the import is added up to that point and the type is retained from that point with type annotations and type arguments.

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.

The content of the compilation unit itself is actually not modified in any way by this method; rather, the rewriter just records that a new import has been added.

Parameters:

binding - the signature of the type to be added.

ast - the AST to create the returned type for.

Returns:

a type node for the given type binding. Type names are simple names if an import could be used, or else qualified names if an import conflict prevented an import.

addImport

public 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. 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. If type annotations or type arguments are present at any point, the import is added up to that point and the type is retained from that point with type annotations and type arguments

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.

The content of the compilation unit itself is actually not modified in any way by this method; rather, the rewriter just records that a new import has been added.

Parameters:

binding - the signature of the type to be added.

ast - the AST to create the returned type for.

context - an optional context that knows about types visible in the current scope or null to use the default context only using the available imports.

Returns:

a type node for the given type binding. Type names are simple names if an import could be used, or else qualified names if an import conflict prevented an import.

addImport

public Type addImport(ITypeBinding binding,
 AST ast,
 ImportRewrite.ImportRewriteContext context,
 ImportRewrite.TypeLocation location)

Adds a new import to the rewriter's record and returns a Type that can be used in the code. 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. If type annotations or type arguments are present at any point, the import is added up to that point and the type is retained from that point with type annotations and type arguments

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.

The content of the compilation unit itself is actually not modified in any way by this method; rather, the rewriter just records that a new import has been added.

Parameters:

binding - the signature of the type to be added.

ast - the AST to create the returned type for.

context - an optional context that knows about types visible in the current scope or null to use the default context only using the available imports.

location - where the type will be used. This information is needed to filter unwanted (nullness) type annotations.

Returns:

a type node for the given type binding. Type names are simple names if an import could be used, or else qualified names if an import conflict prevented an import.

Since:

3.13

addImport

public 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. The type binding can only be an array or non-generic type.

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.

The content of the compilation unit itself is actually not modified in any way by this method; rather, the rewriter just records that a new import has been added.

Parameters:

qualifiedTypeName - the qualified type name of the type to be added

context - an optional context that knows about types visible in the current scope or null to use the default context only using the available imports.

Returns:

a type reference for the given qualified type name. The type name is a simple name if an import could be used, or else a qualified name if an import conflict prevented an import.

addImport

public 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. The type binding can only be an array or non-generic type.

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.

The content of the compilation unit itself is actually not modified in any way by this method; rather, the rewriter just records that a new import has been added.

Parameters:

qualifiedTypeName - the qualified type name of the type to be added

Returns:

a type reference for the given qualified type name. The type name is a simple name if an import could be used, or else a qualified name if an import conflict prevented an import.

addStaticImport

public String addStaticImport(IBinding binding)

Adds a new static import to the rewriter's record and returns a name - single member name if import is successful, else qualified name.

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

The content of the compilation unit itself is actually not modified in any way by this method; rather, the rewriter just records that a new import has been added.

Parameters:

binding - The binding of the static field or method to be added.

Returns:

either the simple member name if the import was successful or else the qualified name if an import conflict prevented the import

Throws:

IllegalArgumentException - an IllegalArgumentException is thrown if the binding is not a static field or method.

addStaticImport

public String addStaticImport(IBinding binding,
 ImportRewrite.ImportRewriteContext context)

Adds a new static import to the rewriter's record and returns a name - single member name if import is successful, else qualified name.

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

The content of the compilation unit itself is actually not modified in any way by this method; rather, the rewriter just records that a new import has been added.

Parameters:

binding - The binding of the static field or method to be added.

context - an optional context that knows about members visible in the current scope or null to use the default context only using the available imports.

Returns:

either the simple member name if the import was successful or else the qualified name if an import conflict prevented the import

Throws:

IllegalArgumentException - an IllegalArgumentException is thrown if the binding is not a static field or method.

addStaticImport

public String addStaticImport(String declaringTypeName,
 String simpleName,
 boolean isField)

Adds a new static import to the rewriter's record and returns a name - single member name if import is successful, else qualified name.

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

The content of the compilation unit itself is actually not modified in any way by this method; rather, the rewriter just records that a new import has been added.

Parameters:

declaringTypeName - The qualified name of the static's member declaring type

simpleName - the simple name of the member; either a field or a method name.

isField - true specifies that the member is a field, false if it is a method.

Returns:

either the simple member name if the import was successful or else the qualified name if an import conflict prevented the import

addStaticImport

public String addStaticImport(String declaringTypeName,
 String simpleName,
 boolean isField,
 ImportRewrite.ImportRewriteContext context)

Adds a new static import to the rewriter's record and returns a name - single member name if import is successful, else qualified name.

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

The content of the compilation unit itself is actually not modified in any way by this method; rather, the rewriter just records that a new import has been added.

Parameters:

declaringTypeName - The qualified name of the static's member declaring type

simpleName - the simple name of the member; either a field or a method name.

isField - true specifies that the member is a field, false if it is a method.

context - an optional context that knows about members visible in the current scope or null to use the default context only using the available imports.

Returns:

either the simple member name if the import was successful or else the qualified name if an import conflict prevented the import

removeImport

public boolean removeImport(String qualifiedName)

Records to remove a import. No remove is recorded if no such import exists or if such an import is recorded to be added. In that case the record of the addition is discarded.

The content of the compilation unit itself is actually not modified in any way by this method; rather, the rewriter just records that an import has been removed.

Parameters:

qualifiedName - The import name to remove.

Returns:

true is returned of an import of the given name could be found.

removeStaticImport

public boolean removeStaticImport(String qualifiedName)

Records to remove a static import. No remove is recorded if no such import exists or if such an import is recorded to be added. In that case the record of the addition is discarded.

The content of the compilation unit itself is actually not modified in any way by this method; rather, the rewriter just records that a new import has been removed.

Parameters:

qualifiedName - The import name to remove.

Returns:

true is returned of an import of the given name could be found.

rewriteImports

public final org.eclipse.text.edits.TextEdit rewriteImports(org.eclipse.core.runtime.IProgressMonitor monitor)
                                                     throws org.eclipse.core.runtime.CoreException

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. The compilation unit itself is not modified.

Calling this methods does not discard the modifications on record. Subsequence modifications are added to the ones already on record. If this method is called again later, the resulting text edit object will accurately reflect the net cumulative effect of all those changes.

Parameters:

monitor - the progress monitor or null

Returns:

text edit object describing the changes to the document corresponding to the changes recorded by this rewriter

Throws:

org.eclipse.core.runtime.CoreException - the exception is thrown if the rewrite fails.

getCreatedImports

public 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.

Note that this list doesn't need to be the same as the added imports (see getAddedImports()) as implicit imports are not created and some imports are represented by on-demand imports instead.

Returns:

the created imports

getCreatedStaticImports

public 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.

Note that this list doesn't need to be the same as the added static imports (getAddedStaticImports()) as implicit imports are not created and some imports are represented by on-demand imports instead.

Returns:

the created imports

getAddedImports

public String[] getAddedImports()

Returns all non-static imports that are recorded to be added.

Returns:

the imports recorded to be added.

getAddedStaticImports

public String[] getAddedStaticImports()

Returns all static imports that are recorded to be added.

Returns:

the static imports recorded to be added.

getRemovedImports

public String[] getRemovedImports()

Returns all non-static imports that are recorded to be removed.

Returns:

the imports recorded to be removed.

getRemovedStaticImports

public String[] getRemovedStaticImports()

Returns all static imports that are recorded to be removed.

Returns:

the static imports recorded to be removed.

hasRecordedChanges

public boolean hasRecordedChanges()

Returns true if imports have been recorded to be added or removed.

Returns:

boolean returns if any changes to imports have been recorded.