org.apache.mina.core.session.IoSession Maven / Gradle / Ivy
/*
* 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 org.apache.mina.core.session;
import java.net.SocketAddress;
import java.util.Set;
import org.apache.mina.core.filterchain.IoFilter;
import org.apache.mina.core.filterchain.IoFilterChain;
import org.apache.mina.core.future.CloseFuture;
import org.apache.mina.core.future.ReadFuture;
import org.apache.mina.core.future.WriteFuture;
import org.apache.mina.core.service.IoAcceptor;
import org.apache.mina.core.service.IoConnector;
import org.apache.mina.core.service.IoHandler;
import org.apache.mina.core.service.IoService;
import org.apache.mina.core.service.TransportMetadata;
import org.apache.mina.core.write.WriteRequest;
import org.apache.mina.core.write.WriteRequestQueue;
/**
*
* A handle which represents connection between two end-points regardless of
* transport types.
*
*
* {@link IoSession} provides user-defined attributes. User-defined attributes
* are application-specific data which are associated with a session.
* It often contains objects that represents the state of a higher-level protocol
* and becomes a way to exchange data between filters and handlers.
*
* Adjusting Transport Type Specific Properties
*
* You can simply downcast the session to an appropriate subclass.
*
* Thread Safety
*
* {@link IoSession} is thread-safe. But please note that performing
* more than one {@link #write(Object)} calls at the same time will
* cause the {@link IoFilter#filterWrite(IoFilter.NextFilter,IoSession,WriteRequest)}
* to be executed simultaneously, and therefore you have to make sure the
* {@link IoFilter} implementations you're using are thread-safe, too.
*
* Equality of Sessions
* TODO : The getId() method is totally wrong. We can't base
* a method which is designed to create a unique ID on the hashCode method.
* {@link Object#equals(Object)} and {@link Object#hashCode()} shall not be overriden
* to the default behavior that is defined in {@link Object}.
*
* @author Apache MINA Project
*/
public interface IoSession {
/**
* @return a unique identifier for this session. Every session has its own
* ID which is different from each other.
*
* TODO : The way it's implemented does not guarantee that the contract is
* respected. It uses the HashCode() method which don't guarantee the key
* unicity.
*/
long getId();
/**
* @return the {@link IoService} which provides I/O service to this session.
*/
IoService getService();
/**
* @return the {@link IoHandler} which handles this session.
*/
IoHandler getHandler();
/**
* @return the configuration of this session.
*/
IoSessionConfig getConfig();
/**
* @return the filter chain that only affects this session.
*/
IoFilterChain getFilterChain();
/**
* Get the queue that contains the message waiting for being written.
* As the reader might not be ready, it's frequent that the messages
* aren't written completely, or that some older messages are waiting
* to be written when a new message arrives. This queue is used to manage
* the backlog of messages.
*
* @return The queue containing the pending messages.
*/
WriteRequestQueue getWriteRequestQueue();
/**
* @return the {@link TransportMetadata} that this session runs on.
*/
TransportMetadata getTransportMetadata();
/**
* TODO This javadoc is wrong. The return tag should be short.
*
* @return a {@link ReadFuture} which is notified when a new message is
* received, the connection is closed or an exception is caught. This
* operation is especially useful when you implement a client application.
* TODO : Describe here how we enable this feature.
* However, please note that this operation is disabled by default and
* throw {@link IllegalStateException} because all received events must be
* queued somewhere to support this operation, possibly leading to memory
* leak. This means you have to keep calling {@link #read()} once you
* enabled this operation. To enable this operation, please call
* {@link IoSessionConfig#setUseReadOperation(boolean)} with true.
*
* @throws IllegalStateException if
* {@link IoSessionConfig#setUseReadOperation(boolean) useReadOperation}
* option has not been enabled.
*/
ReadFuture read();
/**
* Writes the specified message
to remote peer. This
* operation is asynchronous; {@link IoHandler#messageSent(IoSession,Object)}
* will be invoked when the message is actually sent to remote peer.
* You can also wait for the returned {@link WriteFuture} if you want
* to wait for the message actually written.
*
* @param message The message to write
* @return The associated WriteFuture
*/
WriteFuture write(Object message);
/**
* (Optional) Writes the specified message to the specified destination.
* This operation is asynchronous; {@link IoHandler#messageSent(IoSession, Object)}
* will be invoked when the message is actually sent to remote peer. You can
* also wait for the returned {@link WriteFuture} if you want to wait for
* the message actually written.
*
* When you implement a client that receives a broadcast message from a server
* such as DHCP server, the client might need to send a response message for the
* broadcast message the server sent. Because the remote address of the session
* is not the address of the server in case of broadcasting, there should be a
* way to specify the destination when you write the response message.
* This interface provides {@link #write(Object, SocketAddress)} method so you
* can specify the destination.
*
* @param message The message to write
* @param destination null if you want the message sent to the
* default remote address
* @return The associated WriteFuture
*/
WriteFuture write(Object message, SocketAddress destination);
/**
* Closes this session immediately or after all queued write requests
* are flushed. This operation is asynchronous. Wait for the returned
* {@link CloseFuture} if you want to wait for the session actually closed.
*
* @param immediately {@code true} to close this session immediately
* . The pending write requests
* will simply be discarded.
* {@code false} to close this session after all queued
* write requests are flushed.
* @return The associated CloseFuture
* @deprecated Use either the {@link #closeNow()} or the {@link #closeOnFlush()} methods
*/
@Deprecated
CloseFuture close(boolean immediately);
/**
* Closes this session immediately. This operation is asynchronous, it
* returns a {@link CloseFuture}.
*
* @return The {@link CloseFuture} that can be use to wait for the completion of this operation
*/
CloseFuture closeNow();
/**
* Closes this session after all queued write requests are flushed. This operation
* is asynchronous. Wait for the returned {@link CloseFuture} if you want to wait
* for the session actually closed.
*
* @return The associated CloseFuture
*/
CloseFuture closeOnFlush();
/**
* Closes this session after all queued write requests
* are flushed. This operation is asynchronous. Wait for the returned
* {@link CloseFuture} if you want to wait for the session actually closed.
* @deprecated use {@link #closeNow()}
*
* @return The associated CloseFuture
*/
@Deprecated
CloseFuture close();
/**
* Returns an attachment of this session.
* This method is identical with getAttribute( "" ).
*
* @return The attachment
* @deprecated Use {@link #getAttribute(Object)} instead.
*/
@Deprecated
Object getAttachment();
/**
* Sets an attachment of this session.
* This method is identical with setAttribute( "", attachment ).
*
* @param attachment The attachment
* @return Old attachment. null if it is new.
* @deprecated Use {@link #setAttribute(Object, Object)} instead.
*/
@Deprecated
Object setAttachment(Object attachment);
/**
* Returns the value of the user-defined attribute of this session.
*
* @param key the key of the attribute
* @return null if there is no attribute with the specified key
*/
Object getAttribute(Object key);
/**
* Returns the value of user defined attribute associated with the
* specified key. If there's no such attribute, the specified default
* value is associated with the specified key, and the default value is
* returned. This method is same with the following code except that the
* operation is performed atomically.
*
* if (containsAttribute(key)) {
* return getAttribute(key);
* } else {
* setAttribute(key, defaultValue);
* return defaultValue;
* }
*
*
* @param key the key of the attribute we want to retreive
* @param defaultValue the default value of the attribute
* @return The retrieved attribute or null if not found
*/
Object getAttribute(Object key, Object defaultValue);
/**
* Sets a user-defined attribute.
*
* @param key the key of the attribute
* @param value the value of the attribute
* @return The old value of the attribute. null if it is new.
*/
Object setAttribute(Object key, Object value);
/**
* Sets a user defined attribute without a value. This is useful when
* you just want to put a 'mark' attribute. Its value is set to
* {@link Boolean#TRUE}.
*
* @param key the key of the attribute
* @return The old value of the attribute. null if it is new.
*/
Object setAttribute(Object key);
/**
* Sets a user defined attribute if the attribute with the specified key
* is not set yet. This method is same with the following code except
* that the operation is performed atomically.
*
* if (containsAttribute(key)) {
* return getAttribute(key);
* } else {
* return setAttribute(key, value);
* }
*
*
* @param key The key of the attribute we want to set
* @param value The value we want to set
* @return The old value of the attribute. null if not found.
*/
Object setAttributeIfAbsent(Object key, Object value);
/**
* Sets a user defined attribute without a value if the attribute with
* the specified key is not set yet. This is useful when you just want to
* put a 'mark' attribute. Its value is set to {@link Boolean#TRUE}.
* This method is same with the following code except that the operation
* is performed atomically.
*
* if (containsAttribute(key)) {
* return getAttribute(key); // might not always be Boolean.TRUE.
* } else {
* return setAttribute(key);
* }
*
*
* @param key The key of the attribute we want to set
* @return The old value of the attribute. null if not found.
*/
Object setAttributeIfAbsent(Object key);
/**
* Removes a user-defined attribute with the specified key.
*
* @param key The key of the attribute we want to remove
* @return The old value of the attribute. null if not found.
*/
Object removeAttribute(Object key);
/**
* Removes a user defined attribute with the specified key if the current
* attribute value is equal to the specified value. This method is same
* with the following code except that the operation is performed
* atomically.
*
* if (containsAttribute(key) && getAttribute(key).equals(value)) {
* removeAttribute(key);
* return true;
* } else {
* return false;
* }
*
*
* @param key The key we want to remove
* @param value The value we want to remove
* @return true if the removal was successful
*/
boolean removeAttribute(Object key, Object value);
/**
* Replaces a user defined attribute with the specified key if the
* value of the attribute is equals to the specified old value.
* This method is same with the following code except that the operation
* is performed atomically.
*
* if (containsAttribute(key) && getAttribute(key).equals(oldValue)) {
* setAttribute(key, newValue);
* return true;
* } else {
* return false;
* }
*
*
* @param key The key we want to replace
* @param oldValue The previous value
* @param newValue The new value
* @return true if the replacement was successful
*/
boolean replaceAttribute(Object key, Object oldValue, Object newValue);
/**
* @param key The key of the attribute we are looking for in the session
* @return true if this session contains the attribute with
* the specified key.
*/
boolean containsAttribute(Object key);
/**
* @return the set of keys of all user-defined attributes.
*/
Set