/*
 *  Licensed to the Apache Software Foundation (ASF) under one or more
 *  contributor license agreements.  See the NOTICE file distributed with
 *  this work for additional information regarding copyright ownership.
 *  The ASF licenses this file to You under the Apache License, Version 2.0
 *  (the "License"); you may not use this file except in compliance with
 *  the License.  You may obtain a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 *  Unless required by applicable law or agreed to in writing, software
 *  distributed under the License is distributed on an "AS IS" BASIS,
 *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 *  See the License for the specific language governing permissions and
 *  limitations under the License.
 */

package java.nio.channels;

import java.io.IOException;
import java.net.Socket;
import java.net.SocketAddress;
import java.nio.ByteBuffer;
import java.nio.channels.spi.AbstractSelectableChannel;
import java.nio.channels.spi.SelectorProvider;

/**
 * A {@code SocketChannel} is a selectable channel that provides a partial
 * abstraction of stream connecting socket. {@code socket()} returns the related
 * {@link Socket} instance which can handle the socket.
 * <p>
 * A socket channel is open but not connected when created by {@code open()}.
 * After connecting it by calling {@code connect(SocketAddress)}, it will remain
 * connected until it gets closed. If the connection is non-blocking then
 * {@code connect(SocketAddress)} is used to initiate the connection, followed
 * by a call of {@code finishConnect()} to perform the final steps of
 * connecting. {@code isConnectionPending()} indicates if the connection is
 * blocked or not; {@code isConnected()} indicates if the socket is finally
 * connected or not.
 * <p>
 * The input and output sides of a channel can be shut down independently and
 * asynchronously without closing the channel. The {@code shutdownInput} method
 * is used for the input side of a channel and subsequent read operations return
 * -1, which means end of stream. If another thread is blocked in a read
 * operation when the shutdown occurs, the read will end without effect and
 * return end of stream. The {@code shutdownOutput} method is used for the
 * output side of the channel; subsequent write operations throw a
 * {@link ClosedChannelException}. If the output is shut down and another thread
 * is blocked in a write operation, an {@link AsynchronousCloseException} will
 * be thrown to the pending thread.
 * <p>
 * Socket channels are thread-safe, no more than one thread can read or write at
 * any given time. The {@code connect(SocketAddress)} and {@code
 * finishConnect()} methods are synchronized against each other; when they are
 * processing, calls to {@code read} and {@code write} will block.
 */
