org.jboss.netty.channel.group

## Interface ChannelGroup

- All Superinterfaces:
    Collection<Channel>, Comparable<ChannelGroup>, Iterable<Channel>, Set<Channel>
  All Known Implementing Classes:
    DefaultChannelGroup

      public interface ChannelGroup
      extends Set<Channel>, Comparable<ChannelGroup>

  A thread-safe `Set` that contains open `Channel`s and provides various bulk operations on them. Using `ChannelGroup`, you can categorize `Channel`s into a meaningful group (e.g. on a per-service or per-state basis.) A closed `Channel` is automatically removed from the collection, so that you don't need to worry about the life cycle of the added `Channel`. A `Channel` can belong to more than one `ChannelGroup`.

  ### Broadcast a message to multiple `Channel`s

  If you need to broadcast a message to more than one `Channel`, you can add the `Channel`s associated with the recipients and call `write(Object)`:

       ChannelGroup recipients = new DefaultChannelGroup();
       recipients.add(channelA);
       recipients.add(channelB);
       ..
       recipients.write(ChannelBuffers.copiedBuffer(
               "Service will shut down for maintenance in 5 minutes.",
               CharsetUtil.UTF_8));

  ### Simplify shutdown process with `ChannelGroup`

  If both `ServerChannel`s and non-`ServerChannel`s exist in the same `ChannelGroup`, any requested I/O operations on the group are performed for the `ServerChannel`s first and then for the others.

  This rule is very useful when you shut down a server in one shot:

       ChannelGroup allChannels = new DefaultChannelGroup();

       public static void main(String[] args) throws Exception {
           ServerBootstrap b = new ServerBootstrap(..);
           ...

           // Start the server
           b.getPipeline().addLast("handler", new MyHandler());
           Channel serverChannel = b.bind(..);
           allChannels.add(serverChannel);

           ... Wait until the shutdown signal reception ...

           // Close the serverChannel and then all accepted connections.
           allChannels.close().awaitUninterruptibly();
           b.releaseExternalResources();
       }

       public class MyHandler extends SimpleChannelUpstreamHandler {
           @Override
           public void channelOpen(ChannelHandlerContext ctx, ChannelStateEvent e) {
               // Add all open channels to the global group so that they are
               // closed on shutdown.
               allChannels.add(e.getChannel());
           }
       }

- - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `ChannelGroupFuture` | `close()` Closes all `Channel`s in this group.
    `ChannelGroupFuture` | `disconnect()` Disconnects all `Channel`s in this group from their remote peers.
    `Channel` | `find(Integer id)` Returns the `Channel` whose ID matches the specified integer.
    `String` | `getName()` Returns the name of this group.
    `ChannelGroupFuture` | `setInterestOps(int interestOps)` Calls `Channel.setInterestOps(int)` for all `Channel`s in this group with the specified `interestOps`.
    `ChannelGroupFuture` | `setReadable(boolean readable)` Calls `Channel.setReadable(boolean)` for all `Channel`s in this group with the specified boolean flag.
    `ChannelGroupFuture` | `unbind()` Unbinds all `Channel`s in this group from their local address.
    `ChannelGroupFuture` | `write(Object message)` Writes the specified `message` to all `Channel`s in this group.
    `ChannelGroupFuture` | `write(Object message, SocketAddress remoteAddress)` Writes the specified `message` with the specified `remoteAddress` to all `Channel`s in this group.

    - ### Methods inherited from interface java.util.Set

      `add, addAll, clear, contains, containsAll, equals, hashCode, isEmpty, iterator, remove, removeAll, retainAll, size, toArray, toArray`

    - ### Methods inherited from interface java.lang.Comparable

      `compareTo`

- - ### Method Detail

    - #### getName

          String getName()

      Returns the name of this group. A group name is purely for helping you to distinguish one group from others.

    - #### find

          Channel find(Integer id)

      Returns the `Channel` whose ID matches the specified integer.
      Returns:
        the matching `Channel` if found. `null` otherwise.

    - #### setInterestOps

          ChannelGroupFuture setInterestOps(int interestOps)

      Calls `Channel.setInterestOps(int)` for all `Channel`s in this group with the specified `interestOps`. Please note that this operation is asynchronous as `Channel.setInterestOps(int)` is.
      Returns:
        the `ChannelGroupFuture` instance that notifies when the operation is done for all channels

    - #### setReadable

          ChannelGroupFuture setReadable(boolean readable)

      Calls `Channel.setReadable(boolean)` for all `Channel`s in this group with the specified boolean flag. Please note that this operation is asynchronous as `Channel.setReadable(boolean)` is.
      Returns:
        the `ChannelGroupFuture` instance that notifies when the operation is done for all channels

    - #### write

          ChannelGroupFuture write(Object message)

      Writes the specified `message` to all `Channel`s in this group. If the specified `message` is an instance of `ChannelBuffer`, it is automatically duplicated to avoid a race condition. Please note that this operation is asynchronous as `Channel.write(Object)` is.
      Returns:
        the `ChannelGroupFuture` instance that notifies when the operation is done for all channels

    - #### write

          ChannelGroupFuture write(Object message,
                                 SocketAddress remoteAddress)

      Writes the specified `message` with the specified `remoteAddress` to all `Channel`s in this group. If the specified `message` is an instance of `ChannelBuffer`, it is automatically duplicated to avoid a race condition. Please note that this operation is asynchronous as `Channel.write(Object, SocketAddress)` is.
      Returns:
        the `ChannelGroupFuture` instance that notifies when the operation is done for all channels

    - #### disconnect

          ChannelGroupFuture disconnect()

      Disconnects all `Channel`s in this group from their remote peers.
      Returns:
        the `ChannelGroupFuture` instance that notifies when the operation is done for all channels

    - #### unbind

          ChannelGroupFuture unbind()

      Unbinds all `Channel`s in this group from their local address.
      Returns:
        the `ChannelGroupFuture` instance that notifies when the operation is done for all channels

    - #### close

          ChannelGroupFuture close()

      Closes all `Channel`s in this group. If the `Channel` is connected to a remote peer or bound to a local address, it is automatically disconnected and unbound.
      Returns:
        the `ChannelGroupFuture` instance that notifies when the operation is done for all channels

Copyright © 2008-2012 The Netty Project. All Rights Reserved.