org.apache.flume.channel

## Class ChannelUtils

- java.lang.Object
- - org.apache.flume.channel.ChannelUtils

-     public class ChannelUtils
      extends Object

  A collection of utilities for interacting with `Channel` objects. Use of these utilities prevents error-prone replication of required transaction usage semantics, and allows for more concise code.

  However, as a side-effect of its generality, and in particular of its use of `Callable`, any checked exceptions thrown by user-created transactors will be silently wrapped with `ChannelException` before being propagated. Only direct use of `transact(Channel,Callable)` suffers from this issue, even though all other methods are based upon it, because none of the other methods are capable of producing or allowing checked exceptions in the first place.

- - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `static void` | `put(Channel channel, Collection<Event> events)` A convenience method for multiple-event `put` transactions.
    `static void` | `put(Channel channel, Event event)` A convenience method for single-event `put` transactions.
    `static Event` | `take(Channel channel)` A convenience method for single-event `take` transactions.
    `static List<Event>` | `take(Channel channel, int max)` A convenience method for multiple-event `take` transactions.
    `static <T> T` | `transact(Channel channel, Callable<T> transactor)` A general optimistic implementation of `Transaction` client semantics.
    `static void` | `transact(Channel channel, Runnable transactor)` A convenience method for transactions that don't require a return value.

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Method Detail

    - #### put

          public static void put(Channel channel,
                 Event event)
                          throws ChannelException

      A convenience method for single-event `put` transactions.

      Throws:
        `ChannelException`
      See Also:
        `transact(Channel,Callable)`

    - #### put

          public static void put(Channel channel,
                 Collection<Event> events)
                          throws ChannelException

      A convenience method for multiple-event `put` transactions.

      Throws:
        `ChannelException`
      See Also:
        `transact(Channel,Callable)`

    - #### take

          public static Event take(Channel channel)
                            throws ChannelException

      A convenience method for single-event `take` transactions.

      Returns:
        a single event, or null if the channel has none available
      Throws:
        `ChannelException`
      See Also:
        `transact(Channel,Callable)`

    - #### take

          public static List<Event> take(Channel channel,
                         int max)
                                  throws ChannelException

      A convenience method for multiple-event `take` transactions.

      Returns:
        a list of at most `max` events
      Throws:
        `ChannelException`
      See Also:
        `transact(Channel,Callable)`

    - #### transact

          public static void transact(Channel channel,
                      Runnable transactor)
                               throws ChannelException

      A convenience method for transactions that don't require a return value. Simply wraps the `transactor` using `Executors.callable(java.lang.Runnable, T)` and passes that to `transact(Channel,Callable)`.

      Throws:
        `ChannelException`
      See Also:
        `transact(Channel,Callable)`, `Executors.callable(Runnable)`

    - #### transact

          public static <T> T transact(Channel channel,
                       Callable<T> transactor)
                            throws ChannelException

      A general optimistic implementation of `Transaction` client semantics. It gets a new transaction object from the `channel`, calls `begin()` on it, and then invokes the supplied `transactor` object. If an exception is thrown, then the transaction is rolled back; otherwise the transaction is committed and the value returned by the `transactor` is returned. In either case, the transaction is closed before the function exits. All secondary exceptions (i.e. those thrown by `Transaction.rollback()` or `Transaction.close()` while recovering from an earlier exception) are logged, allowing the original exception to be propagated instead.

      This implementation is optimistic in that it expects transaction rollback to be infrequent: it will rollback a transaction only when the supplied `transactor` throws an exception, and exceptions are a fairly heavyweight mechanism for handling frequently-occurring events.

      Returns:
        the value returned by `transactor.call()`
      Throws:
        `ChannelException`

Copyright © 2009-2016 Apache Software Foundation. All Rights Reserved.