001/* 002 * Licensed to the Apache Software Foundation (ASF) under one 003 * or more contributor license agreements. See the NOTICE file 004 * distributed with this work for additional information 005 * regarding copyright ownership. The ASF licenses this file 006 * to you under the Apache License, Version 2.0 (the 007 * "License"); you may not use this file except in compliance 008 * with the License. You may obtain a copy of the License at 009 * 010 * http://www.apache.org/licenses/LICENSE-2.0 011 * 012 * Unless required by applicable law or agreed to in writing, 013 * software distributed under the License is distributed on an 014 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY 015 * KIND, either express or implied. See the License for the 016 * specific language governing permissions and limitations 017 * under the License. 018 * 019 */ 020package org.apache.mina.core.future; 021 022import org.apache.mina.core.session.IoSession; 023 024/** 025 * An {@link IoFuture} for {@link IoSession#read() asynchronous read requests}. 026 * 027 * <h3>Example</h3> 028 * <pre> 029 * IoSession session = ...; 030 * 031 * // useReadOperation must be enabled to use read operation. 032 * session.getConfig().setUseReadOperation(true); 033 * 034 * ReadFuture future = session.read(); 035 * 036 * // Wait until a message is received. 037 * future.awaitUninterruptibly(); 038 * 039 * try { 040 * Object message = future.getMessage(); 041 * } catch (Exception e) { 042 * ... 043 * } 044 * </pre> 045 * 046 * @author <a href="http://mina.apache.org">Apache MINA Project</a> 047 */ 048public interface ReadFuture extends IoFuture { 049 050 /** 051 * Get the read message. 052 * 053 * @return the received message. It returns <tt>null</tt> if this 054 * future is not ready or the associated {@link IoSession} has been closed. 055 */ 056 Object getMessage(); 057 058 /** 059 * @return <tt>true</tt> if a message was received successfully. 060 */ 061 boolean isRead(); 062 063 /** 064 * @return <tt>true</tt> if the {@link IoSession} associated with this 065 * future has been closed. 066 */ 067 boolean isClosed(); 068 069 /** 070 * @return the cause of the read failure if and only if the read 071 * operation has failed due to an {@link Exception}. Otherwise, 072 * <tt>null</tt> is returned. 073 */ 074 Throwable getException(); 075 076 /** 077 * Sets the message is written, and notifies all threads waiting for 078 * this future. This method is invoked by MINA internally. Please do 079 * not call this method directly. 080 * 081 * @param message The received message to store in this future 082 */ 083 void setRead(Object message); 084 085 /** 086 * Sets the associated {@link IoSession} is closed. This method is invoked 087 * by MINA internally. Please do not call this method directly. 088 */ 089 void setClosed(); 090 091 /** 092 * Sets the cause of the read failure, and notifies all threads waiting 093 * for this future. This method is invoked by MINA internally. Please 094 * do not call this method directly. 095 * 096 * @param cause The exception to store in the Future instance 097 */ 098 void setException(Throwable cause); 099 100 /** 101 * {@inheritDoc} 102 */ 103 ReadFuture await() throws InterruptedException; 104 105 /** 106 * {@inheritDoc} 107 */ 108 ReadFuture awaitUninterruptibly(); 109 110 /** 111 * {@inheritDoc} 112 */ 113 ReadFuture addListener(IoFutureListener<?> listener); 114 115 /** 116 * {@inheritDoc} 117 */ 118 ReadFuture removeListener(IoFutureListener<?> listener); 119}