/*
 * Copyright 2013 The Netty Project
 *
 * The Netty Project licenses this file to you under the Apache License,
 * version 2.0 (the "License"); you may not use this file except in compliance
 * with the License. You may obtain a copy of the License at:
 *
 *   http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
 * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
 * License for the specific language governing permissions and limitations
 * under the License.
 */
package io.netty.channel.group;

import io.netty.bootstrap.ServerBootstrap;
import io.netty.buffer.ByteBuf;
import io.netty.buffer.ByteBufHolder;
import io.netty.buffer.Unpooled;
import io.netty.channel.Channel;
import io.netty.channel.ChannelHandlerContext;
import io.netty.channel.ChannelId;
import io.netty.channel.ChannelInboundHandlerAdapter;
import io.netty.channel.EventLoop;
import io.netty.channel.ServerChannel;
import io.netty.util.CharsetUtil;
import io.netty.util.concurrent.GlobalEventExecutor;

import java.util.Set;

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 Channels
 If you need to broadcast a message to more than one Channel, you can add the Channels associated with the recipients and call 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);
    }
}

/**
 * A thread-safe {@link Set} that contains open {@link Channel}s and provides
 * various bulk operations on them.  Using {@link ChannelGroup}, you can
 * categorize {@link Channel}s into a meaningful group (e.g. on a per-service
 * or per-state basis.)  A closed {@link Channel} is automatically removed from
 * the collection, so that you don't need to worry about the life cycle of the
 * added {@link Channel}.  A {@link Channel} can belong to more than one
 * {@link ChannelGroup}.
 *
 * <h3>Broadcast a message to multiple {@link Channel}s</h3>
 * <p>
 * If you need to broadcast a message to more than one {@link Channel}, you can
 * add the {@link Channel}s associated with the recipients and call {@link ChannelGroup#write(Object)}:
 * <pre>
 * <strong>{@link ChannelGroup} recipients =
 *         new {@link DefaultChannelGroup}({@link GlobalEventExecutor}.INSTANCE);</strong>
 * recipients.add(channelA);
 * recipients.add(channelB);
 * ..
 * <strong>recipients.write({@link Unpooled}.copiedBuffer(
 *         "Service will shut down for maintenance in 5 minutes.",
 *         {@link CharsetUtil}.UTF_8));</strong>
 * </pre>
 *
 * <h3>Simplify shutdown process with {@link ChannelGroup}</h3>
 * <p>
 * If both {@link ServerChannel}s and non-{@link ServerChannel}s exist in the
 * same {@link ChannelGroup}, any requested I/O operations on the group are
 * performed for the {@link ServerChannel}s first and then for the others.
 * <p>
 * This rule is very useful when you shut down a server in one shot:
 *
 * <pre>
 * <strong>{@link ChannelGroup} allChannels =
 *         new {@link DefaultChannelGroup}({@link GlobalEventExecutor}.INSTANCE);</strong>
 *
 * public static void main(String[] args) throws Exception {
 *     {@link ServerBootstrap} b = new {@link ServerBootstrap}(..);
 *     ...
 *     b.childHandler(new MyHandler());
 *
 *     // Start the server
 *     b.getPipeline().addLast("handler", new MyHandler());
 *     {@link Channel} serverChannel = b.bind(..).sync();
 *     <strong>allChannels.add(serverChannel);</strong>
 *
 *     ... Wait until the shutdown signal reception ...
 *
 *     // Close the serverChannel and then all accepted connections.
 *     <strong>allChannels.close().awaitUninterruptibly();</strong>
 * }
 *
 * public class MyHandler extends {@link ChannelInboundHandlerAdapter} {
 *     {@code @Override}
 *     public void channelActive({@link ChannelHandlerContext} ctx) {
 *         // closed on shutdown.
 *         <strong>allChannels.add(ctx.channel());</strong>
 *         super.channelActive(ctx);
 *     }
 * }
 * </pre>
 */
