CHAPTER 7: Packages

Previous

Java Language

Index

Next

7.5 Import Declarations

An import declaration allows a type declared in another package to be referred to by a simple name (S6.2) 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 (S6.7).

ImportDeclaration:

	SingleTypeImportDeclaration

	TypeImportOnDemandDeclaration

A single-type-import declaration (S7.5.1) imports a single type, by mentioning its fully qualified name. A type-import-on-demand declaration (S7.5.2) 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. Please see S7.5.4 for an illustrative example.

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 (S6.6)-in an accessible package and declared public (S8.1.2, S9.1.2)-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 (S6.3) 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 (S7.5.2), 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 (S6.7). 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 (S6.6), as determined by the host system (S7.2). 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 (S6.3) 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 full specification of java.lang is given in Chapter 20. 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 under the naming conventions described in S6.8. 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 (S7.5.1) 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