A package name should prevent collisions with other packages, so choosing a name that's both meaningful and unique is an important aspect of package design. But with programmers around the globe developing packages, there is no way to find out who is using what package names. So choosing unique package names is a problem. If you are certain a package will be used only inside your organization, you can use an internal arbiter to ensure that no projects pick clashing names.

But in the world at large, this approach is not practical. Package identifiers are simple names. A good way to ensure unique package names is to use an Internet domain name. If you worked at a company named Magic, Inc., that owned the domain name magic.com, the attribute package declaration should be

package com.magic.attr;

Notice that the components of the domain name are reversed from the normal domain name convention.

If you use this convention, your package names should not conflict with those of anyone else, except possibly within your organization. If such conflicts arise (likely in a large organization), you can further qualify using a more specific domain. Many large companies have internal subdomains with names such as east and europe. You could further qualify the package name with such a subdomain name:

package com.magic.japan.attr;

Package names can become quite long under this scheme, but it is relatively safe. No one else using this technique will choose the same package name, and programmers not using the technique are unlikely to pick your names.

Type imports are a generalization of the static imports that you learned about in Chapter 2 on page 71. They allow you to refer to types by their simple names instead of having to write their fully qualified name.

When you write code outside a package that needs types declared within that package you have two options. One is to use the fully qualified name of the type. This option is reasonable if you use only a few items from a package, but given the long names that packages tend to acquire (or even the shorter ones in the standard libraries) it can be quite tedious to use fully qualified names.

The other way to use types from a package is to import part or all of the package. A programmer who wants to use the attr package could put the following line near the top of a source file (after any package declaration but before anything else):

import attr.*;

Now the types in that package can be referred to simply by name, such as Attributed. An import that uses a * is called an import on demand declaration. You can also perform a single type import:

import attr.Attributed;

The name used with an import statement must be the canonical name of a package (for import on demand) or type (for single type import). As discussed in “Naming Classes” on page 411, the canonical name and fully qualified name can differ only for nested types. Note that generic types are imported using their raw type name—that name can then be used in a parameterized type without further qualification.

Code in a package imports the rest of its own package implicitly, so everything defined in a package is available to all types in the same package. The package java.lang is implicitly imported in all code.

The import mechanism is passive in that it does not cause information about the named packages and types to be read in at compile time—unless a type is used. The import statement simply tells the compiler how it can determine the fully qualified name for a type that is used in your program if it can't find that type defined locally. For example, as described on page 181, if your class declares a reference of type Attributed the compiler will search for the type in the following order:

If, after that, the type is still not found it is an error. It is also an error if any package named in an import statement cannot be located—even if there is no actual need to obtain a type from that package.

Resolving which type is being referred to requires some work by the compiler, and use of import on demand may involve more work than resolving a single type import. However, this is rarely significant in the compilation process. The choice between a single type import and import on demand is usually a matter of personal preference or local style rules. Naturally, to resolve conflicts or to ensure that a specific type is resolved correctly you may need to use a single type import.^[1]

Type imports can also be used with nested class names. For example, in Chapter 5 we defined the BankAcount class and its nested Permissions class. If these classes were in the package bank and you imported bank.BankAccount, you would still need to use BankAccount.Permissions to name the Permissions class. However, you could instead import bank.BankAccount.Permissions and then use the simple name Permissions. You don't have to import BankAccount to import the class BankAccount.Permissions. Importing nested type names in this way should generally be avoided because it loses the important information that the type is actually a nested type.

Static nested types can be imported using either the type import mechanism or the static import mechanism. If you insist on importing nested types, then you should use the type import mechanism for consistency.

The package and import mechanisms give programmers control over potentially conflicting names. If a package used for another purpose, such as linguistics, has a class called Attributed for language attributes, programmers who want to use both types in the same source file have several options:

It is an error to import a specific type that exists as a top-level (that is non-nested) type within the current source file. For example, you can't declare your own Vector class and import java.util.Vector. Nor can you import the same type name from two different packages using two single type imports. As noted above, if two types of the same name are implicitly imported on demand, you cannot use the simple type name but must use the fully qualified name. Use of the simple name would be ambiguous and so result in a compile-time error.

