Dear Wiki user, You have subscribed to a wiki page or wiki category on "Jakarta-httpclient Wiki" for change notification.
The following page has been changed by RolandWeber: http://wiki.apache.org/jakarta-httpclient/HttpAsyncThreadingDesign The comment on the change is: added synchronization details to the API description ------------------------------------------------------------------------------ too many problems to be solved first, so let's not worry about chasing redirects now. + === Synchronization Details === + + {{{HttpDispatcher}}} has a method {{{sendRequest}}} to transfer control + of a request and obtain a handle. {{{abortAll}}} can be used to cancel all + request (handles) currently controlled by the dispatcher, but it leaves + the dispatcher operational. + {{{shutdown}}} (''not yet implemented'') will cancel all requests and + stop operation of the dispatcher. It releases resources such as + background threads. Dispatcher implementations may have methods + that allow reinitialization, but that is not part of the interface. + + {{{HttpHandle}}} has a method {{{awaitResponse}}} which will block + the calling process until the response is available or until an error + is encountered. By using notifications, the caller can make sure that + it will be blocked only momentarily, if at all. + [[BR]] + {{{close}}} indicates that processing of the response has finished + and that the connection over which the response is being received + can be used for another request. When the handle is closed while + the response has not been read completely, the rest of the response + may be consumed. + [[BR]] + {{{abort}}} can be called at any time to abort processing of the + request. If the request is not yet sent, it will be removed from + the relevant queue gracefully. If it is sent but the response not + yet received, the response will be discarded. Aborting a handle + never consumes the rest of the response, but it has a negative effect + on keep-alive and pipelining. After being aborted, the handle behaves + as if an error was encountered. + [[BR]] + {{{isLinked}}} indicates whether the handle is still linked to the + dispatcher and it's connection. Closing or aborting the handle will + unlink it. Note that access to {{{isLinked}}} can not be synchronized: + even if it returns true, you can't be sure that the handle is still + linked by the time you call another method. Once a handle is unlinked, + it remains unlinked. + + {{{HttpNotificationHandler}}} has methods {{{notifyResponse}}} and {{{notifyProblem}}}, + which are called for incoming responses and encountered problems, respectively. + There will be at most one notification for either the response or a fatal problem. + If {{{notifyResponse}}} is called but throws a runtime exception, that is a fatal problem. + But there will be no problem notification, since the response notification has already + been given. On the application side, the handle will behave as if an error was encountered. + [[BR]] + There can be several notifications about non-fatal problems before + the final notification, but not afterwards. Imagine a server that + receives the request header, sends an error response immediately, + and closes the connection while the dispatcher still tries to send the + request body. This triggers an exception on sending, but the response + from the server is available. {{{notifyProblem}}} may be called + for a non-fatal problem then. It's return value indicates whether + the problem should be handled as a fatal one, or whether processing + should resume and another notification given. + [[BR]] + Notifications are triggered exclusively by operations of the background threads. + Aborting a request at any time does ''not'' trigger a notification, even though + the handle will behave as if an error was encountered. + + All methods in {{{HttpDispatcher}}} and {{{HttpHandle}}} are thread safe. + All methods in {{{HttpNotificationHandler}}} must be thread safe. + They also must return quickly to keep the background threads available + for tasks related to other requests. In particular, none of the blocking or + time-consuming methods of {{{HttpHandle}}} must be called during a notification. + {{{HttpHandle.abort}}} is OK to be called. Some implementations may also allow + {{{HttpHandle.close}}} to be called, but that is not guaranteed by the API. + + == Blocking IO Implementation == === Red Design === --------------------------------------------------------------------- To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
