Package com.onwbp.adaptation

# Interface RequestResult

All Superinterfaces:
  `AutoCloseable`, `Iterable<Adaptation>`

public interface RequestResult extends Iterable<Adaptation>, AutoCloseable
Represents the result of a `Request`.

### 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 associated `try`-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 by `nextAdaptation()`. Trying to create multiple iterators will result in an exception. Similarly, trying to call `nextAdaptation()` 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

  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)`
  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.
  `boolean`
  `refreshIfNeeded()`
  Deprecated.
  This method does not do anything: in accordance to Query snapshot isolation, the result is frozen when `Request.execute()` is called.

  ### Methods inherited from interface java.lang.Iterable

  `forEach, iterator, spliterator`

- ## Method Details

  - ### 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:

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

    Note that this is the historical way of traversing a `RequestResult`, and now using the `Iterable` 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 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`