Package com.ganteater.ae.util

package com.ganteater.ae.util
Utility types and small helpers used across the application that deliberately minimize external dependencies and runtime state.

This package groups thin, well-documented components intended to be reused by higher-level modules. The classes here favor clarity and small, focused responsibilities: resource resolution and loading, lightweight reflection and SPI discovery, simple text and masking utilities, small compatibility adapters, and minimal test/assert helpers that do not bring a full test framework into runtime code.

Design goals

  • Low dependencies: types avoid pulling heavy libraries into callers unless required.
  • Small surface area: each class performs a narrowly scoped task and documents failure modes and expected inputs/outputs.
  • Runtime safety: utilities are defensive about nulls, I/O errors, and common platform differences (classpath vs. filesystem vs. jar URLs).

Primary responsibilities and notable types

  • Resource loading - AEUtils provides helpers to open resources from the filesystem, classpath, or jar:file:... locations and to read them into strings or streams. - Methods signal I/O problems with IOException and prefer explicit return/exception semantics over hidden behavior.
  • Text conveniences - AEUtils also exposes formatting helpers (e.g. best-effort JSON pretty printing), masking utilities (email masking), and small string normalization functions. - These helpers are intended for logging and lightweight presentation only.
  • SPI discovery and reflection helpers - ClassUtils wraps ServiceLoader and common reflection patterns to find implementations or load classes by name in a predictable way across classloader boundaries.
  • Encryption - Encryptor offers a minimal symmetric encryption/decryption API; callers are responsible for key management. Implementations may rely on Jasypt or the JCE depending on platform availability.
  • Path/file filtering - RegexPathFilter provides a regex-backed predicate for file traversals and can be plugged into Apache Commons IO walkers or custom traversal logic.
  • Assertion and test helpers - Small runtime assertions (TestCase, AssertionFailedError) are included for sanity checks outside of unit-test frameworks. They throw runtime exceptions rather than depend on JUnit APIs.
  • Compatibility adapters - Lightweight implementations of common interfaces (for example, a NameValuePair implementation compatible with NameValuePair) are provided where copying or shading a larger dependency would be undesirable.

Usage examples

Load a resource relative to a base directory (this supports classpath, filesystem, and jar:file: locations):

 String xml = AEUtils.loadResource("config.xml", new java.io.File("/opt/app"), null);

Discover SPI implementations registered via ServiceLoader:

 java.util.List<Class<?>> implementations = ClassUtils.findAssignable(MySpi.class);

Thread-safety and exception behavior

Most types in this package are stateless and therefore safe for concurrent use. When state is required (for example, an Encryptor instance that holds a key or configuration), the Javadoc for the specific type documents whether instances are thread-safe.

Methods that perform I/O explicitly declare IOException. Other runtime error conditions typically throw unchecked exceptions with clear messages; callers should catch and translate these where appropriate.