Класс HttpCookie

Все реализованные интерфейсы:
Cloneable
public final class HttpCookie
extends Object
implements Cloneable

Объект HttpCookie представляет собой HTTP-cookie, который переносит информацию о состоянии между сервером и пользовательским агентом. Куки широко используются для создания состоятельных сессий.

Существует 3 спецификации HTTP-cookie:

Черновик Netscape
RFC 2109 - http://www.ietf.org/rfc/rfc2109.txt
RFC 2965 - http://www.ietf.org/rfc/rfc2965.txt

Класс HttpCookie может принимать все эти 3 формы синтаксиса.

С момента:
1.6

Конструкторы

Конструктор Описание
HttpCookie​(String name, String value)

Создаёт куки с заданным именем и значением.

Методы

Модификатор и тип Метод Описание
Object clone()

Создаёт и возвращает копию этого объекта.
static boolean domainMatches​(String domain, String host)

Утилитарный метод для проверки, находится ли имя хоста в домене.
boolean equals​(Object obj)

Проверяет равенство двух HTTP-cookies.
String getComment()

Возвращает комментарий, описывающий назначение этого cookie, или null, если у cookie нет комментария.
String getCommentURL()

Возвращает URL комментария, описывающего назначение этого cookie, или null, если у cookie нет URL комментария.
boolean getDiscard()

Возвращает атрибут удаления cookie.
String getDomain()

Возвращает имя домена, заданное для этого cookie.
long getMaxAge()

Возвращает максимальную продолжительность действия cookie в секундах.
String getName()

Возвращает имя cookie.
String getPath()

Возвращает путь на сервере, в который браузер возвращает этот cookie.
String getPortlist()

Возвращает атрибут списка портов cookie.
boolean getSecure()

Возвращает true, если отправка этого cookie должна быть ограничена защищённым протоколом, или false, если его можно отправить с помощью любого протокола.
String getValue()

Возвращает значение cookie.
int getVersion()

Возвращает версию протокола, с которой соответствует этот cookie.
boolean hasExpired()

Указывает, истек ли срок действия этого HTTP-cookie.
int hashCode()

Возвращает хэш-код этого HTTP-cookie.
boolean isHttpOnly()

Возвращает true, если этот cookie содержит атрибут HttpOnly.
static List<HttpCookie> parse​(String header)

Создаёт cookie из строки заголовка set-cookie или set-cookie2.
void setComment​(String purpose)

Устанавливает комментарий, описывающий назначение cookie.
void setCommentURL​(String purpose)

Устанавливает URL комментария, описывающего назначение cookie.
void setDiscard​(boolean discard)

Указывает, должен ли пользовательский агент безусловно удалить cookie.
void setDomain​(String pattern)

Указывает домен, в котором этот cookie должен быть представлен.
void setHttpOnly​(boolean httpOnly)

Указывает, должен ли cookie считаться HTTP Only.
void setMaxAge​(long expiry)

Устанавливает максимальный срок действия cookie в секундах.
void setPath​(String uri)

Указывает путь для cookie, на который клиент должен вернуть cookie.
void setPortlist​(String ports)

Указывает список портов cookie, который ограничивает порт(ы), на которые cookie может быть отправлен обратно в заголовке Cookie.
void setSecure​(boolean flag)

Указывает, должен ли cookie отправляться только по защищённому протоколу, например HTTPS или SSL.
void setValue​(String newValue)

Присваивает новое значение cookie после создания cookie.
void setVersion​(int v)

Устанавливает версию протокола cookie, с которой соответствует этот cookie.
String toString()

Создаёт строковое представление заголовка cookie этого cookie в формате, определённом соответствующей спецификацией cookie, но без начального токена «Cookie:».

Методы, объявленные в классе java.lang.Object

finalize, getClass, notify, notifyAll, wait, wait, wait

Конструкторы

HttpCookie

public HttpCookie(String name,
                  String value)

Создаёт cookie с заданным именем и значением.

Имя должно соответствовать RFC 2965. Это означает, что оно может содержать только символы ASCII буквенно-цифрового алфавита и не может содержать запятые, точки с запятой или пробелы или начинаться с символа $. Имя cookie не может быть изменено после создания.

