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

Add some javadocs

Browse Source
This commit is contained in:
Norman Maurer 2012-12-17 16:01:58 +01:00
parent 3f9441f4c1
commit 39250873ae
8 changed files with 221 additions and 15 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

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

@ -164,7 +164,7 @@ public interface Channel extends AttributeMap, ChannelOutboundInvoker, ChannelPr
* {@code null} if this channel is not connected.
* If this channel is not connected but it can receive messages
* from arbitrary remote addresses (e.g. {@link DatagramChannel},
* use {@link MessageEvent#getRemoteAddress()} to determine
* use {@link io.netty.channel.socket.DatagramPacket#remoteAddress()} to determine
* the origination of the received message as this method will
* return {@code null}.
*/
@ -277,6 +277,11 @@ public interface Channel extends AttributeMap, ChannelOutboundInvoker, ChannelPr
*/
void resumeRead();
/**
* Send a {@link FileRegion} to the remote peer and notify the {@link ChannelFuture} once it completes
* or an error was detected. Once the {@link FileRegion} was transfered or an error was thrown it will
* automaticly closed via {@link io.netty.channel.FileRegion#close()}.
*/
void sendFile(FileRegion region, ChannelFuture future);
}
}

124
transport/src/main/java/io/netty/channel/ChannelOutboundInvoker.java
View File

@ -18,23 +18,147 @@ package io.netty.channel;
import java.net.SocketAddress;
public interface ChannelOutboundInvoker {
/**
* Bind to the given {@link SocketAddress} and notify the {@link ChannelFuture} once the operation completes,
* either because the operation was successful or because of an error.
*/
ChannelFuture bind(SocketAddress localAddress);
/**
* Connect to the given {@link SocketAddress} and notify the {@link ChannelFuture} once the operation completes,
* either because the operation was successful or because of
* an error.
*/
ChannelFuture connect(SocketAddress remoteAddress);
/**
* Connect to the given {@link SocketAddress} while bind to the localAddress and notify the {@link ChannelFuture}
* once the operation completes, either because the operation was successful or because of
* an error.
*/
ChannelFuture connect(SocketAddress remoteAddress, SocketAddress localAddress);
/**
* Discconect from the remote peer and notify the {@link ChannelFuture} once the operation completes,
* either because the operation was successful or because of
* an error.
*/
ChannelFuture disconnect();
/**
* Close this ChannelOutboundInvoker and notify the {@link ChannelFuture} once the operation completes,
* either because the operation was successful or because of
* an error.
*
* After it is closed it is not possible to reuse it again.
*/
ChannelFuture close();
/**
* Deregister this ChannelOutboundInvoker from the previous assigned {@link EventExecutor} and notify the
* {@link ChannelFuture} once the operation completes, either because the operation was successful or because of
* an error.
*
*/
ChannelFuture deregister();
/**
* Flush all pending data which belongs to this ChannelOutboundInvoker and notify the {@link ChannelFuture}
* once the operation completes, either because the operation was successful or because of an error.
*/
ChannelFuture flush();
/**
* Write a message via this ChannelOutboundInvoker and notify the {@link ChannelFuture}
* once the operation completes, either because the operation was successful or because of an error.
*
* If you want to write a {@link FileRegion} use {@link #sendFile(FileRegion)}
*/
ChannelFuture write(Object message);
/**
* Send a {@link FileRegion} via this ChannelOutboundInvoker and notify the {@link ChannelFuture}
* once the operation completes, either because the operation was successful or because of an error.
*/
ChannelFuture sendFile(FileRegion region);
/**
* Bind to the given {@link SocketAddress} and notify the {@link ChannelFuture} once the operation completes,
* either because the operation was successful or because of an error.
*
* The given {@link ChannelFuture} will be notified and also returned.
*/
ChannelFuture bind(SocketAddress localAddress, ChannelFuture future);
/**
* Connect to the given {@link SocketAddress} and notify the {@link ChannelFuture} once the operation completes,
* either because the operation was successful or because of
* an error.
*
* The given {@link ChannelFuture} will be notified and also returned.
*/
ChannelFuture connect(SocketAddress remoteAddress, ChannelFuture future);
/**
* Connect to the given {@link SocketAddress} while bind to the localAddress and notify the {@link ChannelFuture}
* once the operation completes, either because the operation was successful or because of
* an error.
*
* The given {@link ChannelFuture} will be notified and also returned.
*/
ChannelFuture connect(SocketAddress remoteAddress, SocketAddress localAddress, ChannelFuture future);
/**
* Discconect from the remote peer and notify the {@link ChannelFuture} once the operation completes,
* either because the operation was successful or because of
* an error.
*
* The given {@link ChannelFuture} will be notified and also returned.
*/
ChannelFuture disconnect(ChannelFuture future);
/**
* Close this ChannelOutboundInvoker and notify the {@link ChannelFuture} once the operation completes,
* either because the operation was successful or because of
* an error.
*
* After it is closed it is not possible to reuse it again.
* The given {@link ChannelFuture} will be notified and also returned.
*/
ChannelFuture close(ChannelFuture future);
/**
* Deregister this ChannelOutboundInvoker from the previous assigned {@link EventExecutor} and notify the
* {@link ChannelFuture} once the operation completes, either because the operation was successful or because of
* an error.
*
* The given {@link ChannelFuture} will be notified and also returned.
*/
ChannelFuture deregister(ChannelFuture future);
/**
* Flush all pending data which belongs to this ChannelOutboundInvoker and notify the {@link ChannelFuture}
* once the operation completes, either because the operation was successful or because of an error.
*
* The given {@link ChannelFuture} will be notified and also returned.
*/
ChannelFuture flush(ChannelFuture future);
/**
* Write a message via this ChannelOutboundInvoker and notify the {@link ChannelFuture}
* once the operation completes, either because the operation was successful or because of an error.
*
* If you want to write a {@link FileRegion} use {@link #sendFile(FileRegion)}
* The given {@link ChannelFuture} will be notified and also returned.
*/
ChannelFuture write(Object message, ChannelFuture future);
/**
* Send a {@link FileRegion} via this ChannelOutboundInvoker and notify the {@link ChannelFuture}
* once the operation completes, either because the operation was successful or because of an error.
*
* The given {@link ChannelFuture} will be notified and also returned.
*/
ChannelFuture sendFile(FileRegion region, ChannelFuture future);
}

81
transport/src/main/java/io/netty/channel/socket/DatagramChannel.java
View File

@ -23,7 +23,7 @@ import java.net.InetSocketAddress;
import java.net.NetworkInterface;
/**
* A UDP/IP {@link Channel} which is created by {@link DatagramChannelFactory}.
* A UDP/IP {@link Channel}}.
* @apiviz.landmark
* @apiviz.composedOf io.netty.channel.socket.DatagramChannelConfig
*/
@ -35,70 +35,131 @@ public interface DatagramChannel extends Channel {
@Override
InetSocketAddress remoteAddress();
/**
* Return {@code true} if the {@link DatagramChannel} is connected to the remote peer.
*/
boolean isConnected();
/**
* Joins a multicast group.
* Joins a multicast group and notifies the {@link ChannelFuture} once the operation completes.
*/
ChannelFuture joinGroup(InetAddress multicastAddress);
/**
* Joins a multicast group and notifies the {@link ChannelFuture} once the operation completes.
*
* The given {@link ChannelFuture} will be notified and also returned.
*/
ChannelFuture joinGroup(InetAddress multicastAddress, ChannelFuture future);
/**
* Joins the specified multicast group at the specified interface.
* Joins the specified multicast group at the specified interface and notifies the {@link ChannelFuture}
* once the operation completes.
*/
ChannelFuture joinGroup(InetSocketAddress multicastAddress, NetworkInterface networkInterface);
/**
* Joins the specified multicast group at the specified interface and notifies the {@link ChannelFuture}
* once the operation completes.
*
* The given {@link ChannelFuture} will be notified and also returned.
*/
ChannelFuture joinGroup(
InetSocketAddress multicastAddress, NetworkInterface networkInterface, ChannelFuture future);
/**
* Joins the specified multicast group at the specified interface and notifies the {@link ChannelFuture}
* once the operation completes.
*/
ChannelFuture joinGroup(InetAddress multicastAddress, NetworkInterface networkInterface, InetAddress source);
/**
* Joins the specified multicast group at the specified interface and notifies the {@link ChannelFuture}
* once the operation completes.
*
* The given {@link ChannelFuture} will be notified and also returned.
*/
ChannelFuture joinGroup(
InetAddress multicastAddress, NetworkInterface networkInterface, InetAddress source, ChannelFuture future);
/**
* Leaves a multicast group.
* Leaves a multicast group and notifies the {@link ChannelFuture} once the operation completes.
*/
ChannelFuture leaveGroup(InetAddress multicastAddress);
/**
* Leaves a multicast group and notifies the {@link ChannelFuture} once the operation completes.
*
* The given {@link ChannelFuture} will be notified and also returned.
*/
ChannelFuture leaveGroup(InetAddress multicastAddress, ChannelFuture future);
/**
* Leaves a multicast group on a specified local interface.
* Leaves a multicast group on a specified local interface and notifies the {@link ChannelFuture} once the
* operation completes.
*/
ChannelFuture leaveGroup(InetSocketAddress multicastAddress, NetworkInterface networkInterface);
/**
* Leaves a multicast group on a specified local interface and notifies the {@link ChannelFuture} once the
* operation completes.
*
* The given {@link ChannelFuture} will be notified and also returned.
*/
ChannelFuture leaveGroup(
InetSocketAddress multicastAddress, NetworkInterface networkInterface, ChannelFuture future);
/**
* Leave the specified multicast group at the specified interface using the specified source.
* Leave the specified multicast group at the specified interface using the specified source and notifies
* the {@link ChannelFuture} once the operation completes.
*
*/
ChannelFuture leaveGroup(
InetAddress multicastAddress, NetworkInterface networkInterface, InetAddress source);
/**
* Leave the specified multicast group at the specified interface using the specified source and notifies
* the {@link ChannelFuture} once the operation completes.
*
* The given {@link ChannelFuture} will be notified and also returned.
*/
ChannelFuture leaveGroup(
InetAddress multicastAddress, NetworkInterface networkInterface, InetAddress source,
ChannelFuture future);
/**
* Block the given sourceToBlock address for the given multicastAddress on the given networkInterface
* Block the given sourceToBlock address for the given multicastAddress on the given networkInterface and notifies
* the {@link ChannelFuture} once the operation completes.
*
* The given {@link ChannelFuture} will be notified and also returned.
*/
ChannelFuture block(
InetAddress multicastAddress, NetworkInterface networkInterface,
InetAddress sourceToBlock);
/**
* Block the given sourceToBlock address for the given multicastAddress on the given networkInterface
* Block the given sourceToBlock address for the given multicastAddress on the given networkInterface and notifies
* the {@link ChannelFuture} once the operation completes.
*
* The given {@link ChannelFuture} will be notified and also returned.
*/
ChannelFuture block(
InetAddress multicastAddress, NetworkInterface networkInterface,
InetAddress sourceToBlock, ChannelFuture future);
/**
* Block the given sourceToBlock address for the given multicastAddress
* Block the given sourceToBlock address for the given multicastAddress and notifies the {@link ChannelFuture} once
* the operation completes.
*
* The given {@link ChannelFuture} will be notified and also returned.
*/
ChannelFuture block(InetAddress multicastAddress, InetAddress sourceToBlock);
/**
* Block the given sourceToBlock address for the given multicastAddress
* Block the given sourceToBlock address for the given multicastAddress and notifies the {@link ChannelFuture} once
* the operation completes.
*
* The given {@link ChannelFuture} will be notified and also returned.
*/
ChannelFuture block(
InetAddress multicastAddress, InetAddress sourceToBlock, ChannelFuture future);

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

@ -19,6 +19,9 @@ import io.netty.buffer.ByteBuf;
import java.net.InetSocketAddress;
/**
* The message container that is used for {@link DatagramChannel} to communicate with the remote peer.
*/
public class DatagramPacket {
private final ByteBuf data;
@ -36,10 +39,17 @@ public class DatagramPacket {
this.remoteAddress = remoteAddress;
}
/**
* Return the data which is container. May return an empty {@link ByteBuf}
*/
public ByteBuf data() {
return data;
}
/**
* 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;
}

2
transport/src/main/java/io/netty/channel/socket/InternetProtocolFamily.java
View File

@ -16,7 +16,7 @@
package io.netty.channel.socket;
/**
* Internet Protocol (IP) families
* Internet Protocol (IP) families used byte the {@link DatagramChannel}
*/
public enum InternetProtocolFamily {
IPv4,

4
transport/src/main/java/io/netty/channel/socket/SctpChannel.java
View File

@ -85,6 +85,8 @@ public interface SctpChannel extends Channel {
/**
* Bind a address to the already bound channel to enable multi-homing.
* The Channel bust be bound and yet to be connected.
*
* The given {@link ChannelFuture} will be notified and also returned.
*/
ChannelFuture bindAddress(InetAddress localAddress, ChannelFuture future);
@ -97,6 +99,8 @@ public interface SctpChannel extends Channel {
/**
* Unbind the address from channel's multi-homing address list.
* The address should be added already in multi-homing address list.
*
* The given {@link ChannelFuture} will be notified and also returned.
*/
ChannelFuture unbindAddress(InetAddress localAddress, ChannelFuture future);
}

4
transport/src/main/java/io/netty/channel/socket/SctpMessage.java
View File

@ -28,8 +28,7 @@ public final class SctpMessage {
private final int protocolIdentifier;
private final ByteBuf payloadBuffer;
private MessageInfo msgInfo;
private final MessageInfo msgInfo;
/**
* Essential data that is being carried within SCTP Data Chunk
@ -41,6 +40,7 @@ public final class SctpMessage {
this.protocolIdentifier = protocolIdentifier;
this.streamIdentifier = streamIdentifier;
this.payloadBuffer = payloadBuffer;
this.msgInfo = null;
}
public SctpMessage(MessageInfo msgInfo, ByteBuf payloadBuffer) {

2
transport/src/main/java/io/netty/channel/socket/SocketChannel.java
View File

@ -54,6 +54,8 @@ public interface SocketChannel extends Channel {
/**
* @see Socket#shutdownOutput()
*
* Will notify and return the given {@link ChannelFuture}
*/
ChannelFuture shutdownOutput(ChannelFuture future);
}