org.jboss.netty.channel.group.ChannelGroup Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of netty Show documentation
The Netty project is an effort to provide an asynchronous event-driven network application framework and tools for rapid development of maintainable high performance and high scalability protocol servers and clients. In other words, Netty is a NIO client server framework which enables quick and easy development of network applications such as protocol servers and clients. It greatly simplifies and streamlines network programming such as TCP and UDP socket server.
There is a newer version: 4.0.0.Alpha8
Show newest version
/*
 * Copyright 2012 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 org.jboss.netty.channel.group;

import java.net.SocketAddress;
import java.util.Set;

import org.jboss.netty.bootstrap.ServerBootstrap;
import org.jboss.netty.buffer.ChannelBuffer;
import org.jboss.netty.buffer.ChannelBuffers;
import org.jboss.netty.channel.Channel;
import org.jboss.netty.channel.ChannelHandlerContext;
import org.jboss.netty.channel.ChannelStateEvent;
import org.jboss.netty.channel.ServerChannel;
import org.jboss.netty.channel.SimpleChannelUpstreamHandler;
import org.jboss.netty.util.CharsetUtil;

/**
 * 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}.
 *
 * Broadcast a message to multiple {@link Channel}s
 * 
 * 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)}:
 * 
 * {@link ChannelGroup} recipients = new {@link DefaultChannelGroup}();
 * recipients.add(channelA);
 * recipients.add(channelB);
 * ..
 * recipients.write({@link ChannelBuffers}.copiedBuffer(
 *         "Service will shut down for maintenance in 5 minutes.",
 *         {@link CharsetUtil}.UTF_8));
 * 
 *
 * Simplify shutdown process with {@link ChannelGroup}
 * 
 * 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.
 * 

 * This rule is very useful when you shut down a server in one shot:
 *
 * 
 * {@link ChannelGroup} allChannels = new {@link DefaultChannelGroup}();
 *
 * public static void main(String[] args) throws Exception {
 *     {@link ServerBootstrap} b = new {@link ServerBootstrap}(..);
 *     ...
 *
 *     // Start the server
 *     b.getPipeline().addLast("handler", new MyHandler());
 *     {@link 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 {@link SimpleChannelUpstreamHandler} {
 *     {@code @Override}
 *     public void channelOpen({@link ChannelHandlerContext} ctx, {@link ChannelStateEvent} e) {
 *         // Add all open channels to the global group so that they are
 *         // closed on shutdown.
 *         allChannels.add(e.getChannel());
 *     }
 * }
 * 
 * @apiviz.landmark
 * @apiviz.has org.jboss.netty.channel.group.ChannelGroupFuture oneway - - returns
 */
public interface ChannelGroup extends Set, Comparable {

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

    /**
     * Returns the {@link Channel} whose ID matches the specified integer.
     *
     * @return the matching {@link Channel} if found. {@code null} otherwise.
     */
    Channel find(Integer id);

    /**
     * Calls {@link Channel#setInterestOps(int)} for all {@link Channel}s in
     * this group with the specified {@code interestOps}. Please note that
     * this operation is asynchronous as {@link Channel#setInterestOps(int)} is.
     *
     * @return the {@link ChannelGroupFuture} instance that notifies when
     *         the operation is done for all channels
     */
    ChannelGroupFuture setInterestOps(int interestOps);

    /**
     * Calls {@link Channel#setReadable(boolean)} for all {@link Channel}s in
     * this group with the specified boolean flag. Please note that this
     * operation is asynchronous as {@link Channel#setReadable(boolean)} is.
     *
     * @return the {@link ChannelGroupFuture} instance that notifies when
     *         the operation is done for all channels
     */
    ChannelGroupFuture setReadable(boolean readable);

    /**
     * Writes the specified {@code message} to all {@link Channel}s in this
     * group. If the specified {@code message} is an instance of
     * {@link ChannelBuffer}, it is automatically
     * {@linkplain ChannelBuffer#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
     */
    ChannelGroupFuture write(Object message);

    /**
     * Writes the specified {@code message} with the specified
     * {@code remoteAddress} to all {@link Channel}s in this group.  If the
     * specified {@code message} is an instance of {@link ChannelBuffer}, it is
     * automatically {@linkplain ChannelBuffer#duplicate() duplicated} to avoid
     * a race condition. Please note that this operation is asynchronous as
     * {@link Channel#write(Object, SocketAddress)} is.
     *
     * @return the {@link ChannelGroupFuture} instance that notifies when
     *         the operation is done for all channels
     */
    ChannelGroupFuture write(Object message, SocketAddress remoteAddress);

    /**
     * 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();

    /**
     * Unbinds all {@link Channel}s in this group from their local address.
     *
     * @return the {@link ChannelGroupFuture} instance that notifies when
     *         the operation is done for all channels
     */
    ChannelGroupFuture unbind();

    /**
     * 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();
}