Класс 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 варианта синтаксиса. Этот класс также обеспечивает частичную поддержку RFC 6265.

Начиная с:

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()`	Возвращает атрибут 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()`	Сообщает, истек ли срок действия этой 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, по которому клиент должен отправлять ее обратно.
`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, но без начального токена "Cookie:".

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

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

Модификатор и тип	Метод	Описание
`protected void`	`finalize()`	Устарело, будет удалено: этот элемент API может быть удален в будущей версии. Финализация устарела и будет удалена в одном из будущих выпусков.
`final Class<?>`	`getClass()`	Возвращает класс времени выполнения этого `Object`.
`final void`	`notify()`	Пробуждает один поток, ожидающий на мониторе этого объекта.
`final void`	`notifyAll()`	Пробуждает все потоки, ожидающие на мониторе этого объекта.
`final void`	`wait()`	Заставляет текущий поток ожидать пробуждения, обычно вследствие вызова notify или interrupt.
`final void`	`wait(long timeoutMillis)`	Заставляет текущий поток ожидать пробуждения, обычно вследствие вызова notify или interrupt, либо истечения заданного промежутка реального времени.
`final void`	`wait(long timeoutMillis, int nanos)`	Заставляет текущий поток ожидать пробуждения, обычно вследствие вызова notify или interrupt, либо истечения заданного промежутка реального времени.

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

HttpCookie

public HttpCookie(String name, String value)

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

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

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

По умолчанию файлы 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()

Сообщает, истёк ли срок действия этого HTTP-файла cookie. Это определяется тем, прошло ли getMaxAge() секунд с момента создания этого объекта.

Возвращает:: true, если срок действия этого HTTP-файла cookie истёк; в противном случае — 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, если его нет

См. также:

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 виден серверам в указанной зоне системы доменных имён (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 будет храниться до закрытия браузера. Значение этого атрибута определяется следующими шагами в соответствии с RFC 6265:

Если был вызван setMaxAge(long), возвращается заданное значение.
Если предыдущий шаг не дал результата и был разобран атрибут Max-Age, возвращается его значение.
Если предыдущий шаг не дал результата и был разобран атрибут Expires, возвращается значение maxAge, вычисленное при разборе на основе этой даты.
Если предыдущие шаги не дали результата, возвращается -1.

Возвращает:

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

См. также:

setPath

public void setPath(String uri)

Задаёт путь, по которому клиент должен возвращать файл 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 следует считать HTTPOnly

См. также:

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, но без начального токена "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.