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.common;
21  
22  import java.net.SocketAddress;
23  
24  /**
25   * Connects to endpoint, communicates with the server, and fires events to
26   * {@link IoHandler}s.
27   * <p>
28   * Please refer to
29   * <a href="../../../../../xref-examples/org/apache/mina/examples/netcat/Main.html">NetCat</a>
30   * example.
31   * <p>
32   * You should connect to the desired socket address to start communication,
33   * and then events for incoming connections will be sent to the specified
34   * default {@link IoHandler}.
35   * <p>
36   * Threads connect to endpoint start automatically when
37   * {@link #connect(SocketAddress)} is invoked, and stop when all
38   * connection attempts are finished.
39   *
40   * @author The Apache MINA Project (dev@mina.apache.org)
41   * @version $Rev: 607163 $, $Date: 2007-12-27 20:20:07 -0700 (Thu, 27 Dec 2007) $
42   */
43  public interface IoConnector extends IoService {
44      /**
45       * Returns the connect timeout in seconds.  The default value is 1 minute.
46       */
47      int getConnectTimeout();
48  
49      /**
50       * Returns the connect timeout in milliseconds.  The default value is 1 minute.
51       */
52      long getConnectTimeoutMillis();
53  
54      /**
55       * Sets the connect timeout in seconds.  The default value is 1 minute.
56       */
57      void setConnectTimeout(int connectTimeout);
58  
59      /**
60       * Returns the default remote address to connect to when no argument
61       * is specified in {@link #connect()} method.
62       */
63      SocketAddress getDefaultRemoteAddress();
64      
65      /**
66       * Sets the default remote address to connect to when no argument is
67       * specified in {@link #connect()} method.
68       */
69      void setDefaultRemoteAddress(SocketAddress defaultRemoteAddress);
70  
71      /**
72       * Connects to the {@link #setDefaultRemoteAddress(SocketAddress) default remote address}.
73       * 
74       * @throws IllegalStateException if no default remoted address is set.
75       */
76      ConnectFuture connect();
77      
78      /**
79       * Connects to the {@link #setDefaultRemoteAddress(SocketAddress) default
80       * remote address} and invokes the <code>ioSessionInitializer</code> when
81       * the IoSession is created but before {@link IoHandler#sessionCreated(IoSession)}
82       * is invoked.  There is <em>no</em> guarantee that the <code>ioSessionInitializer</code>
83       * will be invoked before this method returns.
84       * 
85       * @param sessionInitializer  the callback to invoke when the {@link IoSession} object is created
86       * 
87       * @throws IllegalStateException if no default remote address is set.
88       */
89      ConnectFuture connect(IoSessionInitializer<? extends ConnectFuture> sessionInitializer);
90      
91      /**
92       * Connects to the specified remote address.
93       *
94       * @return the {@link ConnectFuture} instance which is completed when the
95       *         connection attempt initiated by this call succeeds or fails.
96       */
97      ConnectFuture connect(SocketAddress remoteAddress);
98  
99      /**
100      * Connects to the specified remote address and invokes
101      * the <code>ioSessionInitializer</code> when the IoSession is created but before
102      * {@link IoHandler#sessionCreated(IoSession)} is invoked.  There is <em>no</em>
103      * guarantee that the <code>ioSessionInitializer</code> will be invoked before
104      * this method returns.
105      * 
106      * @param remoteAddress  the remote address to connect to
107      * @param sessionInitializer  the callback to invoke when the {@link IoSession} object is created
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, IoSessionInitializer<? extends ConnectFuture> sessionInitializer);
113 
114     /**
115      * Connects to the specified remote address binding to the specified local address.
116      *
117      * @return the {@link ConnectFuture} instance which is completed when the
118      *         connection attempt initiated by this call succeeds or fails.
119      */
120     ConnectFuture connect(SocketAddress remoteAddress, SocketAddress localAddress);
121     
122     /**
123      * Connects to the specified remote address binding to the specified local
124      * address and and invokes the <code>ioSessionInitializer</code> when the
125      * IoSession is created but before {@link IoHandler#sessionCreated(IoSession)}
126      * is invoked.  There is <em>no</em> guarantee that the <code>ioSessionInitializer</code>
127      * will be invoked before this method returns.
128      * 
129      * @param remoteAddress  the remote address to connect to
130      * @param localAddress  the local interface to bind 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,
137             SocketAddress localAddress, IoSessionInitializer<? extends ConnectFuture> sessionInitializer);
138 }