1 /*
2  * Copyright (C) 2015 Square, Inc.
3  *
4  * Licensed under the Apache License, Version 2.0 (the "License");
5  * you may not use this file except in compliance with the License.
6  * You may obtain a copy of the License at
7  *
8  *      http://www.apache.org/licenses/LICENSE-2.0
9  *
10  * Unless required by applicable law or agreed to in writing, software
11  * distributed under the License is distributed on an "AS IS" BASIS,
12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13  * See the License for the specific language governing permissions and
14  * limitations under the License.
15  */
16 package okhttp3;
17
18 import java.util.Collections;
19 import java.util.List;
20
21 /**
22  * Provides <strong>policy</strong> and <strong>persistence</strong> for HTTP cookies.
23  *
24  * <p>As policy, implementations of this interface are responsible for selecting which cookies to
25  * accept and which to reject. A reasonable policy is to reject all cookies, though that may
26  * interfere with session-based authentication schemes that require cookies.
27  *
28  * <p>As persistence, implementations of this interface must also provide storage of cookies. Simple
29  * implementations may store cookies in memory; sophisticated ones may use the file system or
30  * database to hold accepted cookies. The <a
31  * href="https://tools.ietf.org/html/rfc6265#section-5.3">cookie storage model</a> specifies
32  * policies for updating and expiring cookies.
33  */
34 public interface CookieJar {
35   /** A cookie jar that never accepts any cookies. */
36   CookieJar NO_COOKIES = new CookieJar() {
37     @Override public void saveFromResponse(HttpUrl url, List<Cookie> cookies) {
38     }
39
40     @Override public List<Cookie> loadForRequest(HttpUrl url) {
41       return Collections.emptyList();
42     }
43   };
44
45   /**
46    * Saves {@code cookies} from an HTTP response to this store according to this jar's policy.
47    *
48    * <p>Note that this method may be called a second time for a single HTTP response if the response
49    * includes a trailer. For this obscure HTTP feature, {@code cookies} contains only the trailer's
50    * cookies.
51    */
52   void saveFromResponse(HttpUrl url, List<Cookie> cookies);
53
54   /**
55    * Load cookies from the jar for an HTTP request to {@code url}. This method returns a possibly
56    * empty list of cookies for the network request.
57    *
58    * <p>Simple implementations will return the accepted cookies that have not yet expired and that
59    * {@linkplain Cookie#matches match} {@code url}.
60    */
61   List<Cookie> loadForRequest(HttpUrl url);
62 }
63