public interface ChannelGroup extends Set<Channel>, Comparable<ChannelGroup> {

    
Returns the name of this group.  A group name is purely for helping
you to distinguish one group from others.
/**
     * Returns the name of this group.  A group name is purely for helping
     * you to distinguish one group from others.
     */
    String name();

    
Returns the Channel which has the specified ChannelId. 
Returns:
the matching Channel if found. null otherwise./**
     * Returns the {@link Channel} which has the specified {@link ChannelId}.
     *
     * @return the matching {@link Channel} if found. {@code null} otherwise.
     */
    Channel find(ChannelId id);

    
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 ChannelOutboundInvoker.write(Object) is. 
Returns:
itself/**
     * Writes the specified {@code message} to all {@link Channel}s in this
     * group. If the specified {@code message} is an instance of
     * {@link ByteBuf}, it is automatically
     * {@linkplain ByteBuf#duplicate() duplicated} to avoid a race
     * condition. The same is true for {@link ByteBufHolder}. Please note that this operation is asynchronous as
     * {@link Channel#write(Object)} is.
     *
     * @return itself
     */
    ChannelGroupFuture write(Object message);

    
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 ChannelOutboundInvoker.write(Object) is. 
Returns:
the ChannelGroupFuture instance that notifies when the operation is done for all channels/**
     * Writes the specified {@code message} to all {@link Channel}s in this
     * group that are matched by the given {@link ChannelMatcher}. If the specified {@code message} is an instance of
     * {@link ByteBuf}, it is automatically
     * {@linkplain ByteBuf#duplicate() duplicated} to avoid a race
     * condition. The same is true for {@link ByteBufHolder}. Please note that this operation is asynchronous as
     * {@link Channel#write(Object)} is.
     *
     * @return the {@link ChannelGroupFuture} instance that notifies when
     *         the operation is done for all channels
     */
    ChannelGroupFuture write(Object message, ChannelMatcher matcher);

    
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 ChannelOutboundInvoker.write(Object) is. If voidPromise is true ChannelOutboundInvoker.voidPromise() is used for the writes and so the same restrictions to the returned ChannelGroupFuture apply as to a void promise. 
Returns:
the ChannelGroupFuture instance that notifies when the operation is done for all channels/**
     * Writes the specified {@code message} to all {@link Channel}s in this
     * group that are matched by the given {@link ChannelMatcher}. If the specified {@code message} is an instance of
     * {@link ByteBuf}, it is automatically
     * {@linkplain ByteBuf#duplicate() duplicated} to avoid a race
     * condition. The same is true for {@link ByteBufHolder}. Please note that this operation is asynchronous as
     * {@link Channel#write(Object)} is.
     *
     * If {@code voidPromise} is {@code true} {@link Channel#voidPromise()} is used for the writes and so the same
     * restrictions to the returned {@link ChannelGroupFuture} apply as to a void promise.
     *
     * @return the {@link ChannelGroupFuture} instance that notifies when
     *         the operation is done for all channels
     */
    ChannelGroupFuture write(Object message, ChannelMatcher matcher, boolean voidPromise);

    
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 ChannelOutboundInvoker.write(Object) is. 
Returns:
the ChannelGroupFuture instance that notifies when the operation is done for all channels/**
     * Flush all {@link Channel}s in this
     * group. If the specified {@code messages} are an instance of
     * {@link ByteBuf}, it is automatically
     * {@linkplain ByteBuf#duplicate() duplicated} to avoid a race
     * condition. Please note that this operation is asynchronous as
     * {@link Channel#write(Object)} is.
     *
     * @return the {@link ChannelGroupFuture} instance that notifies when
     *         the operation is done for all channels
     */
    ChannelGroup flush();

    
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 ChannelOutboundInvoker.write(Object) is. 
Returns:
the ChannelGroupFuture instance that notifies when the operation is done for all channels/**
     * Flush all {@link Channel}s in this group that are matched by the given {@link ChannelMatcher}.
     * If the specified {@code messages} are an instance of
     * {@link ByteBuf}, it is automatically
     * {@linkplain ByteBuf#duplicate() duplicated} to avoid a race
     * condition. Please note that this operation is asynchronous as
     * {@link Channel#write(Object)} is.
     *
     * @return the {@link ChannelGroupFuture} instance that notifies when
     *         the operation is done for all channels
     */
    ChannelGroup flush(ChannelMatcher matcher);

    
Shortcut for calling write(Object) and flush(). /**
     * Shortcut for calling {@link #write(Object)} and {@link #flush()}.
     */
    ChannelGroupFuture writeAndFlush(Object message);

    
Deprecated:
Use writeAndFlush(Object) instead./**
     * @deprecated Use {@link #writeAndFlush(Object)} instead.
     */
    @Deprecated
    ChannelGroupFuture flushAndWrite(Object message);

    
Shortcut for calling write(Object) and flush() and only act on Channels that are matched by the ChannelMatcher. /**
     * Shortcut for calling {@link #write(Object)} and {@link #flush()} and only act on
     * {@link Channel}s that are matched by the {@link ChannelMatcher}.
     */
    ChannelGroupFuture writeAndFlush(Object message, ChannelMatcher matcher);

    
Shortcut for calling write(Object, ChannelMatcher, boolean) and flush() and only act on Channels that are matched by the ChannelMatcher. /**
     * Shortcut for calling {@link #write(Object, ChannelMatcher, boolean)} and {@link #flush()} and only act on
     * {@link Channel}s that are matched by the {@link ChannelMatcher}.
     */
    ChannelGroupFuture writeAndFlush(Object message, ChannelMatcher matcher, boolean voidPromise);

    
Deprecated:
Use writeAndFlush(Object, ChannelMatcher) instead./**
     * @deprecated Use {@link #writeAndFlush(Object, ChannelMatcher)} instead.
     */
    @Deprecated
    ChannelGroupFuture flushAndWrite(Object message, ChannelMatcher matcher);

    
Disconnects all Channels in this group from their remote peers. 
Returns:
the ChannelGroupFuture instance that notifies when the operation is done for all channels/**
     * Disconnects all {@link Channel}s in this group from their remote peers.
     *
     * @return the {@link ChannelGroupFuture} instance that notifies when
     *         the operation is done for all channels
     */
    ChannelGroupFuture disconnect();

    
Disconnects all Channels in this group from their remote peers, that are matched by the given ChannelMatcher. 
Returns:
the ChannelGroupFuture instance that notifies when the operation is done for all channels/**
     * Disconnects all {@link Channel}s in this group from their remote peers,
     * that are matched by the given {@link ChannelMatcher}.
     *
     * @return the {@link ChannelGroupFuture} instance that notifies when
     *         the operation is done for all channels
     */
    ChannelGroupFuture disconnect(ChannelMatcher matcher);

    
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:
the ChannelGroupFuture instance that notifies when the operation is done for all channels/**
     * Closes all {@link Channel}s in this group.  If the {@link Channel} is
     * connected to a remote peer or bound to a local address, it is
     * automatically disconnected and unbound.
     *
     * @return the {@link ChannelGroupFuture} instance that notifies when
     *         the operation is done for all channels
     */
    ChannelGroupFuture close();

    
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:
the ChannelGroupFuture instance that notifies when the operation is done for all channels/**
     * Closes all {@link Channel}s in this group that are matched by the given {@link ChannelMatcher}.
     * If the {@link Channel} is  connected to a remote peer or bound to a local address, it is
     * automatically disconnected and unbound.
     *
     * @return the {@link ChannelGroupFuture} instance that notifies when
     *         the operation is done for all channels
     */
    ChannelGroupFuture close(ChannelMatcher matcher);

    
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 ChannelOutboundInvoker.deregister() is.
Returns:
the ChannelGroupFuture instance that notifies when the operation is done for all channels/**
     * @deprecated This method will be removed in the next major feature release.
     *
     * Deregister all {@link Channel}s in this group from their {@link EventLoop}.
     * Please note that this operation is asynchronous as {@link Channel#deregister()} is.
     *
     * @return the {@link ChannelGroupFuture} instance that notifies when
     *         the operation is done for all channels
     */
    @Deprecated
    ChannelGroupFuture deregister();

    
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 ChannelOutboundInvoker.deregister() is.
Returns:
the ChannelGroupFuture instance that notifies when the operation is done for all channels/**
     * @deprecated This method will be removed in the next major feature release.
     *
     * Deregister all {@link Channel}s in this group from their {@link EventLoop} that are matched by the given
     * {@link ChannelMatcher}. Please note that this operation is asynchronous as {@link Channel#deregister()} is.
     *
     * @return the {@link ChannelGroupFuture} instance that notifies when
     *         the operation is done for all channels
     */
    @Deprecated
    ChannelGroupFuture deregister(ChannelMatcher matcher);

    
Returns the ChannelGroupFuture which will be notified when all Channels that are part of this ChannelGroup, at the time of calling, are closed. /**
     * Returns the {@link ChannelGroupFuture} which will be notified when all {@link Channel}s that are part of this
     * {@link ChannelGroup}, at the time of calling, are closed.
     */
    ChannelGroupFuture newCloseFuture();

    
Returns the ChannelGroupFuture which will be notified when all Channels that are part of this ChannelGroup, at the time of calling, are closed. /**
     * Returns the {@link ChannelGroupFuture} which will be notified when all {@link Channel}s that are part of this
     * {@link ChannelGroup}, at the time of calling, are closed.
     */
    ChannelGroupFuture newCloseFuture(ChannelMatcher matcher);
}