doc/JAVA_INSTALL_GUIDE.md

# Java 11+ Installation Guide for JAOPuTo Tool

**Required for**: JAO FBMC data collection via JAOPuTo tool

---

## Quick Install (Windows)

### Option 1: Adoptium Eclipse Temurin (Recommended)

1. **Download Java 17 (LTS)**:
   - Visit: https://adoptium.net/temurin/releases/
   - Select:
     - **Operating System**: Windows
     - **Architecture**: x64
     - **Package Type**: JDK
     - **Version**: 17 (LTS)
   - Download: `.msi` installer

2. **Install**:
   - Run the downloaded `.msi` file
   - Accept defaults (includes adding to PATH)
   - Click "Install"

3. **Verify**:
   ```bash
   java -version
   ```
   Should output: `openjdk version "17.0.x"`

---

### Option 2: Chocolatey (If Installed)

```bash
choco install temurin17
```

Then verify:
```bash
java -version
```

---

### Option 3: Manual Download (Alternative)

If Adoptium doesn't work:

1. **Oracle JDK** (Requires Oracle account):
   - https://www.oracle.com/java/technologies/downloads/#java17

2. **Amazon Corretto**:
   - https://aws.amazon.com/corretto/

---

## Post-Installation

### 1. Verify Java Installation

Open **Git Bash** or **Command Prompt** and run:

```bash
java -version
```

**Expected output**:
```
openjdk version "17.0.10" 2024-01-16
OpenJDK Runtime Environment Temurin-17.0.10+7 (build 17.0.10+7)
OpenJDK 64-Bit Server VM Temurin-17.0.10+7 (build 17.0.10+7, mixed mode, sharing)
```

### 2. Verify JAVA_HOME (Optional but Recommended)

```bash
echo $JAVA_HOME  # Git Bash
echo %JAVA_HOME%  # Command Prompt
```

If not set, add to environment variables:
- Path: `C:\Program Files\Eclipse Adoptium\jdk-17.0.10.7-hotspot\`
- Variable: `JAVA_HOME`

### 3. Test JAOPuTo

Download JAOPuTo.jar (see next section), then test:

```bash
java -jar tools/JAOPuTo.jar --help
```

Should display help information without errors.

---

## Download JAOPuTo Tool

### Official Download

1. **Visit**: https://publicationtool.jao.eu/core/
2. **Look for**: Download section or "JAOPuTo" link
3. **Save to**: `C:\Users\evgue\projects\fbmc_chronos2\tools\JAOPuTo.jar`

### Alternative Sources

If official site is unclear:

1. **JAO Support**:
   - Email: [email protected]
   - Subject: "JAOPuTo Tool Download Request"
   - Request: Latest JAOPuTo.jar for FBMC data download

2. **Check Documentation**:
   - https://www.jao.eu/core-fbmc
   - Look for API or data download tools

---

## Troubleshooting

### Issue: "java: command not found"

**Solution 1**: Restart Git Bash/terminal after installation

**Solution 2**: Manually add Java to PATH
- Open: System Properties → Environment Variables
- Edit: PATH
- Add: `C:\Program Files\Eclipse Adoptium\jdk-17.0.10.7-hotspot\bin`
- Restart terminal

### Issue: "JAR file not found"

**Check**:
```bash
ls -la tools/JAOPuTo.jar
```

**Solution**: Ensure JAOPuTo.jar is in `tools/` directory

### Issue: "Unsupported Java version"

JAOPuTo requires Java **11 or higher**.

Check version:
```bash
java -version
```

If you have Java 8 or older, install Java 17 (LTS).

### Issue: Multiple Java Versions

If you have multiple Java installations:

1. Check current version:
   ```bash
   java -version
   ```

2. List all installations:
   ```bash
   where java  # Windows
   ```

3. Set specific version:
   - Update PATH to prioritize Java 17
   - Or use full path: `"C:\Program Files\Eclipse Adoptium\...\bin\java.exe"`

---

## Next Steps After Java Installation

Once Java is installed and verified:

1. **Download JAOPuTo.jar**:
   - Save to: `tools/JAOPuTo.jar`

2. **Test JAO collection**:
   ```bash
   python src/data_collection/collect_jao.py --manual-instructions
   ```

3. **Begin Day 1 data collection**:
   ```bash
   # OpenMeteo (5 minutes)
   python src/data_collection/collect_openmeteo.py

   # ENTSO-E (longer, depends on data volume)
   python src/data_collection/collect_entsoe.py

   # JAO FBMC data
   python src/data_collection/collect_jao.py
   ```

---

## Quick Reference

| Item | Value |
|------|-------|
| **Recommended Version** | Java 17 (LTS) |
| **Minimum Version** | Java 11 |
| **Download** | https://adoptium.net/temurin/releases/ |
| **JAOPuTo Tool** | https://publicationtool.jao.eu/core/ |
| **Support** | [email protected] |
| **Verify Command** | `java -version` |

---

**Document Version**: 1.0
**Last Updated**: 2025-10-27
**Project**: FBMC Flow Forecasting MVP