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.http.nio.reactor;
29  
30  import java.net.SocketAddress;
31  
32  /**
33   * ConnectingIOReactor represents an I/O reactor capable of establishing
34   * connections to remote hosts.
35   *
36   * @since 4.0
37   */
38  public interface ConnectingIOReactor extends IOReactor {
39  
40      /**
41       * Requests a connection to a remote host.
42       * <p>
43       * Opening a connection to a remote host usually tends to be a time
44       * consuming process and may take a while to complete. One can monitor and
45       * control the process of session initialization by means of the
46       * {@link SessionRequest} interface.
47       * <p>
48       * There are several parameters one can use to exert a greater control over
49       * the process of session initialization:
50       * <p>
51       * A non-null local socket address parameter can be used to bind the socket
52       * to a specific local address.
53       * <p>
54       * An attachment object can added to the new session's context upon
55       * initialization. This object can be used to pass an initial processing
56       * state to the protocol handler.
57       * <p>
58       * It is often desirable to be able to react to the completion of a session
59       * request asynchronously without having to wait for it, blocking the
60       * current thread of execution. One can optionally provide an implementation
61       * {@link SessionRequestCallback} instance to get notified of events related
62       * to session requests, such as request completion, cancellation, failure or
63       * timeout.
64       *
65       * @param remoteAddress the socket address of the remote host.
66       * @param localAddress the local socket address. Can be {@code null},
67       *    in which can the default local address and a random port will be used.
68       * @param attachment the attachment object. Can be {@code null}.
69       * @param callback interface. Can be {@code null}.
70       * @return session request object.
71       */
72      SessionRequest connect(
73              SocketAddress remoteAddress,
74              SocketAddress localAddress,
75              Object attachment,
76              SessionRequestCallback callback);
77  
78  }