John Viegas created HTTPCLIENT-2374:
---------------------------------------
Summary: Document CONNECTION_TIME_TO_LIVE semantic change in
migration guide (timeToLive=0 behavior)
Key: HTTPCLIENT-2374
URL: https://issues.apache.org/jira/browse/HTTPCLIENT-2374
Project: HttpComponents HttpClient
Issue Type: Improvement
Components: Documentation
Affects Versions: 5.3.1, 5.3
Reporter: John Viegas
*Summary:*
{{The migration guide should document the semantic breaking change in
connection timeToLive behavior between Apache 4.x and 5.x when timeToLive=0.}}
*Description:*
{{## Issue Description
The migration from Apache HttpClient 4.x to 5.x introduces a semantic breaking
change in connection pool behavior when `timeToLive=0` that is not documented
in the migration guide.}}
{{## Behavior Change
**Apache 4.x:**
- `timeToLive = 0` → Infinite connection lifetime (never expires)
- Implementation: `if (timeToLive > 0) \{ setDeadline } else \{ Long.MAX_VALUE
}`
**Apache 5.x:**
- `timeToLive = 0` → Immediate expiration (connections expire instantly)
- Implementation: `if (TimeValue.isZero(ttl)) \{ currentTime }`
## Impact
This causes connection pooling to break silently:
1. Connections are created and returned to pool correctly
2. On next request, connection is immediately marked as expired
3. Connection is closed gracefully and new one created
4. Results in creating new connection for every request instead of reusing
## Code Example
```java
// This worked in Apache 4.x but breaks connection reuse in 5.x
PoolingHttpClientConnectionManager cm =
PoolingHttpClientConnectionManagerBuilder.create()
.setConnectionTimeToLive(TimeValue.of(0, TimeUnit.MILLISECONDS))
.build();}}
Suggested Fix
*Migration Guide Enhancement:* Add section documenting this behavior change:
{{### Connection Time-To-Live Changes
⚠️ **Breaking Change**: The behavior of `timeToLive = 0` has changed:
- **Apache 4.x**: Zero timeToLive meant infinite connection lifetime
- **Apache 5.x**: Zero timeToLive means immediate expiration
**Migration Action**:
- If you previously used `timeToLive = 0` for infinite lifetime, remove the
`setConnectionTimeToLive()` call entirely
- Apache 5.x uses infinite lifetime by default when TTL is not specified}}
Documentation Impact
* Migration guide:
{{https://hc.apache.org/httpcomponents-client-5.0.x/migration-guide/}}
* JavaDoc:
{{PoolingHttpClientConnectionManagerBuilder.setConnectionTimeToLive()}} method
documentation
Environment
* Apache HttpClient version: 5.x
* Migration from: Apache HttpClient 4.x
* Impact: Silent breaking change in connection pooling behavior
{{### **Environment:**}}
Apache HttpClient Version: 5.2.x (or whatever version you're using) Previous
Version: 4.5.x JDK Version: 11 Operating System: (your OS)
--
This message was sent by Atlassian Jira
(v8.20.10#820010)
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscr...@hc.apache.org
For additional commands, e-mail: dev-h...@hc.apache.org