public abstract class SocketChannel extends AbstractSelectableChannel implements
        ByteChannel, ScatteringByteChannel, GatheringByteChannel {

    /**
     * Constructs a new {@code SocketChannel}.
     *
     * @param selectorProvider
     *            an instance of SelectorProvider.
     */
    protected SocketChannel(SelectorProvider selectorProvider) {
        super(selectorProvider);
    }

    /**
     * Creates an open and unconnected socket channel.
     * <p>
     * This channel is created by calling {@code openSocketChannel()} of the
     * default {@link SelectorProvider} instance.
     *
     * @return the new channel which is open but unconnected.
     * @throws IOException
     *             if an I/O error occurs.
     */
    public static SocketChannel open() throws IOException {
        return SelectorProvider.provider().openSocketChannel();
    }

    /**
     * Creates a socket channel and connects it to a socket address.
     * <p>
     * This method performs a call to {@code open()} followed by a call to
     * {@code connect(SocketAddress)}.
     *
     * @param address
     *            the socket address to be connected to.
     * @return the new connected channel.
     * @throws AsynchronousCloseException
     *             if this channel is closed by another thread while this method
     *             is executing.
     * @throws ClosedByInterruptException
     *             if another thread interrupts the calling thread while this
     *             operation is executing. The calling thread will have the
     *             interrupt state set and the channel will be closed.
     * @throws UnresolvedAddressException
     *             if the address is not resolved.
     * @throws UnsupportedAddressTypeException
     *             if the address type is not supported.
     * @throws IOException
     *             if an I/O error occurs.
     */
    public static SocketChannel open(SocketAddress address) throws IOException {
        SocketChannel socketChannel = open();
        if (socketChannel != null) {
            socketChannel.connect(address);
        }
        return socketChannel;
    }

    /**
     * Gets the valid operations of this channel. Socket channels support
     * connect, read and write operation, so this method returns
     * {@code SelectionKey.OP_CONNECT | SelectionKey.OP_READ | SelectionKey.OP_WRITE}.
     *
     * @return the operations supported by this channel.
     * @see java.nio.channels.SelectableChannel#validOps()
     */
    @Override
    public final int validOps() {
        return (SelectionKey.OP_CONNECT | SelectionKey.OP_READ | SelectionKey.OP_WRITE);
    }

    /**
     * Returns the socket assigned to this channel, which does not declare any public
     * methods that are not declared in {@code Socket}.
     *
     * @return the socket assigned to this channel.
     */
    public abstract Socket socket();

    /**
     * Indicates whether this channel's socket is connected.
     *
     * @return {@code true} if this channel's socket is connected, {@code false}
     *         otherwise.
     */
    public abstract boolean isConnected();

    /**
     * Indicates whether this channel's socket is still trying to connect.
     *
     * @return {@code true} if the connection is initiated but not finished;
     *         {@code false} otherwise.
     */
    public abstract boolean isConnectionPending();

    /**
     * Connects this channel's socket with a remote address.
     * <p>
     * If this channel is blocking, this method will suspend until connecting is
     * finished or an I/O exception occurs. If the channel is non-blocking,
     * this method will return {@code true} if the connection is finished at
     * once or return {@code false} when the connection must be finished later
     * by calling {@code finishConnect()}.
     * <p>
     * This method can be called at any moment and can block other read and
     * write operations while connecting. It executes the same security checks
     * as the connect method of the {@code Socket} class.
     *
     * @param address
     *            the address to connect with.
     * @return {@code true} if the connection is finished, {@code false}
     *         otherwise.
     * @throws AlreadyConnectedException
     *             if the channel is already connected.
     * @throws ConnectionPendingException
     *             a non-blocking connecting operation is already executing on
     *             this channel.
     * @throws ClosedChannelException
     *             if this channel is closed.
     * @throws AsynchronousCloseException
     *             if this channel is closed by another thread while this method
     *             is executing.
     * @throws ClosedByInterruptException
     *             if another thread interrupts the calling thread while this
     *             operation is in progress. The calling thread will have the
     *             interrupt state set and this channel will be closed.
     * @throws UnresolvedAddressException
     *             if the address is not resolved.
     * @throws UnsupportedAddressTypeException
     *             if the address type is not supported.
     * @throws IOException
     *             if an I/O error occurs.
     */
    public abstract boolean connect(SocketAddress address) throws IOException;

    /**
     * Completes the connection process initiated by a call of {@code
     * connect(SocketAddress)}.
     * <p>
     * This method returns {@code true} if the connection is finished already
     * and returns {@code false} if the channel is non-blocking and the
     * connection is not finished yet.
     * <p>
     * If this channel is in blocking mode, this method will suspend and return
     * {@code true} when the connection is finished. It closes this channel and
     * throws an exception if the connection fails.
     * <p>
     * This method can be called at any moment and it can block other {@code
     * read} and {@code write} operations while connecting.
     *
     * @return {@code true} if the connection is successfully finished, {@code
     *         false} otherwise.
     * @throws NoConnectionPendingException
     *             if the channel is not connected and the connection process
     *             has not been initiated.
     * @throws ClosedChannelException
     *             if this channel is closed.
     * @throws AsynchronousCloseException
     *             if this channel is closed by another thread while this method
     *             is executing.
     * @throws ClosedByInterruptException
     *             if another thread interrupts the calling thread while this
     *             operation is in progress. The calling thread has the
     *             interrupt state set, and this channel is closed.
     * @throws IOException
     *             if an I/O error occurs.
     */
    public abstract boolean finishConnect() throws IOException;

    /**
     * Reads bytes from this socket channel into the given buffer.
     * <p>
     * The maximum number of bytes that will be read is the remaining number of
     * bytes in the buffer when the method is invoked. The bytes will be copied
     * into the buffer starting at the buffer's current position.
     * <p>
     * The call may block if other threads are also attempting to read from this
     * channel.
     * <p>
     * Upon completion, the buffer's position is set to the end of the bytes
     * that have been read. The buffer's limit is not changed.
     *
     * @param target
     *            the byte buffer to receive the bytes.
     * @return the number of bytes actually read.
     * @throws AsynchronousCloseException
     *             if another thread closes the channel during the read.
     * @throws NotYetConnectedException
     *             if this channel is not yet connected.
     * @throws ClosedByInterruptException
     *             if another thread interrupts the calling thread while this
     *             operation is in progress. The interrupt state of the calling
     *             thread is set and the channel is closed.
     * @throws ClosedChannelException
     *             if this channel is closed.
     * @throws IOException
     *             if another I/O error occurs.
     * @see java.nio.channels.ReadableByteChannel#read(java.nio.ByteBuffer)
     */
    public abstract int read(ByteBuffer target) throws IOException;

    /**
     * Reads bytes from this socket channel into a subset of the given buffers.
     * This method attempts to read all {@code remaining()} bytes from {@code
     * length} byte buffers, in order, starting at {@code targets[offset]}. The
     * number of bytes actually read is returned.
     * <p>
     * If a read operation is in progress, subsequent threads will block until
     * the read is completed and will then contend for the ability to read.
     *
     * @param targets
     *            the array of byte buffers into which the bytes will be copied.
     * @param offset
     *            the index of the first buffer to store bytes in.
     * @param length
     *            the maximum number of buffers to store bytes in.
     * @return the number of bytes actually read.
     * @throws AsynchronousCloseException
     *             if this channel is closed by another thread during this read
     *             operation.
     * @throws ClosedByInterruptException
     *             if another thread interrupts the calling thread while this
     *             operation is in progress. The interrupt state of the calling
     *             thread is set and the channel is closed.
     * @throws ClosedChannelException
     *             if this channel is closed.
     * @throws IndexOutOfBoundsException
     *             if {@code offset < 0} or {@code length < 0}, or if {@code
     *             offset + length} is greater than the size of {@code targets}.
     * @throws IOException
     *             if another I/O error occurs.
     * @throws NotYetConnectedException
     *             if this channel is not yet connected.
     * @see java.nio.channels.ScatteringByteChannel#read(java.nio.ByteBuffer[],
     *      int, int)
     */
    public abstract long read(ByteBuffer[] targets, int offset, int length) throws IOException;

    /**
     * Reads bytes from this socket channel and stores them in the specified
     * array of buffers. This method attempts to read as many bytes as can be
     * stored in the buffer array from this channel and returns the number of
     * bytes actually read.
     * <p>
     * If a read operation is in progress, subsequent threads will block until
     * the read is completed and will then contend for the ability to read.
     * <p>
     * Calling this method is equivalent to calling {@code read(targets, 0,
     * targets.length);}
     *
     * @param targets
     *            the array of byte buffers into which the bytes will be copied.
     * @return the number of bytes actually read.
     * @throws AsynchronousCloseException
     *             if this channel is closed by another thread during this read
     *             operation.
     * @throws ClosedByInterruptException
     *             if another thread interrupts the calling thread while this
     *             operation is in progress. The interrupt state of the calling
     *             thread is set and the channel is closed.
     * @throws ClosedChannelException
     *             if this channel is closed.
     * @throws IOException
     *             if another I/O error occurs.
     * @throws NotYetConnectedException
     *             if this channel is not yet connected.
     */
    public synchronized final long read(ByteBuffer[] targets) throws IOException {
        return read(targets, 0, targets.length);
    }

    /**
     * Writes bytes from the given byte buffer to this socket channel. The
     * maximum number of bytes that are written is the remaining number of bytes
     * in the buffer when this method is invoked. The bytes are taken from the
     * buffer starting at the buffer's position.
     * <p>
     * The call may block if other threads are also attempting to write to the
     * same channel.
     * <p>
     * Upon completion, the buffer's position is updated to the end of the bytes
     * that have been written. The buffer's limit is not changed.
     *
     * @param source
     *            the byte buffer containing the bytes to be written.
     * @return the number of bytes actually written.
     * @throws AsynchronousCloseException
     *             if another thread closes the channel during the write.
     * @throws ClosedByInterruptException
     *             if another thread interrupts the calling thread while this
     *             operation is in progress. The interrupt state of the calling
     *             thread is set and the channel is closed.
     * @throws ClosedChannelException
     *             if the channel was already closed.
     * @throws IOException
     *             if another I/O error occurs.
     * @throws NotYetConnectedException
     *             if this channel is not connected yet.
     * @see java.nio.channels.WritableByteChannel#write(java.nio.ByteBuffer)
     */
    public abstract int write(ByteBuffer source) throws IOException;

    /**
     * Attempts to write a subset of the given bytes from the buffers to this
     * socket channel. This method attempts to write all {@code remaining()}
     * bytes from {@code length} byte buffers, in order, starting at {@code
     * sources[offset]}. The number of bytes actually written is returned.
     * <p>
     * If a write operation is in progress, subsequent threads will block until
     * the write is completed and then contend for the ability to write.
     *
     * @param sources
     *            the array of byte buffers that is the source for bytes written
     *            to this channel.
     * @param offset
     *            the index of the first buffer in {@code buffers }to get bytes
     *            from.
     * @param length
     *            the number of buffers to get bytes from.
     * @return the number of bytes actually written to this channel.
     * @throws AsynchronousCloseException
     *             if this channel is closed by another thread during this write
     *             operation.
     * @throws ClosedByInterruptException
     *             if another thread interrupts the calling thread while this
     *             operation is in progress. The interrupt state of the calling
     *             thread is set and the channel is closed.
     * @throws ClosedChannelException
     *             if this channel is closed.
     * @throws IndexOutOfBoundsException
     *             if {@code offset < 0} or {@code length < 0}, or if {@code
     *             offset + length} is greater than the size of {@code sources}.
     * @throws IOException
     *             if another I/O error occurs.
     * @throws NotYetConnectedException
     *             if this channel is not yet connected.
     * @see java.nio.channels.GatheringByteChannel#write(java.nio.ByteBuffer[],
     *      int, int)
     */
    public abstract long write(ByteBuffer[] sources, int offset, int length) throws IOException;

    /**
     * Writes bytes from all the given byte buffers to this socket channel.
     * <p>
     * Calling this method is equivalent to calling {@code write(sources, 0,
     * sources.length);}
     *
     * @param sources
     *            the buffers containing bytes to write.
     * @return the number of bytes actually written.
     * @throws AsynchronousCloseException
     *             if this channel is closed by another thread during this write
     *             operation.
     * @throws ClosedByInterruptException
     *             if another thread interrupts the calling thread while this
     *             operation is in progress. The interrupt state of the calling
     *             thread is set and the channel is closed.
     * @throws ClosedChannelException
     *             if this channel is closed.
     * @throws IOException
     *             if another I/O error occurs.
     * @throws NotYetConnectedException
     *             if this channel is not yet connected.
     * @see java.nio.channels.GatheringByteChannel#write(java.nio.ByteBuffer[])
     */
    public synchronized final long write(ByteBuffer[] sources) throws IOException {
        return write(sources, 0, sources.length);
    }
}