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.io.IOException;
31  import java.net.SocketAddress;
32  
33  /**
34   * SessionRequest interface represents a request to establish a new connection
35   * (or session) to a remote host. It can be used to monitor the status of the
36   * request, to block waiting for its completion, or to cancel the request.
37   * <p>
38   * Implementations of this interface are expected to be threading safe.
39   *
40   * @since 4.0
41   */
42  public interface SessionRequest {
43  
44      /**
45       * Returns socket address of the remote host.
46       *
47       * @return socket address of the remote host
48       */
49      SocketAddress getRemoteAddress();
50  
51      /**
52       * Returns local socket address.
53       *
54       * @return local socket address.
55       */
56      SocketAddress getLocalAddress();
57  
58      /**
59       * Returns attachment object will be added to the session's context upon
60       * initialization. This object can be used to pass an initial processing
61       * state to the protocol handler.
62       *
63       * @return attachment object.
64       */
65      Object getAttachment();
66  
67      /**
68       * Determines whether the request has been completed (either successfully
69       * or unsuccessfully).
70       *
71       * @return <code>true</true> if the request has been completed,
72       *  <code>false</true> if still pending.
73       */
74      boolean isCompleted();
75  
76      /**
77       * Returns {@link IOSession} instance created as a result of this request
78       * or <code>null</code> if the request is still pending.
79       *
80       * @return I/O session or <code>null</code> if the request is still pending.
81       */
82      IOSession getSession();
83  
84      /**
85       * Returns {@link IOException} instance if the request could not be
86       * successfully executed due to an I/O error or <code>null</code> if no
87       * error occurred to this point.
88       *
89       * @return I/O exception or <code>null</code> if no error occurred to
90       * this point.
91       */
92      IOException getException();
93  
94      /**
95       * Waits for completion of this session request.
96       *
97       * @throws InterruptedException in case the execution process was
98       *   interrupted.
99       */
100     void waitFor() throws InterruptedException;
101 
102     /**
103      * Sets connect timeout value in milliseconds.
104      *
105      * @param timeout connect timeout value in milliseconds.
106      */
107     void setConnectTimeout(int timeout);
108 
109     /**
110      * Returns connect timeout value in milliseconds.
111      *
112      * @return connect timeout value in milliseconds.
113      */
114     int getConnectTimeout();
115 
116     /**
117      * Cancels the request. Invocation of this method will set the status of
118      * the request to completed and will unblock threads blocked in
119      * the {{@link #waitFor()}} method.
120      */
121     void cancel();
122 
123 }