Java Foundations
for Spring Boot

# Your .java file is compiled to bytecode
javac UserService.java → UserService.class  (bytecode, platform-neutral)

# JVM loads the class
ClassLoader → reads .class → loads into Method Area

# JIT compiles HOT code to native machine code
Interpreter → runs bytecode slowly at first
JIT Compiler → identifies "hot" methods (called 10,000+ times)
              → compiles to native CPU instructions
              → now runs at near-native speed

# That's why Spring Boot is slow to start but fast in production!

public class MemoryDemo {
    // Static fields → Method Area (Metaspace in JDK8+)
    private static final String APP_NAME = "MyApp";

    public void processOrder(int orderId) {
        // orderId → Stack (primitive, per-frame local variable)
        // orderRef → Stack (reference/pointer variable)
        // new Order(...) → Heap (actual object)
        Order order = new Order(orderId);

        // name → Stack (reference)
        // "Baljeet" → Heap (String object, possibly interned)
        String name = order.getCustomerName();

        calculateTax(order); // New frame pushed onto Stack
    } // ← Frame popped from Stack. order ref gone. Object eligible for GC.

    private double calculateTax(Order order) {
        double rate = 0.18; // Stack — primitive double
        return order.getAmount() * rate;
    } // ← Frame popped. rate gone from Stack.
}

// COMMON MISTAKE: Holding references prevents GC
public class LeakyCache {
    // This Map holds STRONG references — objects can never be GC'd!
    private static final Map<String, byte[]> cache = new HashMap<>();

    public void addToCache(String key) {
        // Each call adds 1MB to heap. GC CANNOT reclaim this.
        cache.put(key, new byte[1024 * 1024]);
    }
    // Fix: Use WeakHashMap or Caffeine cache with eviction policy
}

// Way 1: Extending Thread (avoid in modern code)
class MyThread extends Thread {
    @Override
    public void run() {
        System.out.println("Running in: " + Thread.currentThread().getName());
    }
}
new MyThread().start();

// Way 2: Implementing Runnable (better — separates task from executor)
Runnable task = () -> System.out.println("Lambda Runnable");
new Thread(task).start();

// Way 3: ExecutorService (production standard — reuses threads)
ExecutorService executor = Executors.newFixedThreadPool(10);
executor.submit(() -> processOrder(orderId));
executor.shutdown(); // Always shut down!

// Way 4: Spring's @Async (recommended in Spring Boot apps)
@Service
public class EmailService {
    @Async  // Spring runs this in a separate thread automatically
    public CompletableFuture<Void> sendEmailAsync(String to, String body) {
        // Runs in Spring's task executor thread pool
        sendEmail(to, body);
        return CompletableFuture.completedFuture(null);
    }
}

// Configure the thread pool for @Async
@Configuration
@EnableAsync
public class AsyncConfig implements AsyncConfigurer {
    @Override
    public Executor getAsyncExecutor() {
        ThreadPoolTaskExecutor executor = new ThreadPoolTaskExecutor();
        executor.setCorePoolSize(10);
        executor.setMaxPoolSize(50);
        executor.setQueueCapacity(100);
        executor.setThreadNamePrefix("async-exec-");
        executor.initialize();
        return executor;
    }
}

// ❌ DANGEROUS: Singleton bean with mutable state
@Service // This bean is shared across ALL threads!
public class OrderCounter {
    private int count = 0; // MUTABLE INSTANCE FIELD — race condition!

    public void increment() {
        count++; // NOT ATOMIC! count = count + 1 is THREE operations:
                 // 1. Read count
                 // 2. Add 1
                 // 3. Write back
                 // Two threads can read the same value and both write back,
                 // losing an increment. At 1000 req/sec, you lose many counts.
    }

    public int getCount() { return count; }
}

// ✅ FIX 1: Use AtomicInteger — lock-free thread safety
@Service
public class OrderCounter {
    private final AtomicInteger count = new AtomicInteger(0);

    public void increment() {
        count.incrementAndGet(); // Atomic — guaranteed correct
    }

    public int getCount() { return count.get(); }
}

// ✅ FIX 2: Use synchronized (heavier, but sometimes needed)
@Service
public class OrderCounter {
    private int count = 0;

    public synchronized void increment() { count++; } // Only one thread at a time
    public synchronized int getCount() { return count; }
}

// ✅ FIX 3: Stateless design (best for Spring services!)
@Service
public class OrderService {
    // NO instance fields that change — stateless = thread-safe by design
    private final OrderRepository orderRepo; // final, injected, immutable ref

    public OrderDto processOrder(OrderRequest request) {
        // All state is in local variables (stack) — thread-safe!
        Order order = new Order(request);
        return orderRepo.save(order);
    }
}

// ❌ VISIBILITY BUG: Thread may NEVER see the update
class Runner {
    private boolean running = true; // NOT volatile

