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       * @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, SocketAddress localAddress,
151             IoSessionInitializer<? extends ConnectFuture> sessionInitializer);
152 }