Class BoundedBundleIO

java.lang.Object

org.j7m.middleware.application.internal.BoundedBundleIO

public final class BoundedBundleIO
extends Object

Internal bounded I/O utility for the application-platform repository and deployment implementation.

The type is intentionally located in a non-exported package. Public application code must use J7mBundleReader, J7mBundleWriter, and ApplicationBundleVerifier instead.

Method Summary

Modifier and Type	Method	Description
static long	checkedAdd(long left, long right, String message)	Adds two non-negative counters with overflow detection.
static long	copy(InputStream input, OutputStream output, long maxBytes, int bufferBytes, MessageDigest digest)	Copies a stream with a fixed caller-provided maximum byte count.
static org.j7m.middleware.api.MiddlewareException	failure(String message)	Creates a safe public invalid-argument middleware exception.
static void	forceDirectory(Path directory)	Forces a directory entry when the file system supports directory channels.
static void	forceFile(Path path)	Forces file data and metadata when the file system supports it.
static String	hex(byte[] bytes)	Encodes bytes as lowercase hexadecimal text.
static String	normalizeEntryName(String name, boolean directory, ApplicationPlatformLimits limits)	Validates and normalizes a bundle entry name.
static byte[]	readEntryBytes(ZipFile zip, ZipEntry entry, long maxBytes, ApplicationPlatformLimits limits)	Reads a bounded ZIP entry into a newly allocated byte array.
static String	readEntryString(ZipFile zip, ZipEntry entry, long maxBytes, ApplicationPlatformLimits limits)	Reads a bounded ZIP entry as UTF-8 text.
static String	sha256(Path path, ApplicationPlatformLimits limits)	Computes the SHA-256 digest of a bounded application bundle file.
static String	sha256(ZipFile zip, ZipEntry entry, ApplicationPlatformLimits limits)	Computes the SHA-256 digest of a bounded ZIP entry.
static void	validateBundleFile(Path path, ApplicationPlatformLimits limits)	Validates that a bundle path names a regular file within the configured artifact byte limit.
static List<ZipEntry>	validatedEntries(ZipFile zip, ApplicationPlatformLimits limits)	Returns validated ZIP entries in deterministic name order.
static void	writeSmallFileAtomically(Path target, byte[] bytes)	Writes a small metadata file through a same-directory temporary file and replacement.
static void	writeSmallFileAtomically(Path target, String text, long maxBytes)	Writes a bounded UTF-8 metadata file through a same-directory temporary file and replacement.

Methods inherited from class Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Details

validateBundleFile

public static void validateBundleFile(Path path,
 ApplicationPlatformLimits limits)
                               throws IOException

Validates that a bundle path names a regular file within the configured artifact byte limit.

Parameters:

path - bundle path to validate

limits - active platform limits

Throws:

IOException - if the file metadata cannot be read

org.j7m.middleware.api.MiddlewareException - if the file is missing, not regular, or too large

validatedEntries

public static List<ZipEntry> validatedEntries(ZipFile zip,
 ApplicationPlatformLimits limits)

Returns validated ZIP entries in deterministic name order.

Parameters:

zip - open ZIP file owned by the caller

limits - active platform limits

Returns:

validated entries sorted by raw ZIP name

Throws:

org.j7m.middleware.api.MiddlewareException - if names, counts, sizes, duplicates, or compression ratios violate the configured limits

readEntryString

public static String readEntryString(ZipFile zip,
 ZipEntry entry,
 long maxBytes,
 ApplicationPlatformLimits limits)
                              throws IOException

Reads a bounded ZIP entry as UTF-8 text.

The caller retains ownership of the supplied ZipFile. The method reads at most maxBytes expanded bytes, also honoring the active per-entry expansion limit, and decodes the resulting byte sequence with StandardCharsets.UTF_8. The returned string is newly allocated and does not retain references to the ZIP entry buffer.

Parameters:

zip - open ZIP file owned and closed by the caller

entry - entry to read from zip

maxBytes - maximum expanded bytes accepted for this read

limits - active platform limits that bound entry expansion and I/O buffer size

Returns:

decoded UTF-8 entry contents

Throws:

IOException - if ZIP input cannot be opened or read

org.j7m.middleware.api.MiddlewareException - if the declared or observed expanded entry size exceeds the configured limit

readEntryBytes

public static byte[] readEntryBytes(ZipFile zip,
 ZipEntry entry,
 long maxBytes,
 ApplicationPlatformLimits limits)
                             throws IOException

Reads a bounded ZIP entry into a newly allocated byte array.

The caller retains ownership of the supplied ZipFile. The method rejects entries whose declared size exceeds maxBytes or the active platform limit and also enforces the same bound while reading, protecting callers from missing or dishonest ZIP size metadata. This helper is intended for small bundle metadata, not application artifacts.

Parameters:

zip - open ZIP file owned and closed by the caller

entry - entry to read from zip

maxBytes - maximum expanded bytes accepted for this read

limits - active platform limits that bound entry expansion and I/O buffer size

Returns:

newly allocated entry bytes

Throws:

IOException - if ZIP input cannot be opened or read

