1 /*

     2  * Copyright 2007-2008 Sun Microsystems, Inc.  All Rights Reserved.

     3  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.

     4  *

     5  * This code is free software; you can redistribute it and/or modify it

     6  * under the terms of the GNU General Public License version 2 only, as

     7  * published by the Free Software Foundation.  Sun designates this

     8  * particular file as subject to the "Classpath" exception as provided

     9  * by Sun in the LICENSE file that accompanied this code.

    10  *

    11  * This code is distributed in the hope that it will be useful, but WITHOUT

    12  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or

    13  * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License

    14  * version 2 for more details (a copy is included in the LICENSE file that

    15  * accompanied this code).

    16  *

    17  * You should have received a copy of the GNU General Public License version

    18  * 2 along with this work; if not, write to the Free Software Foundation,

    19  * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.

    20  *

    21  * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,

    22  * CA 95054 USA or visit www.sun.com if you need additional information or

    23  * have any questions.

    24  */

    25 

    26 package java.nio.channels;

    27 

    28 import java.net.SocketOption;

    29 import java.net.SocketAddress;

    30 import java.util.Set;

    31 import java.io.IOException;

    32 

    33 /**

    34  * A channel to a network socket.

    35  *

    36  * <p> A channel that implements this interface is a channel to a network

    37  * socket. The {@link #bind(SocketAddress) bind} method is used to bind the

    38  * socket to a local {@link SocketAddress address}, the {@link #getLocalAddress()

    39  * getLocalAddress} method returns the address that the socket is bound to, and

    40  * the {@link #setOption(SocketOption,Object) setOption} and {@link

    41  * #getOption(SocketOption) getOption} methods are used to set and query socket

    42  * options.  An implementation of this interface should specify the socket options

    43  * that it supports.

    44  *

    45  * <p> The {@link #bind bind} and {@link #setOption setOption} methods that do

    46  * not otherwise have a value to return are specified to return the network

    47  * channel upon which they are invoked. This allows method invocations to be

    48  * chained. Implementations of this interface should specialize the return type

    49  * so that method invocations on the implementation class can be chained.

    50  *

    51  * @since 1.7

    52  */

    53 

    54 public interface NetworkChannel

    55     extends Channel

    56 {

    57     /**

    58      * Binds the channel's socket to a local address.

    59      *

    60      * <p> This method is used to establish an association between the socket and

    61      * a local address. Once an association is established then the socket remains

    62      * bound until the channel is closed. If the {@code local} parameter has the

    63      * value {@code null} then the socket will be bound to an address that is

    64      * assigned automatically.

    65      *

    66      * @param   local

    67      *          The address to bind the socket, or {@code null} to bind the socket

    68      *          to an automatically assigned socket address

    69      *

    70      * @return  This channel

    71      *

    72      * @throws  AlreadyBoundException

    73      *          If the socket is already bound

    74      * @throws  UnsupportedAddressTypeException

    75      *          If the type of the given address is not supported

    76      * @throws  ClosedChannelException

    77      *          If the channel is closed

    78      * @throws  IOException

    79      *          If some other I/O error occurs

    80      * @throws  SecurityException

    81      *          If a security manager is installed and it denies an unspecified

    82      *          permission. An implementation of this interface should specify

    83      *          any required permissions.

    84      *

    85      * @see #getLocalAddress

    86      */

    87     NetworkChannel bind(SocketAddress local) throws IOException;

    88 

    89     /**

    90      * Returns the socket address that this channel's socket is bound to, or

    91      * {@code null} if the socket is not bound.

    92      *

    93      * <p> Where the channel is {@link #bind bound} to an Internet Protocol

    94      * socket address then the return value from this method is of type {@link

    95      * java.net.InetSocketAddress}.

    96      *

    97      * @return  The socket address that the socket is bound to, or {@code null}

    98      *          if the channel is not {@link #isOpen open} or the channel's socket

    99      *          is not bound

   100      *

   101      * @throws  IOException

   102      *          If an I/O error occurs

   103      */

   104     SocketAddress getLocalAddress() throws IOException;

   105 

   106     /**

   107      * Sets the value of a socket option.

   108      *

   109      * @param   name

   110      *          The socket option

   111      * @param   value

   112      *          The value of the socket option. A value of {@code null} may be

   113      *          a valid value for some socket options.

   114      *

   115      * @return  This channel

   116      *

   117      * @throws  IllegalArgumentException

   118      *          If the socket option is not supported by this channel, or

   119      *          the value is not a valid value for this socket option

   120      * @throws  ClosedChannelException

   121      *          If this channel is closed

   122      * @throws  IOException

   123      *          If an I/O error occurs

   124      *

   125      * @see java.net.StandardSocketOption

   126      */

   127     <T> NetworkChannel setOption(SocketOption<T> name, T value) throws IOException;

   128 

   129     /**

   130      * Returns the value of a socket option.

   131      *

   132      * @param   name

   133      *          The socket option

   134      *

   135      * @return  The value of the socket option. A value of {@code null} may be

   136      *          a valid value for some socket options.

   137      *

   138      * @throws  IllegalArgumentException

   139      *          If the socket option is not supported by this channel

   140      * @throws  ClosedChannelException

   141      *          If this channel is closed

   142      * @throws  IOException

   143      *          If an I/O error occurs

   144      *

   145      * @see java.net.StandardSocketOption

   146      */

   147     <T> T getOption(SocketOption<T> name) throws IOException;

   148 

   149     /**

   150      * Returns a set of the socket options supported by this channel.

   151      *

   152      * <p> This method will continue to return the set of options even after the

   153      * channel has been closed.

   154      *

   155      * @return  A set of the socket options supported by this channel

   156      */

   157     Set<SocketOption<?>> options();

   158 }