v0.14.0

Release Notes

Features

Checked DataReadException for I/O read failures

DataReader now surfaces read failures through a checked DataReadException instead of silently returning null. Callers can finally tell a missing record apart from a genuine I/O error, and Vortex's batch tools report read failures as ERROR events rather than dropping them.

What's new

• mil.army.usace.hec.vortex.io.DataReadException — a checked exception (extends java.io.IOException) thrown when a DataReader fails to read a record from its underlying source: non-zero DSS status, JNI/native failure, an undecodable record, or an unopenable dataset. It carries diagnostic context without leaking the underlying provider's API:
  • a coarse Kind — MISSING_RECORD, UNSUPPORTED, or IO_ERROR — for control-flow decisions,
  • the raw native status code,
  • the data-source path, and
  • the record-level pathname, when applicable.
• DataReadExceptions — utility class whose reportTo(Logger, PropertyChangeSupport, DataReadException) performs the standard batch-boundary handling: log at SEVERE and fire a VortexProperty.ERROR event.

API changes

• These DataReader methods now declare throws DataReadException: getDtos(), getDto(int), getDataIntervals(), DataReaderBuilder.build(), and DataReader.copy(DataReader). Previously they silently returned null (or an empty/partial result) on failure.
• getDto(int) now throws IndexOutOfBoundsException for an out-of-range index (a programmer error), distinct from DataReadException for a real read failure.
• Bulk reads: getDtos() still skips MISSING_RECORD / UNSUPPORTED records (now logged at FINE), preserving the prior "absence is legitimate" behavior — but a genuine IO_ERROR now aborts the read instead of being silently dropped. Readers do not return a partial result on failure.

Migration

• DataReadException extends IOException, so callers that already declare throws IOException or catch (IOException ...) compile unchanged.
• Callers that previously checked for null from getDto(int), or filtered nulls out of getDtos(), should instead let the exception propagate, or catch DataReadException and branch on getKind() (e.g. skip MISSING_RECORD, abort on IO_ERROR).
• Switches on Kind should include a default case — new values may be added in future releases.
• Vortex's own batch tools (importers, exporter, subsetter, transposer, sanitizer, calculators, normalizer, grid-to-point converter) already route failures through DataReadExceptions.reportTo, surfacing them as ERROR property-change events instead of failing silently.

Bug Fixes

None in this release.