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