Packages and imports

Interviewers ask about packages for two reasons. The warm-up version checks that you understand how a class name turns into a file on disk and how the JVM finds it. The deeper version probes whether you've debugged real classpath problems: two versions of the same class, a NoClassDefFoundError that only happens in production, or an import that compiles on one machine and not another.

For this lesson, we'll focus on package naming and directory mapping, the classpath, imports and static imports, name clashes, why the default package is a trap, and a short introduction to Java modules (JPMS) and how they relate to packages.

01Picture it first: name, folder, classpath

Think of a fully qualified class name as a postal address: country, city, street, house. com.acme.billing.Invoice reads from the broadest part to the most specific. Just as the post office maps an address to a physical building, the JVM maps a class name to a physical file by turning dots into slashes.

Fig. 1

The package name maps to a directory for both the source and compiled class file, and at runtime the class loader checks each classpath entry from left to right and uses the first match

These pieces work together like this: you write package com.acme.billing;, the source lives in src/com/acme/billing/, javac -d out writes out/com/acme/billing/Invoice.class, and at runtime the class loader looks for com/acme/billing/Invoice.class in each classpath entry in order.

02How it works under the hood

// File: src/com/acme/billing/Invoice.java
package com.acme.billing;          // must be the first statement (comments are fine above it)

import java.math.BigDecimal;       // single-type import
import java.util.*;                // on-demand (wildcard) import
import static java.util.Objects.requireNonNull;   // static import (Java 5)

public class Invoice {
    private final List<BigDecimal> lines = new ArrayList<>();

    public void add(BigDecimal amount) {
        lines.add(requireNonNull(amount));
    }

    public static void main(String[] args) {
        System.out.println("ok");  // String, System: java.lang, imported implicitly
    }
}

javac -d out src/com/acme/billing/Invoice.java
# → out/com/acme/billing/Invoice.class

java -cp out com.acme.billing.Invoice      # run by fully qualified name
java -cp out Invoice                       # Error: Could not find or load main class Invoice

Package naming

The convention is your organisation's domain reversed, all lowercase: com.acme.billing, org.apache.commons.lang3. Reversing puts the most general part first, so packages from different organisations never collide. Hyphens and leading digits aren't legal in identifiers, so my-app.io becomes something like io.my_app.

Two names are off limits: you can't define classes in java.* (the JVM throws SecurityException: Prohibited package name), and javax.* belongs to the platform and its extensions by convention.

Directory mapping

Each dot is a directory level. This mapping is a convention for sources and a requirement for class files: javac will compile a file wherever it sits if you name it explicitly, but -d always writes the class file into the package directory structure, and class loaders always look for it there. Build tools and IDEs enforce the source layout too, so treat it as mandatory.

The classpath

The classpath is an ordered list of directories and JAR files where the class loader looks for classes. You set it with -cp (or --class-path, or the CLASSPATH environment variable). If you set none, it defaults to the current directory ..

# Linux/macOS use ':' as the separator, Windows uses ';'
java -cp "out:lib/pdf.jar:lib/*" com.acme.billing.Main
#                          └ wildcard: every .jar directly in lib/ (not .class files, not subfolders)

The JDK's own classes (java.*, javax.* and friends) don't come from your classpath. Since Java 9 they come from the runtime image's modules, which are always searched first through the class loader delegation, so you can't accidentally replace java.lang.String.

Imports are a compile-time convenience

import never loads anything. It only tells the compiler how to expand a simple name. Look at any class file with javap -v and you'll see only fully qualified names like java/util/ArrayList. That gives us three useful facts:

1. Wildcard imports have zero runtime cost. import java.util.*; produces exactly the same bytecode as importing each class by name. The only cost is a negligible amount of compile time.
2. Wildcards import one package, not its subpackages. import java.util.*; does not give you java.util.concurrent.ConcurrentHashMap.
3. You never need an import. java.util.List<String> names = new java.util.ArrayList<>(); compiles fine. Imports just save typing.

