## 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` -

Copyright 2001-2006 IBM Corporation and others. All Rights Reserved.