Netty 4.1.107.Final · io.netty.channel.group.ChannelGroup

A thread-safe Set that contains open Channels and provides various bulk operations on them. Using ChannelGroup, you can categorize Channels 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 Channels associated with the recipients and call ChannelGroup#write(Object):

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

Simplify shutdown process with `ChannelGroup`

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

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

ChannelGroup allChannels =
        new DefaultChannelGroup(GlobalEventExecutor.INSTANCE);

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

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

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

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

public class MyHandler extends ChannelInboundHandlerAdapter {
    @Override
    public void channelActive(ChannelHandlerContext ctx) {
        // closed on shutdown.
        allChannels.add(ctx.channel());
        super.channelActive(ctx);
    }
}

Method Summary

Modifier and Type	Method and Description
public ChannelGroupFuture	Returns: the `ChannelGroupFuture` instance that notifies when the operation is done for all channels close() Closes all `Channel`s in this group.
public ChannelGroupFuture	Returns: the `ChannelGroupFuture` instance that notifies when the operation is done for all channels close(ChannelMatcher matcher) Closes all `Channel`s in this group that are matched by the given `ChannelMatcher`.
public ChannelGroupFuture	Returns: the `ChannelGroupFuture` instance that notifies when the operation is done for all channels deregister() Deprecated This method will be removed in the next major feature release.
public ChannelGroupFuture	Returns: the `ChannelGroupFuture` instance that notifies when the operation is done for all channels deregister(ChannelMatcher matcher) Deprecated This method will be removed in the next major feature release.
public ChannelGroupFuture	Returns: the `ChannelGroupFuture` instance that notifies when the operation is done for all channels disconnect() Disconnects all `Channel`s in this group from their remote peers.
public ChannelGroupFuture	Returns: the `ChannelGroupFuture` instance that notifies when the operation is done for all channels disconnect(ChannelMatcher matcher) Disconnects all `Channel`s in this group from their remote peers, that are matched by the given `ChannelMatcher`.
public Channel	Returns: the matching `Channel` if found. `null` otherwise. find(ChannelId id) Returns the `Channel` which has the specified `ChannelId`.
public ChannelGroup	Returns: the `ChannelGroupFuture` instance that notifies when the operation is done for all channels flush() Flush all `Channel`s in this group.
public ChannelGroup	Returns: the `ChannelGroupFuture` instance that notifies when the operation is done for all channels flush(ChannelMatcher matcher) Flush all `Channel`s in this group that are matched by the given `ChannelMatcher`.
public ChannelGroupFuture	flushAndWrite(Object message) Deprecated Use `writeAndFlush(Object)` instead.
public ChannelGroupFuture	flushAndWrite(Object message, ChannelMatcher matcher) Deprecated Use `writeAndFlush(Object, ChannelMatcher)` instead.
public String	name() Returns the name of this group.
public ChannelGroupFuture	newCloseFuture() Returns the `ChannelGroupFuture` which will be notified when all `Channel`s that are part of this `ChannelGroup`, at the time of calling, are closed.
public ChannelGroupFuture	newCloseFuture(ChannelMatcher matcher) Returns the `ChannelGroupFuture` which will be notified when all `Channel`s that are part of this `ChannelGroup`, at the time of calling, are closed.
public ChannelGroupFuture	Returns: itself write(Object message) Writes the specified `message` to all `Channel`s in this group.
public ChannelGroupFuture	Returns: the `ChannelGroupFuture` instance that notifies when the operation is done for all channels write(Object message, ChannelMatcher matcher) Writes the specified `message` to all `Channel`s in this group that are matched by the given `ChannelMatcher`.
public ChannelGroupFuture	Returns: the `ChannelGroupFuture` instance that notifies when the operation is done for all channels write(Object message, ChannelMatcher matcher, boolean voidPromise) Writes the specified `message` to all `Channel`s in this group that are matched by the given `ChannelMatcher`.
public ChannelGroupFuture	writeAndFlush(Object message) Shortcut for calling `write(Object)` and `flush()`.
public ChannelGroupFuture	writeAndFlush(Object message, ChannelMatcher matcher) Shortcut for calling `write(Object)` and `flush()` and only act on `Channel`s that are matched by the `ChannelMatcher`.
public ChannelGroupFuture	writeAndFlush(Object message, ChannelMatcher matcher, boolean voidPromise) Shortcut for calling `write(Object, ChannelMatcher, boolean)` and `flush()` and only act on `Channel`s that are matched by the `ChannelMatcher`.

Inherited from java.lang.Comparable:: compareTo
Inherited from java.util.Set:: add addAll clear contains containsAll copyOf equals hashCode isEmpty iterator of of of of of of of of of of of of remove removeAll retainAll size spliterator toArray toArray

Method Detail

close back to summary

close	back to summary
public 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:ChannelGroupFuture the `ChannelGroupFuture` instance that notifies when the operation is done for all channels

public ChannelGroupFuture close()

