1 /*
2 * Licensed to the Apache Software Foundation (ASF) under one
3 * or more contributor license agreements. See the NOTICE file
4 * distributed with this work for additional information
5 * regarding copyright ownership. The ASF licenses this file
6 * to you under the Apache License, Version 2.0 (the
7 * "License"); you may not use this file except in compliance
8 * with the License. You may obtain a copy of the License at
9 *
10 * http://www.apache.org/licenses/LICENSE-2.0
11 *
12 * Unless required by applicable law or agreed to in writing,
13 * software distributed under the License is distributed on an
14 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
15 * KIND, either express or implied. See the License for the
16 * specific language governing permissions and limitations
17 * under the License.
18 *
19 */
20 package org.apache.mina.core.service;
21
22 import java.net.SocketAddress;
23
24 import org.apache.mina.core.future.ConnectFuture;
25 import org.apache.mina.core.session.IoSession;
26 import org.apache.mina.core.session.IoSessionInitializer;
27
28 /**
29 * Connects to endpoint, communicates with the server, and fires events to
30 * {@link IoHandler}s.
31 * <p>
32 * Please refer to
33 * <a href="../../../../../xref-examples/org/apache/mina/examples/netcat/Main.html">NetCat</a>
34 * example.
35 * <p>
36 * You should connect to the desired socket address to start communication,
37 * and then events for incoming connections will be sent to the specified
38 * default {@link IoHandler}.
39 * <p>
40 * Threads connect to endpoint start automatically when
41 * {@link #connect(SocketAddress)} is invoked, and stop when all
42 * connection attempts are finished.
43 *
44 * @author <a href="http://mina.apache.org">Apache MINA Project</a>
45 */
46 public interface IoConnector extends IoService {
47 /**
48 * @return the connect timeout in seconds. The default value is 1 minute.
49 *
50 * @deprecated
51 */
52 @Deprecated
53 int getConnectTimeout();
54
55 /**
56 * @return the connect timeout in milliseconds. The default value is 1 minute.
57 */
58 long getConnectTimeoutMillis();
59
60 /**
61 * Sets the connect timeout in seconds. The default value is 1 minute.
62 *
63 * @deprecated
64 * @param connectTimeout The time out for the connection
65 */
66 @Deprecated
67 void setConnectTimeout(int connectTimeout);
68
69 /**
70 * Sets the connect timeout in milliseconds. The default value is 1 minute.
71 *
72 * @param connectTimeoutInMillis The time out for the connection
73 */
74 void setConnectTimeoutMillis(long connectTimeoutInMillis);
75
76 /**
77 * @return the default remote address to connect to when no argument
78 * is specified in {@link #connect()} method.
79 */
80 SocketAddress getDefaultRemoteAddress();
81
82 /**
83 * Sets the default remote address to connect to when no argument is
84 * specified in {@link #connect()} method.
85 *
86 * @param defaultRemoteAddress The default remote address
87 */
88 void setDefaultRemoteAddress(SocketAddress defaultRemoteAddress);
89
90 /**
91 * @return the default local address
92 */
93 SocketAddress getDefaultLocalAddress();
94
95 /**
96 * Sets the default local address
97 *
98 * @param defaultLocalAddress The default local address
99 */
100 void setDefaultLocalAddress(SocketAddress defaultLocalAddress);
101
102 /**
103 * Connects to the {@link #setDefaultRemoteAddress(SocketAddress) default
104 * remote address}.
105 *
106 * @return the {@link ConnectFuture} instance which is completed when the
107 * connection attempt initiated by this call succeeds or fails.
108 * @throws IllegalStateException
109 * if no default remoted address is set.
110 */
111 ConnectFuture connect();
112
113 /**
114 * Connects to the {@link #setDefaultRemoteAddress(SocketAddress) default
115 * remote address} and invokes the <code>ioSessionInitializer</code> when
116 * the IoSession is created but before {@link IoHandler#sessionCreated(IoSession)}
117 * is invoked. There is <em>no</em> guarantee that the <code>ioSessionInitializer</code>
118 * will be invoked before this method returns.
119 *
120 * @param sessionInitializer the callback to invoke when the {@link IoSession} object is created
121 * @return the {@link ConnectFuture} instance which is completed when the
122 * connection attempt initiated by this call succeeds or fails.
123 *
124 * @throws IllegalStateException if no default remote address is set.
125 */
126 ConnectFuture connect(IoSessionInitializer<? extends ConnectFuture> sessionInitializer);
127
128 /**
129 * Connects to the specified remote address.
130 *
131 * @param remoteAddress The remote address to connect to
132 * @return the {@link ConnectFuture} instance which is completed when the
133 * connection attempt initiated by this call succeeds or fails.
134 */
135 ConnectFuture connect(SocketAddress remoteAddress);
136
137 /**
138 * Connects to the specified remote address and invokes
139 * the <code>ioSessionInitializer</code> when the IoSession is created but before
140 * {@link IoHandler#sessionCreated(IoSession)} is invoked. There is <em>no</em>
141 * guarantee that the <code>ioSessionInitializer</code> will be invoked before
142 * this method returns.
143 *
144 * @param remoteAddress the remote address to connect to
145 * @param sessionInitializer the callback to invoke when the {@link IoSession} object is created
146 *
147 * @return the {@link ConnectFuture} instance which is completed when the
148 * connection attempt initiated by this call succeeds or fails.
149 */
150 ConnectFuture connect(SocketAddress remoteAddress, IoSessionInitializer<? extends ConnectFuture> sessionInitializer);
151
152 /**
153 * Connects to the specified remote address binding to the specified local address.
154 *
155 * @param remoteAddress The remote address to connect
156 * @param localAddress The local address to bind
157 *
158 * @return the {@link ConnectFuture} instance which is completed when the
159 * connection attempt initiated by this call succeeds or fails.
160 */
161 ConnectFuture connect(SocketAddress remoteAddress, SocketAddress localAddress);
162
163 /**
164 * Connects to the specified remote address binding to the specified local
165 * address and and invokes the <code>ioSessionInitializer</code> when the
166 * IoSession is created but before {@link IoHandler#sessionCreated(IoSession)}
167 * is invoked. There is <em>no</em> guarantee that the <code>ioSessionInitializer</code>
168 * will be invoked before this method returns.
169 *
170 * @param remoteAddress the remote address to connect to
171 * @param localAddress the local interface to bind to
172 * @param sessionInitializer the callback to invoke when the {@link IoSession} object is created
173 *
174 * @return the {@link ConnectFuture} instance which is completed when the
175 * connection attempt initiated by this call succeeds or fails.
176 */
177 ConnectFuture connect(SocketAddress remoteAddress, SocketAddress localAddress,
178 IoSessionInitializer<? extends ConnectFuture> sessionInitializer);
179 }