001/* 002 * ==================================================================== 003 * Licensed to the Apache Software Foundation (ASF) under one 004 * or more contributor license agreements. See the NOTICE file 005 * distributed with this work for additional information 006 * regarding copyright ownership. The ASF licenses this file 007 * to you under the Apache License, Version 2.0 (the 008 * "License"); you may not use this file except in compliance 009 * with the License. You may obtain a copy of the License at 010 * 011 * http://www.apache.org/licenses/LICENSE-2.0 012 * 013 * Unless required by applicable law or agreed to in writing, 014 * software distributed under the License is distributed on an 015 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY 016 * KIND, either express or implied. See the License for the 017 * specific language governing permissions and limitations 018 * under the License. 019 * ==================================================================== 020 * 021 * This software consists of voluntary contributions made by many 022 * individuals on behalf of the Apache Software Foundation. For more 023 * information on the Apache Software Foundation, please see 024 * <http://www.apache.org/>. 025 * 026 */ 027 028package org.apache.http.nio.reactor; 029 030import java.net.SocketAddress; 031 032/** 033 * ConnectingIOReactor represents an I/O reactor capable of establishing 034 * connections to remote hosts. 035 * 036 * @since 4.0 037 */ 038public interface ConnectingIOReactor extends IOReactor { 039 040 /** 041 * Requests a connection to a remote host. 042 * <p> 043 * Opening a connection to a remote host usually tends to be a time 044 * consuming process and may take a while to complete. One can monitor and 045 * control the process of session initialization by means of the 046 * {@link SessionRequest} interface. 047 * <p> 048 * There are several parameters one can use to exert a greater control over 049 * the process of session initialization: 050 * <p> 051 * A non-null local socket address parameter can be used to bind the socket 052 * to a specific local address. 053 * <p> 054 * An attachment object can added to the new session's context upon 055 * initialization. This object can be used to pass an initial processing 056 * state to the protocol handler. 057 * <p> 058 * It is often desirable to be able to react to the completion of a session 059 * request asynchronously without having to wait for it, blocking the 060 * current thread of execution. One can optionally provide an implementation 061 * {@link SessionRequestCallback} instance to get notified of events related 062 * to session requests, such as request completion, cancellation, failure or 063 * timeout. 064 * 065 * @param remoteAddress the socket address of the remote host. 066 * @param localAddress the local socket address. Can be {@code null}, 067 * in which can the default local address and a random port will be used. 068 * @param attachment the attachment object. Can be {@code null}. 069 * @param callback interface. Can be {@code null}. 070 * @return session request object. 071 */ 072 SessionRequest connect( 073 SocketAddress remoteAddress, 074 SocketAddress localAddress, 075 Object attachment, 076 SessionRequestCallback callback); 077 078}