|
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 |
|
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. |
|
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 } |