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 */ 027 028package org.apache.http.cookie; 029 030import java.util.List; 031 032import org.apache.http.Header; 033import org.apache.http.annotation.Obsolete; 034 035/** 036 * Defines the cookie management specification. 037 * <p>Cookie management specification must define 038 * <ul> 039 * <li> rules of parsing "Set-Cookie" header 040 * <li> rules of validation of parsed cookies 041 * <li> formatting of "Cookie" header 042 * </ul> 043 * for a given host, port and path of origin 044 * <p> 045 * Please do not use methods marked as @Obsolete. They have been rendered 046 * obsolete by RFC 6265. 047 * 048 * @since 4.0 049 */ 050public interface CookieSpec { 051 052 /** 053 * Returns version of the state management this cookie specification 054 * conforms to. 055 * 056 * @return version of the state management specification 057 */ 058 @Obsolete 059 int getVersion(); 060 061 /** 062 * Parse the {@code "Set-Cookie"} Header into an array of Cookies. 063 * 064 * <p>This method will not perform the validation of the resultant 065 * {@link Cookie}s</p> 066 * 067 * @see #validate 068 * 069 * @param header the {@code Set-Cookie} received from the server 070 * @param origin details of the cookie origin 071 * @return an array of {@code Cookie}s parsed from the header 072 * @throws MalformedCookieException if an exception occurs during parsing 073 */ 074 List<Cookie> parse(Header header, CookieOrigin origin) throws MalformedCookieException; 075 076 /** 077 * Validate the cookie according to validation rules defined by the 078 * cookie specification. 079 * 080 * @param cookie the Cookie to validate 081 * @param origin details of the cookie origin 082 * @throws MalformedCookieException if the cookie is invalid 083 */ 084 void validate(Cookie cookie, CookieOrigin origin) throws MalformedCookieException; 085 086 /** 087 * Determines if a Cookie matches the target location. 088 * 089 * @param cookie the Cookie to be matched 090 * @param origin the target to test against 091 * 092 * @return {@code true} if the cookie should be submitted with a request 093 * with given attributes, {@code false} otherwise. 094 */ 095 boolean match(Cookie cookie, CookieOrigin origin); 096 097 /** 098 * Create {@code "Cookie"} headers for an array of Cookies. 099 * 100 * @param cookies the Cookies format into a Cookie header 101 * @return a Header for the given Cookies. 102 * @throws IllegalArgumentException if an input parameter is illegal 103 */ 104 List<Header> formatCookies(List<Cookie> cookies); 105 106 /** 107 * Returns a request header identifying what version of the state management 108 * specification is understood. May be {@code null} if the cookie 109 * specification does not support {@code Cookie2} header. 110 */ 111 @Obsolete 112 Header getVersionHeader(); 113 114}