View Javadoc
1   /*
2    * ====================================================================
3    * Licensed to the Apache Software Foundation (ASF) under one
4    * or more contributor license agreements.  See the NOTICE file
5    * distributed with this work for additional information
6    * regarding copyright ownership.  The ASF licenses this file
7    * to you under the Apache License, Version 2.0 (the
8    * "License"); you may not use this file except in compliance
9    * with the License.  You may obtain a copy of the License at
10   *
11   *   http://www.apache.org/licenses/LICENSE-2.0
12   *
13   * Unless required by applicable law or agreed to in writing,
14   * software distributed under the License is distributed on an
15   * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
16   * KIND, either express or implied.  See the License for the
17   * specific language governing permissions and limitations
18   * under the License.
19   * ====================================================================
20   *
21   * This software consists of voluntary contributions made by many
22   * individuals on behalf of the Apache Software Foundation.  For more
23   * information on the Apache Software Foundation, please see
24   * <http://www.apache.org/>.
25   *
26   */
27  
28  package org.apache.hc.core5.reactor;
29  
30  import java.net.SocketAddress;
31  import java.util.concurrent.Future;
32  
33  import org.apache.hc.core5.concurrent.FutureCallback;
34  import org.apache.hc.core5.net.NamedEndpoint;
35  import org.apache.hc.core5.util.TimeValue;
36  
37  /**
38   * Non-blocking connection initiator.
39   *
40   * @since 5.0
41   */
42  public interface ConnectionInitiator {
43  
44      /**
45       * Requests a connection to a remote host.
46       * <p>
47       * Opening a connection to a remote host usually tends to be a time
48       * consuming process and may take a while to complete. One can monitor and
49       * control the process of session initialization by means of the
50       * {@link Future} interface.
51       * <p>
52       * There are several parameters one can use to exert a greater control over
53       * the process of session initialization:
54       * <p>
55       * A non-null local socket address parameter can be used to bind the socket
56       * to a specific local address.
57       * <p>
58       * An attachment object can added to the new session's context upon
59       * initialization. This object can be used to pass an initial processing
60       * state to the protocol handler.
61       * <p>
62       * It is often desirable to be able to react to the completion of a session
63       * request asynchronously without having to wait for it, blocking the
64       * current thread of execution. One can optionally provide an implementation
65       * {@link FutureCallback} instance to get notified of events related
66       * to session requests, such as request completion, cancellation, failure or
67       * timeout.
68       *
69       * @param remoteEndpoint name of the remote host.
70       * @param remoteAddress remote socket address.
71       * @param localAddress local socket address. Can be {@code null},
72       *    in which can the default local address and a random port will be used.
73       * @param timeout connect timeout.
74       * @param attachment the attachment object. Can be {@code null}.
75       * @param callback interface. Can be {@code null}.
76       * @return session request object.
77       */
78      Future<IOSession> connect(
79              NamedEndpoint remoteEndpoint,
80              SocketAddress remoteAddress,
81              SocketAddress localAddress,
82              TimeValue timeout,
83              Object attachment,
84              FutureCallback<IOSession> callback);
85  
86  }