Add comprehensive streaming support and enhanced error handling

Major improvements to the elearning module parser with focus on large file handling
and better error diagnostics:

STREAMING SUPPORT:
- Add StreamingProgressListener interface for progress tracking
- Implement StreamingUtils with buffering and progress reporting
- Enhance all FileAccess implementations (Local, ZIP, S3) with streaming support
- Add configurable buffer sizes and progress intervals
- Support both small file caching and large file streaming

ERROR MESSAGE ENHANCEMENTS:
- LocalFileAccess: Add full paths, file attributes, and root context
- ZipFileAccess: Add intelligent file suggestions and ZIP context
- S3FileAccessV2: Add bucket, key, and size information to all errors
- XML parsing: Include file paths and encoding information
- AICC parser: Add module context and file suggestions
- All error messages now provide actionable debugging information

SCORM 1.2 PREREQUISITES:
- Fix prerequisites parsing with @JacksonXmlText annotation
- Add comprehensive test coverage with complex prerequisite scenarios
- Extract item-level metadata including mastery scores and custom data

CMI5 ENHANCEMENTS:
- Complete metadata extraction for all AU attributes
- Add support for nested blocks and recursive AU extraction
- Include mastery scores, moveOn criteria, launch parameters
- Maintain backward compatibility with legacy fields

CHARACTER ENCODING:
- Add BOM detection and encoding-aware stream processing
- Support UTF-8, UTF-16, and other encodings automatically
- Enhance XML parsing with proper encoding handling

RESOURCE MANAGEMENT:
- Improve stream cleanup and resource management
- Add proper exception handling in cleanup paths
- Ensure all FileAccess implementations properly close resources

TESTS:
- Add comprehensive test coverage for all new features
- Create test modules for SCORM 1.2 prerequisites
- Verify enhanced error messages provide useful context
- All existing tests continue to pass

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>

Author: jcputney

src/main/java/dev/jcputney/elearning/parser/api/StreamingProgressListener.java

@@ -0,0 +1,41 @@
+/*
+ * Copyright (c) 2024-2025. Jonathan Putney
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Lesser General Public License as published by
+ * the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU Lesser General Public License for more details.
+ *
+ * You should have received a copy of the GNU Lesser General Public License
+ * along with this program.  If not, see <https://www.gnu.org/licenses/>.
+ */
+
+package dev.jcputney.elearning.parser.api;
+
+/**
+ * Interface for listening to streaming progress events.
+ * Implementations can use this to track the progress of streaming operations
+ * such as file downloads, uploads, or processing.
+ */
+public interface StreamingProgressListener {
+  
+  /**
+   * Called periodically during a streaming operation to report progress.
+   *
+   * @param bytesRead The number of bytes read so far
+   * @param totalSize The total size of the stream in bytes, or -1 if unknown
+   */
+  void onProgress(long bytesRead, long totalSize);
+  
+  /**
+   * Called when the streaming operation is complete.
+   *
+   * @param totalBytesRead The total number of bytes that were read
+   */
+  void onComplete(long totalBytesRead);
+}

src/main/java/dev/jcputney/elearning/parser/impl/LocalFileAccess.java

@@ -18,6 +18,8 @@
 package dev.jcputney.elearning.parser.impl;
 
 import dev.jcputney.elearning.parser.api.FileAccess;
+import dev.jcputney.elearning.parser.api.StreamingProgressListener;
+import dev.jcputney.elearning.parser.util.StreamingUtils;
 import java.io.IOException;
 import java.io.InputStream;
 import java.nio.file.Files;
@@ -57,7 +59,12 @@ public LocalFileAccess(String rootPath) {
     }
     this.rootPath = rootPath;
     if (!Files.isDirectory(Paths.get(rootPath))) {
-      throw new IllegalArgumentException("Provided path is not a valid directory: " + rootPath);
+      Path path = Paths.get(rootPath);
+      String context = Files.exists(path) ? 
+          (Files.isRegularFile(path) ? "path points to a file" : "path exists but is not a directory") :
+          "path does not exist";
+      throw new IllegalArgumentException(
+          "Invalid root directory for LocalFileAccess: '" + rootPath + "' (" + context + ")");
     }
   }
 
