Java packages¶

The section describing Java code file structure mentioned that a code file can begin with a package declaration of form “package package_name”. A package declaration states that all classes defined in the code belong to the package named in the package declaration. Consider the simple example code:

package fi.tuni.programming3;

public class HelloWorld {
  public static void main(String[] args) {
    System.out.println("Hello World!");
  }
}

Here the class HelloWorld was declared to belong into the package fi.tuni.programming3. This in effect means that the class HelloWorld has a so-called “fully qualified” name fi.tuni.programming3.HelloWorld. A package declaration defines the class into a namespace. This is on high level similar to e.g. C++ namespaces. References to classes (or interfaces) of a package use similar dot notation as class member references. For example fi.tuni.programming3.HelloWorld refers to the class HelloWorld in the package fi.tuni.programming3, and on the other hand fi.tuni.programming3.HelloWorld.main refers to the main member function of that class.

The package name “fi.tuni.programming3” used above was an example of the widely adopted convention that package names are based on the internet domain name of the code owner. A package name lists the domain name parts in reverse order. E.g. here the Tampere university domain name “tuni.fi” formed the basis of the package name, and the suffix programming3 would further specify that the package is related to this course. A real life example could be e.g. the fact that Java libraries published by Google and Microsoft are defined in packages whose names start with com.google and com.microsoft, respectively.

Packages help avoid class name clashes. For example the Java class library contains two different classes named Date: one in the package java.sql and another in the package java.util. These classes could not be used in the same program without packages, because in that case the Java compiler would not know to which class the name Date refers to. We can use fully qualified names, that is, names prefixed with package names, to refer to classes, and this allows to distinguish the two Date classes by referring to them as java.sql.Date and java.util.Date. It should be obvious by now that a package should not contain two classes with the same name, as then even the fully qualified names would be unable to distinguish between them.

import java.util.Arrays;

public class SortedParameters {
  public static void main(String[] args) {
    Arrays.sort(args);
    for(String arg : args) {
      System.out.println(arg);
    }
  }
}

public class SortedParameters {
  public static void main(String[] args) {
    java.util.Arrays.sort(args);
    for(String arg : args) {
      System.out.println(arg);
    }
  }
}

A second motive for using packages is that they facilitate grouping related classes together. This is useful especially in large software projects that may hundreds or even thousands of classes. Using packages in Java actually more or less imposes a hierarchical directory structure on the code base: Java interprets a package name as a directory path that specifies where the code files are stored. Dot characters of a package are interpreted to separate directory levels. For example the class HelloWorld defined in the package fi.tuni.programming3 should be stored in the subdirectory “fi/tuni/programming3” (or “fi\tuni\programming3” in Windows). A class defined in a package should be executed using the fully qualified class name, for example as java fi.tuni.programming3.HelloWorld. Here the Java virtual machine would begin the program execution from the class file fi/tuni/programming3/HelloWorld.class (or fi\tuni\programming3\HelloWorld.class in Windows).

If we follow the principle that package names begin with reversed internet domain names, the code base will be organized into a directory structure where e.g. all code from the same organization will be located under the same subdirectory.

This course will really start to use packages when we turn to maintaining the program code in so-called Maven-projects instead of as independent Java source code files. Maven is a quite versatile build automation tool.