View Javadoc

1   /*
2    *   @(#) $Id: ProtocolConnector.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.protocol;
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 ProtocolProvider}s.
27   * <p>
28   * Please refer to
29   * <a href="../../../../../xref-examples/org/apache/mina/examples/sumup/Client.html">SumUp client</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
34   * {@link ProtocolHandler} of the specified {@link ProtocolProvider}.
35   * <p>
36   * Threads connect to endpoint start automatically when
37   * {@link #connect(SocketAddress, ProtocolProvider)} is invoked, and stop when
38   * all 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 ProtocolConnector extends ProtocolSessionManager
44  {
45      /***
46       * Connects to the specified <code>address</code>.  If communication starts
47       * successfully, events are fired to the specified
48       * <code>protocolProvider</code>.  This method blocks.
49       * 
50       * @throws IOException if failed to connect
51       */
52      ProtocolSession connect( SocketAddress address,
53                               ProtocolProvider protocolProvider ) 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>protocolProvider</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      ProtocolSession connect( SocketAddress address, SocketAddress localAddress,
64                               ProtocolProvider protocolProvider ) 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>protocolProvider</code>.  This method blocks.
70       * 
71       * @throws IOException if failed to connect
72       */
73      ProtocolSession connect( SocketAddress address, int timeout,
74                               ProtocolProvider protocolProvider ) 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>protocolProvider</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      ProtocolSession connect( SocketAddress address, SocketAddress localAddress,
85                               int timeout, ProtocolProvider protocolProvider ) throws IOException;
86  }