java.net

クラス HttpCookie

java.lang.Object

java.net.HttpCookie

すべての実装されたインタフェース:

Cloneable

public final class HttpCookie
extends Object
implements Cloneable

HttpCookie オブジェクトは、サーバーとユーザーエージェントとの間で状態情報を伝達する HTTP Cookie を表します。Cookie は、ステートフルセッションを作成する目的で広く採用されています。

HTTP Cookie の仕様には次の 3 つがあります。

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) 2 つの HTTP Cookie が等しいかどうかを判定します。
String	getComment() この Cookie の目的を説明するコメントを返します。Cookie にコメントがない場合は、null を返します。
String	getCommentURL() この Cookie の目的を説明するコメント URL を返します。この Cookie にコメント URL がない場合は nullを返します。
boolean	getDiscard() Cookie の破棄属性を返します。
String	getDomain() この Cookie に設定されたドメイン名を返します。
long	getMaxAge() Cookie の最長有効期間を秒数で返します。
String	getName() Cookie の名前を返します。
String	getPath() ブラウザがこの Cookie を返す先となる、サーバー上のパスを返します。
String	getPortlist() Cookie のポートリスト属性を返します。
boolean	getSecure() この Cookie の送信をセキュアなプロトコルに制限すべき場合は true、どのようなプロトコルを使用して送信してもかまわない場合は false を返します。
String	getValue() Cookie の値を返します。
int	getVersion() この Cookie が準拠するプロトコルのバージョンを返します。
boolean	hasExpired() この HTTP Cookie の有効期限が切れているかどうかを報告します。
int	hashCode() この HTTP Cookie のハッシュコードを返します。
boolean	isHttpOnly() この Cookie が HttpOnly 属性を含む場合は true を返します。
static List<HttpCookie>	parse(String header) set-cookie または set-cookie2 ヘッダー文字列から Cookie を構築します。
void	setComment(String purpose) Cookie の目的を説明するコメントを指定します。
void	setCommentURL(String purpose) Cookie の目的を説明するコメント URL を指定します。
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 は RFC 2965 の Cookie 仕様に従って作成されます。バージョンを変更するには setVersion メソッドを使用します。

パラメータ:

name − Cookie の名前を指定する String

value − Cookie の値を指定する String

例外:

IllegalArgumentException − Cookie 名に不当な文字が含まれているか、Cookie 名が Cookie プロトコル用として予約されているトークンの 1 つである場合

NullPointerException - name が null の場合

関連項目:

setValue(java.lang.String), setVersion(int)

メソッドの詳細

parse

public static List<HttpCookie> parse(String header)

set-cookie または set-cookie2 ヘッダー文字列から Cookie を構築します。RFC 2965 セクション 3.2.2 の set-cookie2 構文によれば、1 つのヘッダー行に複数の Cookie 定義を含めることができます。それで、これは別のコンストラクタではなく、static ユーティリティーメソッドになっています。

パラメータ:

header − set-cookie ヘッダーを指定する String。ヘッダーは、「set-cookie」または「set-cookie2」トークンで始まっているか、開始トークンをまったく持たないか、のいずれかにすべきである。

戻り値:

ヘッダー行文字列から解析された Cookie のリスト

例外:

IllegalArgumentException − ヘッダー文字列が Cookie 仕様の構文に違反しているか、Cookie 名に不当な文字が含まれているか、Cookie 名が Cookie プロトコル用として予約されているトークンの 1 つである場合

NullPointerException − ヘッダー文字列が null の場合

hasExpired

public boolean hasExpired()

この HTTP Cookie の有効期限が切れているかどうかを報告します。

戻り値:

この HTTP Cookie の有効期限が切れていることを示す場合は true。そうでない場合は false

setComment

public void setComment(String purpose)

Cookie の目的を説明するコメントを指定します。コメントは、ブラウザが Cookie をユーザーに表示する場合に役立ちます。Netscape バージョン 0 の Cookie では、コメントはサポートされません。

パラメータ:

purpose − ユーザーに表示するコメントを指定する String

関連項目:

getComment()

getComment

public String getComment()

この Cookie の目的を説明するコメントを返します。Cookie にコメントがない場合は、null を返します。

戻り値:

コメントが格納された String。コメントがない場合は null

関連項目:

setComment(java.lang.String)

setCommentURL

public void setCommentURL(String purpose)

Cookie の目的を説明するコメント URL を指定します。コメント URL は、ブラウザが Cookie をユーザーに表示する場合に役立ちます。コメント URL は RFC 2965 専用です。

パラメータ:

purpose − ユーザーに表示するコメント URL を指定する String

関連項目:

getCommentURL()

getCommentURL

public String getCommentURL()

この Cookie の目的を説明するコメント URL を返します。この Cookie にコメント URL がない場合は nullを返します。

