Code in a compilation unit automatically has access to all classes and interfaces declared in its package and also automatically imports all of the public classes and interfaces declared in the predefined package java.lang . A top level class or interface is accessible ( §6.6 ) outside the package that declares it only if the class or interface is declared public . A top level class or interface is accessible outside the module that declares it only if the class or interface is declared public and is a member of an exported package. A class or interface that is declared public but is not a member of an exported package is accessible only to code inside the module.

For small programs and casual development, a package can be unnamed ( §7.4.2 ) or have a simple name, but if code is to be widely distributed, unique package names should be chosen using qualified names. This can prevent the conflicts that would otherwise occur if two development groups happened to pick the same package name and these packages were later to be used in a single program. The members of a package are its subpackages and all the top level classes ( §8 ( Classes ) ) and top level interfaces ( §9 ( Interfaces ) ) declared in all the compilation units ( §7.3 ) of the package.

For example, in the Java SE Platform API:

The package java has subpackages awt , applet , io , lang , net , and util , but no compilation units.

The package java.awt has a subpackage named image , as well as a number of compilation units containing declarations of classes and interfaces. If the fully qualified name ( §6.7 ) of a package is P , and Q is a subpackage of P , then P.Q is the fully qualified name of the subpackage, and furthermore denotes a package. A package may not contain two members of the same name, or a compile-time error results.

Here are some examples:

Because the package java.awt has a subpackage image , it cannot (and does not) contain a declaration of a class or interface named image .

If there is a package named mouse and a member class Button in that package (which then might be referred to as mouse.Button ), then there cannot be any package with the fully qualified name mouse.Button or mouse.Button.Click .

If com.nighthacks.java.jag is the fully qualified name of a class, then there cannot be any package whose fully qualified name is either com.nighthacks.java.jag or com.nighthacks.java.jag.scrabble .

It is however possible for members of different packages to have the same simple name. For example, it is possible to declare a package: package vector; public class Vector { Object[] vec; }

that has as a member a public class named Vector , even though the package java.util also declares a class named Vector . These two classes are different, reflected by the fact that they have different fully qualified names ( §6.7 ). The fully qualified name of this example Vector is vector.Vector , whereas java.util.Vector is the fully qualified name of the Vector class included in the Java SE Platform. Because the package vector contains a class named Vector , it cannot also have a subpackage named Vector . The hierarchical naming structure for packages is intended to be convenient for organizing related packages in a conventional manner, but has no significance in itself other than the prohibition against a package having a subpackage with the same simple name as a top level class or interface ( §7.6 ) declared in that package.

For example, there is no special access relationship between a package named oliver and another package named oliver.twist , or between packages named evelyn.wood and evelyn.waugh . That is, the code in a package named oliver.twist has no better access to the classes and interfaces declared within package oliver than code in any other package. Each host system determines how modules, packages, and compilation units are created and stored. Each host system determines which compilation units are observable in a particular compilation ( §7.3 ). Each host system also determines which observable compilation units are associated with a module. The observability of compilation units associated with a module determines which modules are observable ( §7.7.3 ) and which packages are visible within those modules ( §7.4.3 ). The host system is free to determine that a compilation unit which contains a module declaration is not, in fact, observable, and thus is not associated with the module declared therein. This enables a compiler to choose which directory on a modulesourcepath is "really" the embodiment of a given module. However, if the host system determines that a compilation unit which contains a module declaration is observable, then §7.4.3 mandates that the compilation unit must be associated with the module declared therein, and not with any other module. The host system is free to determine that a compilation unit which contains a class or interface declaration is (first) observable and (second) associated with an unnamed module or an automatic module - despite no declaration of an unnamed or automatic module existing in any compilation unit, observable or otherwise. In simple implementations of the Java SE Platform, packages and compilation units may be stored in a local file system. Other implementations may store them using a distributed file system or some form of database.

If a host system stores packages and compilation units in a database, then the database must not impose the optional restrictions ( §7.6 ) on compilation units permissible in file-based implementations.

For example, a system that uses a database to store packages may not enforce a maximum of one public class or interface per compilation unit.

Systems that use a database must, however, provide an option to convert a program to a form that obeys the restrictions, for purposes of export to file-based implementations.

As an extremely simple example of storing packages in a file system, all the packages and source and binary code in a project might be stored in a single directory and its subdirectories. Each immediate subdirectory of this directory would represent a top level package, that is, one whose fully qualified name consists of a single simple name. Each further level of subdirectory would represent a subpackage of the package represented by the containing directory, and so on.

The directory might contain the following immediate subdirectories:

where directory java would contain the Java SE Platform packages; the directories jag , gls , and wnj might contain packages that three of the authors of this specification created for their personal use and to share with each other within this small group; and the directory com would contain packages procured from companies that used the conventions described in §6.1 to generate unique names for their packages.

Continuing the example, the directory java would contain, among others, the following subdirectories: applet

corresponding to the packages java.applet , java.awt , java.io , java.lang , java.net , and java.util that are defined as part of the Java SE Platform API.

