Класс 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-cookies.
`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)` Создает cookies из строки заголовка 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 - a String specifying the name of the cookie; value - a String specifying the value of the cookie
Исключения:: IllegalArgumentException - if the cookie name contains illegal characters; NullPointerException - if name is null
См. также:: setValue(java.lang.String), setVersion(int)

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

parse

public static List<HttpCookie> parse(String header)

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

Параметры:: header - a String specifying the set-cookie header. The header should start with "set-cookie", or "set-cookie2" token; or it should have no leading token at all.
Возвращает:: a List of cookie parsed from header line string
Исключения:: IllegalArgumentException - if header string violates the cookie specification's syntax or the cookie name contains illegal characters.; NullPointerException - if the header string is null

hasExpired

public boolean hasExpired()

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

Возвращает:: true to indicate this HTTP cookie has expired; otherwise, false

setComment

public void setComment(String purpose)

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

Параметры:: purpose - a String specifying the comment to display to the user
См. также:: getComment()

getComment

public String getComment()

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

Возвращает:: a String containing the comment, or null if none
См. также:: setComment(java.lang.String)

setCommentURL

public void setCommentURL(String purpose)

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

Параметры:: purpose - a String specifying the comment URL to display to the user
См. также:: getCommentURL()

getCommentURL

public String getCommentURL()

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

Возвращает:: a String containing the comment URL, or null if none
См. также:: setCommentURL(java.lang.String)

setDiscard

public void setDiscard(boolean discard)

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

Параметры:: discard - true indicates to discard cookie unconditionally
См. также:: getDiscard()

getDiscard

public boolean getDiscard()

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

Возвращает:: a boolean to represent this cookie's discard attribute
См. также:: setDiscard(boolean)

setPortlist

public void setPortlist(String ports)

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

Параметры:: ports - a String specify the port list, which is comma separated series of digits
См. также:: getPortlist()

getPortlist

public String getPortlist()

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

Возвращает:: a String contains the port list or null if none
См. также:: setPortlist(java.lang.String)

setDomain

public void setDomain(String pattern)

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

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

Параметры:: pattern - a String containing the domain name within which this cookie is visible; form is according to RFC 2965
См. также:: getDomain()

getDomain

public String getDomain()

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

Возвращает:: a String containing the domain name
См. также:: setDomain(java.lang.String)

setMaxAge

public void setMaxAge(long expiry)

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

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

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

Параметры:: expiry - an integer specifying the maximum age of the cookie in seconds; if zero, the cookie should be discarded immediately; otherwise, the cookie's max age is unspecified.
См. также:: getMaxAge()

getMaxAge

public long getMaxAge()

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

Возвращает:: an integer specifying the maximum age of the cookie in seconds
См. также:: setMaxAge(long)

setPath

public void setPath(String uri)

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

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

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

Параметры:: uri - a String specifying a path
См. также:: getPath()

getPath

public String getPath()

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

Возвращает:: a String specifying a path that contains a servlet name, for example, /catalog
См. также:: setPath(java.lang.String)

setSecure

public void setSecure(boolean flag)

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

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

Параметры:: flag - If true, the cookie can only be sent over a secure protocol like HTTPS. If false, it can be sent over any protocol.
См. также:: getSecure()

getSecure

public boolean getSecure()

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

Возвращает:: false if the cookie can be sent over any standard protocol; otherwise, true
См. также:: setSecure(boolean)

getName

public String getName()

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

Возвращает:: a String specifying the cookie's name

setValue

public void setValue(String newValue)

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

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

Параметры:: newValue - a String specifying the new value
См. также:: getValue()

getValue

public String getValue()

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

Возвращает:: объект 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 , если данная куки должна считаться HTTPOnly
См. также:: setHttpOnly(boolean)

setHttpOnly

public void setHttpOnly(boolean httpOnly)

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

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

domainMatches

public static boolean domainMatches(String domain,
                                    String host)

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

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

эффективный имя хоста = имя хоста, если имя хоста содержит точку
или = имя хоста.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:".

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

equals

public boolean equals(Object obj)

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

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

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

hashCode

public int hashCode()

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

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

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

clone

public Object clone()

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

Переопределяет:: clone в классе Object
Возвращает:: копию этой HTTP-куки
См. также:: 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.