戻り値:

コメント URL が格納された String。コメントがない場合は null

関連項目:

setCommentURL(java.lang.String)

setDiscard

public void setDiscard(boolean discard)

ユーザーエージェントが Cookie を無条件に破棄すべきかどうかを指定します。これは、RFC 2965 専用の属性です。

パラメータ:

discard − true は、Cookie を無条件に破棄することを示します

関連項目:

getDiscard()

getDiscard

public boolean getDiscard()

Cookie の破棄属性を返します。

戻り値:

この Cookie の破棄属性を表す boolean

関連項目:

setDiscard(boolean)

setPortlist

public void setPortlist(String ports)

Cookie のポートリストを指定します。このリストは、Cookie を Cookie ヘッダー内に収めて送り返す際に使用できるポート (複数可) を制約します。

パラメータ:

ports − ポートリストを指定する String。これは数字のコンマ区切りリストです

関連項目:

getPortlist()

getPortlist

public String getPortlist()

Cookie のポートリスト属性を返します。

戻り値:

ポートリストが格納された String。存在しない場合は null

関連項目:

setPortlist(java.lang.String)

setDomain

public void setDomain(String pattern)

この Cookie が提示されるドメインを指定します。

ドメイン名の形式は、RFC 2965 に指定されています。ドメイン名は .foo.com のようにドットで始まり、指定されたドメインネームシステム (DNS) のゾーン内のサーバーがその Cookie を参照できることを示しています。たとえばこの場合、www.foo.com は Cookie を参照できますが、a.b.foo.com は Cookie を参照できません。特に指定しないかぎり、Cookie はそれを送信したサーバーにのみ返されます。

パラメータ:

pattern − この Cookie が可視となるドメイン名が格納された String。形式は RFC 2965 に従います

関連項目:

getDomain()

getDomain

public String getDomain()

この Cookie に設定されたドメイン名を返します。ドメイン名の形式は、RFC 2965 によって規定されています。

戻り値:

ドメイン名が格納された String

関連項目:

setDomain(java.lang.String)

setMaxAge

public void setMaxAge(long expiry)

Cookie の最長有効期間を秒数で設定します。

正の値を指定すると、その秒数が経過したあとに Cookie が期限切れになります。この値は、Cookie の現在の有効期間ではなく、Cookie の期限が切れるまでの最長の有効期間であることに注意してください。

負の値を指定すると、Cookie は持続的に保持されずに、Web ブラウザが終了したときに削除されます。0 の値を指定すると、Cookie が削除されます。

パラメータ:

expiry − Cookie の最長有効期間を秒数で指定する整数。0 の場合、Cookie はすぐに破棄され、それ以外の場合、Cookie の最長有効期間は未定義となります。

関連項目:

getMaxAge()

getMaxAge

public long getMaxAge()

Cookie の最長有効期間を秒数で返します。デフォルトは -1 です。これは、ブラウザがシャットダウンされるまで Cookie が持続することを示します。

戻り値:

Cookie の最長有効期間を秒数で指定する整数

関連項目:

setMaxAge(long)

setPath

public void setPath(String uri)

クライアントが Cookie を返す必要のある Cookie のパスを指定します。

指定されたディレクトリ内のすべてのページと、そのディレクトリのサブディレクトリ内のすべてのページに対して、Cookie が可視になります。Cookie のパスにはその Cookie を設定するサーブレットを含めてください。たとえば、/catalog を指定した場合、サーバー上の /catalog の下にあるすべてのディレクトリに対して、Cookie が可視になります。

Cookie のパス名の設定方法についての詳細は、RFC 2965 で調べてください。RFC 2109 は、インターネットで公開されています。

パラメータ:

uri − パスを指定する String

関連項目:

getPath()

getPath

public String getPath()

ブラウザがこの Cookie を返す先となる、サーバー上のパスを返します。サーバー上のすべてのサブパスに対して、Cookie が可視になります。

戻り値:

サーブレット名を含むパスを指定する String。例: /catalog

関連項目:

setPath(java.lang.String)

setSecure

public void setSecure(boolean flag)

Cookie を HTTPS や SSL などのセキュアなプロトコルのみを使用して送信するべきかどうかを示します。

デフォルト値は false です。

パラメータ:

flag - true の場合、Cookie を送信できるのは HTTPS のようなセキュアなプロトコル上でのみです。false の場合、任意のプロトコル上で送信できます。

関連項目:

getSecure()

getSecure

public boolean getSecure()

この Cookie の送信をセキュアなプロトコルに制限すべき場合は true、どのようなプロトコルを使用して送信してもかまわない場合は false を返します。

戻り値:

Cookie を任意の標準プロトコル上で送信できる場合は false。その他の場合は true

関連項目:

setSecure(boolean)

getName

public String getName()

Cookie の名前を返します。作成後に名前を変更することはできません。

戻り値:

Cookie の名前を指定する String

setValue

public void setValue(String newValue)

Cookie の作成後に、Cookie に新しい値を割り当てます。バイナリ値を使用する場合は、BASE64 エンコーディングの使用をお勧めします。

バージョン 0 の Cookie の場合、空白、角括弧、括弧、等号、コンマ、二重引用符、スラッシュ、疑問符、単価記号、コロン、およびセミコロンを値に含めないようにしてください。空の値を指定すると、ブラウザ間で異なる動作をする可能性があります。

パラメータ:

newValue − 新しい値を指定する String

関連項目:

getValue()

getValue

public String getValue()

Cookie の値を返します。

戻り値:

Cookie の現在の値が格納された String

関連項目:

setValue(java.lang.String)

getVersion

public int getVersion()

この Cookie が準拠するプロトコルのバージョンを返します。バージョン 1 は RFC 2965/2109 に準拠し、バージョン 0 は Netscape による元の Cookie ドラフト仕様に準拠します。ブラウザから提供される Cookie は、そのブラウザの Cookie バージョンを使用および識別します。

戻り値:

Cookie が元の Netscape 仕様に準拠する場合は 0、RFC 2965/2109 に準拠する場合は 1

関連項目:

setVersion(int)

setVersion

public void setVersion(int v)

この Cookie が準拠する Cookie プロトコルのバージョンを設定します。バージョン 0 は元の Netscape Cookie 仕様に準拠します。バージョン 1 は RFC 2965/2109 に準拠します。

パラメータ:

v − Cookie が元の Netscape 仕様に準拠すべきである場合は 0、RFC 2965/2109 に準拠すべきである場合は 1

例外:

IllegalArgumentException − v が 0、1 のいずれでもない場合

関連項目:

getVersion()

isHttpOnly

public boolean isHttpOnly()

この Cookie が HttpOnly 属性を含む場合は true を返します。これは、JavaScript のようなスクリプトエンジンが Cookie にアクセスできてはいけないことを意味します。

戻り値:

この Cookie を HTTP のみとみなすべき場合は true。

関連項目:

setHttpOnly(boolean)

setHttpOnly

public void setHttpOnly(boolean httpOnly)

Cookie を HTTP Only とみなすべきかどうかを示します。true に設定されている場合、JavaScript のようなスクリプトエンジンが Cookie にアクセスできてはいけないことを意味します。

パラメータ:

httpOnly - true の場合は Cookie を HTTP のみとします。つまり、HTTP 要求の一部としてのみ可視となります。

関連項目:

isHttpOnly()

domainMatches

public static boolean domainMatches(String domain,
                    String host)

あるホスト名があるドメインに含まれるかどうかをチェックするためのユーティリティーメソッド。

この概念については、Cookie 仕様内で説明されています。この概念を理解するには、まず、いくつかの用語を定義しておく必要があります。

有効ホスト名 = ホスト名にドットが含まれる場合は hostname、
ドットが含まれない場合は hostname.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 は 1 つ以上のドットを含む文字列である。

例

• 要求ホスト y.x.foo.com からの Domain=.foo.com の Set-Cookie2 は拒否される。なぜなら、H は y.x であり、ドットが含まれるからである。
• 要求ホスト x.foo.com からの Domain=.foo.com の Set-Cookie2 は受け入れられる。
• Domain=.com または Domain=.com. を含む Set-Cookie2 は常に拒否される。なぜなら、埋め込みドットが存在しないからである。
• Domain=ajax.com を含む Set-Cookie2 は受け入れられ、Domain の値は .ajax.com であるとみなされる。なぜなら、値の先頭にはドットが追加されるからである。
• 要求ホスト example からの Domain=.local の Set-Cookie2 は受け入れられる。なぜなら、要求ホストの有効ホスト名は 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)

2 つの HTTP Cookie が等しいかどうかを判定します。

結果が true になるのは、2 つの Cookie が同じドメイン (大文字、小文字の区別なし) から送られてきたものであり、同じ名前 (大文字、小文字の区別なし) を持ち、同じパス (大文字、小文字の区別あり) を持つ場合だけです。

オーバーライド:

equals、クラス: Object

パラメータ:

obj - 比較対象の参照オブジェクト。

戻り値:

2 つの HTTP Cookie が互いに等しい場合は true。そうでない場合は false

関連項目:

Object.hashCode(), HashMap

hashCode

public int hashCode()

この HTTP Cookie のハッシュコードを返します。結果は、この Cookie の 3 つの主要コンポーネントである名前、ドメイン、パスのハッシュコード値を合計したものになります。すなわち、ハッシュコードは次の式の値です。

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