/*
 * ====================================================================
 * 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.
 * ====================================================================
 *
 * This software consists of voluntary contributions made by many
 * individuals on behalf of the Apache Software Foundation.  For more
 * information on the Apache Software Foundation, please see
 * <http://www.apache.org/>.
 *
 */

package org.apache.http.nio.reactor;

import java.net.SocketAddress;
import java.nio.channels.ByteChannel;

IOSession interface represents a sequence of logically related data exchanges
between two end points.

The channel associated with implementations of this interface can be used to
read data from and write data to the session.

I/O sessions are not bound to an execution thread, therefore one cannot use
the context of the thread to store a session's state. All details about
a particular session must be stored within the session itself, usually
using execution context associated with it.

Implementations of this interface are expected to be threading safe.
Since:
4.0/**
 * IOSession interface represents a sequence of logically related data exchanges
 * between two end points.
 * <p>
 * The channel associated with implementations of this interface can be used to
 * read data from and write data to the session.
 * <p>
 * I/O sessions are not bound to an execution thread, therefore one cannot use
 * the context of the thread to store a session's state. All details about
 * a particular session must be stored within the session itself, usually
 * using execution context associated with it.
 * <p>
 * Implementations of this interface are expected to be threading safe.
 *
 * @since 4.0
 */
public interface IOSession {

    
Name of the context attribute key, which can be used to obtain the
session attachment object.
/**
     * Name of the context attribute key, which can be used to obtain the
     * session attachment object.
     */
    public static final String ATTACHMENT_KEY = "http.session.attachment";