Значение может быть любым, которое сервер выбирает для отправки. Его значение, вероятно, интересно только серверу. Значение cookie можно изменить после создания с помощью метода setValue.

По умолчанию cookie создаются в соответствии со спецификацией cookie RFC 2965. Версию можно изменить с помощью метода setVersion.

Параметры:
name - String имя cookie
value - String значение cookie
Исключения:
IllegalArgumentException - если имя cookie содержит недопустимые символы
NullPointerException - если name равно null
См. также:
setValue(java.lang.String), setVersion(int)

Методы

parse

public static List<HttpCookie> parse(String header)

Создаёт куки из строки заголовка set-cookie или set-cookie2. Синтаксис заголовка set-cookie2 из RFC 2965, раздел 3.2.2, указывает, что одна строка заголовка может содержать более одного определения куки, поэтому этот статический утилитарный метод вместо другого конструктора.

Параметры:
header - String , указывающий заголовок set-cookie. Заголовок должен начинаться с токена «set-cookie» или «set-cookie2»; или он вообще не должен иметь ведущего токена.
Возвращает:
Список куки, разобранных из строки заголовка
Исключения:
IllegalArgumentException - если строка заголовка нарушает синтаксис спецификации куки или имя куки содержит недопустимые символы.
NullPointerException - если строка заголовка null

hasExpired

public boolean hasExpired()

Указывает, истек ли срок действия HTTP-куки.

Возвращает:
true , чтобы указать, что срок действия HTTP-куки истек; в противном случае, false

setComment

public void setComment(String purpose)

Устанавливает комментарий, описывающий назначение куки. Комментарий полезен, если браузер предоставляет куки пользователю. Комментарии не поддерживаются куками Netscape версии 0.

Параметры:
purpose - String , содержащий комментарий для отображения пользователю
См. также:
getComment()

getComment

public String getComment()

Возвращает комментарий, описывающий назначение этой куки, или null , если куки нет комментария.

Возвращает:
String , содержащий комментарий, или null , если нет
См. также:
setComment(java.lang.String)

setCommentURL

public void setCommentURL(String purpose)

Устанавливает URL комментария, описывающий назначение куки. URL комментария полезен, если браузер предоставляет куки пользователю. URL комментария поддерживается только RFC 2965.

Параметры:
purpose - String , содержащий URL комментария для отображения пользователю
См. также:
getCommentURL()

getCommentURL

public String getCommentURL()

Возвращает URL комментария, описывающий назначение этой куки, или null , если куки нет URL комментария.

Возвращает:
String , содержащий URL комментария, или null , если нет
См. также:
setCommentURL(java.lang.String)

setDiscard

public void setDiscard(boolean discard)

Указывает, должен ли пользовательский агент безусловно удалить куки. Это атрибут только RFC 2965.

Параметры:
discard - true указывает на безусловное удаление куки
См. также:
getDiscard()

getDiscard

public boolean getDiscard()

Возвращает атрибут удаления куки

Возвращает:
boolean , представляющий атрибут удаления этой куки
См. также:
setDiscard(boolean)

setPortlist

public void setPortlist(String ports)

Указывает список портов куки, который ограничивает порт(ы), на которые куки может быть отправлена обратно в заголовке Cookie.

Параметры:
ports - String , определяющий список портов, который представляет собой серию цифр, разделённых запятыми
См. также:
getPortlist()

getPortlist

public String getPortlist()

Возвращает атрибут списка портов куки

Возвращает:
String , содержащий список портов, или null , если нет
См. также:
setPortlist(java.lang.String)

setDomain

public void setDomain(String pattern)

Устанавливает домен, в котором эта кука должна быть представлена.

Формат имени домена задан в RFC 2965. Имя домена начинается с точки (.foo.com) и означает, что кука доступна серверам в указанной зоне DNS (например, www.foo.com, но не a.b.foo.com). По умолчанию куки возвращаются только серверу, который их отправил.

Параметры:
pattern - String , содержащий имя домена, в котором эта кука доступна; формат соответствует RFC 2965
См. также:
getDomain()

getDomain

public String getDomain()

Возвращает имя домена, установленное для этой куки. Формат имени домена задан RFC 2965.

Возвращает:
String , содержащий имя домена
См. также:
setDomain(java.lang.String)

setMaxAge

public void setMaxAge(long expiry)

