(dc) Clarify implicit bind behavior of DatagramChannel

Summary

The DatagramChannel connect, send, and receive methods may implicitly bind the channel, if not already bound. If a security manager has been installed and its checkListen method denies the operation, a SecurityException will be thrown. This behaviour is not described in the javadoc.

Problem

The current spec of DatagramChannel connect, receive, and send methods do not list all the cases in which a SecurityException might be thrown. In particular, the fact that a permission check is performed in case an implicit bind occurs is not documented. In practice, an implicit bind operation is unlikely to fail as binding using port 0 is part of the permissions granted by default. However the case may arise if a custom security manager overriding the SecurityManager::checkListen method has been installed.

Solution

Update the spec to make it clear that SecurityException can be thrown if a security manager's checkListen call denies the operation.

Specification

DatagramChannel::connect

      * @throws  SecurityException
-     *          If a security manager has been installed
-     *          and it does not permit access to the given remote address
+     *          If a security manager has been installed and it does not
+     *          permit access to the given remote address, or if unbound,
+     *          the security manager {@link SecurityManager#checkListen checkListen}
+     *          method denies the operation
      *
      * @throws  IOException
      *          If some other I/O error occurs
      */
     public abstract DatagramChannel connect(SocketAddress remote)

DatagramChannel::receive

+     * @throws  SecurityException
+     *          If unbound, and a security manager has been installed and
+     *          its {@link SecurityManager#checkListen checkListen} method
+     *          denies the operation
+     *
      * @throws  IOException
      *          If some other I/O error occurs
      */
     public abstract SocketAddress receive(ByteBuffer dst) throws IOException;

DatagramChannel::send

      * @throws  SecurityException
-     *          If a security manager has been installed
-     *          and it does not permit datagrams to be sent
-     *          to the given address
+     *          If a security manager has been installed and it does not permit
+     *          datagrams to be sent to the given address, or if unbound, and
+     *          the security manager's {@link SecurityManager#checkListen checkListen}
+     *          method denies the operation
      *
      * @throws  IOException
      *          If some other I/O error occurs
      */
     public abstract int send(ByteBuffer src, SocketAddress target)