1/*
2 * Copyright (c) 2007, 2013, Oracle and/or its affiliates. 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.  Oracle designates this
8 * particular file as subject to the "Classpath" exception as provided
9 * by Oracle 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 Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22 * or visit www.oracle.com if you need additional information or have any
23 * questions.
24 */
25
26package java.nio.channels;
27
28import java.net.SocketOption;
29import java.net.SocketAddress;
30import java.util.Set;
31import 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
54public 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.
91     *
92     * <p> Where the channel is {@link #bind bound} to an Internet Protocol
93     * socket address then the return value from this method is of type {@link
94     * java.net.InetSocketAddress}.
95     *
96     * @return  The socket address that the socket is bound to, or {@code null}
97     *          if the channel's socket is not bound
98     *
99     * @throws  ClosedChannelException
100     *          If the channel is closed
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   <T>
110     *          The type of the socket option value
111     * @param   name
112     *          The socket option
113     * @param   value
114     *          The value of the socket option. A value of {@code null} may be
115     *          a valid value for some socket options.
116     *
117     * @return  This channel
118     *
119     * @throws  UnsupportedOperationException
120     *          If the socket option is not supported by this channel
121     * @throws  IllegalArgumentException
122     *          If the value is not a valid value for this socket option
123     * @throws  ClosedChannelException
124     *          If this channel is closed
125     * @throws  IOException
126     *          If an I/O error occurs
127     *
128     * @see java.net.StandardSocketOptions
129     */
130    <T> NetworkChannel setOption(SocketOption<T> name, T value) throws IOException;
131
132    /**
133     * Returns the value of a socket option.
134     *
135     * @param   <T>
136     *          The type of the socket option value
137     * @param   name
138     *          The socket option
139     *
140     * @return  The value of the socket option. A value of {@code null} may be
141     *          a valid value for some socket options.
142     *
143     * @throws  UnsupportedOperationException
144     *          If the socket option is not supported by this channel
145     * @throws  ClosedChannelException
146     *          If this channel is closed
147     * @throws  IOException
148     *          If an I/O error occurs
149     *
150     * @see java.net.StandardSocketOptions
151     */
152    <T> T getOption(SocketOption<T> name) throws IOException;
153
154    /**
155     * Returns a set of the socket options supported by this channel.
156     *
157     * <p> This method will continue to return the set of options even after the
158     * channel has been closed.
159     *
160     * @return  A set of the socket options supported by this channel
161     */
162    Set<SocketOption<?>> supportedOptions();
163}
164