andreacavalli/netty5
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

More javadoc fixes

Browse Source
This commit is contained in:
Norman Maurer 2012-12-21 07:13:31 +01:00
parent 7a9d9d6a88
commit 62bf98af8c
5 changed files with 107 additions and 64 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

50
transport/src/main/java/io/netty/channel/Channel.java
View File

@ -24,7 +24,6 @@ import io.netty.util.AttributeMap;
import java.net.InetSocketAddress;
import java.net.SocketAddress;
import java.nio.channels.SelectionKey;
/**
@ -36,7 +35,7 @@ import java.nio.channels.SelectionKey;
* <li>the current state of the channel (e.g. is it open? is it connected?),</li>
* <li>the {@linkplain ChannelConfig configuration parameters} of the channel (e.g. receive buffer size),</li>
* <li>the I/O operations that the channel supports (e.g. read, write, connect, and bind), and</li>
* <li>the {@link ChannelPipeline} which handles all {@linkplain ChannelEvent I/O events and requests}
* <li>the {@link ChannelPipeline} which handles all I/O events and requests
* associated with the channel.</li>
* </ul>
*
@ -50,10 +49,10 @@ import java.nio.channels.SelectionKey;
*
* <h3>Channels are hierarchical</h3>
* <p>
* A {@link Channel} can have a {@linkplain #getParent() parent} depending on
* A {@link Channel} can have a {@linkplain #parent() parent} depending on
* how it was created. For instance, a {@link SocketChannel}, that was accepted
* by {@link ServerSocketChannel}, will return the {@link ServerSocketChannel}
* as its parent on {@link #getParent()}.
* as its parent on {@link #parent()}.
* <p>
* The semantics of the hierarchical structure depends on the transport
* implementation where the {@link Channel} belongs to. For example, you could
@ -68,38 +67,6 @@ import java.nio.channels.SelectionKey;
* operations. For example, with the old I/O datagram transport, multicast
* join / leave operations are provided by {@link DatagramChannel}.
*
* <h3>InterestOps</h3>
* <p>
* A {@link Channel} has a property called {@link #getInterestOps() interestOps}
* which is similar to that of {@link SelectionKey#interestOps() NIO SelectionKey}.
* It is represented as a <a href="http://en.wikipedia.org/wiki/Bit_field">bit
* field</a> which is composed of the two flags.
* <ul>
* <li>{@link #OP_READ} - If set, a message sent by a remote peer will be read
* immediately. If unset, the message from the remote peer will not be read
* until the {@link #OP_READ} flag is set again (i.e. read suspension).</li>
* <li>{@link #OP_WRITE} - If set, a write request will not be sent to a remote
* peer until the {@link #OP_WRITE} flag is cleared and the write request
* will be pending in a queue. If unset, the write request will be flushed
* out as soon as possible from the queue.</li>
* <li>{@link #OP_READ_WRITE} - This is a combination of {@link #OP_READ} and
* {@link #OP_WRITE}, which means only write requests are suspended.</li>
* <li>{@link #OP_NONE} - This is a combination of (NOT {@link #OP_READ}) and
* (NOT {@link #OP_WRITE}), which means only read operation is suspended.</li>
* </ul>
* </p><p>
* You can set or clear the {@link #OP_READ} flag to suspend and resume read
* operation via {@link #setReadable(boolean)}.
* </p><p>
* Please note that you cannot suspend or resume write operation just like you
* can set or clear {@link #OP_READ}. The {@link #OP_WRITE} flag is read only
* and provided simply as a mean to tell you if the size of pending write
* requests exceeded a certain threshold or not so that you don't issue too many
* pending writes that lead to an {@link OutOfMemoryError}. For example, the
* NIO socket transport uses the {@code writeBufferLowWaterMark} and
* {@code writeBufferHighWaterMark} properties in {@link NioSocketChannelConfig}
* to determine when to set or clear the {@link #OP_WRITE} flag.
* </p>
* @apiviz.landmark
* @apiviz.composedOf io.netty.channel.ChannelConfig
* @apiviz.composedOf io.netty.channel.ChannelPipeline
@ -131,8 +98,19 @@ public interface Channel extends AttributeMap, ChannelOutboundInvoker, ChannelPr
*/
ChannelConfig config();
/**
* Returns {@code true} if the {@link Channel} is open an may get active later
*/
boolean isOpen();
/**
* Returns {@code true} if the {@link Channel} is registered with an {@link EventLoop}.
*/
boolean isRegistered();
/**
* Return {@code true} if the {@link Channel} is active and so connected.
*/
boolean isActive();
/**

48
transport/src/main/java/io/netty/channel/ChannelHandlerContext.java
View File

@ -18,6 +18,8 @@ package io.netty.channel;
import io.netty.buffer.ByteBuf;
import io.netty.buffer.MessageBuf;
import io.netty.util.Attribute;
import io.netty.util.AttributeKey;
import io.netty.util.AttributeMap;
import java.nio.channels.Channels;
@ -25,20 +27,19 @@ import java.util.Set;
/**
* Enables a {@link ChannelHandler} to interact with its {@link ChannelPipeline}
* and other handlers. A handler can send a {@link ChannelEvent} upstream or
* downstream, modify the {@link ChannelPipeline} it belongs to dynamically.
* and other handlers. A handler can notify the next {@link ChannelHandler} in the {@link ChannelPipeline},
* modify the {@link ChannelPipeline} it belongs to dynamically.
*
* <h3>Sending an event</h3>
* <h3>Notify</h3>
*
* You can send or forward a {@link ChannelEvent} to the closest handler in the
* same {@link ChannelPipeline} by calling {@link #sendUpstream(ChannelEvent)}
* or {@link #sendDownstream(ChannelEvent)}. Please refer to
* {@link ChannelPipeline} to understand how an event flows.
* You can notify the closest handler in the
* same {@link ChannelPipeline} by calling one of the various methods which are listed in {@link ChannelInboundInvoker}
* and {@link ChannelOutboundInvoker}. Please refer to {@link ChannelPipeline} to understand how an event flows.
*
* <h3>Modifying a pipeline</h3>
*
* You can get the {@link ChannelPipeline} your handler belongs to by calling
* {@link #getPipeline()}. A non-trivial application could insert, remove, or
* {@link #pipeline()}. A non-trivial application could insert, remove, or
* replace handlers in the pipeline dynamically in runtime.
*
* <h3>Retrieving for later use</h3>
@ -46,8 +47,7 @@ import java.util.Set;
* You can keep the {@link ChannelHandlerContext} for later use, such as
* triggering an event outside the handler methods, even from a different thread.
* <pre>
* public class MyHandler extends {@link SimpleChannelHandler}
* implements {@link LifeCycleAwareChannelHandler} {
* public class MyHandler extends {@link ChannelHandlerAdapter} {
*
* <b>private {@link ChannelHandlerContext} ctx;</b>
*
@ -56,10 +56,7 @@ import java.util.Set;
* }
*
* public void login(String username, password) {
* {@link Channels}.write(
* <b>this.ctx</b>,
* {@link Channels}.succeededFuture(<b>this.ctx.getChannel()</b>),
* new LoginMessage(username, password));
* ctx.write(new LoginMessage(username, password));
* }
* ...
* }
@ -67,7 +64,7 @@ import java.util.Set;
*
* <h3>Storing stateful information</h3>
*
* {@link #setAttachment(Object)} and {@link #getAttachment()} allow you to
* {@link #attr(AttributeKey)} allow you to
* store and access stateful information that is related with a handler and its
* context. Please refer to {@link ChannelHandler} to learn various recommended
* ways to manage stateful information.
@ -85,20 +82,23 @@ import java.util.Set;
* as how many times it is added to pipelines, regardless if it is added to the
* same pipeline multiple times or added to different pipelines multiple times:
* <pre>
* public class FactorialHandler extends {@link SimpleChannelHandler} {
* public class FactorialHandler extends {@link ChannelInboundMessageHandlerAdapter}&lt{@link Integer}&gt {
*
* private final {@link AttributeKey}&lt{@link Integer}&gt counter =
* new {@link AttributeKey}&lt{@link Integer}&gt("counter");
*
* // This handler will receive a sequence of increasing integers starting
* // from 1.
* {@code @Override}
* public void messageReceived({@link ChannelHandlerContext} ctx, {@link MessageEvent} evt) {
* Integer a = (Integer) ctx.getAttachment();
* Integer b = (Integer) evt.getMessage();
* public void messageReceived({@link ChannelHandlerContext} ctx, {@link Integer} integer) {
* {@link Attribute}&lt{@link Integer}&gt} attr = ctx.getAttr(counter);
* Integer a = ctx.getAttr(counter).get();
*
* if (a == null) {
* a = 1;
* }
*
* ctx.setAttachment(Integer.valueOf(a * b));
* attr.set(a * integer));
* }
* }
*
@ -119,10 +119,10 @@ import java.util.Set;
*
* <h3>Additional resources worth reading</h3>
* <p>
* Please refer to the {@link ChannelHandler}, {@link ChannelEvent}, and
* {@link ChannelPipeline} to find out what a upstream event and a downstream
* event are, what fundamental differences they have, how they flow in a
* pipeline, and how to handle the event in your application.
* Please refer to the {@link ChannelHandler}, and
* {@link ChannelPipeline} to find out more about inbound and outbound operations,
* what fundamental differences they have, how they flow in a pipeline, and how to handle
* the operation in your application.
* @apiviz.owns io.netty.channel.ChannelHandler
*/
public interface ChannelHandlerContext

