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}