Still continuing the example, if we were to look inside the directory util , we might see the following files: BitSet.java Observable.java BitSet.class Observable.class Date.java Observer.java Date.class Observer.class

where each of the .java files contains the source for a compilation unit ( §7.3 ) that contains the definition of a class or interface whose binary compiled form is contained in the corresponding .class file.

Under this simple organization of packages, an implementation of the Java SE Platform would transform a package name into a pathname by concatenating the components of the package name, placing a file name separator (directory indicator) between adjacent components.

For example, if this simple organization were used on an operating system where the file name separator is / , the package name: jag.scrabble.board

would be transformed into the directory name:

jag/scrabble/board

A package name component or class name might contain a character that cannot correctly appear in a host file system's ordinary directory name, such as a Unicode character on a system that allows only ASCII characters in file names. As a convention, the character can be escaped by using, say, the @ character followed by four hexadecimal digits giving the numeric value of the character, as in the \u xxxx escape ( §3.3 ).

Under this convention, the package name:

children.activities.crafts.papierM\u00e2ch\u00e9

which can also be written using full Unicode children.activities.crafts.papierMâché

might be mapped to the directory name:

children/activities/crafts/papierM@00e2ch@00e9

If the @ character is not a valid character in a file name for some given host file system, then some other character that is not valid in a identifier could be used instead. CompilationUnit is the goal symbol ( §2.1 ) for the syntactic grammar ( §2.3 ) of Java programs. It is defined by the following production: A package declaration ( §7.4 ), giving the fully qualified name ( §6.7 ) of the package to which the compilation unit belongs. A compilation unit that has no package declaration is part of an unnamed package ( §7.4.2 ). import declarations ( §7.5 ) that allow classes and interface from other packages, and static members of classes and interfaces, to be referred to using their simple names. A modular compilation unit consists of a module declaration ( §7.7 ), optionally preceded by import declarations. The import declarations allow classes and interfaces from packages in this module and other modules, as well as static members of classes and interfaces, to be referred to using their simple names within the module declaration. Every compilation unit implicitly imports every public class or interface declared in the predefined package java.lang , as if the declaration import java.lang.*; appeared at the beginning of each compilation unit immediately after any package declaration. As a result, the names of all those classes and interfaces are available as simple names in every compilation unit. The host system determines which compilation units are observable , except for the compilation units in the predefined package java and its subpackages lang and io , which are all always observable. Each observable compilation unit may be associated with a module, as follows: The host system may determine that an observable ordinary compilation unit is associated with a module chosen by the host system, except for (i) the ordinary compilation units in the predefined package java and its subpackages lang and io , which are all associated with the java.base module, and (ii) any ordinary compilation unit in an unnamed package, which is associated with a module as specified in §7.4.2 . The host system must determine that an observable modular compilation unit is associated with the module declared by the modular compilation unit. The observability of a compilation unit influences the observability of its package ( §7.4.3 ), while the association of an observable compilation unit with a module influences the observability of that module ( §7.7.6 ). When compiling the modular and ordinary compilation units associated with a module M , the host system must respect the dependences specified in M 's declaration. Specifically, the host system must limit the ordinary compilation units that would otherwise be observable, to only those that are visible to M . The ordinary compilation units that are visible to M are the observable ordinary compilation units associated with the modules that are read by M . The modules read by M are given by the result of resolution , as described in the java.lang.module package specification, with M as the only root module. The host system must perform resolution to determine the modules read by M ; it is a compile-time error if resolution fails for any of the reasons described in the java.lang.module package specification. The readability relation is reflexive, so M reads itself, and thus all of the modular and ordinary compilation units associated with M are visible to M . The modules read by M drive the packages that are uniquely visible to M ( §7.4.3 ), which in turn drives both the top level packages in scope and the meaning of package names for code in the modular and ordinary compilation units associated with M ( §6.3 , §6.5.3 , §6.5.5 ). The rules above ensure that package and type names used in annotations in a modular compilation unit (in particular, annotations applied to the module declaration) are interpreted as if they appeared in an ordinary compilation unit associated with the module. Classes and interfaces declared in different ordinary compilation units can refer to each other, circularly. A Java compiler must arrange to compile all such classes and interfaces at the same time. A package declaration appears within an ordinary compilation unit to indicate the package to which the compilation unit belongs. A package declaration in an ordinary compilation unit specifies the name ( §6.2 ) of the package to which the compilation unit belongs. The package name mentioned in a package declaration must be the fully qualified name of the package ( §6.7 ). The scope and shadowing of a package declaration is specified in §6.3 and §6.4 . The rules concerning annotation modifiers for a package declaration are specified in §9.7.4 and §9.7.5 . At most one annotated package declaration is permitted for a given package.

The manner in which this restriction is enforced must, of necessity, vary from implementation to implementation. The following scheme is strongly recommended for file-system-based implementations: The sole annotated package declaration, if it exists, is placed in a source file called package-info.java in the directory containing the source files for the package. This file does not contain the source for a class called package-info ; indeed it would be illegal for it to do so, as package-info is not a legal identifier. Typically package-info.java contains only a package declaration, preceded immediately by the annotations on the package. While the file could technically contain the source code for one or more classes with package access, it would be very bad form.

