Java User-Defined Packages: Create, Compile, Structure

// ── File: src/com/example/model/Order.java ───────────────────────────
package com.example.model;      // FIRST statement — before imports

public class Order {
    private final String id;
    private final String customerId;
    private final double total;

    public Order(String id, String customerId, double total) {
        this.id         = id;
        this.customerId = customerId;
        this.total      = total;
    }

    public String getId()         { return id;         }
    public String getCustomerId() { return customerId; }
    public double getTotal()      { return total;      }
}

// ── File: src/com/example/service/OrderService.java ───────────────────
package com.example.service;

import com.example.model.Order;         // import from another package

public class OrderService {

    private static int nextId = 1001;

    // Can use Order by simple name because it was imported:
    public Order createOrder(String customerId, double total) {
        return new Order(generateId(), customerId, total);
    }

    // Without an import, the fully qualified name is required:
    public com.example.model.Order findOrder(String id) {
        return null;   // lookup omitted in this example
    }

    private String generateId() {
        return "ORD-" + nextId++;
    }
}

// ── File: src/com/example/App.java  (has the main method) ─────────────
package com.example;

import com.example.model.Order;
import com.example.service.OrderService;

public class App {
    public static void main(String[] args) {
        OrderService service = new OrderService();
        Order order = service.createOrder("C-42", 99.5);
        System.out.println("Created " + order.getId()
                + " for " + order.getCustomerId()
                + ", total " + order.getTotal());
    }
}

// ── Directory structure: ──────────────────────────────────────────────
//  src/
//  └── com/
//      └── example/
//          ├── App.java
//          ├── model/
//          │   └── Order.java
//          └── service/
//              └── OrderService.java
//
// ── Compile (javac finds Order and OrderService through -sourcepath): ─
//  javac -sourcepath src -d out src/com/example/App.java
//
// ── Resulting output: ─────────────────────────────────────────────────
//  out/com/example/App.class
//  out/com/example/model/Order.class
//  out/com/example/service/OrderService.class
//
// ── Run (fully qualified name, classpath = output root): ──────────────
//  java -cp out com.example.App
//
// ── Output: ───────────────────────────────────────────────────────────
//  Created ORD-1001 for C-42, total 99.5

// File: src/com/example/order/Order.java
package com.example.order;

public class Order {                       // public: part of the package API
    String internalNotes = "";             // package-private field
    protected double discount;             // visible to subclasses elsewhere
    public double getTotal() { return 0; } // public API

    double applyRounding(double v) {       // package-private helper
        return Math.round(v * 100) / 100.0;
    }
}

// File: src/com/example/order/OrderValidator.java
package com.example.order;

class OrderValidator {                     // package-private class: hidden from other packages
    boolean isValid(Order o) {
        // Same package, so package-private members of Order are accessible:
        return o.getTotal() >= 0 && o.internalNotes != null;
    }
}

// File: src/com/example/billing/Invoice.java
package com.example.billing;

import com.example.order.Order;
// import com.example.order.OrderValidator;   // COMPILE ERROR: not public

public class Invoice {
    void print(Order o) {
        System.out.println(o.getTotal());      // OK: public
        // System.out.println(o.internalNotes); // ERROR: package-private
        // o.applyRounding(1.234);              // ERROR: package-private
    }
}

// Standard Maven / Gradle layout:
//
//  my-app/
//  ├── pom.xml
//  └── src/
//      ├── main/
//      │   └── java/
//      │       └── com/example/order/
//      │           ├── Order.java
//      │           ├── OrderService.java
//      │           └── OrderValidator.java     // package-private
//      └── test/
//          └── java/
//              └── com/example/order/          // SAME package as the code under test
//                  └── OrderValidatorTest.java // can see package-private OrderValidator
//
// Good package names:   com.example.order      com.example.payment.gateway
// Bad package names:    com.example.Order      com.example.my_utils     Com.Example

// Test in the same package can reach package-private code:
package com.example.order;

import org.junit.jupiter.api.Test;
import static org.junit.jupiter.api.Assertions.assertTrue;

class OrderValidatorTest {
    @Test
    void validOrderPasses() {
        assertTrue(new OrderValidator().isValid(new Order()));
    }
}

// ── Package-by-layer structure: ───────────────────────────────────────
//
//  com.example
//  ├── controller
//  │   ├── OrderController.java
//  │   └── UserController.java
//  ├── service
//  │   ├── OrderService.java
//  │   └── UserService.java
//  ├── repository
//  │   ├── OrderRepository.java
//  │   └── UserRepository.java
//  ├── model
//  │   ├── Order.java
//  │   └── User.java
//  └── exception
//      ├── OrderNotFoundException.java
//      └── UserNotFoundException.java
//
// Pro: easy to find any class of a given type
// Con: changes to one feature touch many packages; most classes must be public

// ── Package-by-feature structure: ────────────────────────────────────
//
//  com.example
//  ├── order
//  │   ├── OrderController.java
//  │   ├── OrderService.java
//  │   ├── OrderRepository.java
//  │   ├── Order.java
//  │   └── OrderNotFoundException.java
//  ├── user
//  │   ├── UserController.java
//  │   ├── UserService.java
//  │   ├── UserRepository.java
//  │   ├── User.java
//  │   └── UserNotFoundException.java
//  └── common
//      ├── BaseEntity.java
//      └── ApiResponse.java
//
// Pro: all code for a feature in one place; helpers can be package-private
// Con: shared code needs a separate 'common' package

// ── Hybrid structure: ─────────────────────────────────────────────────
//
//  com.example
//  ├── order
//  │   ├── controller
//  │   │   └── OrderController.java
//  │   ├── service
//  │   │   └── OrderService.java
//  │   ├── repository
//  │   │   └── OrderRepository.java
//  │   ├── dto
//  │   │   ├── CreateOrderRequest.java
//  │   │   └── OrderResponse.java
//  │   ├── exception
//  │   │   └── OrderNotFoundException.java
//  │   └── Order.java
//  └── shared
//      ├── exception
//      │   └── BaseException.java
//      └── util
//          └── DateUtils.java

// ── Package-private for internal implementation (package-by-feature) ──
// Each top-level class goes in its OWN file (one public class per file):

// File: com/example/order/Order.java
package com.example.order;

public class Order { /* public API of the order package */ }

// File: com/example/order/OrderService.java
package com.example.order;

public class OrderService {
    private final OrderValidator validator = new OrderValidator();   // internal use
    // ...
}

// File: com/example/order/OrderValidator.java
package com.example.order;

class OrderValidator { /* invisible outside com.example.order */ }

// File: com/example/order/OrderPriceCalculator.java
package com.example.order;

class OrderPriceCalculator { /* invisible outside com.example.order */ }