    public static final int ACTIVE       = 0;
    public static final int CLOSING      = 1;
    public static final int CLOSED       = Integer.MAX_VALUE;

    
Returns the underlying I/O channel associated with this session.
Returns:
the I/O channel./**
     * Returns the underlying I/O channel associated with this session.
     *
     * @return the I/O channel.
     */
    ByteChannel channel();

    
Returns address of the remote peer.
Returns:
socket address./**
     * Returns address of the remote peer.
     *
     * @return socket address.
     */
    SocketAddress getRemoteAddress();

    
Returns local address.
Returns:
socket address./**
     * Returns local address.
     *
     * @return socket address.
     */
    SocketAddress getLocalAddress();

    
Returns mask of I/O evens this session declared interest in.
Returns:
I/O event mask./**
     * Returns mask of I/O evens this session declared interest in.
     *
     * @return I/O event mask.
     */
    int getEventMask();

    
Declares interest in I/O event notifications by setting the event mask
associated with the session
Params:
ops – new I/O event mask./**
     * Declares interest in I/O event notifications by setting the event mask
     * associated with the session
     *
     * @param ops new I/O event mask.
     */
    void setEventMask(int ops);

    
Declares interest in a particular I/O event type by updating the event
mask associated with the session.
Params:
op – I/O event type./**
     * Declares interest in a particular I/O event type by updating the event
     * mask associated with the session.
     *
     * @param op I/O event type.
     */
    void setEvent(int op);

    
Clears interest in a particular I/O event type by updating the event
mask associated with the session.
Params:
op – I/O event type./**
     * Clears interest in a particular I/O event type by updating the event
     * mask associated with the session.
     *
     * @param op I/O event type.
     */
    void clearEvent(int op);

    
Terminates the session gracefully and closes the underlying I/O channel.
This method ensures that session termination handshake, such as the one
used by the SSL/TLS protocol, is correctly carried out.
/**
     * Terminates the session gracefully and closes the underlying I/O channel.
     * This method ensures that session termination handshake, such as the one
     * used by the SSL/TLS protocol, is correctly carried out.
     */
    void close();

    
Terminates the session by shutting down the underlying I/O channel.
/**
     * Terminates the session by shutting down the underlying I/O channel.
     */
    void shutdown();

    
Returns status of the session:
 ACTIVE: session is active. 
 CLOSING: session is being closed. 
 CLOSED: session has been terminated. 
Returns:
session status./**
     * Returns status of the session:
     * <p>
     * {@link #ACTIVE}: session is active.
     * <p>
     * {@link #CLOSING}: session is being closed.
     * <p>
     * {@link #CLOSED}: session has been terminated.
     *
     * @return session status.
     */
    int getStatus();

    
Determines if the session has been terminated.
Returns:
true if the session has been terminated, false otherwise./**
     * Determines if the session has been terminated.
     *
     * @return {@code true} if the session has been terminated,
     *   {@code false} otherwise.
     */
    boolean isClosed();

    
Returns value of the socket timeout in milliseconds. The value of 0 signifies the session cannot time out. 
Returns:
socket timeout./**
     * Returns value of the socket timeout in milliseconds. The value of
     * {@code 0} signifies the session cannot time out.
     *
     * @return socket timeout.
     */
    int getSocketTimeout();

    
Sets value of the socket timeout in milliseconds. The value of 0 signifies the session cannot time out. 
Params:
timeout – socket timeout./**
     * Sets value of the socket timeout in milliseconds. The value of
     * {@code 0} signifies the session cannot time out.
     *
     * @param timeout socket timeout.
     */
    void setSocketTimeout(int timeout);

    
Quite often I/O sessions need to maintain internal I/O buffers in order
to transform input / output data prior to returning it to the consumer or
writing it to the underlying channel. Memory management in HttpCore NIO
is based on the fundamental principle that the data consumer can read
only as much input data as it can process without having to allocate more
memory. That means, quite often some input data may remain unread in one
of the internal or external session buffers. The I/O reactor can query
the status of these session buffers, and make sure the consumer gets
notified correctly as more data gets stored in one of the session
buffers, thus allowing the consumer to read the remaining data once it
is able to process it
 I/O sessions can be made aware of the status of external session buffers using the SessionBufferStatus interface. /**
     * Quite often I/O sessions need to maintain internal I/O buffers in order
     * to transform input / output data prior to returning it to the consumer or
     * writing it to the underlying channel. Memory management in HttpCore NIO
     * is based on the fundamental principle that the data consumer can read
     * only as much input data as it can process without having to allocate more
     * memory. That means, quite often some input data may remain unread in one
     * of the internal or external session buffers. The I/O reactor can query
     * the status of these session buffers, and make sure the consumer gets
     * notified correctly as more data gets stored in one of the session
     * buffers, thus allowing the consumer to read the remaining data once it
     * is able to process it
     * <p>
     * I/O sessions can be made aware of the status of external session buffers
     * using the {@link SessionBufferStatus} interface.
     */
    void setBufferStatus(SessionBufferStatus status);

    
Determines if the input buffer associated with the session contains data.
Returns:
true if the session input buffer contains data, false otherwise./**
     * Determines if the input buffer associated with the session contains data.
     *
     * @return {@code true} if the session input buffer contains data,
     *   {@code false} otherwise.
     */
    boolean hasBufferedInput();

    
Determines if the output buffer associated with the session contains
data.
Returns:
true if the session output buffer contains data, false otherwise./**
     * Determines if the output buffer associated with the session contains
     * data.
     *
     * @return {@code true} if the session output buffer contains data,
     *   {@code false} otherwise.
     */
    boolean hasBufferedOutput();

    
This method can be used to associate a particular object with the
session by the given attribute name.

I/O sessions are not bound to an execution thread, therefore one cannot
use the context of the thread to store a session's state. All details
about a particular session must be stored within the session itself.
Params:
name – name of the attribute.
obj – value of the attribute./**
     * This method can be used to associate a particular object with the
     * session by the given attribute name.
     * <p>
     * I/O sessions are not bound to an execution thread, therefore one cannot
     * use the context of the thread to store a session's state. All details
     * about a particular session must be stored within the session itself.
     *
     * @param name name of the attribute.
     * @param obj value of the attribute.
     */
    void setAttribute(String name, Object obj);

    
Returns the value of the attribute with the given name. The value can be null if not set. 
 The value of the session attachment object can be obtained using ATTACHMENT_KEY name. 
Params:
name – name of the attribute.
See Also:
setAttribute(String, Object)
Returns:
value of the attribute./**
     * Returns the value of the attribute with the given name. The value can be
     * {@code null} if not set.
     * <p>
     * The value of the session attachment object can be obtained using
     * {@link #ATTACHMENT_KEY} name.
     *
     * @see #setAttribute(String, Object)
     *
     * @param name name of the attribute.
     * @return value of the attribute.
     */
    Object getAttribute(String name);

    
Removes attribute with the given name.
Params:
name – name of the attribute to be removed.
See Also:
setAttribute(String, Object)
Returns:
value of the removed attribute./**
     * Removes attribute with the given name.
     *
     * @see #setAttribute(String, Object)
     *
     * @param name name of the attribute to be removed.
     * @return value of the removed attribute.
     */
    Object removeAttribute(String name);

}