Устанавливает максимальный срок действия куки в секундах.

Положительное значение указывает, что кука истечёт через указанное количество секунд. Обратите внимание, что значение — это максимальный срок действия, когда кука истечёт, а не текущий срок действия куки.

Отрицательное значение означает, что кука не сохраняется постоянно и будет удалена при выходе веб-браузера. Нулевое значение приводит к удалению куки.

Параметры:
expiry - целое число, указывающее максимальный срок действия куки в секундах; если ноль, кука должна быть удалена немедленно; в противном случае максимальный срок действия куки не указан.
См. также:
getMaxAge()

getMaxAge

public long getMaxAge()

Возвращает максимальный срок действия куки в секундах. По умолчанию -1, указывая, что кука сохранится до закрытия браузера.

Возвращает:
Целое число, указывающее максимальный срок действия куки в секундах
См. также:
setMaxAge(long)

setPath

public void setPath(String uri)

Устанавливает путь для куки, на который клиент должен вернуть куки.

Кука видна для всех страниц в указанном каталоге и всех страниц в подкаталогах этого каталога. Путь куки должен включать сервлет, который установил куки, например, /catalog, что делает куки видимой для всех каталогов на сервере под /catalog.

Для получения дополнительной информации о назначении имён путей для куки см. RFC 2965 (доступен в Интернете).

Параметры:
uri - String , указывающий путь
См. также:
getPath()

getPath

public String getPath()

Возвращает путь на сервере, на который браузер возвращает эту куки. Кука видна для всех подпутей на сервере.

Возвращает:
String , указывающий путь, содержащий имя сервлета, например, /catalog
См. также:
setPath(java.lang.String)

setSecure

public void setSecure(boolean flag)

Указывает, должна ли кука отправляться только с помощью защищённого протокола, такого как HTTPS или SSL.

Значение по умолчанию — false.

Параметры:
flag - Если true, кука может быть отправлена только по защищённому протоколу, например HTTPS. Если false, она может быть отправлена по любому протоколу.
См. также:
getSecure()

getSecure

public boolean getSecure()

Возвращает true , если отправка этой куки должна быть ограничена защищённым протоколом, или false , если она может быть отправлена по любому протоколу.

Возвращает:
false , если кука может быть отправлена по любому стандартному протоколу; в противном случае, true
См. также:
setSecure(boolean)

getName

public String getName()

Возвращает имя куки. Имя нельзя изменить после создания.

Возвращает:
String , указывающее имя куки

setValue

public void setValue(String newValue)

Присваивает новое значение куки после создания куки. Если вы используете двоичное значение, вы можете использовать кодирование BASE64.

Для куки версии 0 значения не должны содержать пробелы, скобки, знаки равенства, запятые, двойные кавычки, косые черты, вопросительные знаки, знаки «@», двоеточия и точки с запятой. Пустые значения могут вести себя по-разному в разных браузерах.

Параметры:
newValue - String , указывающее новое значение
См. также:
getValue()

getValue

public String getValue()

Возвращает значение куки.

Возвращает:
String , содержащее текущее значение куки
См. также:
setValue(java.lang.String)

getVersion

public int getVersion()

Возвращает версию протокола, с которой соответствует эта кука. Версия 1 соответствует RFC 2965/2109, а версия 0 — оригинальной спецификации куки, разработанной компанией Netscape. Куки, предоставленные браузером, используют и идентифицируют версию куки браузера.

Возвращает:
0, если кука соответствует оригинальной спецификации Netscape; 1, если кука соответствует RFC 2965/2109
См. также:
setVersion(int)

setVersion

public void setVersion(int v)

Устанавливает версию протокола куки, с которой соответствует эта кука. Версия 0 соответствует оригинальной спецификации куки Netscape. Версия 1 соответствует RFC 2965/2109.

Параметры:
v - 0, если кука должна соответствовать оригинальной спецификации Netscape; 1, если кука должна соответствовать RFC 2965/2109
Исключения:
IllegalArgumentException - если v ни 0, ни 1
См. также:
getVersion()

isHttpOnly

public boolean isHttpOnly()

Возвращает true , если эта кука содержит атрибут HttpOnly. Это означает, что кука недоступна для скриптовых движков, таких как javascript.

