001/*
002 *  Licensed to the Apache Software Foundation (ASF) under one
003 *  or more contributor license agreements.  See the NOTICE file
004 *  distributed with this work for additional information
005 *  regarding copyright ownership.  The ASF licenses this file
006 *  to you under the Apache License, Version 2.0 (the
007 *  "License"); you may not use this file except in compliance
008 *  with the License.  You may obtain a copy of the License at
009 *
010 *    http://www.apache.org/licenses/LICENSE-2.0
011 *
012 *  Unless required by applicable law or agreed to in writing,
013 *  software distributed under the License is distributed on an
014 *  "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
015 *  KIND, either express or implied.  See the License for the
016 *  specific language governing permissions and limitations
017 *  under the License.
018 *
019 */
020package org.apache.mina.core.service;
021
022import java.net.SocketAddress;
023
024import org.apache.mina.core.future.ConnectFuture;
025import org.apache.mina.core.session.IoSession;
026import org.apache.mina.core.session.IoSessionInitializer;
027
028/**
029 * Connects to endpoint, communicates with the server, and fires events to
030 * {@link IoHandler}s.
031 * <p>
032 * Please refer to
033 * <a href="../../../../../xref-examples/org/apache/mina/examples/netcat/Main.html">NetCat</a>
034 * example.
035 * <p>
036 * You should connect to the desired socket address to start communication,
037 * and then events for incoming connections will be sent to the specified
038 * default {@link IoHandler}.
039 * <p>
040 * Threads connect to endpoint start automatically when
041 * {@link #connect(SocketAddress)} is invoked, and stop when all
042 * connection attempts are finished.
043 *
044 * @author <a href="http://mina.apache.org">Apache MINA Project</a>
045 */
046public interface IoConnector extends IoService {
047    /**
048     * @return the connect timeout in seconds.  The default value is 1 minute.
049     * 
050     * @deprecated
051     */
052    int getConnectTimeout();
053
054    /**
055     * @return the connect timeout in milliseconds.  The default value is 1 minute.
056     */
057    long getConnectTimeoutMillis();
058
059    /**
060     * Sets the connect timeout in seconds.  The default value is 1 minute.
061     * 
062     * @deprecated
063     * @param connectTimeout The time out for the connection
064     */
065    void setConnectTimeout(int connectTimeout);
066
067    /**
068     * Sets the connect timeout in milliseconds.  The default value is 1 minute.
069     * 
070     * @param connectTimeoutInMillis The time out for the connection
071     */
072    void setConnectTimeoutMillis(long connectTimeoutInMillis);
073
074    /**
075     * @return the default remote address to connect to when no argument
076     * is specified in {@link #connect()} method.
077     */
078    SocketAddress getDefaultRemoteAddress();
079
080    /**
081     * Sets the default remote address to connect to when no argument is
082     * specified in {@link #connect()} method.
083     * 
084     * @param defaultRemoteAddress The default remote address
085     */
086    void setDefaultRemoteAddress(SocketAddress defaultRemoteAddress);
087
088    /**
089     * @return the default local address
090     */
091    SocketAddress getDefaultLocalAddress();
092
093    /**
094     * Sets the default local address
095     * 
096     * @param defaultLocalAddress The default local address
097     */
098    void setDefaultLocalAddress(SocketAddress defaultLocalAddress);
099
100    /**
101     * Connects to the {@link #setDefaultRemoteAddress(SocketAddress) default
102     * remote address}.
103     * 
104     * @return the {@link ConnectFuture} instance which is completed when the
105     *         connection attempt initiated by this call succeeds or fails.
106     * @throws IllegalStateException
107     *             if no default remoted address is set.
108     */
109    ConnectFuture connect();
110
111    /**
112     * Connects to the {@link #setDefaultRemoteAddress(SocketAddress) default
113     * remote address} and invokes the <code>ioSessionInitializer</code> when
114     * the IoSession is created but before {@link IoHandler#sessionCreated(IoSession)}
115     * is invoked.  There is <em>no</em> guarantee that the <code>ioSessionInitializer</code>
116     * will be invoked before this method returns.
117     * 
118     * @param sessionInitializer  the callback to invoke when the {@link IoSession} object is created
119     * @return the {@link ConnectFuture} instance which is completed when the
120     *         connection attempt initiated by this call succeeds or fails.
121     * 
122     * @throws IllegalStateException if no default remote address is set.
123     */
124    ConnectFuture connect(IoSessionInitializer<? extends ConnectFuture> sessionInitializer);
125
126    /**
127     * Connects to the specified remote address.
128     * 
129     * @param remoteAddress The remote address to connect to
130     * @return the {@link ConnectFuture} instance which is completed when the
131     *         connection attempt initiated by this call succeeds or fails.
132     */
133    ConnectFuture connect(SocketAddress remoteAddress);
134
135    /**
136     * Connects to the specified remote address and invokes
137     * the <code>ioSessionInitializer</code> when the IoSession is created but before
138     * {@link IoHandler#sessionCreated(IoSession)} is invoked.  There is <em>no</em>
139     * guarantee that the <code>ioSessionInitializer</code> will be invoked before
140     * this method returns.
141     * 
142     * @param remoteAddress  the remote address to connect to
143     * @param sessionInitializer  the callback to invoke when the {@link IoSession} object is created
144     * 
145     * @return the {@link ConnectFuture} instance which is completed when the
146     *         connection attempt initiated by this call succeeds or fails.
147     */
148    ConnectFuture connect(SocketAddress remoteAddress, IoSessionInitializer<? extends ConnectFuture> sessionInitializer);
149
150    /**
151     * Connects to the specified remote address binding to the specified local address.
152     *
153     * @param remoteAddress The remote address to connect
154     * @param localAddress The local address to bind
155     * 
156     * @return the {@link ConnectFuture} instance which is completed when the
157     *         connection attempt initiated by this call succeeds or fails.
158     */
159    ConnectFuture connect(SocketAddress remoteAddress, SocketAddress localAddress);
160
161    /**
162     * Connects to the specified remote address binding to the specified local
163     * address and and invokes the <code>ioSessionInitializer</code> when the
164     * IoSession is created but before {@link IoHandler#sessionCreated(IoSession)}
165     * is invoked.  There is <em>no</em> guarantee that the <code>ioSessionInitializer</code>
166     * will be invoked before this method returns.
167     * 
168     * @param remoteAddress  the remote address to connect to
169     * @param localAddress  the local interface to bind to
170     * @param sessionInitializer  the callback to invoke when the {@link IoSession} object is created
171     *
172     * @return the {@link ConnectFuture} instance which is completed when the
173     *         connection attempt initiated by this call succeeds or fails.
174     */
175    ConnectFuture connect(SocketAddress remoteAddress, SocketAddress localAddress,
176            IoSessionInitializer<? extends ConnectFuture> sessionInitializer);
177}