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