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 The Apache MINA Project (dev@mina.apache.org)
45 * @version $Rev: 671827 $, $Date: 2008-06-26 10:49:48 +0200 (jeu, 26 jun 2008) $
46 */
47 public interface IoConnector extends IoService {
48 /**
49 * Returns the connect timeout in seconds. The default value is 1 minute.
50 *
51 * @deprecated
52 * @see getConnectTimeoutMillis()
53 */
54 int getConnectTimeout();
55
56 /**
57 * Returns the connect timeout in milliseconds. The default value is 1 minute.
58 */
59 long getConnectTimeoutMillis();
60
61 /**
62 * Sets the connect timeout in seconds. The default value is 1 minute.
63 *
64 * @deprecated
65 * @see setConnectTimeoutMillis()
66 */
67 void setConnectTimeout(int connectTimeout);
68
69 /**
70 * Sets the connect timeout in milliseconds. The default value is 1 minute.
71 */
72 void setConnectTimeoutMillis(long connectTimeoutInMillis);
73
74 /**
75 * Returns the default remote address to connect to when no argument
76 * is specified in {@link #connect()} method.
77 */
78 SocketAddress getDefaultRemoteAddress();
79
80 /**
81 * Sets the default remote address to connect to when no argument is
82 * specified in {@link #connect()} method.
83 */
84 void setDefaultRemoteAddress(SocketAddress defaultRemoteAddress);
85
86 /**
87 * Connects to the {@link #setDefaultRemoteAddress(SocketAddress) default remote address}.
88 *
89 * @throws IllegalStateException if no default remoted address is set.
90 */
91 ConnectFuture connect();
92
93 /**
94 * Connects to the {@link #setDefaultRemoteAddress(SocketAddress) default
95 * remote address} and invokes the <code>ioSessionInitializer</code> when
96 * the IoSession is created but before {@link IoHandler#sessionCreated(IoSession)}
97 * is invoked. There is <em>no</em> guarantee that the <code>ioSessionInitializer</code>
98 * will be invoked before this method returns.
99 *
100 * @param sessionInitializer the callback to invoke when the {@link IoSession} object is created
101 *
102 * @throws IllegalStateException if no default remote address is set.
103 */
104 ConnectFuture connect(IoSessionInitializer<? extends ConnectFuture> sessionInitializer);
105
106 /**
107 * Connects to the specified remote address.
108 *
109 * @return the {@link ConnectFuture} instance which is completed when the
110 * connection attempt initiated by this call succeeds or fails.
111 */
112 ConnectFuture connect(SocketAddress remoteAddress);
113
114 /**
115 * Connects to the specified remote address and invokes
116 * the <code>ioSessionInitializer</code> when the IoSession is created but before
117 * {@link IoHandler#sessionCreated(IoSession)} is invoked. There is <em>no</em>
118 * guarantee that the <code>ioSessionInitializer</code> will be invoked before
119 * this method returns.
120 *
121 * @param remoteAddress the remote address to connect to
122 * @param sessionInitializer the callback to invoke when the {@link IoSession} object is created
123 *
124 * @return the {@link ConnectFuture} instance which is completed when the
125 * connection attempt initiated by this call succeeds or fails.
126 */
127 ConnectFuture connect(SocketAddress remoteAddress, IoSessionInitializer<? extends ConnectFuture> sessionInitializer);
128
129 /**
130 * Connects to the specified remote address binding to the specified local address.
131 *
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, SocketAddress localAddress);
136
137 /**
138 * Connects to the specified remote address binding to the specified local
139 * address and and invokes the <code>ioSessionInitializer</code> when the
140 * IoSession is created but before {@link IoHandler#sessionCreated(IoSession)}
141 * is invoked. There is <em>no</em> guarantee that the <code>ioSessionInitializer</code>
142 * will be invoked before this method returns.
143 *
144 * @param remoteAddress the remote address to connect to
145 * @param localAddress the local interface to bind to
146 * @param sessionInitializer the callback to invoke when the {@link IoSession} object is created
147 *
148 * @return the {@link ConnectFuture} instance which is completed when the
149 * connection attempt initiated by this call succeeds or fails.
150 */
151 ConnectFuture connect(SocketAddress remoteAddress,
152 SocketAddress localAddress, IoSessionInitializer<? extends ConnectFuture> sessionInitializer);
153 }