62
transport/src/main/java/io/netty/channel/ChannelOperationHandler.java
View File

@ -17,15 +17,77 @@ package io.netty.channel;
import java.net.SocketAddress;
/**
* {@link ChannelHandler} which will get notified for IO-outbound-operations.
*/
public interface ChannelOperationHandler extends ChannelHandler {
/**
* Called once a bind operation is made.
*
* @param ctx the {@link ChannelHandlerContext} for which the bind operation is made
* @param localAddress the {@link SocketAddress} to which it should bound
* @param future the {@link ChannelFuture} to notify once the operation completes
* @throws Exception thrown if an error accour
*/
void bind(ChannelHandlerContext ctx, SocketAddress localAddress, ChannelFuture future) throws Exception;
/**
* Called once a connect operation is made.
*
* @param ctx the {@link ChannelHandlerContext} for which the connect operation is made
* @param remoteAddress the {@link SocketAddress} to which it should connect
* @param localAddress the {@link SocketAddress} which is used as source on connect
* @param future the {@link ChannelFuture} to notify once the operation completes
* @throws Exception thrown if an error accour
*/
void connect(
ChannelHandlerContext ctx, SocketAddress remoteAddress,
SocketAddress localAddress, ChannelFuture future) throws Exception;
/**
* Called once a disconnect operation is made.
*
* @param ctx the {@link ChannelHandlerContext} for which the disconnect operation is made
* @param future the {@link ChannelFuture} to notify once the operation completes
* @throws Exception thrown if an error accour
*/
void disconnect(ChannelHandlerContext ctx, ChannelFuture future) throws Exception;
/**
* Called once a close operation is made.
*
* @param ctx the {@link ChannelHandlerContext} for which the close operation is made
* @param future the {@link ChannelFuture} to notify once the operation completes
* @throws Exception thrown if an error accour
*/
void close(ChannelHandlerContext ctx, ChannelFuture future) throws Exception;
/**
* Called once a deregister operation is made from the current registered {@link EventLoop}.
*
* @param ctx the {@link ChannelHandlerContext} for which the close operation is made
* @param future the {@link ChannelFuture} to notify once the operation completes
* @throws Exception thrown if an error accour
*/
void deregister(ChannelHandlerContext ctx, ChannelFuture future) throws Exception;
/**
* Called once a flush operation is made and so the outbound data should be written.
*
* @param ctx the {@link ChannelHandlerContext} for which the flush operation is made
* @param future the {@link ChannelFuture} to notify once the operation completes
* @throws Exception thrown if an error accour
*/
void flush(ChannelHandlerContext ctx, ChannelFuture future) throws Exception;
/**
* Called once a sendFile operation is made and so the {@link FileRegion} should be transfered.
*
* @param ctx the {@link ChannelHandlerContext} for which the flush operation is made
* @param region the {@link FileRegion} to transfer
* @param future the {@link ChannelFuture} to notify once the operation completes
* @throws Exception thrown if an error accour
*/
void sendFile(ChannelHandlerContext ctx, FileRegion region, ChannelFuture future) throws Exception;
}

