{"title":"Packages","description":"","content":"A Java program of any real size has dozens, often hundreds, of classes. A retail system has classes for products, carts, orders, customers, payments, shipping, inventory, discounts, and reviews. Two of those classes might want the same simple name (`Order` in the customer-facing module and `Order` in the warehouse module). Some classes are meant for the whole codebase to use, others belong to a single feature and shouldn't be touched from outside. A package is the language feature that makes all of this manageable. This lesson covers what a package is, how to declare one, how the folder layout on disk has to match the declaration, and how to compile and run code that lives inside packages.\n\n---\n\n# What a Package Is\n\nA package is a named container for classes. Every class in Java belongs to exactly one package. If you don't declare a package, the class belongs to the default (unnamed) package, which production code avoids.\n\nThree problems disappear once classes are grouped into packages.\n\nThe first is **naming conflicts**. Two different teams, or two different libraries, can both define a class called `Order` without colliding, as long as each class lives in its own package. The full identity of a class is its **fully qualified name**, which is the package name plus the class name. `com.algomaster.shop.Order` and `com.algomaster.warehouse.Order` are different types, even though their short names match. Without packages, the second declaration would shadow the first and the compiler would refuse the build.\n\nThe second is **organization**. A package is a folder on disk. The package name maps directly to a directory path, so the structure of the source tree mirrors the structure of the program. Browsing `com/algomaster/shop/cart/` shows exactly what code handles shopping carts, the same way a folder named `invoices/` in any office indicates its contents.\n\nThe third is **access control**. Java has a visibility level called *package-private* (the default when you write no modifier on a class member). Members at this level are visible to other classes in the same package and hidden from everything else. Packages are the unit Java uses to draw that boundary.\n\n\n```mermaid\nflowchart LR\n Root[\"com.algomaster
(root package)\"]:::cyan\n Shop[\"com.algomaster.shop\"]:::orange\n Cart[\"com.algomaster.shop.cart\"]:::orange\n Orders[\"com.algomaster.shop.orders\"]:::orange\n Util[\"com.algomaster.util\"]:::teal\n\n Root --> Shop\n Root --> Util\n Shop --> Cart\n Shop --> Orders\n\n classDef cyan fill:#00ceff,stroke:#000,color:#000\n classDef orange fill:#ffa94d,stroke:#000,color:#000\n classDef teal fill:#38d9a9,stroke:#000,color:#000\n```\n\n\nThe diagram shows a small package tree for an e-commerce app. The root is `com.algomaster`. Underneath it, `shop` holds feature-specific code, which is further broken into `cart` and `orders`. A sibling `util` package holds helpers that the rest of the codebase reuses. Each dotted name is a separate package, and each one maps to a folder of the same path on disk.\n\n---\n\n# The `package` Declaration\n\nA class joins a package by declaring it on the very first line of code in the file (comments are allowed before the declaration; nothing else is). The syntax is the keyword `package`, the package name, and a semicolon.\n\n\n```java\npackage com.algomaster.shop;\n\npublic class Product {\n private String name;\n private double price;\n\n public Product(String name, double price) {\n this.name = name;\n this.price = price;\n }\n\n public String getName() {\n return name;\n }\n\n public double getPrice() {\n return price;\n }\n}\n```\n\n\nThis file declares one public class, `Product`, and tells the compiler that the class belongs to the package `com.algomaster.shop`. The fully qualified name of the class is `com.algomaster.shop.Product`. Any other class in any other package refers to it by that full name (or by importing it).\n\nThree rules apply to the declaration itself.\n\nThe `package` statement, if present, must be the first non-comment line in the file. Putting an `import` or a class declaration above it fails to compile.\n\nA file can declare at most one package. There's no syntax for splitting a single source file across packages, and there's no way for one file to \"join\" two packages at once.\n\nEvery file in a package repeats the same `package` declaration at the top. The compiler reads each file independently, so the line has to appear in each one. A file in `com.algomaster.shop` that forgets the declaration lands in the default package, even if every neighboring file declares the right package.\n\nA second class in the same package:\n\n\n```java\npackage com.algomaster.shop;\n\npublic class CartItem {\n private Product product;\n private int quantity;\n\n public CartItem(Product product, int quantity) {\n this.product = product;\n this.quantity = quantity;\n }\n\n public double getSubtotal() {\n return product.getPrice() * quantity;\n }\n}\n```\n\n\n`CartItem` refers to `Product` by its short name, not as `com.algomaster.shop.Product`. Two classes in the same package see each other directly without imports or qualifications. This convenience is one of the common reasons to put related classes in the same package.\n\n---\n\n# Naming Conventions\n\nJava doesn't force a specific naming style, but the conventions are universal across the ecosystem. Following them keeps one team's package layout legible to another team without explanation.\n\n**Lowercase only.** Package names are written entirely in lowercase. `com.algomaster.shop` is correct; `com.AlgoMaster.Shop` compiles but looks wrong to every Java reader. Mixed case is reserved for type names (classes, interfaces, enums).\n\n**Reverse domain name as the root.** The standard practice is to start the package with a domain the team owns, written in reverse. A company that owns `algomaster.io` uses `io.algomaster.*` as its root. The Oracle JDK uses `java.*` and `javax.*` (a special case, reserved for the platform). A company at `example.com` would use `com.example.*`. The reverse-domain prefix guarantees global uniqueness: as long as each team starts with a domain it controls, no two teams ever pick the same package name by accident.\n\n**No hyphens.** Package name segments must be valid Java identifiers. Identifiers can contain letters, digits, underscores, and dollar signs, and they cannot start with a digit. Hyphens are illegal. A domain like `algo-master.io` becomes `io.algomaster` or `io.algo_master` in package form (the underscore is allowed but unusual).\n\n**No Java keywords or reserved words.** A segment cannot be a Java keyword like `int`, `class`, `new`, or `void`. A domain like `int.example.com` would have to become `int_.example.com` or similar in package form.\n\n**Avoid digits as the first character of a segment.** Identifiers can't start with a digit. A segment that has to start with one needs a workaround, usually a leading underscore.\n\nA small table of legal versus illegal forms:\n\n\n| Package name | Legal? | Why |\n| --- | --- | --- |\n| `com.algomaster.shop` | Yes | Lowercase, reverse domain, valid identifiers. |\n| `com.algomaster.shop.cart` | Yes | Sub-package of `shop`. |\n| `com.AlgoMaster.Shop` | Yes, but discouraged | Compiles, but breaks convention. |\n| `com.algo-master.shop` | No | Hyphen is not a valid identifier character. |\n| `com.algomaster.new` | No | `new` is a Java keyword. |\n| `com.algomaster.3d` | No | A segment cannot start with a digit. |\n| `Com.Algomaster.Shop` | Yes, but discouraged | Compiles. Mixed case breaks convention. |\n\n\nFor internal projects with no public domain, picking a stable prefix (`com.algomaster.internal`, `io.algomaster.tools`) keeps the same uniqueness property and matches everything else in the codebase.\n\n---\n\n# Folder Layout on Disk\n\nThe package name is not just a label. It maps directly to a folder structure on disk, with each dot in the name corresponding to a folder boundary. The Java compiler and the JVM both rely on this mapping to find class files.\n\nA class declared as `package com.algomaster.shop;` must live in a file at path `com/algomaster/shop/.java` (using `/` on macOS and Linux, `\\` on Windows). The reverse is also true: a file at `com/algomaster/shop/Product.java` must declare `package com.algomaster.shop;` at the top. The two must match exactly.\n\nA small project that has two classes, `Product` and `CartItem`, both in `com.algomaster.shop`, plus a `Main` class in `com.algomaster.shop.app`, looks like this on disk:\n\n\n```shell\nshop-project/\n src/\n com/\n algomaster/\n shop/\n Product.java\n CartItem.java\n app/\n Main.java\n```\n\n\nFive folder levels under `src/` lead to the actual source files. The depth comes straight from the dots in the package names. `com.algomaster.shop.app` has three dots, so the path inside `src/` has three folder transitions before the file name.\n\n\n```mermaid\nflowchart TD\n Decl[\"package com.algomaster.shop;\"]:::cyan\n Dot1[\"dot 1\"]:::orange\n Dot2[\"dot 2\"]:::orange\n Folder[\"Folder path:
com/algomaster/shop/\"]:::green\n File[\"File: Product.java\"]:::teal\n\n Decl --> Dot1\n Dot1 --> Dot2\n Dot2 --> Folder\n Folder --> File\n\n classDef cyan fill:#00ceff,stroke:#000,color:#000\n classDef orange fill:#ffa94d,stroke:#000,color:#000\n classDef green fill:#69db7c,stroke:#000,color:#000\n classDef teal fill:#38d9a9,stroke:#000,color:#000\n```\n\n\nThe diagram traces the mapping. Each dot in the package name becomes a folder separator. The full path of the file is the package as folders, joined with the file name. A mismatch of even one folder level causes the compiler to fail the build.\n\nThe source of `Main.java`, sitting at `src/com/algomaster/shop/app/Main.java`:\n\n\n```java\npackage com.algomaster.shop.app;\n\nimport com.algomaster.shop.Product;\nimport com.algomaster.shop.CartItem;\n\npublic class Main {\n public static void main(String[] args) {\n Product book = new Product(\"Java in Action\", 29.99);\n CartItem item = new CartItem(book, 2);\n\n System.out.println(\"Item: \" + book.getName());\n System.out.println(\"Quantity: 2\");\n System.out.println(\"Subtotal: $\" + item.getSubtotal());\n }\n}\n```\n\n\n`Main` lives in a different package (`com.algomaster.shop.app`) from `Product` and `CartItem` (which live in `com.algomaster.shop`), so the file uses `import` statements to refer to those classes by short name. The relevant point here is that `Main` would not compile if either of those classes was in the wrong folder, because the compiler wouldn't find them at the path the package declaration specifies.\n\n---\n\n# Compiling and Running Classes in Packages\n\nOnce a project has packages, the commands to compile and run change in two small but important ways. `javac` needs to be told where to put the compiled `.class` files, and `java` needs the fully qualified name of the class to start.\n\nAssume this source layout:\n\n\n```shell\nshop-project/\n src/\n com/\n algomaster/\n shop/\n Product.java\n CartItem.java\n app/\n Main.java\n```\n\n\nFrom the `shop-project/` folder, compile everything with:\n\n\n```shell\njavac -d out src/com/algomaster/shop/Product.java src/com/algomaster/shop/CartItem.java src/com/algomaster/shop/app/Main.java\n```\n\n\nThe `-d out` flag tells `javac` to write the compiled `.class` files into an `out/` directory, preserving the package folder structure. After the command finishes, the project tree looks like this:\n\n\n```shell\nshop-project/\n src/\n com/algomaster/shop/Product.java\n com/algomaster/shop/CartItem.java\n com/algomaster/shop/app/Main.java\n out/\n com/algomaster/shop/Product.class\n com/algomaster/shop/CartItem.class\n com/algomaster/shop/app/Main.class\n```\n\n\nThe `out/` tree mirrors the `src/` tree. Without `-d out`, `javac` writes class files next to the sources, which mixes generated artifacts into the source tree and makes cleanup harder.\n\nListing every source file by hand is tedious for any project beyond three or four files. The usual shortcut is to let the shell expand the list:\n\n\n```shell\njavac -d out $(find src -name \"*.java\")\n```\n\n\nOr, on Windows or for a portable alternative, write the list to a file and use `@filename` syntax:\n\n\n```shell\nfind src -name \"*.java\" > sources.txt\njavac -d out @sources.txt\n```\n\n\nReal projects almost always use a build tool (Maven, Gradle) that handles this automatically. The hand-rolled commands here are useful to understand because they show what every build tool eventually delegates to.\n\nTo run the program, point `java` at the `out/` folder and pass the **fully qualified name** of the class that has `main`:\n\n\n```shell\njava -cp out com.algomaster.shop.app.Main\n```\n\n\nTwo pieces matter here. The `-cp out` flag (short for `--class-path`) tells the JVM where the root of the compiled tree is. The argument `com.algomaster.shop.app.Main` is the fully qualified class name of `Main`, written with dots, not slashes. The JVM combines the classpath with the FQN, looking for `out/com/algomaster/shop/app/Main.class`. When it finds it, it invokes the `main` method.\n\nA common mistake is to try `java -cp out Main` (just the short name), which fails because `Main` isn't in the default package; the JVM searches for `out/Main.class` and reports `Error: Could not find or load main class Main`. Another common mistake is passing the file path (`java out/com/algomaster/shop/app/Main.class`), which also fails because `java` takes a class name, not a path.\n\n\n| Command | What it does |\n| --- | --- |\n| `javac -d out src/...` | Compiles `.java` files and writes `.class` files under `out/`. |\n| `java -cp out com.algomaster.shop.app.Main` | Runs the class whose fully qualified name follows the classpath. |\n| `java -cp out Main` | Fails. The JVM looks for `Main.class` directly under `out/`. |\n| `java out/com/algomaster/shop/app/Main.class` | Fails. `java` takes a class name, not a file path. |\n\n\nThe first run of a JVM has a warm-up overhead from class loading. For a short program that runs once and exits, package depth has no measurable cost. The classpath lookup is a hash map, not a directory scan.\n\n---\n\n# The Default (Unnamed) Package\n\nA file that has no `package` declaration belongs to the **default package**, sometimes called the unnamed package. It works fine for the kind of throwaway example shown in a first lesson, where every class lives in one folder and there's nothing to organize.\n\n\n```java\npublic class HelloShop {\n public static void main(String[] args) {\n System.out.println(\"Hello, shop!\");\n }\n}\n```\n\n\nThis file has no `package` line at all. The class `HelloShop` lives in the default package, and the file lives directly in the source root (not inside any sub-folder).\n\nThe default package is fine for one-off scripts. It breaks down for anything bigger, and production code avoids it for three concrete reasons.\n\nA class in the default package cannot be imported into a named package. The Java language specification says: \"A type in the unnamed package can never be referred to by code in a named package.\" Once a project has any class in a real package, classes still in the default package are unreachable from it. `import HelloShop;` from a file in `com.algomaster.shop` is not valid syntax, because the `import` statement requires a package name to read from.\n\nThe default package can't define a unique name space. Two third-party libraries that both use the default package will collide if they ship classes with the same simple name. Named packages exist specifically to prevent that. The default package opts out of the protection.\n\nThe Java module system doesn't recognize the default package at all. A class in the default package cannot live inside a module. For any code that uses modules, the default package is not an option.\n\nThe rule of thumb is: as soon as a project has more than one source file or is intended to be shared, give every class a real package. The cost is one extra `package` line at the top of each file and a slightly deeper folder layout. Both are tiny prices for the benefits.\n\n---\n\n# Package-Level (Default) Access Briefly\n\nJava has four access levels for class members: `public`, `protected`, default (no modifier, also called package-private), and `private`. Three of them are familiar from the encapsulation lesson. The package-private level is the one packages enable.\n\nA member with no access modifier is visible to every class in the same package and invisible to every class outside it. The rule is at the package level, not the file level, so two classes that share a package see each other's package-private members directly.\n\n\n```java\npackage com.algomaster.shop;\n\npublic class Product {\n String internalSku;\n public String publicName;\n\n public Product(String name, String sku) {\n this.publicName = name;\n this.internalSku = sku;\n }\n}\n```\n\n\nThe field `publicName` is `public`, so any class anywhere can read or write it. The field `internalSku` has no modifier, so only classes in `com.algomaster.shop` can access it. A class in `com.algomaster.shop.app` cannot, even though the names appear related. Package membership is determined by exact match, not by prefix; `com.algomaster.shop` and `com.algomaster.shop.app` are different packages, even though one name starts with the other.\n\n\n| Modifier | Same class | Same package | Subclass (any package) | Anywhere |\n| --- | --- | --- | --- | --- |\n| `public` | Yes | Yes | Yes | Yes |\n| `protected` | Yes | Yes | Yes | No |\n| (no modifier) | Yes | Yes | No | No |\n| `private` | Yes | No | No | No |\n\n\nThe package-private level draws a boundary between code that's part of a package's internal implementation and code that's the package's public API. Helper classes, internal utilities, and methods that one class uses to talk to another class in the same package can stay package-private and be invisible to the rest of the program. The full discussion belongs in a more advanced lesson on API design. The access level exists only because packages exist to scope it.\n\n---\n\n# The `java.*` and `javax.*` Standard Packages\n\nThe JDK ships thousands of pre-built classes, and they live in two top-level package families: `java.*` and `javax.*`. Every Java program uses some of them, and most early work is built on top of them.\n\nA short tour of the most common ones:\n\n\n| Package | What's inside |\n| --- | --- |\n| `java.lang` | Core types: `String`, `Object`, `Integer`, `System`, `Math`, `Thread`, `Exception`. Imported automatically. |\n| `java.util` | Collections, dates, scanners: `List`, `Map`, `ArrayList`, `HashMap`, `Scanner`, `Random`. |\n| `java.io` | Input and output streams, files: `File`, `BufferedReader`, `PrintWriter`. |\n| `java.nio.file` | Modern file APIs: `Path`, `Paths`, `Files`. |\n| `java.net` | Networking: `URL`, `URI`, `HttpURLConnection`. |\n| `java.time` | Modern date and time API (Java 8+): `LocalDate`, `Instant`, `Duration`. |\n| `java.math` | Arbitrary-precision math: `BigInteger`, `BigDecimal`. |\n| `javax.crypto` | Cryptography APIs. |\n| `javax.sql` | Extended JDBC APIs. |\n\n\nThe `java.*` packages are the original platform APIs. `java.lang` is special because the compiler imports it automatically; `import java.lang.String;` is unnecessary even though `String` is in `java.lang`. Every other package, including the rest of `java.*`, has to be imported explicitly to refer to its classes by short name.\n\nThe `javax.*` packages started as extensions (the `x` is for \"extension\"). Originally they shipped separately and were added to the platform later. Over time some of them became standard, but the names stayed for backwards compatibility. There's no consistent rule today for which APIs land under `java.*` versus `javax.*`; for the purposes of this lesson, treat both as JDK-supplied packages usable without adding any dependencies.\n\nA program that uses `java.util.ArrayList` looks like this:\n\n\n```java\npackage com.algomaster.shop;\n\nimport java.util.ArrayList;\nimport java.util.List;\n\npublic class CartListing {\n public static void main(String[] args) {\n List cart = new ArrayList<>();\n cart.add(\"Java in Action\");\n cart.add(\"Effective Java\");\n cart.add(\"Clean Code\");\n\n System.out.println(\"Items in cart: \" + cart.size());\n for (String title : cart) {\n System.out.println(\"- \" + title);\n }\n }\n}\n```\n\n\nTwo imports bring in `ArrayList` and `List` from `java.util`. No import is needed for `String` or `System` because both live in `java.lang`. The class itself sits in `com.algomaster.shop`, our running package. The imports name the package and the class, separated by a dot, ending in a semicolon.\n\n---\n\n# Common Mistakes\n\nA few wrong moves repeat often enough to be worth naming.\n\n**Mismatched package declaration and folder path.** The file says `package com.algomaster.shop;` at the top, but the file is sitting in `src/com/algomaster/cart/Product.java`. The compiler emits an error like:\n\n\n```shell\nsrc/com/algomaster/cart/Product.java:1: error: class Product is public, should be declared in a file named Product.java\npackage com.algomaster.shop;\n```\n\n\nThe fix is to make the path match the package. Either move the file to `src/com/algomaster/shop/Product.java`, or change the declaration to `package com.algomaster.cart;`. The compiler is strict: if the two don't match, the build fails.\n\n**Running with a bare class name instead of the fully qualified name.** After compiling with `-d out`, the common attempt is:\n\n\n```shell\njava -cp out Main\n```\n\n\nThe JVM responds:\n\n\n```shell\nError: Could not find or load main class Main\nCaused by: java.lang.ClassNotFoundException: Main\n```\n\n\nThe fix is to use the FQN:\n\n\n```shell\njava -cp out com.algomaster.shop.app.Main\n```\n\n\n**Slashes in the FQN passed to `java`.** Another common attempt is:\n\n\n```shell\njava -cp out com/algomaster/shop/app/Main\n```\n\n\nThat command also fails, with a similar `ClassNotFoundException`. The argument to `java` is a class name, not a path. Use dots.\n\n**Forgetting `-cp` and assuming the current directory is the classpath.** With no `-cp`, the JVM uses the current directory as the classpath, which works only if the compiled tree is there. From `shop-project/`, running `java com.algomaster.shop.app.Main` without `-cp out` fails because the JVM looks for `com/algomaster/shop/app/Main.class` directly under `shop-project/`, not under `out/`.\n\n**Putting two top-level public classes in the same file.** A `.java` file may contain at most one `public` class, and that class must have the same name as the file. Trying to declare two `public` classes in one file always fails. This rule isn't about packages, but it surfaces during package work because file names and class names are checked together.\n\n**Using a Java keyword as a package segment.** A package like `com.algomaster.new.tools` fails because `new` is a keyword. The compiler error is straightforward, but the fix isn't always obvious. Pick a different segment name (`com.algomaster.newest.tools`, `com.algomaster.new_.tools`), or restructure the hierarchy.\n\n---\n\n# A Two-Package Example End to End\n\nA small, complete example that exercises everything in this lesson: two source files in two different packages, a compile step, and a run step.\n\nThe first file, at `src/com/algomaster/shop/Product.java`:\n\n\n```java\npackage com.algomaster.shop;\n\npublic class Product {\n private String name;\n private double price;\n\n public Product(String name, double price) {\n this.name = name;\n this.price = price;\n }\n\n public String getName() {\n return name;\n }\n\n public double getPrice() {\n return price;\n }\n}\n```\n\n\nThe second file, at `src/com/algomaster/shop/app/CartApp.java`:\n\n\n```java\npackage com.algomaster.shop.app;\n\nimport com.algomaster.shop.Product;\n\npublic class CartApp {\n public static void main(String[] args) {\n Product first = new Product(\"Wireless Mouse\", 19.99);\n Product second = new Product(\"USB-C Cable\", 8.49);\n\n double total = first.getPrice() + second.getPrice();\n System.out.println(\"Items: \" + first.getName() + \", \" + second.getName());\n System.out.println(\"Total: $\" + total);\n }\n}\n```\n\n\nCompile from `shop-project/`:\n\n\n```shell\njavac -d out src/com/algomaster/shop/Product.java src/com/algomaster/shop/app/CartApp.java\n```\n\n\nRun:\n\n\n```shell\njava -cp out com.algomaster.shop.app.CartApp\n```\n\n\nEvery piece this lesson covered appears here. Each file has a `package` declaration on its first non-comment line. The folder layout under `src/` matches the package names exactly. The compiler writes the corresponding folder tree under `out/`. The `java` command names the entry-point class by its fully qualified name. The two classes live in different packages, so `CartApp` uses an `import` to bring `Product` in by short name.","pageType":"java"}

Packages

Get Premium