com.onwbp.adaptation

Interface RequestResult

All Superinterfaces:

AutoCloseable

public interface RequestResult
extends AutoCloseable

Represents the result of a Request.

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 associated try-with-resources notation:

 
 try (RequestResult result = ...)
 {
        for (Adaptation record; (record = result.nextAdaptation()) != null;)
        {
                ...
        }
 }
 
 

Alternate implementation:

 
 try (RequestResult result = ...)
 {
        while (true)
        {
                Adaptation record = result.nextAdaptation();
                if (record == null)
                        break;
                ...
        }
 }
 
 

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

Modifier and Type	Method and 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) Returns true 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() Returns true if the result is empty (that is, size is 0).
boolean	isObsolete() Returns true 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 when Request.execute() is called. Close this RequestResult and execute again the Request to take into account the latest in-procedure changes.
boolean	refreshIfNeeded() Deprecated. This method does not do anything: in accordance to Query snapshot isolation, the result is frozen when Request.execute() is called. Close this RequestResult and execute again the Request to take into account the latest in-procedure changes.

Method Detail

nextAdaptation

Adaptation nextAdaptation()
                   throws RepositoryAccessException

Moves the cursor to the next record in the result and returns it. Returns null if the result has no more elements.

The client code must follow the rules specified by 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 a RequestResult object that is already closed is a no-op.

Specified by:

close in interface AutoCloseable

Throws:

RepositoryAccessException

contains

boolean contains(Adaptation aRecord)
          throws RepositoryAccessException

Returns true 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

Returns true 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, invoke isSizeEqual(int).

Throws:

RepositoryAccessException

See Also:

isEmpty(), isSizeEqual(int), isSizeGreaterOrEqual(int)

isObsolete

boolean isObsolete()

Returns true 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 when Request.execute() is called. Close this RequestResult and execute again the Request to take into account the latest in-procedure changes.

Throws:

IncompatibleChangeError

RepositoryAccessException

refreshIfNeeded

@Deprecated
boolean refreshIfNeeded()
                              throws IncompatibleChangeError,
                                     RepositoryAccessException

Deprecated. This method does not do anything: in accordance to Query snapshot isolation, the result is frozen when Request.execute() is called. Close this RequestResult and execute again the Request to take into account the latest in-procedure changes.

Returns:

false.

Throws:

IncompatibleChangeError

RepositoryAccessException