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 }