# Java SDK Validation Guide

This document provides instructions for validating the Java MCA SDK implementation once Java and Maven are installed.

## Prerequisites

Before validating the Java SDK, ensure the following are installed:

1. **Java Development Kit (JDK) 11 or higher**
   ```bash
   java -version
   # Should output: openjdk version "11.0.x" or higher
   ```

2. **Apache Maven 3.6 or higher**
   ```bash
   mvn -version
   # Should output: Apache Maven 3.x.x
   ```

3. **OpenTelemetry Collector** (for integration tests)
   ```bash
   docker run -d -p 4318:4318 otel/opentelemetry-collector:latest
   ```

## Installation Instructions

### macOS

```bash
# Install Java 11
brew install openjdk@11

# Install Maven
brew install maven
```

### Ubuntu/Debian Linux

```bash
# Install Java 11
sudo apt update
sudo apt install openjdk-11-jdk

# Install Maven
sudo apt install maven
```

### Red Hat/CentOS/Amazon Linux

```bash
# Install Java 11
sudo yum install java-11-openjdk-devel

# Install Maven
sudo yum install maven
```

### Windows

1. Download and install [OpenJDK 11](https://adoptium.net/)
2. Download and install [Apache Maven](https://maven.apache.org/download.cgi)
3. Add both to your PATH environment variable

## Validation Steps

Once Java and Maven are installed, run the following commands from the `mca-sdk-java` directory:

### Step 1: Compile the Project

```bash
cd mca-sdk-java
mvn clean compile
```

**Expected Output:**
```
[INFO] BUILD SUCCESS
```

### Step 2: Run Unit Tests

```bash
mvn clean test
```

**Expected Output:**
```
[INFO] -------------------------------------------------------
[INFO]  T E S T S
[INFO] -------------------------------------------------------
[INFO] Running com.bhsf.mca.sdk.MCAClientTest
[INFO] Tests run: 14, Failures: 0, Errors: 0, Skipped: 0
[INFO] Running com.bhsf.mca.sdk.RecordPredictionTest
[INFO] Tests run: 15, Failures: 0, Errors: 0, Skipped: 0
[INFO]
[INFO] Results:
[INFO]
[INFO] Tests run: 29, Failures: 0, Errors: 0, Skipped: 0
[INFO]
[INFO] BUILD SUCCESS
```

### Step 3: Generate Test Coverage Report

```bash
mvn clean test jacoco:report
```

**Expected Output:**
```
[INFO] BUILD SUCCESS
```

View the coverage report:
```bash
open target/site/jacoco/index.html  # macOS
xdg-open target/site/jacoco/index.html  # Linux
```

**Expected Coverage:** ≥85% line coverage

### Step 4: Run Integration Tests (Optional)

Start the OpenTelemetry Collector:
```bash
docker run -d --name otel-collector -p 4318:4318 otel/opentelemetry-collector:latest
```

Run the example:
```bash
mvn compile exec:java -Dexec.mainClass="examples.InternalModelExample"
```

**Expected Output:**
```
Starting Internal ML Model Example...
MCAClient initialized successfully
Prediction 0: HIGH_RISK (latency: 0.123s)
Prediction 1: LOW_RISK (latency: 0.089s)
...
All predictions recorded. Shutting down...
Example completed successfully
```

Verify telemetry in collector logs:
```bash
docker logs otel-collector | grep "model.predictions.total"
```

### Step 5: Build JAR Package

```bash
mvn clean package
```

**Expected Output:**
```
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------
[INFO] Final Memory: 45M/512M
[INFO] ------------------------------------------------------------------------
```

The built JAR will be at: `target/mca-sdk-java-0.1.0.jar`

## Troubleshooting

### Compilation Errors

If you see compilation errors related to missing dependencies:

1. Check your internet connection (Maven needs to download dependencies)
2. Clear Maven cache and retry:
   ```bash
   rm -rf ~/.m2/repository/io/opentelemetry
   mvn clean compile
   ```

### Test Failures

If tests fail:

1. Check that no other process is using port 4318
2. Verify Java version is 11 or higher
3. Review test output for specific errors:
   ```bash
   mvn test -X  # Run with debug output
   ```

### Coverage Below 85%

If coverage is below the 85% threshold:

1. Check which classes have low coverage:
   ```bash
   open target/site/jacoco/index.html
   ```

2. Review the jacoco report and identify untested code paths

## Success Criteria

✅ All compilation successful
✅ All 29 tests pass
✅ Test coverage ≥85%
✅ No compiler warnings
✅ Example runs and produces telemetry

## Next Steps After Validation

Once validation is complete:

1. **Update Story Status:** Change from "blocked" to "review"
2. **Update Sprint Status:** Mark story as "review" in sprint-status.yaml
3. **Code Review:** Request code review from another developer
4. **Documentation:** Update main README with Java SDK instructions
5. **CI/CD Integration:** Add Java SDK to GitLab CI pipeline

## Docker-based Validation (Alternative)

If you cannot install Java/Maven locally, use Docker:

```bash
cd mca-sdk-java

# Build and test in Docker container
docker run --rm -v "$(pwd)":/app -w /app maven:3.9-openjdk-11 mvn clean test

# View coverage report
docker run --rm -v "$(pwd)":/app -w /app maven:3.9-openjdk-11 mvn jacoco:report
```

## Contact

For issues or questions about validation:
- Story Owner: As referenced in story file
- Dev Team: Clinical AI team at BHSF
