@ngxtm/devkit 3.4.0 → 3.4.1

package/rules/java/java-concurrency/references/virtual-threads.md

@@ -0,0 +1,190 @@
+# Virtual Threads (Java 21+)
+
+## Overview
+
+Virtual threads are lightweight threads managed by the JVM, not the OS. They enable the "thread-per-request" model without the overhead of platform threads.
+
+## Basic Usage
+
+```java
+// Start a virtual thread
+Thread.startVirtualThread(() -> {
+    // blocking I/O is fine - JVM will unmount from carrier thread
+    String response = httpClient.send(request, BodyHandlers.ofString()).body();
+    processResponse(response);
+});
+
+// Create named virtual thread
+Thread vt = Thread.ofVirtual()
+    .name("my-virtual-thread")
+    .start(() -> doWork());
+
+// Check if current thread is virtual
+if (Thread.currentThread().isVirtual()) {
+    // running on virtual thread
+}
+```
+
+## ExecutorService Pattern
+
+```java
+// Preferred: ExecutorService with virtual threads
+try (var executor = Executors.newVirtualThreadPerTaskExecutor()) {
+    List<Future<Result>> futures = tasks.stream()
+        .map(task -> executor.submit(() -> processTask(task)))
+        .toList();
+
+    List<Result> results = new ArrayList<>();
+    for (Future<Result> future : futures) {
+        results.add(future.get());  // blocking is fine
+    }
+    return results;
+}
+
+// For HTTP handlers (e.g., Tomcat, Jetty)
+// Configure server to use virtual threads - each request gets its own
+```
+
+## Structured Concurrency (Preview)
+
+```java
+// Run subtasks with structured lifetime
+try (var scope = new StructuredTaskScope.ShutdownOnFailure()) {
+    Subtask<User> userTask = scope.fork(() -> userService.find(userId));
+    Subtask<List<Order>> ordersTask = scope.fork(() -> orderService.findByUser(userId));
+    Subtask<Preferences> prefsTask = scope.fork(() -> prefsService.find(userId));
+
+    scope.join();           // Wait for all tasks
+    scope.throwIfFailed();  // Propagate exceptions
+
+    return new UserProfile(
+        userTask.get(),
+        ordersTask.get(),
+        prefsTask.get()
+    );
+}
+
+// ShutdownOnSuccess - cancel remaining tasks when one succeeds
+try (var scope = new StructuredTaskScope.ShutdownOnSuccess<String>()) {
+    scope.fork(() -> fetchFromPrimary());
+    scope.fork(() -> fetchFromBackup());
+
+    scope.join();
+    return scope.result();  // First successful result
+}
+```
+
+## When to Use Virtual Threads
+
+### Good Use Cases
+
+```java
+// ✅ I/O-bound operations
+void processRequests(List<Request> requests) {
+    try (var executor = Executors.newVirtualThreadPerTaskExecutor()) {
+        requests.forEach(req ->
+            executor.submit(() -> {
+                String data = httpClient.get(req.url());     // Network I/O
+                String result = database.query(req.query()); // Database I/O
+                fileSystem.write(result);                    // File I/O
+            })
+        );
+    }
+}
+
+// ✅ HTTP servers handling many concurrent connections
+// ✅ Database-heavy applications
+// ✅ Microservices making downstream calls
+```
+
+### When NOT to Use
+
+```java
+// ❌ CPU-bound computation - use platform threads
+// Virtual threads don't help with CPU-bound work
+void cpuIntensive(List<Data> data) {
+    // Use fixed thread pool sized to CPU cores
+    ExecutorService cpuPool = Executors.newFixedThreadPool(
+        Runtime.getRuntime().availableProcessors()
+    );
+}
+
+// ❌ Long synchronized blocks - use ReentrantLock instead
+// synchronized pins the carrier thread
+synchronized (lock) {
+    // Long blocking operation - BAD
+    Thread.sleep(1000);
+}
+
+// GOOD: Use ReentrantLock
+lock.lock();
+try {
+    Thread.sleep(1000);  // Virtual thread unmounts during sleep
+} finally {
+    lock.unlock();
+}
+```
+
+## Migration Tips
+
+```java
+// 1. Replace thread pools with virtual thread executor
+// Before
+ExecutorService executor = Executors.newFixedThreadPool(200);
+
+// After (for I/O-bound work)
+ExecutorService executor = Executors.newVirtualThreadPerTaskExecutor();
+
+// 2. Replace synchronized with ReentrantLock for blocking operations
+// Before
+synchronized (lock) {
+    blockingCall();
+}
+
+// After
+private final ReentrantLock lock = new ReentrantLock();
+
+lock.lock();
+try {
+    blockingCall();
+} finally {
+    lock.unlock();
+}
+
+// 3. Don't pool virtual threads - create new ones freely
+// Virtual threads are cheap (~1KB vs ~1MB for platform threads)
+```
+
+## Debugging
+
+```java
+// Thread dumps show virtual threads
+// jcmd <pid> Thread.dump_to_file -format=json threads.json
+
+// Configure carrier thread count
+// -Djdk.virtualThreadScheduler.parallelism=<n>
+// -Djdk.virtualThreadScheduler.maxPoolSize=<n>
+
+// Detect pinned virtual threads
+// -Djdk.tracePinnedThreads=full
+```
+
+## Pitfalls
+
+```java
+// 1. ThreadLocal can consume memory with many virtual threads
+// Use ScopedValue (preview) instead
+private static final ScopedValue<User> CURRENT_USER = ScopedValue.newInstance();
+
+ScopedValue.where(CURRENT_USER, user).run(() -> {
+    processRequest();
+});
+
+// 2. Don't use thread-per-task executor with CompletableFuture
+// Each stage gets a new virtual thread - may be wasteful
+CompletableFuture.supplyAsync(task, virtualExecutor)
+    .thenApplyAsync(transform, virtualExecutor);  // Unnecessary
+
+// 3. Monitor carrier thread pinning
+// Long synchronized blocks or native calls pin carrier threads
+```