You have two options when declaring accessibility of top-level classes and interfaces within a package: package and public. A public class or interface is accessible to code outside that package. Types that are not public have package scope: They are available to all other code in the same package, but they are hidden outside the package and even from code in subpackages. Declare as public only those types needed by programmers using your package, hiding types that are package implementation details. This technique gives you flexibility when you want to change the implementation—programmers cannot rely on implementation types they cannot access, and that leaves you free to change them.

A class member that is not declared public, protected, or private can be used by any code within the package but is hidden outside the package. In other words, the default access for an identifier is “package” except for members of interfaces, which are implicitly public.

Fields or methods not declared private in a package are available to all other code in that package. Thus, classes within the same package are considered “friendly” or “trusted.” This allows you to define application frameworks that are a combination of predefined code and placeholder code that is designed to be overridden by subclasses of the framework classes. The predefined code can use package access to invoke code intended for use by the cooperating package classes while making that code inaccessible to any external users of the package. However, subpackages are not trusted in enclosing packages or vice versa. For example, package identifiers in package dit are not available to code in package dit.dat, or vice versa.

Every type has therefore three different contracts that it defines:

All of these contracts require careful consideration and design.

package P1;

public abstract class AbstractBase {
    private   void pri() { print("AbstractBase.pri()"); }
              void pac() { print("AbstractBase.pac()"); }
    protected void pro() { print("AbstractBase.pro()"); }
    public    void pub() { print("AbstractBase.pub()"); }

    public final void show() {
        pri();
        pac();
        pro();
        pub();
    }
}

package P2;

import P1.AbstractBase;

public class Concrete1 extends AbstractBase {
    public void pri() { print("Concrete1.pri()"); }
    public void pac() { print("Concrete1.pac()"); }
    public void pro() { print("Concrete1.pro()"); }
    public void pub() { print("Concrete1.pub()"); }
}

new Concrete1().show();

AbstractBase.pri()
AbstractBase.pac()
Concrete1.pro()
Concrete1.pub()

package P1;

import P2.Concrete1;

public class Concrete2 extends Concrete1 {
    public void pri() { print("Concrete2.pri()"); }
    public void pac() { print("Concrete2.pac()"); }
    public void pro() { print("Concrete2.pro()"); }
    public void pub() { print("Concrete2.pub()"); }
}

AbstractBase.pri()
Concrete2.pac()
Concrete2.pro()
Concrete2.pub()

package P3;

import P1.Concrete2;

public class Concrete3 extends Concrete2 {
    public void pri() { print("Concrete3.pri()"); }
    public void pac() { print("Concrete3.pac()"); }
    public void pro() { print("Concrete3.pro()"); }
    public void pub() { print("Concrete3.pub()"); }
}

AbstractBase.pri()
Concrete3.pac()
Concrete3.pro()
Concrete3.pub()

Packages should be designed carefully so that they contain only functionally related classes and interfaces. Classes in a package can freely access one another's non-private members. Protecting class members is intended to prevent misuse by classes that have access to internal details of other classes. Anything not declared private is available to all types in the package, so unrelated classes could end up working more intimately than expected with other classes.

Packages should also provide logical groupings for programmers who are looking for useful interfaces and classes. A package of unrelated classes makes the programmer work harder to figure out what is available. Logical grouping of classes helps programmers reuse your code because they can more easily find what they need. Including only related, coherent sets of types in a package also means that you can use obvious names for types, thereby avoiding name conflicts.

Packages can be nested inside other packages. For example, java.lang is a nested package in which lang is nested inside the larger java package. The java package contains only other packages. Nesting allows a hierarchical naming system for related packages.

For example, to create a set of packages for adaptive systems such as neural networks and genetic algorithms, you could create nested packages by naming the packages with dot-separated names:

package adaptive.neuralNet;

A source file with this declaration lives in the adaptive.neuralNet package, which is itself a subpackage of the adaptive package. The adaptive package might contain classes related to general adaptive algorithms, such as generic problem statement classes or benchmarking. Each package deeper in the hierarchy—such as adaptive.neuralNet or adaptive.genetic—would contain classes specific to the particular kind of adaptive algorithm.

Package nesting is an organizational tool for related packages, but it provides no special access between packages. Class code in adaptive.genetic cannot access package-accessible identifiers of the adaptive or adaptive.neuralNet packages. Package scope applies only to a particular package. Nesting can group related packages and help programmers find classes in a logical hierarchy, but it confers no other benefits.