@@ -82,8 +89,14 @@ public List<String> listFilesInternal(String directoryPath) throws IOException {
     Path dirPath = Paths.get(fullPath(directoryPath));
 
     // Validate directory
-    if (!Files.exists(dirPath) || !Files.isDirectory(dirPath)) {
-      throw new IOException("Provided path is not a valid directory: " + directoryPath);
+    if (!Files.exists(dirPath)) {
+      throw new IOException("Directory not found: '" + directoryPath + "' (full path: '" + 
+          dirPath.toAbsolutePath() + "') in root '" + getRootPath() + "'");
+    }
+    if (!Files.isDirectory(dirPath)) {
+      String fileType = Files.isRegularFile(dirPath) ? "regular file" : "special file";
+      throw new IOException("Path is not a directory: '" + directoryPath + "' (is a " + fileType + 
+          ") in root '" + getRootPath() + "'");
     }
 
     try (Stream<Path> paths = Files.list(dirPath)) {
@@ -95,7 +108,9 @@ public List<String> listFilesInternal(String directoryPath) throws IOException {
           .map(Path::toString)
           .toList();
     } catch (IOException e) {
-      throw new IOException("Failed to list files in directory: " + directoryPath, e);
+      throw new IOException("Failed to list files in directory: '" + directoryPath + 
+          "' (full path: '" + dirPath.toAbsolutePath() + "') in root '" + getRootPath() + 
+          "': " + e.getMessage(), e);
     }
   }
 
@@ -108,16 +123,44 @@ public List<String> listFilesInternal(String directoryPath) throws IOException {
    */
   @Override
   public InputStream getFileContentsInternal(String path) throws IOException {
+    return getFileContentsInternal(path, null);
+  }
+
+  /**
+   * Gets the contents of a file as an InputStream with optional progress tracking.
+   *
+   * @param path The path of the file to read.
+   * @param progressListener Optional progress listener for tracking large file operations.
+   * @return An InputStream for reading the file contents.
+   * @throws IOException if an error occurs while reading the file.
+   */
+  public InputStream getFileContentsInternal(String path, StreamingProgressListener progressListener) throws IOException {
     Path filePath = Paths.get(fullPath(path));
 
     // Check file existence and read permissions
     if (!fileExistsInternal(path)) {
-      throw new NoSuchFileException("File not found: " + path);
+      throw new NoSuchFileException("File not found: '" + path + "' (full path: '" + 
+          filePath.toAbsolutePath() + "') in root '" + getRootPath() + "'");
     }
     if (!Files.isReadable(filePath)) {
-      throw new IOException("File is not readable: " + path);
+      String details = "";
+      try {
+        long size = Files.size(filePath);
+        boolean isDirectory = Files.isDirectory(filePath);
+        details = " (size: " + size + " bytes, type: " + (isDirectory ? "directory" : "file") + ")";
+      } catch (IOException ignored) {
+        details = " (unable to read file attributes)";
+      }
+      throw new IOException("File is not readable: '" + path + "' (full path: '" + 
+          filePath.toAbsolutePath() + "')" + details + " in root '" + getRootPath() + "'");
     }
 
-    return Files.newInputStream(filePath, StandardOpenOption.READ);
+    InputStream inputStream = Files.newInputStream(filePath, StandardOpenOption.READ);
+    
+    // Get file size for progress tracking
+    long fileSize = Files.size(filePath);
+    
+    // Apply streaming enhancements
+    return StreamingUtils.createEnhancedStream(inputStream, fileSize, progressListener);
   }
 }

src/main/java/dev/jcputney/elearning/parser/impl/S3FileAccessV2.java

@@ -18,6 +18,8 @@
 package dev.jcputney.elearning.parser.impl;
 
 import dev.jcputney.elearning.parser.api.FileAccess;
+import dev.jcputney.elearning.parser.api.StreamingProgressListener;
+import dev.jcputney.elearning.parser.util.StreamingUtils;
 import java.io.ByteArrayInputStream;
 import java.io.IOException;
 import java.io.InputStream;
@@ -214,6 +216,18 @@ public List<String> listFilesInternal(String directoryPath) throws IOException {
    */
   @Override
   public InputStream getFileContentsInternal(String path) throws IOException {
+    return getFileContentsInternal(path, null);
+  }
+
+  /**
+   * Gets the contents of a file as an InputStream with optional progress tracking.
+   *
+   * @param path The path of the file to get contents from (guaranteed to be non-null).
+   * @param progressListener Optional progress listener for tracking large file operations.
+   * @return An InputStream containing the file contents.
+   * @throws IOException If an error occurs while getting file contents.
+   */
+  public InputStream getFileContentsInternal(String path, StreamingProgressListener progressListener) throws IOException {
     // Check cache first for small files
     byte[] cachedContent = smallFileCache.get(path);
     if (cachedContent != null) {
@@ -248,20 +262,30 @@ public InputStream getFileContentsInternal(String path) throws IOException {
         }
 
         smallFileCache.put(path, content);
-        return new ByteArrayInputStream(content);
+        InputStream inputStream = new ByteArrayInputStream(content);
+        
+        // Apply streaming enhancements for progress tracking
+        return StreamingUtils.createEnhancedStream(inputStream, fileSize, progressListener);
       } catch (S3Exception e) {
-        throw new IOException("Failed to get file contents for path: " + path, e);
+        throw new IOException("Failed to get file contents from S3: '" + path + "' (bucket: '" + 
+            bucketName + "', key: '" + fullFilePath + "', size: " + fileSize + " bytes) - " + 
+            e.getMessage(), e);
       }
     } else {
       // Stream large files directly
       log.debug(LogMarkers.S3_VERBOSE, "Streaming large file: {} ({} bytes)", path, fileSize);
       try {
-        return s3Client.getObject(GetObjectRequest.builder()
+        InputStream inputStream = s3Client.getObject(GetObjectRequest.builder()
             .bucket(bucketName)
             .key(fullFilePath)
             .build());
+        
+        // Apply streaming enhancements for large files
+        return StreamingUtils.createEnhancedStream(inputStream, fileSize, progressListener);
       } catch (S3Exception e) {
-        throw new IOException("Failed to stream file contents for path: " + path, e);
+        throw new IOException("Failed to stream large file from S3: '" + path + "' (bucket: '" + 
+            bucketName + "', key: '" + fullFilePath + "', size: " + fileSize + " bytes) - " + 
+            e.getMessage(), e);
       }
     }
   }
@@ -324,7 +348,8 @@ private boolean checkFileExistsOnS3(String path) {
     } catch (NoSuchKeyException e) {
       return false;
     } catch (SdkException e) {
-      log.debug("Failed to check file existence for path: {}", path, e);
+      log.debug("Failed to check existence of file '{}' in S3 bucket '{}' with key '{}': {}", 
+          path, bucketName, fullPath(path), e.getMessage(), e);
       return false;
     }
   }
@@ -336,7 +361,8 @@ private long getFileSizeOnS3(String path) {
           .key(fullPath(path))
           .build()).contentLength();
     } catch (SdkException e) {
-      log.debug("Failed to get file size for path: {}", path, e);
+      log.debug("Failed to get size of file '{}' in S3 bucket '{}' with key '{}': {}", 
+          path, bucketName, fullPath(path), e.getMessage(), e);
       return 0;
     }
   }
