org.eclipse.emf.codegen.util
Class ImportManager

java.lang.Object
  org.eclipse.emf.codegen.util.ImportManager

public class ImportManager
extends java.lang.Object

A manager for import declarations in generated code.

An instance of ImportManager should be created for each compilation unit being generated. It maintains the list of imports to be added to the compilation unit and associates registered short names with their corresponding qualified names.

Common usage of ImportManager is very simple. This example assumes that a StringBuilder is being used to accumulate the text for a generated source file:

 StringBuilder result = new StringBuilder();
 ImportManager importManager = new ImportManager("com.example.target", "Target");
 ...
 importManager.markImportLocation(result);
 ...
 result.append(importManager.getImportedName("com.example.lib.Example", true));
 ...
 result.append(importManager.getImportedName("java.lang.String", true));
 ...
 result.append(importManager.getImportedName("java.util.Arrays", true));
 ...
 result.append(importManager.getImportedName("org.test.Example", true));
 ...
 result.append(importManager.getImportedName("org.test.Target", true));
 ...
 result.append(importManager.getImportedName("com.example.target.Helper", true));
 ...
 importManager.emitSortedImports();

The constructor is passed the package name and short name for the compilation unit being generated. The point where the imports should be inserted is marked by calling markImportLocation. Then, getImportedName() is called each time a type name is needed, to determine the correct name to use. Passing true as the second argument instructs the import manager to automatically import the specified type, if possible.

In this case, the following names would be returned:

• Example
• String
• Arrays
• org.test.Example
• org.test.Target
• Helper

Note that org.test.Example cannot be shortened because the short name Example is already taken. Similarly, Target is already taken by the compilation unit, itself. Helper and String are shortened, but they don't actually require imports.

Finally, the needed import declarations are inserted by calling emitSortedImports(). In this case, only two import declarations are produced:

 import com.example.lib.Example;

 import java.util.Arrays;

In addition to auto-importing, ImportManager supports explicit pre-registration of individual and wildcard imports via addImport().

ImportManager provides special handling for inner types, which are specified using $ instead of dot in the qualified name. Note that this means that ImportManager does not support the use of $ as a character within a class name, although this is allowed by the Java language. For example:

 result.append(importManager.getImportedName("com.example.lib.Outer$Inner", true));

This imports com.example.lib.Outer and returns Outer.Inner. Multiple levels of nested classes are supported, but $ must be used as the separator between all of them. A qualified name with any dots following the first $ is not allowed.

Note that it is also possible, instead, to use the simple dot notation for an Outer class, in which case the containing class names will be treated as part of the package name and a more specific import will result. For example:

 result.append(importManager.getImportedName("com.example.lib.Outer.Inner", true));

This imports com.example.lib.Outer.Inner and returns Inner. Later, if the $ notation is used, it can match an import of this type:

 result.append(importManager.getImportedName("com.example.lib.Outer$Inner", false));

This will use the existing import and return Inner. If, however, the second argument had been true it would have imported Outer before getting the chance to consider Inner.

ImportManager also handles array types, by always stripping off the indices (the square brackets) when adding imports and preserving them when forming an imported name.

Since:

2.1

Field Summary

protected java.util.HashSet<java.lang.String>	importedPackages The set of packages that have been imported with wildcards.
protected java.util.SortedSet<java.lang.String>	imports The set of imports to be added to the compilation unit.
protected java.util.HashSet<java.lang.String>	javaLangImports The set of short names from java.lang for which explicit import declarations are desired.
protected java.util.HashMap<java.lang.String,java.lang.String>	shortNameToImportMap The mapping from short names to qualified names for explicit and implicit imports.

Constructor Summary

ImportManager(java.lang.String compilationUnitPackage)
Creates an import manager for a compilation unit in the given package.

ImportManager(java.lang.String compilationUnitPackage, java.lang.String compilationUnitShortName)
Creates an import manager for the given compilation unit package and short name.

Method Summary

