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.service; 021 022import java.net.SocketAddress; 023 024import org.apache.mina.core.future.ConnectFuture; 025import org.apache.mina.core.session.IoSession; 026import org.apache.mina.core.session.IoSessionInitializer; 027 028/** 029 * Connects to endpoint, communicates with the server, and fires events to 030 * {@link IoHandler}s. 031 * <p> 032 * Please refer to 033 * <a href="../../../../../xref-examples/org/apache/mina/examples/netcat/Main.html">NetCat</a> 034 * example. 035 * <p> 036 * You should connect to the desired socket address to start communication, 037 * and then events for incoming connections will be sent to the specified 038 * default {@link IoHandler}. 039 * <p> 040 * Threads connect to endpoint start automatically when 041 * {@link #connect(SocketAddress)} is invoked, and stop when all 042 * connection attempts are finished. 043 * 044 * @author <a href="http://mina.apache.org">Apache MINA Project</a> 045 */ 046public interface IoConnector extends IoService { 047 /** 048 * @return the connect timeout in seconds. The default value is 1 minute. 049 * 050 * @deprecated 051 */ 052 int getConnectTimeout(); 053 054 /** 055 * @return the connect timeout in milliseconds. The default value is 1 minute. 056 */ 057 long getConnectTimeoutMillis(); 058 059 /** 060 * Sets the connect timeout in seconds. The default value is 1 minute. 061 * 062 * @deprecated 063 * @param connectTimeout The time out for the connection 064 */ 065 void setConnectTimeout(int connectTimeout); 066 067 /** 068 * Sets the connect timeout in milliseconds. The default value is 1 minute. 069 * 070 * @param connectTimeoutInMillis The time out for the connection 071 */ 072 void setConnectTimeoutMillis(long connectTimeoutInMillis); 073 074 /** 075 * @return the default remote address to connect to when no argument 076 * is specified in {@link #connect()} method. 077 */ 078 SocketAddress getDefaultRemoteAddress(); 079 080 /** 081 * Sets the default remote address to connect to when no argument is 082 * specified in {@link #connect()} method. 083 * 084 * @param defaultRemoteAddress The default remote address 085 */ 086 void setDefaultRemoteAddress(SocketAddress defaultRemoteAddress); 087 088 /** 089 * @return the default local address 090 */ 091 SocketAddress getDefaultLocalAddress(); 092 093 /** 094 * Sets the default local address 095 * 096 * @param defaultLocalAddress The default local address 097 */ 098 void setDefaultLocalAddress(SocketAddress defaultLocalAddress); 099 100 /** 101 * Connects to the {@link #setDefaultRemoteAddress(SocketAddress) default 102 * remote address}. 103 * 104 * @return the {@link ConnectFuture} instance which is completed when the 105 * connection attempt initiated by this call succeeds or fails. 106 * @throws IllegalStateException 107 * if no default remoted address is set. 108 */ 109 ConnectFuture connect(); 110 111 /** 112 * Connects to the {@link #setDefaultRemoteAddress(SocketAddress) default 113 * remote address} and invokes the <code>ioSessionInitializer</code> when 114 * the IoSession is created but before {@link IoHandler#sessionCreated(IoSession)} 115 * is invoked. There is <em>no</em> guarantee that the <code>ioSessionInitializer</code> 116 * will be invoked before this method returns. 117 * 118 * @param sessionInitializer the callback to invoke when the {@link IoSession} object is created 119 * @return the {@link ConnectFuture} instance which is completed when the 120 * connection attempt initiated by this call succeeds or fails. 121 * 122 * @throws IllegalStateException if no default remote address is set. 123 */ 124 ConnectFuture connect(IoSessionInitializer<? extends ConnectFuture> sessionInitializer); 125 126 /** 127 * Connects to the specified remote address. 128 * 129 * @param remoteAddress The remote address to connect to 130 * @return the {@link ConnectFuture} instance which is completed when the 131 * connection attempt initiated by this call succeeds or fails. 132 */ 133 ConnectFuture connect(SocketAddress remoteAddress); 134 135 /** 136 * Connects to the specified remote address and invokes 137 * the <code>ioSessionInitializer</code> when the IoSession is created but before 138 * {@link IoHandler#sessionCreated(IoSession)} is invoked. There is <em>no</em> 139 * guarantee that the <code>ioSessionInitializer</code> will be invoked before 140 * this method returns. 141 * 142 * @param remoteAddress the remote address to connect to 143 * @param sessionInitializer the callback to invoke when the {@link IoSession} object is created 144 * 145 * @return the {@link ConnectFuture} instance which is completed when the 146 * connection attempt initiated by this call succeeds or fails. 147 */ 148 ConnectFuture connect(SocketAddress remoteAddress, IoSessionInitializer<? extends ConnectFuture> sessionInitializer); 149 150 /** 151 * Connects to the specified remote address binding to the specified local address. 152 * 153 * @param remoteAddress The remote address to connect 154 * @param localAddress The local address to bind 155 * 156 * @return the {@link ConnectFuture} instance which is completed when the 157 * connection attempt initiated by this call succeeds or fails. 158 */ 159 ConnectFuture connect(SocketAddress remoteAddress, SocketAddress localAddress); 160 161 /** 162 * Connects to the specified remote address binding to the specified local 163 * address and and invokes the <code>ioSessionInitializer</code> when the 164 * IoSession is created but before {@link IoHandler#sessionCreated(IoSession)} 165 * is invoked. There is <em>no</em> guarantee that the <code>ioSessionInitializer</code> 166 * will be invoked before this method returns. 167 * 168 * @param remoteAddress the remote address to connect to 169 * @param localAddress the local interface to bind to 170 * @param sessionInitializer the callback to invoke when the {@link IoSession} object is created 171 * 172 * @return the {@link ConnectFuture} instance which is completed when the 173 * connection attempt initiated by this call succeeds or fails. 174 */ 175 ConnectFuture connect(SocketAddress remoteAddress, SocketAddress localAddress, 176 IoSessionInitializer<? extends ConnectFuture> sessionInitializer); 177}