de.ipcon.db.castor

Class CastorPersistenceQueryResults

java.lang.Object

de.ipcon.db.castor.CastorPersistenceQueryResults

All Implemented Interfaces:

de.ipcon.db.core.QueryResultsI, java.io.Closeable, java.lang.AutoCloseable, java.util.Iterator

Direct Known Subclasses:

AsyncCastorPersistenceQueryResults

public class CastorPersistenceQueryResults
extends java.lang.Object
implements de.ipcon.db.core.QueryResultsI

The central query result implementation for the MyTISM framework utilizing the Castor JDO provider.

This class acts as a bridge between the native PersistenceHandlerI (Castor) and the high-level QueryResultsI interface. It supports both legacy SQL calls and modern, compiled OQL queries.

Key Features:

• Server-side Filtering: Integrates with the OQL compiler to apply Predicate filtering during iteration, minimizing the number of Business Objects (BOs) that reach the application layer.
• Memory Optimization: Automatically "slims" (untangles) unmatching or previously processed BOs in read-only mode to reduce memory pressure on the Garbage Collector.
• Prefetching: Supports eager loading of relation paths via prefetchPaths to avoid N+1 select issues in lazy-loading scenarios.

Throughput Optimizations (Java 8):

• Method Splitting: Heavy logging and exception logic moved to cold-path helpers to encourage JIT inlining.
• Eager Slimming: Read-only BOs are untangled before the next fetch to maintain a flat memory footprint.
• Zero-Allocation Guards: String concatenation for diagnostics is strictly deferred.

See Also:

OQLQuery, QueryResults

Constructor Summary

Constructors

Constructor and Description
CastorPersistenceQueryResults(CastorPersistenceHandler _ph, java.lang.String _query, java.lang.Object[] _parms, short _mode, java.lang.String[] _prefetchPaths) Initializes the result set and triggers the query lifecycle.

Method Summary

Modifier and Type	Method and Description
void	cancel() Attempts to cancel the currently running database query, if supported by the underlying driver and Castor implementation
void	close() Closes the underlying result set and the query implementation.
java.lang.String	currentTag()
boolean	hasNext() Determines if a subsequent record is available, respecting any filterPredicate applied during OQL compilation.
boolean	isClosed()
java.lang.Object	next() Throughput Optimization: Memory Management: For read-only transactions, the previous BO is aggressively slimmed before fetching the next to prevent Heap bloat.
void	remove() Modification via iterator is not supported in Castor OQL results.

Methods inherited from class java.lang.Object

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

Methods inherited from interface de.ipcon.db.core.QueryResultsI

spliterator, stream

Methods inherited from interface java.util.Iterator

forEachRemaining

Constructor Detail

CastorPersistenceQueryResults

public CastorPersistenceQueryResults(CastorPersistenceHandler _ph,
                                     java.lang.String _query,
                                     java.lang.Object[] _parms,
                                     short _mode,
                                     java.lang.String[] _prefetchPaths)

Initializes the result set and triggers the query lifecycle.

Parameters:

_ph - The active CastorPersistenceHandler. Must not be finished or closed.

_query - The query string. If prefixed with "CALL SQL", it bypasses the OQL parser.

_parms - Input parameters. Null-safe; converted to empty array if null.

_mode - Persistence lock mode. Determines the isolation level of the fetched objects (e.g. READ_ONLY, SHARED, EXCLUSIVE).

_prefetchPaths - Attribute paths to be eagerly loaded.

Throws:

java.lang.IllegalStateException - If the provided PersistenceHandler is already in a 'finished' state.

PersistenceException - If OQL compilation or SQL execution fails.

Method Detail

close

public void close()

Closes the underlying result set and the query implementation.

In addition to resource cleanup, this method "slims" any currently held Business Objects to aid memory reclamation and notifies the handler of query performance metrics via ph.complainSlowQuery.

Specified by:

close in interface de.ipcon.db.core.QueryResultsI

Specified by:

close in interface java.io.Closeable

Specified by:

close in interface java.lang.AutoCloseable

isClosed

public boolean isClosed()

Specified by:

isClosed in interface de.ipcon.db.core.QueryResultsI

hasNext

public boolean hasNext()

Determines if a subsequent record is available, respecting any filterPredicate applied during OQL compilation.

Optimization Logic:

• Fast Path: If no filter is present, it delegates directly to the underlying ResultSet.
• Look-ahead: If a filter is present, it triggers a recursive fetch to find the next record that satisfies the predicate, caching the result in nextFittingBO.
• Inlining: Exception handling is streamlined via multi-catch to keep the method bytecode compact for JIT optimization.

Specified by:

hasNext in interface java.util.Iterator

Returns:

true if a subsequent call to next() is guaranteed to return a BO.

Throws:

LockNotGrantedException - if a database lock prevents row access.

PersistenceException - if an error occurs during ResultSet navigation.

next

public java.lang.Object next()

Throughput Optimization:

• Memory Management: For read-only transactions, the previous BO is aggressively slimmed before fetching the next to prevent Heap bloat.
• Look-ahead Pipeline: Implements a single-element buffer for filtered queries to ensure O(1) retrieval after hasNext().
• Exception Flattening: Uses multi-catch to reduce method bytecode size.

Specified by:

next in interface java.util.Iterator

remove

public void remove()

Modification via iterator is not supported in Castor OQL results.

Specified by:

remove in interface java.util.Iterator

Throws:

java.lang.UnsupportedOperationException - always.

currentTag

public java.lang.String currentTag()

Specified by:

currentTag in interface de.ipcon.db.core.QueryResultsI

Returns:

An empty string as tags are not supported in this implementation.

cancel

public void cancel()

Attempts to cancel the currently running database query, if supported by the underlying driver and Castor implementation

Specified by:

cancel in interface de.ipcon.db.core.QueryResultsI