Package Concept

// ── Package declaration — first statement in a Java source file: ──────
package com.example.service;   // must be the FIRST statement, before imports

// ── Package establishes the fully qualified class name: ───────────────
// File: src/com/example/service/OrderService.java
// Package: com.example.service
// Simple name: OrderService
// Fully qualified name: com.example.service.OrderService

// ── Two classes with the same simple name in different packages: ───────
// com.example.auth.User        — authentication user
// com.example.billing.User     — billing customer
// Both can exist simultaneously — packages prevent collision.

// ── Package-private access — default when no modifier: ────────────────
package com.example.internal;

class InternalHelper {          // no modifier = package-private
    static String format(String s) { return s.trim(); }
}

class PublicService {           // this is also package-private (no public)
    public void serve() {
        InternalHelper.format("data");   // ✓ same package
    }
}

// From a different package — InternalHelper is INVISIBLE:
// com.example.other.SomeClass cannot reference com.example.internal.InternalHelper
// even with a full import — package-private means invisible outside the package.

// ── Physical directory structure mirrors package: ─────────────────────
//
//  src/
//  └── com/
//      └── example/
//          ├── service/
//          │   ├── OrderService.java    (package com.example.service)
//          │   └── UserService.java     (package com.example.service)
//          ├── model/
//          │   ├── Order.java           (package com.example.model)
//          │   └── User.java            (package com.example.model)
//          └── repository/
//              ├── OrderRepository.java (package com.example.repository)
//              └── UserRepository.java  (package com.example.repository)

// ── Package naming convention — reverse domain + structure: ──────────
//
// Organisation domain: example.com
// Reversed:            com.example
//
// Application packages:
//   com.example.model          — domain model classes
//   com.example.service        — business logic
//   com.example.repository     — data access
//   com.example.controller     — web layer (REST/MVC)
//   com.example.config         — configuration
//   com.example.util           — utilities
//   com.example.exception      — custom exceptions
//   com.example.dto            — data transfer objects
//
// By feature (alternative):
//   com.example.order          — order feature: Order, OrderService, etc.
//   com.example.user           — user feature: User, UserService, etc.
//   com.example.payment        — payment feature

// ── Naming rules: ─────────────────────────────────────────────────────
// ✓ All lowercase:          com.example.service
// ✗ Uppercase letters:      com.Example.Service      — wrong convention
// ✓ Only letters, digits:   com.example.api2
// ✗ Hyphens:                com.example.my-service   — invalid identifier
// ✗ Starting with digit:    com.example.2service     — invalid identifier
// ✓ Underscore ok but rare: com.example.my_service   — legal but rare

// ── Reserved word in package name — underscore prefix: ────────────────
// If a package segment is a reserved word (like 'int', 'class'):
package com.example.int_;      // convention: append underscore
package com.example._new;      // or prefix with underscore

// ── Default (unnamed) package — avoid in production: ─────────────────
// HelloWorld.java with NO package declaration:
public class HelloWorld {
    public static void main(String[] args) {
        System.out.println("Hello");
    }
}
// This class is in the unnamed default package.
// No other named package can import or reference it.
// Use only for simple experiments — never in production code.

// ── Access levels and package boundaries: ────────────────────────────
//
// package com.example.order (four classes):

// PUBLIC — visible everywhere:
public class Order { ... }

// PACKAGE-PRIVATE — visible only within com.example.order:
class OrderValidator { ... }       // no modifier
class OrderRepository { ... }      // no modifier

// PROTECTED — visible in package + subclasses:
public class BaseOrderProcessor {
    protected void processStep() { ... }  // subclasses can override
}

// ── Package-private as an encapsulation tool: ─────────────────────────
// Package: com.example.auth
// Public API: AuthService (what the rest of the app uses)
// Internal implementation: TokenStore, SessionCache, HashUtils (hidden)

// AuthService.java:
package com.example.auth;

public class AuthService {
    private final TokenStore    tokenStore    = new TokenStore();
    private final SessionCache  sessionCache  = new SessionCache();

    public String login(String username, String password) {
        String hash = HashUtils.hash(password);   // package-private
        // ...
        return tokenStore.createToken(username);
    }
}

// TokenStore.java:
package com.example.auth;

class TokenStore {                 // package-private — invisible outside auth
    String createToken(String username) { ... }
    boolean validate(String token) { ... }
}

// HashUtils.java:
package com.example.auth;

class HashUtils {                  // package-private — invisible outside auth
    static String hash(String input) { ... }
}

// From com.example.service.OrderService — cannot access internal types:
// import com.example.auth.TokenStore;   // COMPILE ERROR — package-private
// import com.example.auth.HashUtils;    // COMPILE ERROR — package-private
// Only com.example.auth.AuthService is accessible (it's public).