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 */ bind(SocketAddress local)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 */ getLocalAddress()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 */ setOption(SocketOption<T> name, T value)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 */ getOption(SocketOption<T> name)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 */ supportedOptions()162 Set<SocketOption<?>> supportedOptions(); 163 } 164