package.html revision 417f3b92ba4549b2f22340e3107d869d2b9c5bb8 
1<html>
2<head>
3<!--
4/*
5 * $HeadURL: http://svn.apache.org/repos/asf/httpcomponents/httpclient/trunk/module-client/src/main/java/org/apache/http/conn/package.html $
6 * $Revision: 651813 $
7 * $Date: 2008-04-26 03:43:34 -0700 (Sat, 26 Apr 2008) $
8 *
9 * ====================================================================
10 * Licensed to the Apache Software Foundation (ASF) under one
11 * or more contributor license agreements.  See the NOTICE file
12 * distributed with this work for additional information
13 * regarding copyright ownership.  The ASF licenses this file
14 * to you under the Apache License, Version 2.0 (the
15 * "License"); you may not use this file except in compliance
16 * with the License.  You may obtain a copy of the License at
17 *
18 *   http://www.apache.org/licenses/LICENSE-2.0
19 *
20 * Unless required by applicable law or agreed to in writing,
21 * software distributed under the License is distributed on an
22 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
23 * KIND, either express or implied.  See the License for the
24 * specific language governing permissions and limitations
25 * under the License.
26 * ====================================================================
27 *
28 * This software consists of voluntary contributions made by many
29 * individuals on behalf of the Apache Software Foundation.  For more
30 * information on the Apache Software Foundation, please see
31 * <http://www.apache.org/>.
32 *
33 */
34-->
35</head>
36<body>
37The client-side connection management and handling API
38at the heart of what is referred to as <i>HttpConn</i>.
39This component provides interfaces and implementations for
40opening and managing connections.
41
42<p>
43The lowest layer of connection handling is comprised of
44{@link org.apache.http.conn.OperatedClientConnection OperatedClientConnection}
45and
46{@link org.apache.http.conn.ClientConnectionOperator ClientConnectionOperator}.
47The connection interface extends the core
48{@link org.apache.http.HttpClientConnection HttpClientConnection}
49by operations to set and update a socket.
50An operator encapsulates the logic to open and layer sockets,
51typically using a {@link org.apache.http.conn.scheme.SocketFactory SocketFactory}.
52The socket factory for a protocol
53{@link org.apache.http.conn.scheme.Scheme Scheme}
54such as "http" or "https" can be looked up in a
55{@link org.apache.http.conn.scheme.SchemeRegistry SchemeRegistry}.
56Applications without a need for sophisticated connection management
57can use this layer directly.
58</p>
59
60<p>
61On top of that lies the connection management layer. A
62{@link org.apache.http.conn.ClientConnectionManager ClientConnectionManager}
63internally manages operated connections, but hands out instances of
64{@link org.apache.http.conn.ManagedClientConnection ManagedClientConnection}.
65This interface abstracts from the underlying socket operations and
66provides convenient methods for opening and updating sockets in order
67to establish a {@link org.apache.http.conn.routing.HttpRoute route}.
68The operator is encapsulated by the connection manager and called
69automatically.
70
71<br/>
72
73Connections obtained from a manager have to be returned after use.
74This can be {@link org.apache.http.conn.ConnectionReleaseTrigger triggered}
75on various levels, either by releasing the
76{@link org.apache.http.conn.ManagedClientConnection
77       connection}
78directly, or by calling a method on an
79{@link org.apache.http.conn.BasicManagedEntity entity}
80received from the connection, or by closing the
81{@link org.apache.http.conn.EofSensorInputStream stream}
82from which that entity is being read.
83
84Connection managers will try to keep returned connections alive in
85order to re-use them for subsequent requests along the same route.
86The managed connection interface and all triggers for connection release
87provide methods to enable or disable this behavior.
88</p>
89
90</body>
91</html>
92