7.3. Asynchronous Receiving
7.3.1. Asynchronous Message Retrieval (Prefetch)
By default, a receiver retrieves a single message synchronously in response to a
fetch() call. The receiver's capacity to prefetch messages is 0 by default.
When the receiver's capacity is set to a value greater than 0, the receiver will asynchronously retrieve up to that number of messages from the queue. This asynchronous retrieval is called prefetch, and it is enabled and controlled by setting the
capacity property of a receiver.
Prefetching messages has two advantages:
- Prefetched messages are available locally when requested by the application, without the overhead of a synchronous call to retrieve a message from the broker.
- A receiver with prefetching enabled has an
available()method that can be invoked to determine how many prefetched messages are available.
Note two things about the
available() method:
Prefetching is asynchronous, which means that you cannot rely on the number returned by a call to
available() as an absolute indicator of the state of the queue. For example, calling available() immediately after setting the capacity of a receiver to something other than 0 is likely to return a value of 0 messages available. This does not necessarily mean that the queue has no messages, but rather that no prefetched messages are locally available yet.
Note also that the maximum value reported by the
available method of a receiver with prefetching enabled will be the capacity of the receiver. The available() method reports the number of prefetched messages available, not the number of messages in the queue. If the number of available messages is less than the capacity of the receiver, however, you can infer that this is the number of messages in the queue, with the above caveat about the asynchronous nature of prefetching.
