Support for transactional enqueue.
This method allows a client to provisionally enqueue a number of elements onto the queue, and then later commit the enqueue (with a commitEnqueue call), or abort (with an abortEnqueue call). This mechanism can be used to perform "split-phase" enqueues, where a client first enqueues a set of elements on the queue and then performs some work to "fill in" those elements before performing a commit. This can also be used to perform multi-queue transactional enqueue operations, with an "all-or-nothing" strategy for enqueueing events on multiple Sinks.
This method would generally be used in the following manner:
PreparedEnqueue enqueue = sink.prepareEnqueue(someElements); if (canCommit) { enqueue.commit(); } else { enqueue.abort(); } Note that this method does not protect against "dangling prepares" -- that is, a prepare without an associated commit or abort operation. This method should be used with care. In particular, be sure that all code paths (such as exceptions) after a prepare include either a commit or an abort.
@param elements The element array to provisionally enqueue
@return A
PreparedEnqueue that may be used to commit orabort the provisional enqueue
@throws SinkFullException Indicates that the sink istemporarily full and that the requested elements could not be provisionally enqueued.
@throws SinkClosedException Indicates that the sink isno longer being serviced.
@see PreparedEnqueue