View Javadoc

1   /*
2    *   @(#) $Id: IoConnector.java 210062 2005-07-11 03:52:38Z trustin $
3    *
4    *   Copyright 2004 The Apache Software Foundation
5    *
6    *   Licensed under the Apache License, Version 2.0 (the "License");
7    *   you may not use this file except in compliance with the License.
8    *   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, software
13   *   distributed under the License is distributed on an "AS IS" BASIS,
14   *   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
15   *   See the License for the specific language governing permissions and
16   *   limitations under the License.
17   *
18   */
19  package org.apache.mina.io;
20  
21  import java.io.IOException;
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, IoHandler)} is invoked, and stop when all
38   * connection attempts are finished.
39   * 
40   * @author Trustin Lee (trustin@apache.org)
41   * @version $Rev: 210062 $, $Date: 2005-07-11 12:52:38 +0900 $
42   */
43  public interface IoConnector extends IoSessionManager
44  {
45      /***
46       * Connects to the specified <code>address</code>.  If communication starts
47       * successfully, events are fired to the specified
48       * <code>handler</code>.  This method blocks.
49       * 
50       * @throws IOException if failed to connect
51       */
52      IoSession connect( SocketAddress address, IoHandler handler )
53              throws IOException;
54  
55      /***
56       * Connects to the specified <code>address</code>.  If communication starts
57       * successfully, events are fired to the specified
58       * <code>handler</code>.  This method blocks.
59       * 
60       * @param localAddress the local address the channel is bound to
61       * @throws IOException if failed to connect
62       */
63      IoSession connect( SocketAddress address, SocketAddress localAddress,
64                         IoHandler handler ) throws IOException;
65  
66      /***
67       * Connects to the specified <code>address</code> with timeout.  If
68       * communication starts successfully, events are fired to the specified
69       * <code>handler</code>.  This method blocks.
70       * 
71       * @throws IOException if failed to connect
72       */
73      IoSession connect( SocketAddress address, int timeout, IoHandler handler )
74              throws IOException;
75      
76      /***
77       * Connects to the specified <code>address</code> with timeout.  If
78       * communication starts successfully, events are fired to the specified
79       * <code>handler</code>.  This method blocks.
80       * 
81       * @param localAddress the local address the channel is bound to
82       * @throws IOException if failed to connect
83       */
84      IoSession connect( SocketAddress address, SocketAddress localAddress,
85                         int timeout, IoHandler handler ) throws IOException;
86  }