A package can have annotations applied to it. The problem is that there is no actual definition of a package to which you can apply such annotations—unlike a class or a method—because a package is an organizational structure, not a source code entity. So you annotate packages by applying the annotation to the package statement within a source file for that package. However, only one package declaration per package can have annotations applied to it.

So how do you actually annotate a package? There is no required way to deal with this “single annotated package statement” rule. The suggested approach is to create a file called package-info.java within the package directory, and to put in that file nothing but a package statement with any annotations for the package (plus any useful comments, of course). For example, a package-info.java file for the attr package might look like this:

@PackageSpec(name = "Attr Project", version = "1.0")
@DevelopmentSite("attr.project.org")
@DevelopmentModel("open-source")
package attr;

where PackageSpec, DevelopmentSite, and DevelopmentModel are made up annotation types—with a runtime retention policy, of course. The package-info.java file should be compiled along with the rest of the package source files.

The package-info.java file is recommended as the single place to put all package-related information. To that end, you can place a documentation comment at the start of the file, and that will be the package documentation for that package. Package documentation is covered in more detail in “Package and Overview Documentation” on page 496.

The java.lang.Package class implements AnnotatedElement, so you can ask about any applied annotations using the methods discussed in “Annotation Queries” on page 414.

Packages typically implement a specification, and they are also typically from one organization. A Package object, unlike the other reflection types (see Chapter 16), is not used to create or manipulate packages, but acts only as a repository for information about the specification implemented by a package (its title, vendor, and version number) and for information about the implementation itself (its title, vendor, and version number). Although a package typically comes from a single organization, the specification for that package (such as a statistical analysis library) may have been defined by someone else. Programs using a package may need to be able to determine the version of the specification implemented by the package so that they use only functionality defined in that version. Similarly, programs may need to know which version of the implementation is provided, primarily to deal with bugs that may exist in different versions. The main methods of Package allow access to this information:

For example, extracting this information for the java.lang package on our system yielded the following:^[4]

Specification Title:    Java Platform API Specification
Specification Version:  1.4
Specification Vendor:   Sun Microsystems, Inc.
Implementation Title:   Java Runtime Environment
Implementation Version: 1.5.0_02
Implementation Vendor:  Sun Microsystems, Inc.

Specification version numbers are non-negative numbers separated by periods, as in "2.0" or "11.0.12". This pattern allows you to invoke the isCompatibleWith method to compare a version following this pattern with the version of the package. The method returns true if the package's specification version number is greater than or equal to the one passed in. Comparison is done one dot-separated number at a time. If any such value in the package's number is less than the one from the passed in version, the versions are not compatible. If one of the version numbers has more components than the other, the missing components in the shorter version number are considered to be zero. For example, if the package's specification version is "1.4" and you compare it to "1.2", "1.3.1", or "1.1.8", you will get true, but if you compare it to "1.4.2" or "1.5", you will get false. This comparison mechanism assumes backward compatibility between specification versions.

Implementation version numbers do not have a defined format because these will be defined by the different organizations providing the implementations. The only comparison you can perform between implementation versions is a test for equality—there is no assumption of backward compatibility.

Packages can be sealed, which means that no classes can be added to them. An unsealed package can have classes come from several different places in a class search path. A sealed package's contents must all come from one place—generally either a specific archive file or a location specified by a URL. Two methods ask if a package is sealed:

The specification and implementation information for a package is usually supplied as part of the manifest stored with the package—such as the manifest of a Java Archive (jar) file, as described in “Archive Files — java.util.jar” on page 735. This information is read when a class gets loaded from that package. A ClassLoader can dynamically define a Package object for the classes it loads:

You can get the Package object for a given class from the getPackage method of the Class object for that class. You can also get a Package object by invoking either the static method Package.getPackage with the name of the package, or the static method Package.getPackages, which returns an array of all known packages. Both methods work with respect to the class loader of the code making the call by invoking the getPackage or getPackages method of that class loader. These class loader methods search the specific class loader and all of its parents. If there is no current class loader then the system class loader is used. Note that the class loader methods will return null if the package is unknown because no type from the package has been loaded.