Packages/API

In short: Packages group related Java classes in a namespace (e.g. java.util); the API is the totality of publicly usable classes/methods that Java or a library provides.

In more detail: A package usually corresponds to a folder structure (java.util.ArrayList, for example, sits in the java/util/ folder). To use classes from another package, an import statement is needed at the top of the file. The Java standard library itself is a huge, built-in API with ready-made packages for collections, I/O, networking, and more.

In Depth

package de.emzett.example; // first line of the file - declares your own package
 
import java.util.ArrayList; // import a single class
import java.util.*;          // import ALL classes of the package (usually uncommon/avoided)
 
// java.lang is imported automatically, NO import needed for String, Math, System, ...
public class Example {
    ArrayList<String> list = new ArrayList<>();
}

Packages serve two purposes at once: they logically structure large codebases (a reverse domain notation like com.company.project.module is common), and they prevent naming conflicts — two classes are allowed to carry the same simple name, as long as they sit in different packages (java.util.List vs. a custom class myproject.List). The star import (import java.util.*;) does import all classes of a package at once, but is considered bad practice in most style guides, because it makes it unclear where a given class actually comes from, and can even lead to compile errors on naming collisions between two star-imported packages. The java.lang package (with String, Math, System, the wrapper classes, etc.) is the only exception that’s automatically available with no import.

Access modifiers and package boundaries

Packages are not just organisation, but a genuine visibility boundary: without an explicit modifier (i.e. “package-private”), a class/method is visible ONLY within the same package, even if another class wanted to import it. This makes packages a built-in tool for encapsulation at the module level — internal helper classes only needed within one package don’t have to be public and thus stay invisible to code outside it.

JAR files and external libraries

Third-party libraries (e.g. downloaded from Maven Central) usually ship their packages as a JAR file — a zipped archive of .class files in exactly the folder structure that matches their package name. An import com.google.gson.Gson; only works if the corresponding JAR is on the project’s classpath; build tools like Maven or Gradle automatically handle downloading and including the correct JAR files based on a dependency list.

javadoc — documenting the API itself

The “API” of a package is in practice usually described via Javadoc comments (/** ... */) directly above classes/methods, and can thus be automatically generated into searchable HTML pages (the javadoc tool) — the official documentation of the Java standard library itself is also available in exactly this format.

See also: Classes, Collections, Modifiers