Two packages are always imported implicitly: java.lang (that's why String, Math, System and Integer just work) and the class's own package.

Static imports (Java 5) bring static members into scope, so you can write max(a, b) instead of Math.max(a, b):

import static java.lang.Math.max;          // one member
import static java.util.stream.Collectors.*;   // all static members

int biggest = max(3, 7);
List<String> upper = names.stream().map(String::toUpperCase).collect(toList());

03Real world: name clashes and the default package

import java.util.*;
import java.sql.*;

public class Report {
    Date created;        // ?
}

It doesn't: error: reference to Date is ambiguous, because both on-demand imports offer a Date. Notice the error only appears when you use Date; the two wildcard imports by themselves are fine. You have three fixes, in order of preference:

// 1. A single-type import beats any wildcard
import java.util.*;
import java.sql.*;
import java.util.Date;               // Date now means java.util.Date

// 2. If you need both, import one and fully qualify the other
import java.util.Date;
java.sql.Date sqlDate = java.sql.Date.valueOf("2026-10-17");

// 3. Or skip both legacy types and use java.time.LocalDate

The resolution order is: a single-type import or a type declared in the same file wins first, then types in the same package, then on-demand imports (including the implicit java.lang.*). That's also why declaring your own class called String in your package makes every unqualified String in that package refer to yours. Please don't.

Why the default package is a trap

A class with no package statement lives in the unnamed (default) package. It's fine for a one-file experiment, and that's all it's for:

• Nothing in a named package can import it. There's no name to write in an import statement (allowed until Java 1.4, a compile error since). Our test above gave error: cannot find symbol.
• No namespace at all. Two libraries with a default-package Utils silently shadow each other on the classpath.
• Tools struggle. Frameworks that scan packages, and the module system, can't work with it. A named module can't contain a default-package class at all.

04Advanced: classpath hell and JPMS modules

Classpath order and shadowing. The class loader stops at the first match. If lib/old.jar and lib/new.jar both contain com.google.common.base.Strings, whichever comes first wins, for every class in that package, and the other version is invisible. Mixing two versions of a library this way causes NoSuchMethodError or NoClassDefFoundError at runtime, often only on the code path that uses a method added in the newer version. Build tools resolve versions to avoid this; mvn dependency:tree and -verbose:class (which prints where each class was loaded from) are how you debug it.

Java modules (JPMS, Java 9). A module is a named group of packages with a descriptor, module-info.java, at the root of its source tree:

// src/com.acme.billing/module-info.java
module com.acme.billing {
    requires java.sql;                 // modules I depend on
    exports com.acme.billing.api;      // only this package is visible to other modules
    // com.acme.billing.internal is NOT exported: its public classes are hidden
}

The key relationship: packages organise classes; modules organise packages. Before Java 9, public meant "anyone on the classpath can use this". With modules, a public class is only accessible outside its module if its package is exported. That's how the JDK hides internals like sun.misc and jdk.internal.* (strongly encapsulated by default since Java 16 and 17). Modules also forbid split packages: two named modules may not contain the same package, which removes the shadowing problem described above.

You don't have to adopt modules. Code on the classpath runs in the unnamed module, which can read every module and sees all exported packages. Most applications still use the classpath; libraries and the JDK itself are where modules matter most.

05How to say it in the interview

When I ask about packages and imports, I'm listening for three things: that you know imports are compile-time only, that you can explain how a class name becomes a file lookup on the classpath, and that you know where modules fit. If you mention a real classpath conflict and how you'd debug it, that's the senior signal.

package com.acme.billing  →  com/acme/billing/Invoice.class
FQN = package + simple name; reversed domain, lowercase; no java.*
import = compile-time only → bytecode uses FQNs
  wildcard: no runtime cost, no subpackages
  implicit: java.lang.*, own package
  static import: members (Math.max → max)
clash: single-type import > same package > on-demand
default package: cannot be imported → always declare a package
classpath: ordered, first match wins → shadowing, NoSuchMethodError
JPMS (9): module-info, requires/exports; public ≠ accessible unless exported