Класс HttpCookie

java.lang.Object

java.net.HttpCookie

Все реализуемые интерфейсы:: Cloneable

public final class HttpCookie extends Object implements Cloneable

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

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

черновик 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)`	Создает cookie с указанными именем и значением.

Краткое описание методов

Модификатор и тип	Метод	Описание
`Object`	`clone()`	Создает и возвращает копию этого объекта.
`static boolean`	`domainMatches(String domain, String host)`	Вспомогательный метод для проверки того, входит ли имя хоста в домен.
`boolean`	`equals(Object obj)`	Проверяет равенство двух cookie HTTP.
`String`	`getComment()`	Возвращает комментарий, описывающий назначение этого cookie, или `null`, если у cookie нет комментария.
`String`	`getCommentURL()`	Возвращает URL комментария, описывающего назначение этого cookie, или `null`, если у cookie нет URL комментария.
`boolean`	`getDiscard()`	Возвращает атрибут discard 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()`	Сообщает, истек ли срок действия этого cookie HTTP.
`int`	`hashCode()`	Возвращает хеш-код этого cookie HTTP.
`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.
`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 после его создания.
`void`	`setVersion(int v)`	Задает версию протокола cookie, которой соответствует этот cookie.
`String`	`toString()`	Создает строковое представление этого cookie для заголовка в формате, определенном соответствующей спецификацией cookie, но без начального токена "Cookie:".

Методы, объявленные в классе 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

См. также:

Подробное описание методов

parse

public static List<HttpCookie> parse(String header)

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

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

hasExpired

public boolean hasExpired()

Сообщает, истек ли срок действия этого cookie HTTP.

Возвращает:: true, если срок действия этого cookie HTTP истек; в противном случае — false

setComment

public void setComment(String purpose)

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

Параметры:

purpose — String, задающая комментарий для отображения пользователю

См. также:

getComment

public String getComment()

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

Возвращает:

String, содержащую комментарий, или null, если комментария нет

См. также:

setCommentURL

public void setCommentURL(String purpose)

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

Параметры:

purpose — String, задающая URL комментария для отображения пользователю

См. также:

getCommentURL

public String getCommentURL()

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

Возвращает:

String, содержащую URL комментария, или null, если URL отсутствует

См. также:

setDiscard

public void setDiscard(boolean discard)

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

Параметры:

discard — true указывает, что cookie следует безусловно удалить

См. также:

getDiscard

public boolean getDiscard()

Возвращает атрибут discard cookie

Возвращает:

boolean, представляющую атрибут discard этого cookie

См. также:

setPortlist

public void setPortlist(String ports)

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

Параметры:

ports — String, задающая список портов в виде последовательности цифр, разделенных запятыми

См. также:

getPortlist

public String getPortlist()

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

Возвращает:

String, содержащую список портов, или null, если список отсутствует

См. также:

setDomain

public void setDomain(String pattern)

Задает домен, в пределах которого должен передаваться этот cookie.

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

Параметры:

pattern — String, содержащее имя домена, в пределах которого виден этот cookie; формат имени должен соответствовать RFC 2965

См. также:

getDomain

public String getDomain()

Возвращает имя домена, заданное для этого cookie. Формат имени домена определяется RFC 2965.

Возвращает:

String, содержащее имя домена

См. также:

setMaxAge

public void setMaxAge(long expiry)

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

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

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

Параметры:

expiry — целое число, задающее максимальный срок действия cookie в секундах; если значение равно нулю, cookie следует немедленно удалить; в противном случае максимальный срок действия cookie не задан.

См. также:

getMaxAge

public long getMaxAge()

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

Возвращает:

целое число, задающее максимальный срок действия cookie в секундах

См. также:

setPath

public void setPath(String uri)

Задает путь для cookie, по которому клиент должен отправлять этот cookie.

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

Дополнительные сведения о задании путей для cookie см. в RFC 2965 (доступен в Интернете).

Параметры:

uri — String, задающая путь

См. также:

getPath

public String getPath()

Возвращает путь на сервере, по которому браузер отправляет этот cookie. Cookie виден во всех подкаталогах на сервере.

Возвращает:

String, задающую путь, содержащий имя сервлета, например /catalog

См. также:

setSecure

public void setSecure(boolean flag)

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

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

Параметры:

flag — если true, cookie можно отправлять только по защищенному протоколу, например HTTPS. Если false, его можно отправлять по любому протоколу.

См. также:

getSecure

public boolean getSecure()

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

Возвращает:

false, если cookie можно отправлять по любому стандартному протоколу; в противном случае — true

См. также:

getName

public String getName()

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

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

setValue

public void setValue(String newValue)

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

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

Параметры:

newValue — String, задающая новое значение

См. также:

getValue

public String getValue()

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

Возвращает:

String, содержащее текущее значение cookie

См. также:

getVersion

public int getVersion()

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

Возвращает:

0, если cookie соответствует исходной спецификации Netscape; 1, если cookie соответствует RFC 2965/2109

См. также:

setVersion

public void setVersion(int v)

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

Параметры:

v — 0, если cookie должен соответствовать исходной спецификации Netscape; 1, если cookie должен соответствовать RFC 2965/2109

Исключения:

IllegalArgumentException — если v не равно ни 0, ни 1

См. также:

isHttpOnly

public boolean isHttpOnly()

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

Возвращает:

true, если этот cookie следует считать доступным только по HTTP

См. также:

setHttpOnly

public void setHttpOnly(boolean httpOnly)

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

Параметры:

httpOnly — если true, cookie становится доступным только по HTTP, то есть видимым только в составе HTTP-запроса.

См. также:

domainMatches

public static boolean domainMatches(String domain, String host)

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

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

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

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

строковые представления имен хостов совпадают; или

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

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

Значение атрибута Domain не содержит внутренних точек и не равно .local.

Эффективное имя хоста, полученное из request-host, не соответствует атрибуту Domain.

request-host является 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)

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

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

Переопределяет:

equals в классе Object

Параметры:

obj — объект, с которым выполняется сравнение.

Возвращает:

true, если два cookie HTTP равны; в противном случае — false

См. также:

hashCode

public int hashCode()

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

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

Переопределяет:

hashCode в классе Object

Возвращает:

хеш-код этого cookie HTTP

См. также:

clone

public Object clone()

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

Переопределяет:

clone в классе Object

Возвращает:

копию этого cookie HTTP

См. также:

© 1993, 2025, 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/25/docs/api/java.base/java/net/HttpCookie.html