Project Layout and Packages

Learning goals

Organize Java source into packages and directories, understand the classpath, compile multi-file projects from the terminal, and recognize how Maven/Gradle layouts map to the same rules—without needing a build tool yet.

Why structure matters

A single-file Hello.java scales poorly. Real projects split code into packages (namespaces) and classes (one public top-level class per file, usually). The filesystem mirrors the package name.

Package naming convention

Packages use reverse domain notation:

package com.example.app;

public class Application {
    public static void main(String[] args) {
        System.out.println("Started");
    }
}

File path (standard layout):

src/
  com/
    example/
      app/
        Application.java

Rule: package com.example.app; → directory com/example/app/.

Package names are lowercase. Class names use PascalCase.

Default package (avoid in production)

If you omit package, the class lives in the default package. Fine for tiny experiments; real code always uses named packages to avoid collisions.

Compiling with packages

From the src directory (or project root with -sourcepath):

javac com/example/app/Application.java

Or compile everything:

javac $(find . -name "*.java")

Run:

java com.example.app.Application

Use the fully qualified class name (FQCN): com.example.app.Application.

Classpath

The classpath tells the JVM where to find .class files and JARs.

java -cp src com.example.app.Application
javac -cp lib/some.jar -d out src/com/example/app/Application.java

Modern style separates source (src/) from output (out/ or target/classes/).

Multi-class example

// src/com/example/app/Greeter.java
package com.example.app;

public class Greeter {
    public String greet(String name) {
        return "Hello, " + name;
    }
}

// src/com/example/app/Application.java
package com.example.app;

public class Application {
    public static void main(String[] args) {
        Greeter greeter = new Greeter();
        System.out.println(greeter.greet("Java"));
    }
}

Both files share the same package, so no import is needed. Different packages require import com.other.Util;.

Maven / Gradle layout (preview)

Build tools enforce the same mental model:

my-app/
  src/main/java/com/example/app/Application.java
  src/test/java/com/example/app/ApplicationTest.java
  pom.xml          # Maven
  build.gradle     # Gradle

You will not configure Maven in this course, but interviews assume you recognize src/main/java.

Module path (JDK 9+, awareness)

JPMS modules (module-info.java) add another layer for large apps and libraries. Core learning stays in the classpath world; know that --module-path exists when libraries publish modular JARs.

Common mistakes

1. Directory mismatch. package com.foo; in src/Foo.java (wrong)—must be src/com/foo/Foo.java.
2. Running without FQCN. java Application fails when the class is in a package; use java com.example.app.Application.
3. Wrong current directory. Classpath is relative to where you run java, not where the .java file lives.
4. Multiple public classes in one file. Only one public top-level class per file, and it must match the filename.
5. Case sensitivity on Linux CI. Com.example.App breaks on Linux servers even if macOS seemed forgiving.

Practice checkpoint

1. Where does package org.demo.util; class Helper.java live?

   • Answer: org/demo/util/Helper.java (under source root).

2. Compile and run a two-class project: Calculator with add(int,int) and Main calling it.

   • Answer: Same package, javac both files, java Main.

3. What command puts compiled classes in out/?

   • Answer: javac -d out path/to/Source.java

4. Why use packages?

   • Answer: Avoid name collisions, organize code, control visibility (public vs package-private).

Interview angles

• “Difference between path and classpath?” — -sourcepath for compilation input; -classpath for locating classes at compile and run time.
• “Can two JARs contain the same class?” — Yes; classpath order determines which wins (shadowing)—a common production bug.
• “One public class per file—why?” — Convention and compiler rule for clarity and tooling.

Next: /java/learn/language/variables-and-types/