Interface RequestResult
-
- All Superinterfaces:
AutoCloseable
,Iterable<Adaptation>
public interface RequestResult extends Iterable<Adaptation>, AutoCloseable
Represents the result of aRequest
.Traversing and closing the result
A
RequestResult
instance must always be closed after its use.Here is a code sample benefiting from the automatic closing provided by
AutoCloseable
and its associatedtry
-with-resources notation:try (RequestResult result = ...) { for (Adaptation record : result) { ... } }
Note that a
RequestResult
can be traversed only once, either by iterator (like the above example) or bynextAdaptation()
. Trying to create multiple iterators will result in an exception. Similarly, trying to callnextAdaptation()
after an iterator has been created (or vice-versa) will also result in an exception.Concurrency
A
RequestResult
instance is not thread-safe and it must be used only by the thread that created it.If the table is concurrently updated, the rules specified by Query snapshot isolation apply.
- See Also:
Request
,QueryResult
, Query snapshot isolation
-
-
Method Summary
All Methods Instance Methods Abstract Methods Deprecated Methods Modifier and Type Method Description void
close()
This method must always be invoked once this result is no longer used, so as to ensure that underlying resources are released.boolean
contains(Adaptation aRecord)
Returnstrue
if the specified record belongs to the result of this request (even if the record is obsolete).Request
getRequest()
Returns the request that created this result.int
getSize()
Returns the total number of records held by this result.AdaptationTable
getTable()
Returns the underlying table.boolean
isEmpty()
Returnstrue
if the result is empty (that is, size is 0).boolean
isObsolete()
Returnstrue
if this result may have changed since last computation.boolean
isSizeEqual(int aSize)
Verifies the number of records contained in this result.boolean
isSizeGreaterOrEqual(int minimalSize)
Verifies the number of records contained in this result.Adaptation
nextAdaptation()
Moves the cursor to the next record in the result and returns it.void
refresh()
Deprecated.This method does not do anything: in accordance to Query snapshot isolation, the result is frozen whenRequest.execute()
is called.boolean
refreshIfNeeded()
Deprecated.This method does not do anything: in accordance to Query snapshot isolation, the result is frozen whenRequest.execute()
is called.-
Methods inherited from interface java.lang.Iterable
forEach, iterator, spliterator
-
-
-
-
Method Detail
-
nextAdaptation
Adaptation nextAdaptation() throws RepositoryAccessException
Moves the cursor to the next record in the result and returns it. Returnsnull
if the result has no more elements:try (RequestResult result = ...) { for (Adaptation record; (record = result.nextAdaptation()) != null;) { ... } }
Note that this is the historical way of traversing a
RequestResult
, and now using theIterable
interface is preferred, as shown in the example in Traversing and closing the result.The client code must follow the rules specified by Traversing and closing the result and Concurrency.
Restrictions
In mapped mode, on PostgreSQL, cursors are invalidated at transaction commit. This means that this method can no longer be called after the transaction is committed. The same restriction applies when a
commit threshold
is specified.- Returns:
- the next record in the result,
null
if there are no more elements. - Throws:
RepositoryAccessException
-
close
void close() throws RepositoryAccessException
This method must always be invoked once this result is no longer used, so as to ensure that underlying resources are released.This method is idempotent: calling
close
on aRequestResult
object that is already closed is a no-op.- Specified by:
close
in interfaceAutoCloseable
- Throws:
RepositoryAccessException
-
contains
boolean contains(Adaptation aRecord) throws RepositoryAccessException
Returnstrue
if the specified record belongs to the result of this request (even if the record is obsolete).- Throws:
RepositoryAccessException
-
getRequest
Request getRequest()
Returns the request that created this result.
-
getTable
AdaptationTable getTable()
Returns the underlying table.
-
isEmpty
boolean isEmpty() throws RepositoryAccessException
Returnstrue
if the result is empty (that is, size is 0).Warning: This method has an inherent cost and invoking it must be avoided if the result is then traversed.
- Throws:
RepositoryAccessException
- See Also:
isSizeGreaterOrEqual(int)
-
isSizeGreaterOrEqual
boolean isSizeGreaterOrEqual(int minimalSize) throws RepositoryAccessException
Verifies the number of records contained in this result.This method returns as soon as it has fetched the specified number of records. Thus, it has a lower computational cost than
getSize()
, and is intended as an optimization for cases when the full computation of the request is not necessary.- Parameters:
minimalSize
- the minimal size required.- Throws:
IllegalArgumentException
- if specified size is negative.RepositoryAccessException
- See Also:
isSizeEqual(int)
-
isSizeEqual
boolean isSizeEqual(int aSize)
Verifies the number of records contained in this result.This method returns as soon as it has fetched the specified number of records. Thus, it has a lower computational cost than
getSize()
, and is intended as an optimization for cases when the full computation of the request is not necessary.- Throws:
IllegalArgumentException
- if specified size is negative.- See Also:
isSizeGreaterOrEqual(int)
-
getSize
int getSize() throws RepositoryAccessException
Returns the total number of records held by this result.Warning: As this method must perform the full computation of the result, it may be costly for large numbers of records or if invoked many times. If the client application only needs to check that the result has a minimum size, it is recommended to invoke the method
isSizeGreaterOrEqual(int)
; for an exact size, invokeisSizeEqual(int)
.- Throws:
RepositoryAccessException
- See Also:
isEmpty()
,isSizeEqual(int)
,isSizeGreaterOrEqual(int)
-
isObsolete
boolean isObsolete()
Returnstrue
if this result may have changed since last computation.This may happen if the table has been updated or if the request has been modified (via a
set...
method).
-
refresh
@Deprecated void refresh() throws IncompatibleChangeError, RepositoryAccessException
Deprecated.This method does not do anything: in accordance to Query snapshot isolation, the result is frozen whenRequest.execute()
is called. Close thisRequestResult
and execute again theRequest
to take into account the latest in-procedure changes.
-
refreshIfNeeded
@Deprecated boolean refreshIfNeeded() throws IncompatibleChangeError, RepositoryAccessException
Deprecated.This method does not do anything: in accordance to Query snapshot isolation, the result is frozen whenRequest.execute()
is called. Close thisRequestResult
and execute again theRequest
to take into account the latest in-procedure changes.- Returns:
false
.- Throws:
IncompatibleChangeError
RepositoryAccessException
-
-