It is recommended that package-info.java , if it is present, take the place of package.html for javadoc and other similar documentation generation systems. If this file is present, the documentation generation tool should look for the package documentation comment immediately preceding the (possibly annotated) package declaration in package-info.java . In this way, package-info.java becomes the sole repository for package-level annotations and documentation. If, in future, it becomes desirable to add any other package-level information, this file should prove a convenient home for this information. An ordinary compilation unit that has no package declaration, but has at least one other kind of declaration, is part of an unnamed package . Unnamed packages are provided by the Java SE Platform principally for convenience when developing small or temporary applications or when just beginning development. An unnamed package cannot have subpackages, since the syntax of a package declaration always includes a reference to a named top level package. An implementation of the Java SE Platform must support at least one unnamed package. An implementation may support more than one unnamed package, but is not required to do so. Which ordinary compilation units are in each unnamed package is determined by the host system. The host system must associate ordinary compilation units in an unnamed package with an unnamed module ( §7.7.5 ), not a named module.

class FirstCall {
    public static void main(String[] args) {
        System.out.println("Mr. Watson, come here. "
                           + "I want you.");

One can conclude this from the rule above and from the rules of observable compilation units, as follows. The predefined package java.lang declares the class Object , so the compilation unit for Object is always observable ( §7.3 ). Hence, the java.lang package is observable, and the java package also. Furthermore, since Object is observable, the array type Object [] implicitly exists. Its superinterface java.io.Serializable ( §10.1 ) also exists, hence the java.io package is observable. A package is visible to a module M if and only if an ordinary compilation unit containing a declaration of the package is visible to M . Package visibility is meant to imply that a package is observable in a useful way to a given module. It is generally not useful to know that package P is observable merely because a subpackage P.Q is observable. For example, suppose P.Q is observable (in module M1) and P.R is observable (in module M2); then, P is observable, but where? In M1, or M2, or both? The question is redundant; during compilation of module N that requires only M1, it matters that P.Q is observable, but it does not matter that P is observable. A package is uniquely visible to a module M if and only if one of the following holds: An ordinary compilation unit associated with M contains a declaration of the package, and M does not read any other module that exports the package to M . No ordinary compilation unit associated with M contains a declaration of the package, and M reads exactly one other module that exports the package to M . An import declaration allows a named class, interface, or static member to be referred to by a simple name ( §6.2 ) that consists of a single identifier. Without the use of an appropriate import declaration, a reference to a class or interface declared in another package, or a reference to a static member of another class or interface, would typically need to use a fully qualified name ( §6.7 ). A single-type-import declaration ( §7.5.1 ) imports a single named class or interface, by mentioning its canonical name ( §6.7 ). A type-import-on-demand declaration ( §7.5.2 ) imports all the accessible classes and interfaces of a named package, class, or interface as needed, by mentioning the canonical name of the package, class, or interface. A single-static-import declaration ( §7.5.3 ) imports all accessible static members with a given name from a class or interface, by giving its canonical name. A static-import-on-demand declaration ( §7.5.4 ) imports all accessible static members of a named class or interface as needed, by mentioning the canonical name of the class or interface. The scope and shadowing of a class, interface, or member imported by these declarations is specified in §6.3 and §6.4 . An import declaration makes classes, interfaces, or members available by their simple names only within the compilation unit that actually contains the import declaration. The scope of the class(es), interface(s), or member(s) introduced by an import declaration specifically does not include other compilation units in the same package, other import declarations in the current compilation unit, or a package declaration in the current compilation unit (except for the annotations of a package declaration). A single-type-import declaration imports a single class or interface by giving its canonical name, making it available under a simple name in the module, class, and interface declarations of the compilation unit in which the single-type-import declaration appears. The class or interface must be either a member of a named package, or a member of a class or interface whose outermost lexically enclosing class or interface declaration ( §8.1.3 ) is a member of a named package, or a compile-time error occurs. It is a compile-time error if the named class or interface is not accessible ( §6.6 ). If two single-type-import declarations in the same compilation unit attempt to import classes or interfaces with the same simple name, then a compile-time error occurs, unless the two classes or interface are the same, in which case the duplicate declaration is ignored. If the class or interface imported by the single-type-import declaration is declared as a top level class or interface ( §7.6 ) in the compilation unit that contains the import declaration, then the import declaration is ignored. If a single-type-import declaration imports a class or interface whose simple name is x , and the compilation unit also declares a top level class or interface whose simple name is x , a compile-time error occurs. If a compilation unit contains both a single-type-import declaration that imports a class or interface whose simple name is x , and a single-static-import declaration ( §7.5.3 ) that imports a class or interface whose simple name is x , a compile-time error occurs, unless the two classes or interfaces are the same, in which case the duplicate declaration is ignored.

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

package strange;
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());

module m.A {
    requires m.B;
module m.B {
    requires transitive m.C;
module m.C {
    requires transitive m.D;
module m.D {
    exports p;