org.j7m.middleware.api.MiddlewareException - if the declared or observed expanded entry size exceeds the configured limit

sha256

public static String sha256(Path path,
 ApplicationPlatformLimits limits)

Computes the SHA-256 digest of a bounded application bundle file.

The method validates that path names a regular file within the configured bundle-size limit before reading it. The file is streamed through a fixed-size buffer from limits; the full bundle is never materialized in memory. The returned value is lowercase hexadecimal and contains no path or file-system details.

Parameters:

path - application bundle path to digest

limits - active platform limits that bound file size and I/O buffer size

Returns:

lowercase hexadecimal SHA-256 digest

Throws:

org.j7m.middleware.api.MiddlewareException - if the path is invalid, the file exceeds the configured limit, file I/O fails, or the SHA-256 algorithm is unavailable

sha256

public static String sha256(ZipFile zip,
 ZipEntry entry,
 ApplicationPlatformLimits limits)

Computes the SHA-256 digest of a bounded ZIP entry.

The caller retains ownership of the supplied ZipFile. The entry is streamed through a fixed-size buffer from limits; the expanded entry is never materialized in memory. The read is bounded by the configured maximum expanded entry size and returns lowercase hexadecimal digest text suitable for deterministic bundle metadata.

Parameters:

zip - open ZIP file owned and closed by the caller

entry - entry to digest from zip

limits - active platform limits that bound entry expansion and I/O buffer size

Returns:

lowercase hexadecimal SHA-256 digest

Throws:

org.j7m.middleware.api.MiddlewareException - if ZIP input fails, the expanded entry exceeds the configured limit, or the SHA-256 algorithm is unavailable

copy

public static long copy(InputStream input,
 OutputStream output,
 long maxBytes,
 int bufferBytes,
 MessageDigest digest)
                 throws IOException

Copies a stream with a fixed caller-provided maximum byte count.

The method allocates one buffer of bufferBytes, updates the optional digest with copied bytes, preserves interruption by throwing IOException, and never closes either stream.

Parameters:

input - source stream

output - destination stream

maxBytes - maximum bytes to copy

bufferBytes - buffer size

digest - optional digest to update, or null

Returns:

bytes copied

Throws:

IOException - if stream I/O fails, the current thread is interrupted, or the configured maximum is exceeded

normalizeEntryName

public static String normalizeEntryName(String name,
 boolean directory,
 ApplicationPlatformLimits limits)

Validates and normalizes a bundle entry name.

Parameters:

name - raw ZIP entry name

directory - whether the entry is a directory

limits - active platform limits

Returns:

normalized slash-separated entry name

Throws:

org.j7m.middleware.api.MiddlewareException - if the name is absolute, contains traversal, Windows drive or UNC syntax, NUL/control characters, empty segments, or exceeds configured length/depth limits

checkedAdd

public static long checkedAdd(long left,
 long right,
 String message)

Adds two non-negative counters with overflow detection.

Parameters:

left - left operand

right - right operand

message - safe public failure message

Returns:

sum

Throws:

org.j7m.middleware.api.MiddlewareException - if the addition would overflow or right is negative

writeSmallFileAtomically

public static void writeSmallFileAtomically(Path target,
 String text,
 long maxBytes)
                                     throws IOException

Writes a bounded UTF-8 metadata file through a same-directory temporary file and replacement.

The temporary file is forced before publication. The target directory is forced after replacement when the underlying file system supports directory channels. If atomic replacement is not supported, the method falls back to a regular replacement while preserving the same validation and force ordering.

Parameters:

target - target metadata path

text - UTF-8 text to publish

maxBytes - maximum encoded bytes

Throws:

IOException - if the write, force, replace, or cleanup operation fails

org.j7m.middleware.api.MiddlewareException - if the encoded text exceeds maxBytes

writeSmallFileAtomically

public static void writeSmallFileAtomically(Path target,
 byte[] bytes)
                                     throws IOException

Writes a small metadata file through a same-directory temporary file and replacement.

Parameters:

target - target metadata path

bytes - bytes to publish

Throws:

IOException - if the write, force, replace, or cleanup operation fails

forceFile

public static void forceFile(Path path)
                      throws IOException

Forces file data and metadata when the file system supports it.

Parameters:

path - regular file to force

Throws:

IOException - if forcing fails

forceDirectory

public static void forceDirectory(Path directory)

Forces a directory entry when the file system supports directory channels. Unsupported platforms are treated as a documented best-effort limitation.

Parameters:

directory - directory to force

hex

public static String hex(byte[] bytes)

Encodes bytes as lowercase hexadecimal text.

The method performs a deterministic two-character encoding for each input byte and allocates only the output character array and result string. The input array is read-only from this method's perspective and is not retained.

Parameters:

bytes - bytes to encode

Returns:

lowercase hexadecimal representation of bytes

Throws:

NullPointerException - if bytes is null

failure

public static org.j7m.middleware.api.MiddlewareException failure(String message)

Creates a safe public invalid-argument middleware exception.

Parameters:

message - safe public message that must not include caller payloads

Returns:

middleware exception