From ca19f4cdde81e0ad08cd6561a74c138f7b5465b3 Mon Sep 17 00:00:00 2001
From: Trustin Lee <trustin@gmail.com>
Date: Tue, 21 Jul 2009 09:12:28 +0000
Subject: [PATCH] More documentation on Channel.write() and connectionless
 channels

---
 src/main/java/org/jboss/netty/channel/Channel.java | 12 ++++++++++--
 1 file changed, 10 insertions(+), 2 deletions(-)

diff --git a/src/main/java/org/jboss/netty/channel/Channel.java b/src/main/java/org/jboss/netty/channel/Channel.java
index b6e2f669b1..b8ffe25f1e 100644
--- a/src/main/java/org/jboss/netty/channel/Channel.java
+++ b/src/main/java/org/jboss/netty/channel/Channel.java
@@ -168,7 +168,11 @@ public interface Channel extends Comparable<Channel>{
     SocketAddress getRemoteAddress();
 
     /**
-     * Sends a message to this channel asynchronously.
+     * Sends a message to this channel asynchronously.    If this channel was
+     * created by a connectionless transport (e.g. {@link DatagramChannel})
+     * and is not connected yet, you call {@link #write(Object, SocketAddress)}
+     * instead.  Otherwise, the write request will fail and an
+     * {@code 'exceptionCaught'} event will be triggered.
      *
      * @param message the message to write
      *
@@ -182,7 +186,11 @@ public interface Channel extends Comparable<Channel>{
     /**
      * Sends a message to this channel asynchronously.  It has an additional
      * parameter that allows a user to specify where to send the specified
-     * message instead of this channel's current remote address.
+     * message instead of this channel's current remote address.  If this
+     * channel was created by a connectionless transport (e.g. {@link DatagramChannel})
+     * and is not connected yet, you must specify non-null address.  Otherwise,
+     * the write request will fail and an {@code 'exceptionCaught'} will be
+     * triggered.
      *
      * @param message       the message to write
      * @param remoteAddress where to send the specified message.