git:20260313.be9b40b to git:20260330.4638ea0

---

name: neqsim-java8-rules

description: "Java 8 compatibility rules for NeqSim. USE WHEN: writing or reviewing any Java code for NeqSim, including tests. Covers forbidden Java 9+ features, replacement patterns, API verification, and JavaDoc requirements. All NeqSim Java code MUST compile with Java 8."

---

# Java 8 Compatibility Rules for NeqSim

All NeqSim Java code — including test classes in `src/test/java/` — **MUST** compile with Java 8. The CI build will FAIL if you use Java 9+ features.

## Forbidden Java 9+ Features

| Forbidden | Java 8 Alternative |

|-----------|-------------------|

| `var x = ...` | Explicit type: `String x = ...`, `Map<String, Object> map = ...` |

| `List.of(a, b)` | `Arrays.asList(a, b)` or `Collections.singletonList(a)` |

| `Set.of(a, b)` | `new HashSet<>(Arrays.asList(a, b))` |

| `Map.of(k, v)` | `Collections.singletonMap(k, v)` or `new HashMap<>()` |

| `"str".repeat(n)` | `StringUtils.repeat("str", n)` (Apache Commons) |

| `str.isBlank()` | `str.trim().isEmpty()` |

| `str.strip()` | `str.trim()` |

| `str.lines()` | `str.split("\\R")` or BufferedReader |

| `Optional.isEmpty()` | `!optional.isPresent()` |

| Text blocks `"""..."""` | Regular strings with `\n` |

| Records | Regular class with fields, constructor, getters |

| Pattern matching `instanceof` | Traditional `instanceof` + cast |

| `Stream.toList()` | `.collect(Collectors.toList())` |

## Common `var` Replacements

```java

// WRONG (Java 10+):

var map = someMethod.toMap();

var list = getItems();

var result = calculate();

// CORRECT (Java 8):

Map<String, Object> map = someMethod.toMap();

List<String> list = getItems();

CalculationResult result = calculate();

```

## Required Import for String Repeat

```java

import org.apache.commons.lang3.StringUtils;

// Usage: StringUtils.repeat("=", 70)

```

## API Verification (MANDATORY)

Before using any NeqSim class in code or examples:

1. **Search** for the class: `file_search("**/ClassName.java")`

2. **Read** constructor and method signatures from the actual source

3. **Use only methods that actually exist** with correct parameter types

4. Do NOT assume convenience overloads — check first

Common API mistakes:

- Assuming `getXxx95()` when actual is `getXxx(int percentile)`

- Assuming 1-arg constructors when 2+ args are required

- Calling methods on wrong class

- Assuming `calculate()` when actual is `calculateRisk()` or `run()`

## JavaDoc Requirements

All classes and methods (public, protected, AND private) require complete JavaDoc:

- Class-level: description, `@author`, `@version`

- Method-level: description, `@param` for every parameter, `@return` for non-void, `@throws` for each exception

- HTML5 compatible: use `<caption>` in tables (no `summary` attribute)

- No `@see` with plain text — only valid Java references

- No lambda arrows (`->`) in JavaDoc code examples

## Build Commands

```bash

./mvnw install # full build

./mvnw test -Dtest=ClassName # single test class

./mvnw test -Dtest=ClassName#methodName # single method

./mvnw checkstyle:check spotbugs:check pmd:check # static analysis

./mvnw javadoc:javadoc # verify JavaDoc

```