Возвращает:
true если этот cookie должен рассматриваться как HTTPOnly
См. также:
setHttpOnly(boolean)

setHttpOnly

public void setHttpOnly(boolean httpOnly)

Указывает, должен ли cookie рассматриваться как HTTP Only. Если установлено значение true, это означает, что cookie не должен быть доступен для скриптовых движков, таких как javascript.

Параметры:
httpOnly - если true сделать cookie HTTP только, т.е. видимым только как часть HTTP-запроса.
См. также:
isHttpOnly()

domainMatches

public static boolean domainMatches(String domain,
                                    String host)

Утилитарный метод для проверки того, соответствует ли имя хоста домену.

Эта концепция описана в спецификации cookie. Для понимания концепции необходимо сначала определить некоторые термины:

эффективное имя хоста = имя хоста, если имя хоста содержит точку
или = имя_хоста.local, если нет

Имя хоста А соответствует домену имени хоста Б, если:

  • их строки имен хостов совпадают при сравнении строк; или
  • А — строка HDN и имеет вид NB, где N — непустая строка имени, Б имеет вид .B', и B' — строка HDN. (Таким образом, x.y.com соответствует .Y.com, но не Y.com.)

Хост не находится в домене (RFC 2965, раздел 3.3.2), если:

  • Значение атрибута Domain не содержит вложенных точек и не равно .local.
  • Эффективное имя хоста, полученное из имени хоста запроса, не соответствует атрибуту Domain.
  • Имя хоста запроса — HDN (не IP-адрес) и имеет вид HD, где D — значение атрибута Domain, а H — строка, содержащая одну или несколько точек.

Примеры:

  • Set-Cookie2 с request-host y.x.foo.com для Domain=.foo.com будет отклонен, потому что H — y.x и содержит точку.
  • Set-Cookie2 с request-host x.foo.com для Domain=.foo.com будет принят.
  • Set-Cookie2 с Domain=.com или Domain=.com., всегда будет отклонен, потому что нет вложенной точки.
  • Set-Cookie2 с request-host example для Domain=.local будет принят, потому что эффективное имя хоста для request-host — example.local, и example.local соответствует .local.
Параметры:
domain - имя домена для проверки имени хоста
host - имя хоста, которое проверяется
Возвращает:
true если они соответствуют домену; false если нет

toString

public String toString()

Создаёт строковое представление заголовка cookie, которое соответствует определению соответствующей спецификации cookie, но без начального маркера "Cookie:".

Переопределяет:
toString в классе Object
Возвращает:
строковая форма cookie. Строка имеет определённый формат

equals

public boolean equals(Object obj)

Проверяет равенство двух HTTP-cookie.

Результат равен true только если два cookie происходят из одного домена (без учёта регистра), имеют одинаковое имя (без учёта регистра) и одинаковый путь (с учётом регистра).

Переопределяет:
equals в классе Object
Параметры:
obj - объект-ссылка для сравнения.
Возвращает:
true если два HTTP-cookie равны; в противном случае, false
См. также:
Object.hashCode(), HashMap

hashCode

public int hashCode()

Возвращает хэш-код этого HTTP-cookie. Результат — сумма хэш-кода трёх значимых компонентов этого cookie: имени, домена и пути. То есть, хэш-код — это значение выражения:

getName().toLowerCase().hashCode()
+ getDomain().toLowerCase().hashCode()
+ getPath().hashCode()

Переопределяет:
hashCode в классе Object
Возвращает:
хэш-код этого HTTP-cookie
См. также:
Object.equals(java.lang.Object), System.identityHashCode(java.lang.Object)

clone

public Object clone()

Создаёт и возвращает копию этого объекта.

Переопределяет:
clone в классе Object
Возвращает:
клон этого HTTP-cookie
См. также:
Cloneable

© 1993, 2020, Oracle and/or its affiliates. All rights reserved.
Documentation extracted from Debian's OpenJDK Development Kit package.
Licensed under the GNU General Public License, version 2, with the Classpath Exception.
Various third party code in OpenJDK is licensed under different licenses (see Debian package).
Java and OpenJDK are trademarks or registered trademarks of Oracle and/or its affiliates.
https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/net/HttpCookie.html

Spec-Zone .ru
спецификации, руководства, описания, API