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 */
027package org.apache.http.conn;
028
029import org.apache.http.HttpResponse;
030import org.apache.http.protocol.HttpContext;
031
032/**
033 * Interface for deciding how long a connection can remain
034 * idle before being reused.
035 * <p>
036 * Implementations of this interface must be thread-safe. Access to shared
037 * data must be synchronized as methods of this interface may be executed
038 * from multiple threads.
039 *
040 * @since 4.0
041 */
042public interface ConnectionKeepAliveStrategy {
043
044    /**
045     * Returns the duration of time which this connection can be safely kept
046     * idle. If the connection is left idle for longer than this period of time,
047     * it MUST not reused. A value of 0 or less may be returned to indicate that
048     * there is no suitable suggestion.
049     *
050     * When coupled with a {@link org.apache.http.ConnectionReuseStrategy}, if
051     * {@link org.apache.http.ConnectionReuseStrategy#keepAlive(
052     *   HttpResponse, HttpContext)} returns true, this allows you to control
053     * how long the reuse will last. If keepAlive returns false, this should
054     * have no meaningful impact
055     *
056     * @param response
057     *            The last response received over the connection.
058     * @param context
059     *            the context in which the connection is being used.
060     *
061     * @return the duration in ms for which it is safe to keep the connection
062     *         idle, or &lt;=0 if no suggested duration.
063     */
064    long getKeepAliveDuration(HttpResponse response, HttpContext context);
065
066}