Closes all Channels 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:ChannelGroupFuture: the ChannelGroupFuture instance that notifies when the operation is done for all channels

close back to summary

close	back to summary
public ChannelGroupFuture close(ChannelMatcher matcher) Closes all `Channel`s in this group that are matched by the given `ChannelMatcher`. If the `Channel` is connected to a remote peer or bound to a local address, it is automatically disconnected and unbound. Returns:ChannelGroupFuture the `ChannelGroupFuture` instance that notifies when the operation is done for all channels

public ChannelGroupFuture close(ChannelMatcher matcher)

Closes all Channels in this group that are matched by the given ChannelMatcher. If the Channel is connected to a remote peer or bound to a local address, it is automatically disconnected and unbound.

Returns:ChannelGroupFuture: the ChannelGroupFuture instance that notifies when the operation is done for all channels

deregister back to summary

deregister	back to summary
public ChannelGroupFuture deregister() Deprecated This method will be removed in the next major feature release. Deregister all `Channel`s in this group from their `EventLoop`. Please note that this operation is asynchronous as `Channel#deregister()` is. Returns:ChannelGroupFuture the `ChannelGroupFuture` instance that notifies when the operation is done for all channels Annotations @Deprecated

public ChannelGroupFuture deregister()

Deprecated

This method will be removed in the next major feature release. Deregister all Channels in this group from their EventLoop. Please note that this operation is asynchronous as Channel#deregister() is.

Returns:ChannelGroupFuture

the ChannelGroupFuture instance that notifies when the operation is done for all channels

Annotations

@Deprecated

deregister back to summary

deregister	back to summary
public ChannelGroupFuture deregister(ChannelMatcher matcher) Deprecated This method will be removed in the next major feature release. Deregister all `Channel`s in this group from their `EventLoop` that are matched by the given `ChannelMatcher`. Please note that this operation is asynchronous as `Channel#deregister()` is. Returns:ChannelGroupFuture the `ChannelGroupFuture` instance that notifies when the operation is done for all channels Annotations @Deprecated

public ChannelGroupFuture deregister(ChannelMatcher matcher)

Deprecated

This method will be removed in the next major feature release. Deregister all Channels in this group from their EventLoop that are matched by the given ChannelMatcher. Please note that this operation is asynchronous as Channel#deregister() is.

Returns:ChannelGroupFuture

the ChannelGroupFuture instance that notifies when the operation is done for all channels

Annotations

@Deprecated

disconnect back to summary

disconnect	back to summary
public ChannelGroupFuture disconnect() Disconnects all `Channel`s in this group from their remote peers. Returns:ChannelGroupFuture the `ChannelGroupFuture` instance that notifies when the operation is done for all channels

public ChannelGroupFuture disconnect()

Disconnects all Channels in this group from their remote peers.

Returns:ChannelGroupFuture: the ChannelGroupFuture instance that notifies when the operation is done for all channels

disconnect back to summary

disconnect	back to summary
public ChannelGroupFuture disconnect(ChannelMatcher matcher) Disconnects all `Channel`s in this group from their remote peers, that are matched by the given `ChannelMatcher`. Returns:ChannelGroupFuture the `ChannelGroupFuture` instance that notifies when the operation is done for all channels

public ChannelGroupFuture disconnect(ChannelMatcher matcher)

Disconnects all Channels in this group from their remote peers, that are matched by the given ChannelMatcher.

Returns:ChannelGroupFuture: the ChannelGroupFuture instance that notifies when the operation is done for all channels

find back to summary

find	back to summary
public Channel find(ChannelId id) Returns the `Channel` which has the specified `ChannelId`. Returns:Channel the matching `Channel` if found. `null` otherwise.

public Channel find(ChannelId id)

Returns the Channel which has the specified ChannelId.

Returns:Channel: the matching Channel if found. null otherwise.

flush back to summary

flush	back to summary
public ChannelGroup flush() Flush all `Channel`s in this group. If the specified `messages` are an instance of `ByteBuf`, it is automatically duplicated to avoid a race condition. Please note that this operation is asynchronous as `Channel#write(Object)` is. Returns:ChannelGroup the `ChannelGroupFuture` instance that notifies when the operation is done for all channels

public ChannelGroup flush()

Flush all Channels in this group. If the specified messages are an instance of ByteBuf, it is automatically duplicated to avoid a race condition. Please note that this operation is asynchronous as Channel#write(Object) is.

Returns:ChannelGroup: the ChannelGroupFuture instance that notifies when the operation is done for all channels

flush back to summary

flush	back to summary
public ChannelGroup flush(ChannelMatcher matcher) Flush all `Channel`s in this group that are matched by the given `ChannelMatcher`. If the specified `messages` are an instance of `ByteBuf`, it is automatically duplicated to avoid a race condition. Please note that this operation is asynchronous as `Channel#write(Object)` is. Returns:ChannelGroup the `ChannelGroupFuture` instance that notifies when the operation is done for all channels

public ChannelGroup flush(ChannelMatcher matcher)