package/rules/java/java-core-language/SKILL.md

@@ -0,0 +1,121 @@
+---
+name: Java Core Language
+description: Java language fundamentals, JVM basics, modern features, and idiomatic patterns.
+metadata:
+  labels: [java, core, language]
+  triggers:
+    files: ['**/*.java', 'pom.xml', 'build.gradle', 'build.gradle.kts']
+    keywords: [class, interface, record, enum, package, import, extends, implements, throws, sealed, permits]
+---
+
+# Java Core Language Standards
+
+## Modern Java Features (17+)
+
+```java
+// Records - immutable data carriers
+public record User(String id, String name, String email) {
+    // Compact constructor for validation
+    public User {
+        Objects.requireNonNull(id);
+        Objects.requireNonNull(name);
+    }
+}
+
+// Sealed classes - restricted inheritance
+public sealed interface Shape permits Circle, Rectangle, Triangle {}
+public record Circle(double radius) implements Shape {}
+public record Rectangle(double width, double height) implements Shape {}
+public final class Triangle implements Shape { /* ... */ }
+
+// Pattern matching for switch (21+)
+String describe(Shape shape) {
+    return switch (shape) {
+        case Circle(var r) -> "Circle with radius " + r;
+        case Rectangle(var w, var h) -> "Rectangle " + w + "x" + h;
+        case Triangle t -> "Triangle";
+    };
+}
+
+// Pattern matching for instanceof
+if (obj instanceof String s && !s.isBlank()) {
+    return s.toUpperCase();
+}
+```
+
+## Exception Handling
+
+```java
+// Custom exception hierarchy
+public class DomainException extends RuntimeException {
+    private final ErrorCode code;
+
+    public DomainException(ErrorCode code, String message) {
+        super(message);
+        this.code = code;
+    }
+
+    public DomainException(ErrorCode code, String message, Throwable cause) {
+        super(message, cause);
+        this.code = code;
+    }
+}
+
+// Try-with-resources
+try (var reader = new BufferedReader(new FileReader(path));
+     var writer = new BufferedWriter(new FileWriter(output))) {
+    reader.lines().map(String::toUpperCase).forEach(writer::write);
+} catch (IOException e) {
+    throw new DomainException(ErrorCode.IO_ERROR, "File processing failed", e);
+}
+```
+
+## Generics
+
+```java
+// Bounded type parameters
+public <T extends Comparable<T>> T max(T a, T b) {
+    return a.compareTo(b) > 0 ? a : b;
+}
+
+// Wildcards
+void processItems(List<? extends Number> items) { /* read-only */ }
+void addItems(List<? super Integer> items) { /* write-only */ }
+
+// Generic method with multiple bounds
+public <T extends Serializable & Comparable<T>> void process(T item) {}
+```
+
+## Null Safety
+
+```java
+// Use Optional for return types
+public Optional<User> findById(String id) {
+    return Optional.ofNullable(repository.get(id));
+}
+
+// Never use Optional as parameter or field
+// Use @Nullable annotation for nullable parameters
+public void process(@Nullable String input) {
+    if (input == null) return;
+    // ...
+}
+
+// Objects utility methods
+Objects.requireNonNull(param, "param must not be null");
+Objects.requireNonNullElse(value, defaultValue);
+```
+
+## Best Practices
+
+1. **Prefer records** for data transfer objects and value objects
+2. **Use sealed classes** when you have a fixed set of subtypes
+3. **Pattern matching** over instanceof chains and visitor pattern
+4. **Immutability by default** - use final fields, unmodifiable collections
+5. **Fail fast** - validate at boundaries, throw early
+6. **Meaningful exceptions** - include context, use exception chaining
+
+## References
+
+- [Modern Java Features](references/modern-java-features.md) - Records, Sealed Classes, Pattern Matching
+- [JVM Memory Model](references/jvm-memory-model.md) - Memory, GC, Performance