void	addCompilationUnitImports(java.lang.String compilationUnitContents) Registers pseudo-imports for all of the import declarations in the specified compilation unit contents.
void	addImport(java.lang.String qualifiedName) Registers an import for the given qualified name.
void	addImport(java.lang.String packageName, java.lang.String shortName) Registers an import for the given package name and short name.
void	addJavaLangImports(java.util.List<java.lang.String> javaLangClassNames) Ensures that explicit import declarations will be added for classes from java.lang with the specified short names.
void	addMasterImport(java.lang.String packageName, java.lang.String shortName) Reserves the import mapping for the given package and short name of the compilation unit.
void	addPseudoImport(java.lang.String qualifiedName) Registers a pseudo-import for the given qualified name.
java.lang.String	computeSortedImports() Returns the sorted, formatted import declarations that should be added to the compilation unit.
void	emitSortedImports() Inserts all the computed imports for the compilation unit into the recorded StringBuilder or StringBuffer.
java.lang.String	getImportedName(java.lang.String qualifiedName) Returns the equivalent imported short name for the given qualified name, if there is one, or the qualified name itself otherwise.
java.lang.String	getImportedName(java.lang.String qualifiedName, boolean autoImport) Returns the equivalent imported short name for the given qualified name, if there is one, or the qualified name itself otherwise.
java.util.Collection<java.lang.String>	getImports() Returns the list of qualified names for which imports are to be added to the compilation unit.
java.lang.String	getLineDelimiter() Returns the line delimiter to be used in computeSortedImports().
boolean	hasImport(java.lang.String shortName) Returns whether a mapping for the given short name has been reserved.
void	markImportLocation(java.lang.StringBuffer stringBuffer) Records the given StringBuffer and its current length, so that computed imports can later be emitted, and adds any import declarations that the buffer already contains.
void	markImportLocation(java.lang.StringBuilder stringBuilder) Records the given StringBuilder and its current length, so that computed imports can later be emitted, and adds any import declarations that the builder already contains.
void	setLineDelimiter(java.lang.String lineDelimiter) Sets the line delimiter to be used in computeSortedImports().

Methods inherited from class java.lang.Object

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

Field Detail

imports

protected java.util.SortedSet<java.lang.String> imports

The set of imports to be added to the compilation unit.

shortNameToImportMap

protected java.util.HashMap<java.lang.String,java.lang.String> shortNameToImportMap

The mapping from short names to qualified names for explicit and implicit imports.

importedPackages

protected java.util.HashSet<java.lang.String> importedPackages

The set of packages that have been imported with wildcards. This can also include containing classes, when inner classes are registered using dot separators.

javaLangImports

protected java.util.HashSet<java.lang.String> javaLangImports

The set of short names from java.lang for which explicit import declarations are desired.

Constructor Detail

ImportManager

public ImportManager(java.lang.String compilationUnitPackage,
                     java.lang.String compilationUnitShortName)

Creates an import manager for the given compilation unit package and short name. This is the preferred constructor form, as it automatically adds the master import for the compilation unit.

Since:

2.5

See Also:

addMasterImport(String, String)

ImportManager

public ImportManager(java.lang.String compilationUnitPackage)

Creates an import manager for a compilation unit in the given package. Note that the two-argument form is preferred.

See Also:

ImportManager(String, String)

Method Detail

getImportedName

public java.lang.String getImportedName(java.lang.String qualifiedName,
                                        boolean autoImport)

Returns the equivalent imported short name for the given qualified name, if there is one, or the qualified name itself otherwise. Optionally, the qualified name can be automatically imported if possible. In fact, a parameterized type expression is also allowed, in which case the expression will be parsed to obtain the individual imported names within it. Then the full expression, with the appropriate substitutions, is returned.

Parameters:

qualifiedName - the qualified name or parameterized type expression.

autoImport - whether to try to automatically import types as needed.

Returns:

the equivalent type or type expression, using short names wherever possible.

Since:

2.5

getImportedName

public java.lang.String getImportedName(java.lang.String qualifiedName)

Returns the equivalent imported short name for the given qualified name, if there is one, or the qualified name itself otherwise. Optionally, the qualified name can be automatically imported if possible. In fact, a parameterized type expression is also allowed, in which case the expression will be parsed to obtain the individual imported names within it. Then the full expression, with the appropriate substitutions, is returned.

Parameters:

qualifiedName - the qualified name or parameterized type expression.

autoImport - whether to try to automatically import types as needed.