Flush all Channels in this group that are matched by the given ChannelMatcher. If the specified messages are an instance of ByteBuf, it is automatically duplicated to avoid a race condition. Please note that this operation is asynchronous as Channel#write(Object) is.

Returns:ChannelGroup: the ChannelGroupFuture instance that notifies when the operation is done for all channels

flushAndWrite	back to summary
public ChannelGroupFuture flushAndWrite(Object message) Deprecated Use `writeAndFlush(Object)` instead. Annotations @Deprecated

flushAndWrite	back to summary
public ChannelGroupFuture flushAndWrite(Object message, ChannelMatcher matcher) Deprecated Use `writeAndFlush(Object, ChannelMatcher)` instead. Annotations @Deprecated

name	back to summary
public String name() Returns the name of this group. A group name is purely for helping you to distinguish one group from others.

newCloseFuture	back to summary
public ChannelGroupFuture newCloseFuture() Returns the `ChannelGroupFuture` which will be notified when all `Channel`s that are part of this `ChannelGroup`, at the time of calling, are closed.

newCloseFuture	back to summary
public ChannelGroupFuture newCloseFuture(ChannelMatcher matcher) Returns the `ChannelGroupFuture` which will be notified when all `Channel`s that are part of this `ChannelGroup`, at the time of calling, are closed.

write back to summary

write	back to summary
public ChannelGroupFuture write(Object message) Writes the specified `message` to all `Channel`s in this group. If the specified `message` is an instance of `ByteBuf`, it is automatically duplicated to avoid a race condition. The same is true for `ByteBufHolder`. Please note that this operation is asynchronous as `Channel#write(Object)` is. Returns:ChannelGroupFuture itself

public ChannelGroupFuture write(Object message)

Writes the specified message to all Channels in this group. If the specified message is an instance of ByteBuf, it is automatically duplicated to avoid a race condition. The same is true for ByteBufHolder. Please note that this operation is asynchronous as Channel#write(Object) is.

Returns:ChannelGroupFuture: itself

write back to summary

write	back to summary
public ChannelGroupFuture write(Object message, ChannelMatcher matcher) Writes the specified `message` to all `Channel`s in this group that are matched by the given `ChannelMatcher`. If the specified `message` is an instance of `ByteBuf`, it is automatically duplicated to avoid a race condition. The same is true for `ByteBufHolder`. Please note that this operation is asynchronous as `Channel#write(Object)` is. Returns:ChannelGroupFuture the `ChannelGroupFuture` instance that notifies when the operation is done for all channels

public ChannelGroupFuture write(Object message, ChannelMatcher matcher)

Returns:ChannelGroupFuture: the ChannelGroupFuture instance that notifies when the operation is done for all channels

write back to summary

write	back to summary
public ChannelGroupFuture write(Object message, ChannelMatcher matcher, boolean voidPromise) Writes the specified `message` to all `Channel`s in this group that are matched by the given `ChannelMatcher`. If the specified `message` is an instance of `ByteBuf`, it is automatically duplicated to avoid a race condition. The same is true for `ByteBufHolder`. Please note that this operation is asynchronous as `Channel#write(Object)` is. If `voidPromise` is `true` `Channel#voidPromise()` is used for the writes and so the same restrictions to the returned `ChannelGroupFuture` apply as to a void promise. Returns:ChannelGroupFuture the `ChannelGroupFuture` instance that notifies when the operation is done for all channels

public ChannelGroupFuture write(Object message, ChannelMatcher matcher, boolean voidPromise)

Writes the specified message to all Channels in this group that are matched by the given ChannelMatcher. If the specified message is an instance of ByteBuf, it is automatically duplicated to avoid a race condition. The same is true for ByteBufHolder. Please note that this operation is asynchronous as Channel#write(Object) is. If voidPromise is true Channel#voidPromise() is used for the writes and so the same restrictions to the returned ChannelGroupFuture apply as to a void promise.

Returns:ChannelGroupFuture: the ChannelGroupFuture instance that notifies when the operation is done for all channels

writeAndFlush	back to summary
public ChannelGroupFuture writeAndFlush(Object message) Shortcut for calling `write(Object)` and `flush()`.

writeAndFlush	back to summary
public ChannelGroupFuture writeAndFlush(Object message, ChannelMatcher matcher) Shortcut for calling `write(Object)` and `flush()` and only act on `Channel`s that are matched by the `ChannelMatcher`.

writeAndFlush	back to summary
public ChannelGroupFuture writeAndFlush(Object message, ChannelMatcher matcher, boolean voidPromise) Shortcut for calling `write(Object, ChannelMatcher, boolean)` and `flush()` and only act on `Channel`s that are matched by the `ChannelMatcher`.

public Interface ChannelGroup

Broadcast a message to multiple Channels

Simplify shutdown process with ChannelGroup

Method Summary

Method Detail

Broadcast a message to multiple `Channel`s

Simplify shutdown process with `ChannelGroup`