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
`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