Returns:

the equivalent type or type expression, using short names wherever possible.

addImport

public void addImport(java.lang.String packageName,
                      java.lang.String shortName)

Registers an import for the given package name and short name. Note that the $ notation for inner classes is not supported by this method, since the short name is explicitly specified.

Parameters:

packageName - the package name of the type to import

shortName - the short name of the type to import, or "*" for a wildcard import.

addImport

public void addImport(java.lang.String qualifiedName)

Registers an import for the given qualified name.

Parameters:

qualifiedName - the qualified name of the type to import, which may end with ".*" for a wildcard import.

addPseudoImport

public void addPseudoImport(java.lang.String qualifiedName)

Registers a pseudo-import for the given qualified name. A psuedo-import reserves the mapping from short name to qualified name, just like an ordinary import, but does not actually include the import declarations among those returned by computeSortedImports() or emitted by emitSortedImports(). Note that all pseudo-imports must be added before any other ordinary imports.

Parameters:

qualifiedName - the qualified name of the type to import, which may end with ".*" for a wildcard import.

See Also:

computeSortedImports(), emitSortedImports()

addMasterImport

public void addMasterImport(java.lang.String packageName,
                            java.lang.String shortName)

Reserves the import mapping for the given package and short name of the compilation unit. The $ notation for inner classes is not supported by this method, since the short name is explicitly specified. Note that a master import must be added before any pseudo- or ordinary imports. However, it need not be done explicitly if the preferred, two-argument constructor form is used.

See Also:

ImportManager(String, String)

hasImport

public boolean hasImport(java.lang.String shortName)

Returns whether a mapping for the given short name has been reserved.

getImports

public java.util.Collection<java.lang.String> getImports()

Returns the list of qualified names for which imports are to be added to the compilation unit.

getLineDelimiter

public java.lang.String getLineDelimiter()

Returns the line delimiter to be used in computeSortedImports(). By default, this is System.getProperty("line.separator").

Since:

2.5

See Also:

computeSortedImports(), setLineDelimiter(String)

setLineDelimiter

public void setLineDelimiter(java.lang.String lineDelimiter)

Sets the line delimiter to be used in computeSortedImports().

Since:

2.5

See Also:

computeSortedImports(), getLineDelimiter()

computeSortedImports

public java.lang.String computeSortedImports()

Returns the sorted, formatted import declarations that should be added to the compilation unit. Each statement appears on its own line, with an additional line delimiter before the first import and between imports from different packages.

See Also:

getLineDelimiter()

addCompilationUnitImports

public void addCompilationUnitImports(java.lang.String compilationUnitContents)

Registers pseudo-imports for all of the import declarations in the specified compilation unit contents. This uses JDT's Java AST API to parse the code when Eclipse is running, and a simpler, less accurate approach based on regular expressions otherwise. Note that this must be invoked before any ordinary imports are added.

Parameters:

compilationUnitContents - the contents of a Java source file.

See Also:

addPseudoImport(String)

markImportLocation

public void markImportLocation(java.lang.StringBuilder stringBuilder)

Records the given StringBuilder and its current length, so that computed imports can later be emitted, and adds any import declarations that the builder already contains.

Since:

2.5

See Also:

emitSortedImports(), addCompilationUnitImports(String)

markImportLocation

public void markImportLocation(java.lang.StringBuffer stringBuffer)

Records the given StringBuffer and its current length, so that computed imports can later be emitted, and adds any import declarations that the buffer already contains.

Since:

2.5

See Also:

emitSortedImports(), addCompilationUnitImports(String)

emitSortedImports

public void emitSortedImports()

Inserts all the computed imports for the compilation unit into the recorded StringBuilder or StringBuffer.

Since:

2.5

See Also:

computeSortedImports(), markImportLocation(StringBuilder), markImportLocation(StringBuffer)

addJavaLangImports

public void addJavaLangImports(java.util.List<java.lang.String> javaLangClassNames)

Ensures that explicit import declarations will be added for classes from java.lang with the specified short names. By default, all the short names of classes in this package are reserved so that the implicit imports are used. By specifying particular classes with this method, those imports, if actually used, will be made explicit.

Parameters:

javaLangClassNames -