@@ -368,7 +394,8 @@ private List<String> listFilesOnS3(String directoryPath) {
       log.debug(LogMarkers.S3_VERBOSE, "Listed {} files in directory: {}", allKeys.size(), directoryPath);
       return allKeys;
     } catch (SdkException e) {
-      log.debug("Failed to list files in directory: {}", directoryPath, e);
+      log.debug("Failed to list files in S3 directory '{}' (bucket: '{}', prefix: '{}'): {}", 
+          directoryPath, bucketName, fullPath(directoryPath), e.getMessage(), e);
       return List.of();
     }
   }
@@ -387,7 +414,8 @@ private String detectInternalRootDirectory(String rootPath) {
       }
       return commonPrefixes.get(0).prefix();
     } catch (SdkException e) {
-      log.debug("Failed to detect internal root directory", e);
+      log.debug("Failed to detect internal root directory in S3 bucket '{}' with prefix '{}': {}", 
+          bucketName, rootPath, e.getMessage(), e);
       return rootPath;
     }
   }

src/main/java/dev/jcputney/elearning/parser/impl/ZipFileAccess.java

@@ -18,6 +18,8 @@
 package dev.jcputney.elearning.parser.impl;
 
 import dev.jcputney.elearning.parser.api.FileAccess;
+import dev.jcputney.elearning.parser.api.StreamingProgressListener;
+import dev.jcputney.elearning.parser.util.StreamingUtils;
 import java.io.IOException;
 import java.io.InputStream;
 import java.util.ArrayList;
