com.onwbp.adaptation

Interface RequestResult

public interface RequestResult

Represents the result of a Request.

Concurrency

For multi-threading on a single RequestResult instance, the method nextAdaptation() is not synchronized. If multiple threads invoke it concurrently on the same instance, they must be synchronized externally.

If the table is concurrently updated, the general rules regarding Concurrency and isolation levels apply.

See Also:

Request, Concurrency and isolation levels

Method Summary

Modifier and Type	Method and Description
void	close() This method must be invoked after having invoked the methods nextAdaptation (or getAdaptation) 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).
Adaptation	getAdaptation(int anIndex) Deprecated. It is strongly recommended to use nextAdaptation() instead, as it is safer than this method in the case of concurrent deletion. Moreover, it does not call getSize(), and thus can be less expensive when the iteration is not performed on all records.
Request	getRequest() Returns the request that created this result.
int	getSize() Returns the total number of records held by this result.
AdaptationTable	getTable()
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() Forces a full re-computation of this result.
boolean	refreshIfNeeded() Performs a refresh of the result if it may have changed.

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.

Once this method has been called, it is mandatory to invoke the close() method. Otherwise, if the table is in relational mode, the available database connections will be exhausted.

Code sample

This code sample demonstrates an iteration over the entire result:

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

An alternate implementation of the iteration:

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

Concurrency

See Concurrency for information.

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 be invoked after having invoked the methods nextAdaptation (or getAdaptation) to ensure that underlying resources are released.

Throws:

RepositoryAccessException

See Also:

nextAdaptation()

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()

isEmpty

boolean isEmpty()
         throws RepositoryAccessException

Returns true if the result is empty (that is, size is 0).

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. For an iteration, it is preferable to use the method nextAdaptation() than a loop from 0 to getSize(). 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)

getAdaptation

Adaptation getAdaptation(int anIndex)
                  throws IncompatibleChangeError,
                         ArrayIndexOutOfBoundsException,
                         RepositoryAccessException

Deprecated. It is strongly recommended to use nextAdaptation() instead, as it is safer than this method in the case of concurrent deletion. Moreover, it does not call getSize(), and thus can be less expensive when the iteration is not performed on all records.

Returns the record at a specified position in this result.

Warning: This method may throw an IncompatibleChangeError if a deletion has been performed concurrently (see Concurrency).

Throws:

ArrayIndexOutOfBoundsException - if the specified index is greater than the number of rows in the request result.

IncompatibleChangeError

RepositoryAccessException

isObsolete

boolean isObsolete()

Returns true if this result may have changed since last computation.

This may happens if the table has been updated or if the request has been modified (via a set... method).

See Also:

refreshIfNeeded()

refresh

void refresh()
      throws IncompatibleChangeError,
             RepositoryAccessException

Forces a full re-computation of this result.

Throws:

IncompatibleChangeError - if the underlying data model has become unavailable or table node has been removed from the data model.

RepositoryAccessException

refreshIfNeeded

boolean refreshIfNeeded()
                 throws IncompatibleChangeError,
                        RepositoryAccessException

Performs a refresh of the result if it may have changed.

Returns:

true if a refresh has been performed, false otherwise.

Throws:

IncompatibleChangeError

RepositoryAccessException

See Also:

isObsolete(), Adaptation.getUpToDateInstance()