8
transport/src/main/java/io/netty/channel/socket/DatagramPacket.java
View File

@ -27,6 +27,13 @@ public final class DatagramPacket {
private final ByteBuf data;
private final InetSocketAddress remoteAddress;
/**
* Create a new instance
*
* @param data the {@link ByteBuf} which holds the data of the packet
* @param remoteAddress the (@link InetSocketAddress} from which the packet was received or to which the
* packet will be send
*/
public DatagramPacket(ByteBuf data, InetSocketAddress remoteAddress) {
if (data == null) {
throw new NullPointerException("data");
@ -48,7 +55,6 @@ public final class DatagramPacket {
/**
* The {@link InetSocketAddress} which this {@link DatagramPacket} will send to or was received from.
* If {@code null} is used the default address will be used which the {@link DatagramChannel} was connected to.
*/
public InetSocketAddress remoteAddress() {
return remoteAddress;

3
transport/src/main/java/io/netty/channel/socket/nio/ProtocolFamilyConverter.java
View File

@ -22,8 +22,6 @@ import java.net.StandardProtocolFamily;
/**
* Helper class which convert the {@link InternetProtocolFamily}.
*
*
*/
final class ProtocolFamilyConverter {
@ -38,7 +36,6 @@ final class ProtocolFamilyConverter {
switch (family) {
case IPv4:
return StandardProtocolFamily.INET;
case IPv6:
return StandardProtocolFamily.INET6;
default: