Класс HttpCookie

java.lang.Object

java.net.HttpCookie

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

public final class HttpCookie extends Object implements Cloneable

Объект HttpCookie представляет собой HTTP-cookie, который переносит информацию о состоянии между сервером и пользовательским агентом. 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)`	Создаёт cookie с указанным именем и значением.

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

Модификатор и тип	Метод	Описание
`Object`	`clone()`	Создаёт и возвращает копию этого объекта.
`static boolean`	`domainMatches(String domain, String host)`	Утилитарный метод для проверки, находится ли имя хоста в домене или нет.
`boolean`	`equals(Object obj)`	Проверяет равенство двух HTTP-cookie.
`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-только.
`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 создаются в соответствии со спецификацией RFC 2965 для cookie. Версию можно изменить с помощью метода 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. Синтаксис RFC 2965 раздела 3.2.2 set-cookie2 указывает, что одна строка заголовка может содержать более одного определения cookie, поэтому это статический вспомогательный метод вместо другого конструктора.

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

hasExpired

public boolean hasExpired()

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

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

setComment

public void setComment(String purpose)

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

Параметры:

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, если его нет

См. также:

setDiscard

public void setDiscard(boolean discard)

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

Параметры:

discard - true, указывающий на безоговорочное отбрасывание cookie

См. также:

getDiscard

public boolean getDiscard()

Возвращает атрибут отбрасывания cookie.

Возвращает:

boolean, представляющий атрибут отбрасывания 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 отображается серверам в указанной зоне доменных имён (например, 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 не хранится постоянно и будет удалён при закрытии веб-браузера. Нулевое значение приводит к удалению 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.

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

Параметры:

uri - String, задающий путь

См. также:

getPath

public String getPath()

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

Возвращает:

a 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. Имя нельзя изменить после создания.

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

setValue

public void setValue(String newValue)

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

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

Параметры:

newValue - a String, указывающий новое значение

См. также:

getValue

public String getValue()

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

Возвращает:

a 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 должен рассматриваться как HTTPOnly

См. также:

setHttpOnly

public void setHttpOnly(boolean httpOnly)

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

Параметры:

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

См. также:

domainMatches

public static boolean domainMatches(String domain, String host)

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

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

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

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

их строки имени хоста строково равны; или

A — строка HDN и имеет вид NB, где N — непустая строка имени, B имеет вид .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, но без ведущего маркера "Cookie:".

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

equals

public boolean equals(Object obj)

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

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

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

equals в классе Object

Параметры:

obj - ссылка на объект для сравнения.

Возвращает:

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

См. также:

hashCode

public int hashCode()

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

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

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

hashCode в классе Object

Возвращает:

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

См. также:

clone

public Object clone()

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

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

clone в классе Object

Возвращает:

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

См. также:

© 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://download.java.net/java/early_access/jdk24/docs/api/java.base/java/net/HttpCookie.html