import

7.5 Import Declarations

An import declaration allows a type declared in another package to be referred to by a simple name that consists of a single identifier. Without the use of an appropriate import declaration, the only way to refer to a type declared in another package is to use its fully qualified name.

ImportDeclaration:

SingleTypeImportDeclaration
TypeImportOnDemandDeclaration

A single-type-import declaration imports a single type, by mentioning its fully qualified name. A type-import-on-demand declaration imports all the public types of a named package as needed.

An import declaration makes types available by their simple names only within the compilation unit that actually contains the import declaration. The scope of the name(s) it introduces specifically does not include the package statement, other import statements in the current compilation unit, or other compilation units in the same package.

7.5.1 Single-Type-Import Declaration

A single-type-import declaration imports a single type by giving its fully qualified name, making it available under a simple name in the class and interface declarations of its compilation unit.

SingleTypeImportDeclaration:

import TypeName ;

The TypeName must be the fully qualified name of a class or interface type; a compile-time error occurs if the named type does not exist. If the named type is not in the current package, then it must be accessible in an accessible package and declared public or a compile-time error occurs.

The example:

import java.util.Vector;

causes the simple name Vector to be available within the class and interface declarations in a compilation unit. Thus, the simple name Vector refers to the type Vector in the package java.util in all places where it is not hidden by a declaration of a field, parameter, or local variable with the same name.

If two single-type-import declarations in the same compilation unit attempt to import types with the same simple name, then a compile-time error occurs, unless the two types are the same type, in which case the duplicate declaration is ignored. If another type with the same name is otherwise declared in the current compilation unit except by a type-import-on-demand declaration, then a compile-time error occurs.

So the sample program:


import java.util.Vector;
class Vector { Object[] vec; }

causes a compile-time error because of the duplicate declaration of Vector, as does:


import java.util.Vector;
import myVector.Vector;

where myVector is a package containing the compilation unit:


package myVector;
public class Vector { Object[] vec; }

The compiler keeps track of types by their fully qualified names. Simple names and fully qualified names may be used interchangeably whenever they are both available.

Note that an import statement cannot import a subpackage, only a type. For example, it does not work to try to import java.util and then use the name util.Random to refer to the type java.util.Random:


import java.util; // incorrect: compile-time error
class Test { util.Random generator; }

7.5.2 Type-Import-on-Demand Declaration

A type-import-on-demand declaration allows all public types declared in the package named by a fully qualified name to be imported as needed.

TypeImportOnDemandDeclaration:

import PackageName . * ;

It is a compile-time error for a type-import-on-demand declaration to name a package that is not accessible, as determined by the host system. Two or more type-import-on-demand declarations in the same compilation unit may name the same package; the effect is as if there were exactly one such declaration. It is not a compile-time error to name the current package or java.lang in a type-import-on-demand declaration, even though they are already imported; the duplicate type-import-on-demand declaration is ignored.

The example:

import java.util.*;

causes the simple names of all public types declared in the package java.util to be available within the class and interface declarations of the compilation unit. Thus, the simple name Vector refers to the type Vector in the package java.util in all places where it is not hidden by a single-type-import declaration of a type whose simple name is Vector; by a type named Vector and declared in the package to which the compilation unit belongs; or by a declaration of a field, parameter, or local variable named Vector. (It would be unusual for any of these conditions to occur.)

7.5.3 Automatic Imports

Each compilation unit automatically imports each of the public type names declared in the predefined package java.lang, as if the declaration:

import java.lang.*;

appeared at the beginning of each compilation unit, immediately following any package statement.

The following public types are defined in java.lang:


AbstractMethodError                   LinkageError
ArithmeticException                   Long
ArrayStoreException                   Math
Boolean                   NegativeArraySizeException
Character                   NoClassDefFoundError
Class                   NoSuchFieldError
ClassCastException                    NoSuchMethodError
ClassCircularityError                   NullPointerException
ClassFormatError                    Number
ClassLoader                   NumberFormatException
ClassNotFoundException                    Object
CloneNotSupportedException                    OutOfMemoryError
Cloneable                   Process
Compiler                    Runnable
Double                    Runtime
Error                   RuntimeException
Exception                   SecurityException
ExceptionInInitializerError                   SecurityManager
Float                   StackOverflowError
IllegalAccessError                    String
IllegalAccessException                    StringBuffer
IllegalArgumentException                    System
IllegalMonitorStateException                    Thread
IllegalThreadStateException                   ThreadDeath
IncompatibleClassChangeError                    ThreadGroup
IndexOutOfBoundsException                   Throwable
InstantiationError                    UnknownError
InstantiationException                    UnsatisfiedLinkError
Integer                   VerifyError
InternalError                   VirtualMachineError
InterruptedException

7.5.4 A Strange Example

Package names and type names are usually different. Nevertheless, in a contrived example where there is an unconventionally-named package Vector, which declares a public class named Mosquito:


package Vector;
public class Mosquito { int capacity; }

and then the compilation unit:


package strange.example;

import java.util.Vector;

import Vector.Mosquito;

class Test {
  public static void main(String[] args) {
    System.out.println(new Vector().getClass());
    System.out.println(new Mosquito().getClass());
  }
}

the single-type-import declaration importing class Vector from package java.util does not prevent the package name Vector from appearing and being correctly recognized in subsequent import declarations. The example compiles and produces the output:


class java.util.Vector
class Vector.Mosquito