    public void stop() { running = false; } // Writer thread

    public void run() {
        while (running) { // Reader thread might read cached CPU value!
            doWork();     // This loop may NEVER exit
        }
    }
}

// ✅ FIX: volatile forces main memory read/write
class Runner {
    private volatile boolean running = true;
    // volatile guarantees: writes by Thread-1 are VISIBLE to Thread-2

    public void stop() { running = false; }
    public void run() { while (running) { doWork(); } } // Now works correctly
}

// volatile does NOT make compound operations atomic!
// For i++ use AtomicInteger, not volatile int

// SCENARIO: Process a list of orders from the database
List<Order> orders = orderRepository.findAll();

// ❌ Old imperative style
List<OrderDto> result = new ArrayList<>();
for (Order order : orders) {
    if (order.getStatus() == OrderStatus.PENDING
        && order.getAmount() > 100) {
        result.add(new OrderDto(order.getId(), order.getAmount()));
    }
}
result.sort(Comparator.comparing(OrderDto::getAmount).reversed());

// ✅ Streams — declarative, readable, and parallel-capable
List<OrderDto> result = orders.stream()
    .filter(o -> o.getStatus() == OrderStatus.PENDING)
    .filter(o -> o.getAmount() > 100)
    .map(o -> new OrderDto(o.getId(), o.getAmount()))
    .sorted(Comparator.comparing(OrderDto::getAmount).reversed())
    .collect(Collectors.toList());

// SCENARIO: Group orders by status
Map<OrderStatus, List<Order>> byStatus = orders.stream()
    .collect(Collectors.groupingBy(Order::getStatus));

// SCENARIO: Total revenue by product category
Map<String, Double> revenueByCategory = orders.stream()
    .collect(Collectors.groupingBy(
        o -> o.getProduct().getCategory(),
        Collectors.summingDouble(Order::getAmount)
    ));

// SCENARIO: Parallel stream for CPU-intensive work
// ⚠️ WARNING: Only use parallel streams for CPU-bound tasks on large datasets!
// DO NOT use for I/O-bound tasks (DB calls, HTTP calls) — use CompletableFuture instead
long totalRevenue = orders.parallelStream()
    .mapToLong(Order::getAmount)
    .sum();

// SCENARIO: FlatMap — flattening nested collections
List<String> allTags = orders.stream()
    .flatMap(o -> o.getTags().stream()) // Order has List<String> tags
    .distinct()
    .sorted()
    .collect(Collectors.toList());

// Design your exception hierarchy deliberately
// Use RuntimeExceptions for domain errors (no forced try-catch)

// Base exception for your domain
public abstract class ApplicationException extends RuntimeException {
    private final String errorCode;

    public ApplicationException(String errorCode, String message) {
        super(message);
        this.errorCode = errorCode;
    }
    public String getErrorCode() { return errorCode; }
}

// Specific exceptions
public class ResourceNotFoundException extends ApplicationException {
    public ResourceNotFoundException(String resource, Object id) {
        super("RESOURCE_NOT_FOUND",
              String.format("%s with id '%s' not found", resource, id));
    }
}

public class BusinessRuleViolationException extends ApplicationException {
    public BusinessRuleViolationException(String message) {
        super("BUSINESS_RULE_VIOLATION", message);
    }
}

public class InsufficientFundsException extends ApplicationException {
    public InsufficientFundsException(double required, double available) {
        super("INSUFFICIENT_FUNDS",
              String.format("Required: %.2f, Available: %.2f", required, available));
    }
}

// Spring Boot global handler — catches ALL domain exceptions
@RestControllerAdvice
public class GlobalExceptionHandler {

    @ExceptionHandler(ResourceNotFoundException.class)
    @ResponseStatus(HttpStatus.NOT_FOUND)
    public ErrorResponse handleNotFound(ResourceNotFoundException ex) {
        return new ErrorResponse(ex.getErrorCode(), ex.getMessage(), 404);
    }

    @ExceptionHandler(BusinessRuleViolationException.class)
    @ResponseStatus(HttpStatus.UNPROCESSABLE_ENTITY)
    public ErrorResponse handleBusinessRule(BusinessRuleViolationException ex) {
        return new ErrorResponse(ex.getErrorCode(), ex.getMessage(), 422);
    }

    @ExceptionHandler(Exception.class) // Catch-all — don't expose internals!
    @ResponseStatus(HttpStatus.INTERNAL_SERVER_ERROR)
    public ErrorResponse handleGeneric(Exception ex) {
        log.error("Unhandled exception", ex); // Log the full trace internally
        return new ErrorResponse("INTERNAL_ERROR", "An unexpected error occurred", 500);
        // NEVER return ex.getMessage() — it might leak SQL, stack traces, etc.
    }
}

// Generic repository pattern (what Spring Data JPA gives you)
public interface Repository<T, ID> {
    T findById(ID id);
    T save(T entity);
    void delete(T entity);
    List<T> findAll();
}

// Bounded type parameters — T must extend Serializable
public class Cache<T extends Serializable> {
    private final Map<String, T> store = new ConcurrentHashMap<>();
    public void put(String key, T value) { store.put(key, value); }
    public Optional<T> get(String key) { return Optional.ofNullable(store.get(key)); }
}

// Generic API response wrapper (common Spring pattern)
public class ApiResponse<T> {
    private final T data;
    private final String message;
    private final int status;
    private final Instant timestamp = Instant.now();

    public static <T> ApiResponse<T> success(T data) {
        return new ApiResponse<>(data, "Success", 200);
    }

    public static <T> ApiResponse<T> error(String message, int status) {
        return new ApiResponse<>(null, message, status);
    }
}

// Usage in controller
@GetMapping("/{id}")
public ResponseEntity<ApiResponse<UserDto>> getUser(@PathVariable Long id) {
    UserDto user = userService.findById(id);
    return ResponseEntity.ok(ApiResponse.success(user));
}

// Wildcard — when you need flexibility
public double calculateTotal(List<? extends Order> orders) {
    // Works with List<Order>, List<PremiumOrder>, List<TrialOrder>
    return orders.stream().mapToDouble(Order::getAmount).sum();
}

// This is SIMPLIFIED pseudocode of what Spring does with @Autowired
// The real source is 100x more complex, but this is the idea:

public class SimpleDIContainer {
    private final Map<Class<?>, Object> beans = new HashMap<>();

    public void register(Object bean) {
        beans.put(bean.getClass(), bean);
    }

    // This is what @Autowired triggers
    public void injectDependencies(Object target) throws Exception {
        Class<?> clazz = target.getClass();

        for (Field field : clazz.getDeclaredFields()) {
            if (field.isAnnotationPresent(Autowired.class)) {
                field.setAccessible(true); // Bypass private access!
                Object dependency = beans.get(field.getType());
                field.set(target, dependency); // Inject the bean
            }
        }
    }
}

// And this is how @Transactional works — runtime proxy via reflection
public class TransactionProxy implements InvocationHandler {
    private final Object target;
    private final TransactionManager txManager;

    @Override
    public Object invoke(Object proxy, Method method, Object[] args) throws Throwable {
        if (method.isAnnotationPresent(Transactional.class)) {
            txManager.begin();
            try {
                Object result = method.invoke(target, args); // Call real method
                txManager.commit();
                return result;
            } catch (Exception e) {
                txManager.rollback();
                throw e;
            }
        }
        return method.invoke(target, args);
    }
}
// Spring creates a Proxy.newProxyInstance() wrapping your @Service —
// THAT'S why @Transactional doesn't work when you call methods internally!
// Internal calls skip the proxy.

// Functional interfaces — take a lambda, get a behavior
@FunctionalInterface
public interface Validator<T> {
    boolean validate(T value);
    // Only ONE abstract method = functional interface
}

// Now use lambdas to pass behavior:
Validator<String> emailValidator = email -> email.contains("@") && email.contains(".");
Validator<Integer> ageValidator = age -> age >= 18 && age <= 120;

// BUILT-IN functional interfaces (java.util.function)
// Predicate<T>: T -> boolean (filtering)
Predicate<User> isActive = user -> user.getStatus() == UserStatus.ACTIVE;
List<User> activeUsers = users.stream().filter(isActive).collect(toList());

// Function<T,R>: T -> R (transformation/mapping)
Function<User, UserDto> toDto = user -> new UserDto(user.getId(), user.getName());
List<UserDto> dtos = users.stream().map(toDto).collect(toList());

// Consumer<T>: T -> void (side effects)
Consumer<Order> auditOrder = order -> auditLog.record(order.getId(), "PROCESSED");
orders.forEach(auditOrder);

// Supplier<T>: () -> T (lazy evaluation)
Supplier<String> errorMsg = () -> "Error occurred at " + LocalDateTime.now();
// The string is only created if we actually need it

// Method references — even cleaner lambdas
users.stream()
    .map(User::getName)         // instance method reference
    .filter(Objects::nonNull)   // static method reference
    .forEach(System.out::println); // instance method reference

// Spring Security uses Predicate-like lambdas
http.authorizeHttpRequests(auth -> auth
    .requestMatchers("/api/public/**").permitAll()
    .requestMatchers("/api/admin/**").hasRole("ADMIN")
    .anyRequest().authenticated()
);

// SCENARIO: Place an order — multiple independent async tasks
@Service
public class OrderService {
    private final InventoryService inventoryService;
    private final PaymentService paymentService;
    private final NotificationService notificationService;
    private final Executor asyncExecutor;

    public OrderConfirmation placeOrder(OrderRequest request) {
        // These 3 can run IN PARALLEL — no dependency between them
        CompletableFuture<Boolean> inventoryCheck = CompletableFuture.supplyAsync(
            () -> inventoryService.checkAvailability(request.getProductId()),
            asyncExecutor
        );

        CompletableFuture<PaymentResult> paymentProcess = CompletableFuture.supplyAsync(
            () -> paymentService.charge(request.getPaymentDetails()),
            asyncExecutor
        );

        // Wait for BOTH inventory and payment before proceeding
        CompletableFuture<OrderConfirmation> orderFuture = inventoryCheck
            .thenCombine(paymentProcess, (inventoryOk, paymentResult) -> {
                if (!inventoryOk) throw new BusinessRuleViolationException("Out of stock");
                if (!paymentResult.isSuccess()) throw new BusinessRuleViolationException("Payment failed");

                Order order = createAndSaveOrder(request, paymentResult);
                return new OrderConfirmation(order.getId(), order.getStatus());
            });

        // Non-blocking: send notification AFTER order is confirmed
        orderFuture.thenAcceptAsync(
            confirmation -> notificationService.sendConfirmation(confirmation),
            asyncExecutor
        );

        // Wait for result (in a real async controller, return the Future directly)
        try {
            return orderFuture.get(5, TimeUnit.SECONDS); // Timeout is critical!
        } catch (TimeoutException e) {
            throw new ServiceUnavailableException("Order processing timed out");
        }
    }
}

// ERROR HANDLING in async pipelines
CompletableFuture<User> userFuture = CompletableFuture
    .supplyAsync(() -> userService.findById(userId))
    .exceptionally(ex -> {
        log.error("Failed to fetch user {}: {}", userId, ex.getMessage());
        return User.anonymous(); // Return fallback value
    })
    .thenApply(user -> {
        user.setLastAccessed(Instant.now());
        return user;
    });

// BEFORE Records: Verbose DTO (this was 50 lines with Lombok)
public class CreateUserRequest {
    @NotBlank private String name;
    @Email private String email;
    @Size(min = 8) private String password;

    // getters, setters, equals, hashCode, toString...
}

// WITH Records: Concise, immutable, with validation
public record CreateUserRequest(
    @NotBlank String name,
    @Email String email,
    @Size(min = 8) String password
) {}

// Records in a controller — works perfectly
@PostMapping("/users")
public ResponseEntity<UserResponse> createUser(
        @RequestBody @Valid CreateUserRequest request) {
    User user = userService.create(request.name(), request.email(), request.password());
    return ResponseEntity.created(URI.create("/users/" + user.getId()))
                         .body(new UserResponse(user.getId(), user.getName()));
}

// Response DTO as a record
public record UserResponse(Long id, String name) {}

// Records work with JPA projections too!
public interface UserProjection {
    record UserSummary(Long id, String name, String email) {}
    List<UserSummary> findAllProjectedBy(); // Spring Data generates SQL
}

// 1. RestTemplate (legacy — synchronous, blocking)
// Use only for simple cases or legacy codebases
@Service
public class UserServiceClient {
    private final RestTemplate restTemplate;

    public UserDto getUser(Long id) {
        // Blocks the current thread until response!
        return restTemplate.getForObject("http://user-service/users/" + id, UserDto.class);
    }
}

// 2. WebClient (modern — non-blocking, reactive)
// Best for microservices communicating with each other
@Service
public class UserServiceClient {
    private final WebClient webClient;

    public UserServiceClient(WebClient.Builder builder) {
        this.webClient = builder
            .baseUrl("http://user-service")
            .defaultHeader("X-Api-Key", "secret")
            .build();
    }

    // Returns a Mono — doesn't block the thread
    public Mono<UserDto> getUser(Long id) {
        return webClient.get()
            .uri("/users/{id}", id)
            .retrieve()
            .onStatus(HttpStatusCode::is4xxClientError,
                response -> Mono.error(new UserNotFoundException(id)))
            .bodyToMono(UserDto.class)
            .timeout(Duration.ofSeconds(3)) // Always set timeouts!
            .retryWhen(Retry.backoff(3, Duration.ofSeconds(1))); // Retry on failure
    }
}

// 3. Java 11+ HttpClient (native, no Spring dependency)
HttpClient client = HttpClient.newBuilder()
    .connectTimeout(Duration.ofSeconds(5))
    .followRedirects(HttpClient.Redirect.NORMAL)
    .build();

HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://api.example.com/users/1"))
    .header("Authorization", "Bearer " + token)
    .GET()
    .build();

// Async non-blocking send
client.sendAsync(request, BodyHandlers.ofString())
    .thenApply(HttpResponse::body)
    .thenApply(body -> objectMapper.readValue(body, UserDto.class))
    .exceptionally(ex -> { log.error("HTTP call failed", ex); return null; });