package/rules/java/java-core-language/references/REFERENCE.md

@@ -0,0 +1,15 @@
+# Java Core Language References
+
+## References
+
+- [**Modern Java Features**](modern-java-features.md) - Records, Sealed Classes, Pattern Matching, Text Blocks
+- [**JVM Memory Model**](jvm-memory-model.md) - Memory layout, Garbage Collection, Performance tuning
+
+## Quick Checks
+
+- [ ] Use records for DTOs and value objects
+- [ ] Use sealed classes for closed type hierarchies
+- [ ] Pattern matching over instanceof chains
+- [ ] Try-with-resources for all AutoCloseable
+- [ ] Objects.requireNonNull at method entry points
+- [ ] Optional for return types only, never parameters or fields

package/rules/java/java-core-language/references/jvm-memory-model.md

@@ -0,0 +1,160 @@
+# JVM Memory Model
+
+## Memory Layout
+
+```
++------------------+
+|   Method Area    |  <- Class metadata, static fields
++------------------+
+|       Heap       |  <- Objects, arrays
+|  +------------+  |
+|  |   Young    |  |  <- New objects (Eden + Survivor)
+|  +------------+  |
+|  |    Old     |  |  <- Long-lived objects
+|  +------------+  |
++------------------+
+|      Stack       |  <- Per-thread, local variables, method calls
++------------------+
+|   Native Stack   |  <- JNI calls
++------------------+
+```
+
+## Garbage Collection
+
+### GC Algorithms
+
+```java
+// G1GC (default since Java 9) - balanced latency/throughput
+// -XX:+UseG1GC
+// Good for: heap > 4GB, pause time < 200ms
+
+// ZGC (Java 15+) - ultra-low latency
+// -XX:+UseZGC
+// Good for: heap > 16GB, pause time < 10ms
+
+// Shenandoah (Java 15+) - low latency, Red Hat
+// -XX:+UseShenandoahGC
+
+// Parallel GC - high throughput
+// -XX:+UseParallelGC
+// Good for: batch processing, throughput > latency
+```
+
+### GC Tuning Parameters
+
+```bash
+# Heap sizing
+-Xms4g                    # Initial heap size
+-Xmx4g                    # Maximum heap size
+-XX:NewRatio=2            # Old/Young ratio (Old = 2x Young)
+
+# G1GC tuning
+-XX:MaxGCPauseMillis=200  # Target pause time
+-XX:G1HeapRegionSize=8m   # Region size (1-32MB)
+-XX:InitiatingHeapOccupancyPercent=45
+
+# ZGC tuning
+-XX:ZAllocationSpikeTolerance=2
+-XX:ZCollectionInterval=0  # Disable proactive GC
+
+# Logging
+-Xlog:gc*:file=gc.log:time,level,tags
+```
+
+## Memory Leak Prevention
+
+```java
+// 1. Close resources properly
+try (Connection conn = dataSource.getConnection();
+     PreparedStatement stmt = conn.prepareStatement(sql)) {
+    // use resources
+}
+
+// 2. Remove listeners when done
+public class MyComponent {
+    private final EventListener listener;
+
+    public void init() {
+        listener = event -> handle(event);
+        eventBus.register(listener);
+    }
+
+    public void destroy() {
+        eventBus.unregister(listener);  // Important!
+    }
+}
+
+// 3. Use WeakReference for caches
+Map<Key, WeakReference<Value>> cache = new WeakHashMap<>();
+
+// 4. Avoid static collections holding object references
+// BAD: static List<Object> cache = new ArrayList<>();
+// GOOD: Use proper caching library with eviction
+
+// 5. Be careful with inner classes
+// Non-static inner class holds reference to outer class
+class Outer {
+    // BAD: holds reference to Outer
+    class Inner {}
+
+    // GOOD: no reference to Outer
+    static class StaticInner {}
+}
+```
+
+## Profiling Tools
+
+```bash
+# JFR (Java Flight Recorder)
+java -XX:StartFlightRecording=duration=60s,filename=recording.jfr MyApp
+
+# Heap dump
+jmap -dump:format=b,file=heap.hprof <pid>
+
+# Thread dump
+jstack <pid> > threads.txt
+
+# Native Memory Tracking
+java -XX:NativeMemoryTracking=summary MyApp
+jcmd <pid> VM.native_memory summary
+```
+
+## Performance Best Practices
+
+```java
+// 1. Avoid creating unnecessary objects
+// BAD
+for (int i = 0; i < 1000; i++) {
+    String s = new String("constant");  // Creates 1000 objects
+}
+// GOOD
+String s = "constant";  // String pool, single object
+
+// 2. Use StringBuilder for concatenation in loops
+StringBuilder sb = new StringBuilder();
+for (String item : items) {
+    sb.append(item).append(",");
+}
+
+// 3. Size collections appropriately
+List<String> list = new ArrayList<>(expectedSize);
+Map<K, V> map = new HashMap<>(expectedSize, 0.75f);
+
+// 4. Use primitives over wrappers when possible
+// BAD: Long sum = 0L;
+// GOOD: long sum = 0L;
+
+// 5. Lazy initialization for expensive objects
+private volatile ExpensiveObject instance;
+
+public ExpensiveObject getInstance() {
+    if (instance == null) {
+        synchronized (this) {
+            if (instance == null) {
+                instance = new ExpensiveObject();
+            }
+        }
+    }
+    return instance;
+}
+```

package/rules/java/java-core-language/references/modern-java-features.md

@@ -0,0 +1,168 @@
+# Modern Java Features
+
+## Records (Java 16+)
+
+```java
+// Basic record
+public record Point(int x, int y) {}
+
+// Record with validation
+public record Email(String value) {
+    public Email {
+        if (!value.matches("^[\\w.-]+@[\\w.-]+\\.[a-z]{2,}$")) {
+            throw new IllegalArgumentException("Invalid email: " + value);
+        }
+    }
+}
+
+// Record with additional methods
+public record Range(int start, int end) {
+    public Range {
+        if (start > end) throw new IllegalArgumentException("start > end");
+    }
+
+    public int length() {
+        return end - start;
+    }
+
+    public boolean contains(int value) {
+        return value >= start && value <= end;
+    }
+}
+
+// Record implementing interface
+public record ImmutableUser(String id, String name) implements Identifiable {
+    @Override
+    public String getId() {
+        return id;
+    }
+}
+```
+
+## Sealed Classes (Java 17+)
+
+```java
+// Sealed interface with permits
+public sealed interface Result<T> permits Success, Failure {
+    T getOrThrow();
+}
+
+public record Success<T>(T value) implements Result<T> {
+    @Override
+    public T getOrThrow() {
+        return value;
+    }
+}
+
+public record Failure<T>(Exception error) implements Result<T> {
+    @Override
+    public T getOrThrow() {
+        throw new RuntimeException(error);
+    }
+}
+
+// Usage with pattern matching
+public <T> void handle(Result<T> result) {
+    switch (result) {
+        case Success<T>(var value) -> process(value);
+        case Failure<T>(var error) -> logError(error);
+    }
+}
+```
+
+## Pattern Matching
+
+```java
+// Pattern matching for instanceof (Java 16+)
+public String format(Object obj) {
+    if (obj instanceof String s) {
+        return "String: " + s;
+    } else if (obj instanceof Integer i) {
+        return "Integer: " + i;
+    } else if (obj instanceof List<?> list && !list.isEmpty()) {
+        return "Non-empty list of size: " + list.size();
+    }
+    return "Unknown: " + obj;
+}
+
+// Pattern matching for switch (Java 21+)
+public double area(Shape shape) {
+    return switch (shape) {
+        case Circle(var r) -> Math.PI * r * r;
+        case Rectangle(var w, var h) -> w * h;
+        case Triangle(var b, var h) -> 0.5 * b * h;
+        case null -> 0.0;
+    };
+}
+
+// Guarded patterns
+public String classify(Integer i) {
+    return switch (i) {
+        case Integer n when n < 0 -> "negative";
+        case Integer n when n == 0 -> "zero";
+        case Integer n when n > 0 && n < 10 -> "small positive";
+        case Integer n -> "large positive";
+    };
+}
+```
+
+## Text Blocks (Java 15+)
+
+```java
+// Multi-line strings
+String json = """
+    {
+        "name": "%s",
+        "email": "%s",
+        "roles": ["user", "admin"]
+    }
+    """.formatted(name, email);
+
+// SQL queries
+String query = """
+    SELECT u.id, u.name, u.email
+    FROM users u
+    JOIN roles r ON u.role_id = r.id
+    WHERE r.name = :roleName
+    ORDER BY u.created_at DESC
+    """;
+
+// HTML templates
+String html = """
+    <html>
+        <body>
+            <h1>Welcome, %s</h1>
+        </body>
+    </html>
+    """.formatted(username);
+```
+
+## Virtual Threads (Java 21+)
+
+```java
+// Create virtual thread
+Thread.startVirtualThread(() -> {
+    doBlockingOperation();
+});
+
+// Executor with virtual threads
+try (var executor = Executors.newVirtualThreadPerTaskExecutor()) {
+    List<Future<String>> futures = urls.stream()
+        .map(url -> executor.submit(() -> fetchUrl(url)))
+        .toList();
+
+    for (Future<String> future : futures) {
+        System.out.println(future.get());
+    }
+}
+
+// Structured concurrency (preview)
+try (var scope = new StructuredTaskScope.ShutdownOnFailure()) {
+    Subtask<User> user = scope.fork(() -> fetchUser(userId));
+    Subtask<List<Order>> orders = scope.fork(() -> fetchOrders(userId));
+
+    scope.join().throwIfFailed();
+
+    return new UserWithOrders(user.get(), orders.get());
+}
+```