@@ -40,6 +42,7 @@ public class ZipFileAccess implements FileAccess, AutoCloseable {
   private final String rootPath;
 
   private final ZipFile zipFile;
+  private final String zipFilePath;
 
   /**
    * Constructs a new {@link ZipFileAccess} instance for the specified ZIP path.
@@ -48,7 +51,12 @@ public class ZipFileAccess implements FileAccess, AutoCloseable {
    * @throws IOException If the ZIP file can't be opened.
    */
   public ZipFileAccess(String zipFilePath) throws IOException {
-    this.zipFile = new ZipFile(zipFilePath);
+    this.zipFilePath = zipFilePath;
+    try {
+      this.zipFile = new ZipFile(zipFilePath);
+    } catch (IOException e) {
+      throw new IOException("Failed to open ZIP file: '" + zipFilePath + "' (" + e.getMessage() + ")", e);
+    }
     this.rootPath = getInternalRootDirectory();
   }
 
@@ -96,13 +104,35 @@ public List<String> listFilesInternal(String directoryPath) {
    */
   @Override
   public InputStream getFileContentsInternal(String path) throws IOException {
+    return getFileContentsInternal(path, null);
+  }
+
+  /**
+   * Retrieves the contents of a file within the ZIP archive as an InputStream with optional progress tracking.
+   *
+   * @param path The path to retrieve contents from (guaranteed to be non-null).
+   * @param progressListener Optional progress listener for tracking large file operations.
+   * @return An InputStream of the file contents.
+   * @throws IOException if the file can't be read.
+   */
+  public InputStream getFileContentsInternal(String path, StreamingProgressListener progressListener) throws IOException {
     ZipEntry entry = zipFile.getEntry(fullPath(path));
 
     if (entry == null) {
-      throw new IOException("File not found in ZIP archive: " + path);
+      // Provide helpful information about available files
+      String suggestion = getSimilarFiles(path);
+      throw new IOException("File not found in ZIP archive: '" + path + "' (full path: '" + 
+          fullPath(path) + "') in ZIP file '" + zipFilePath + "'" + 
+          (rootPath.isEmpty() ? "" : " with internal root '" + rootPath + "'") + suggestion);
     }
 
-    return zipFile.getInputStream(entry);
+    InputStream inputStream = zipFile.getInputStream(entry);
+    
+    // Get file size for progress tracking
+    long fileSize = entry.getSize();
+    
+    // Apply streaming enhancements
+    return StreamingUtils.createEnhancedStream(inputStream, fileSize, progressListener);
   }
 
   /**
@@ -111,7 +141,11 @@ public InputStream getFileContentsInternal(String path) throws IOException {
    * @throws IOException if an error occurs while closing the ZIP file.
    */
   public void close() throws IOException {
-    zipFile.close();
+    try {
+      zipFile.close();
+    } catch (IOException e) {
+      throw new IOException("Failed to close ZIP file: '" + zipFilePath + "' (" + e.getMessage() + ")", e);
+    }
   }
 
   /**
@@ -159,4 +193,45 @@ private String getInternalRootDirectory() {
         .iterator()
         .next() : "";
   }
+
+  /**
+   * Provides suggestions for similar files when a file is not found.
+   *
+   * @param targetPath The path that was not found.
+   * @return A string with suggestions or empty string if no suggestions available.
+   */
+  private String getSimilarFiles(String targetPath) {
+    List<String> allFiles = new ArrayList<>();
+    Enumeration<? extends ZipEntry> entries = zipFile.entries();
+    
+    while (entries.hasMoreElements()) {
+      ZipEntry entry = entries.nextElement();
+      if (!entry.isDirectory()) {
+        allFiles.add(entry.getName());
+      }
+    }
+    
+    if (allFiles.isEmpty()) {
+      return ". ZIP archive appears to be empty or contains only directories.";
+    }
+    
+    // Find files with similar names or in same directory
+    String targetName = targetPath.contains("/") ? 
+        targetPath.substring(targetPath.lastIndexOf("/") + 1) : targetPath;
+    String targetDir = targetPath.contains("/") ? 
+        targetPath.substring(0, targetPath.lastIndexOf("/")) : "";
+    
+    List<String> suggestions = allFiles.stream()
+        .filter(file -> file.toLowerCase().contains(targetName.toLowerCase()) ||
+                       (targetDir.isEmpty() || file.startsWith(targetDir)))
+        .limit(3)
+        .toList();
+    
+    if (!suggestions.isEmpty()) {
+      return ". Similar files: " + String.join(", ", suggestions);
+    } else {
+      return ". Available files: " + allFiles.stream().limit(5).reduce((a, b) -> a + ", " + b).orElse("none") +
+             (allFiles.size() > 5 ? " (and " + (allFiles.size() - 5) + " more)" : "");
+    }
+  }
 }

src/main/java/dev/jcputney/elearning/parser/input/scorm12/adl/Scorm12Prerequisites.java

@@ -22,6 +22,7 @@
 import com.fasterxml.jackson.annotation.JsonFormat;
 import com.fasterxml.jackson.annotation.JsonProperty;
 import com.fasterxml.jackson.dataformat.xml.annotation.JacksonXmlProperty;
+import com.fasterxml.jackson.dataformat.xml.annotation.JacksonXmlText;
 import java.io.Serializable;
 import lombok.AllArgsConstructor;
 import lombok.Builder;
@@ -46,7 +47,7 @@ public class Scorm12Prerequisites implements Serializable {
   /**
    * The string content of the "prerequisites" element.
    */
-  @JacksonXmlProperty(localName = "value")
+  @JacksonXmlText
   private String value;
   /**
    * The type attribute of the prerequisites element, which is optional. Example value: