Cookie (Servlet および JavaServer Pages API ドキュメント)

概要

パッケージ

クラス

使用

階層ツリー

非推奨 API

索引

ヘルプ

前のクラス 次のクラス

フレームあり フレームなし

概要: 入れ子 | フィールド | コンストラクタ | メソッド

詳細: フィールド | コンストラクタ | メソッド

javax.servlet.http
クラス Cookie

java.lang.Object
  |
  +--javax.servlet.http.Cookie

すべての実装インタフェース:: Cloneable

public class Cookie
extends Object
implements Cloneable

Cookie を生成します。Cookie は少量の情報を Servlet から Web ブラウザに送り、ブラウザにそれを維持しもらい、以降のアクセスでサーバに送り返してもらう仕組です。 Cookie の値はクライアントを一意に識別できるようになっているので一般にセッション管理に用いられています。

Cookie には名前と値が一つありますが、他にコメントやパス、ドメイン、最長存続期間、バージョンといったオプショナルな属性もあります。 Web ブラウザの中にはオプショナルな属性の扱いにバグがあるものがあります。このため、Servlet の相互運用性を高めるためにはあまり使わないほうがいいでしょう。

Servlet は HttpServletResponse.addCookie(javax.servlet.http.Cookie) メソッドを使って、 Cookie をブラウザに送ります。このメソッドは HTTP レスポンスヘッダにブラウザに送り返す Cookie フィールドを一度にひとつだけ追加します。ブラウザは一つの Web サーバに対して 20 個、全体で 300 個のクッキーが保持できるものとされています。またブラウザは、クッキーに4KB という上限を設けてもかまいません。

ブラウザは HTTP リクエストヘッダに Cookie フィールドを付けて Servlet に送り返してきます。Cookie はリクエストから取得しますが、このとき HttpServletRequest.getCookies() メソッドを使います。同じ名前でもパス属性が違う Cookie がいくつも存在することは十分ありうることです。

Cookie が使われていると、その Webページのキャッシュに影響します。 HTTP/1.0 ではこのクラスを使って生成された Cookie があるページはキャッシュしません。このクラスは HTTP/1.1 で規定されているキャッシュ制御をサポートしていません。

このクラスは Version 0(Netscpe が考案した Cookie) と Version 1 (RFC2109 で規定されている Cookie) の 2種類の仕様をサポートしています。デフォルトでは最も相互運用性があると考えられるVersion 0 で Cookie を生成します。

バージョン:: $Version$
作成者:: Various

コンストラクタの概要

Cookie(String name, String value)
          指定された名前と値で Cookie を生成します。

メソッドの概要

Object clone()
          標準の java.lang.Object.clone メソッドをオーバライドしています。

String getComment()
          この Cookie がどのような目的で使われるかを記述したコメントを返します。

String getDomain()
          この Cookie にセットさえているドメイン名を返します。

int getMaxAge()
          Cookie の最長存続期間の値を秒単位の数値で返します。

String getName()
          Cookie の名前を返します。

String getPath()
          ブラウザが送り返してきた Cookie に含まれているサーバ上のパスを返します。

boolean getSecure()
          セキュアなプロトコルを使っている場合のみ、ブラウザが Cookie を送ってくるようになっているなら true を返します。

String getValue()
          Cookie の値を返します。

int getVersion()
          それぞれの仕様に取り込まれた Cookie のプロトコルのバージョンを返します。

void setComment(String purpose)
          Cookie がどのような目的をもっているのかを記述するコメントをセットします。

void setDomain(String pattern)
          この Cookie がどこで生成されたかを表すドメインを指定します。

void setMaxAge(int expiry)
          Cookie の最長存続期間を秒単位で設定します。

void setPath(String uri)
          クライアントがこの Cookie を返さなくてはいけないパスを指定します。

void setSecure(boolean flag)
          HTTPS や SSL のようなセキュアなプロトコルを使っている場合のみ Cookie を送り返すようにブラウザに指示します。

void setValue(String newValue)
          Cookie が生成された後で、新しい値を設定します。

void setVersion(int v)
          この Cookie が採用しているプロトコルのバージョンを設定します。

クラス java.lang.Object から継承したメソッド

equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

コンストラクタの詳細

Cookie

public Cookie(String name,
              String value)

指定された名前と値で Cookie を生成します。

名前は RFC 2109 に従ったものでなければいけません。つまり、使えるのは ASCII 英数字のみでカンマやセミコロン、空白が入っていたり、 $ 文字で始まっていていはいけません。また、Cookie の名前は後で、変更することはできません。

サーバが送る値には、そのような制約はありません。値はおそらく、それを付与したサーバでなければ意味のないものでしょう。 Cookie で維持する値は setValue メソッドを使うと、生成時だけではなく、後になってから変更できます。

デフォルトでは Cookie は Netscape が考案した Cookie 仕様に従った形式で生成されます。バージョンは setVersion メソッドを使って変更できます。

パラメータ:

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

value - Cookie の値を指定するString

例外:

IllegalArgumentException - Cookie の名前に不正な文字(例えば、カンマ、スペース、セミコロン)か、 Cookie プロトコルで予約されている字句のどれかが含まれている場合

メソッドの詳細

setComment

public void setComment(String purpose)

Cookie がどのような目的をもっているのかを記述するコメントをセットします。コメントはブラウザが Cookie をユーザに表示するときに目的を明示できるので便利です。ただし、Netscape Version 0 ではサポートされていません。

パラメータ:: purpose - ユーザに表示するコメント指定するString
関連項目:: getComment()

getComment

public String getComment()

この Cookie がどのような目的で使われるかを記述したコメントを返します。コメントがなければ null を返します。

戻り値:: コメントの文字列を表す String。コメントがない場合は null を返します。
関連項目:: setComment(java.lang.String)

setDomain

public void setDomain(String pattern)

この Cookie がどこで生成されたかを表すドメインを指定します。

ドメイン名の形式は RFC2109 で指定されています。ドメイン名は (.foo.com のように) ドットで始まります。このように設定すると、Cookie は指定された Domain Name System (DNS) のゾーン内のサーバから見えるようになります(例えば、www.foo.com) からは見えるけれど、a.b.foo.com からは見えないというようにです)。デフォルトでは Cookie を付与したサーバにしか送り返しません。

パラメータ:: pattern - この Cookie が見えてもよいドメイン名を指定するString。 RFC2109 に従った形式で指定
関連項目:: getDomain()

getDomain

public String getDomain()

この Cookie にセットさえているドメイン名を返します。ドメイン名は RFC2109 で指定されている形式になっています。

戻り値:: ドメイン名を表すString
関連項目:: setDomain(java.lang.String)

setMaxAge

public void setMaxAge(int expiry)

Cookie の最長存続期間を秒単位で設定します。

正の値が指定されると Cookie はある秒数が過ぎた後、削除されます。この値は、Cookie の有効期限が切れる最長存続期間であることに注意してください。 Cookie の現在までの存続期間ではありません。

負の値は Cookie が永続的に保存されないことを意味しています。この場合、 Web ブラウザが終了すると Cookie も削除されます。 0 という値を指定すると Cookie が削除されることになります。

パラメータ:: expiry - Cookie の最長存続期間を秒単位で指定する整数値。負の値は Cookie を保存しない、 0 なら Cookie を削除する意味となる。
関連項目:: getMaxAge()

getMaxAge

public int getMaxAge()

Cookie の最長存続期間の値を秒単位の数値で返します。デフォルトでは -1 で、Cookie はブラウザが停止されるまでの間、維持されます。

戻り値:: Cookie の最長存続期間を表す秒単位の整数値。負の値なら Cookie はブラウザが停止されるまでの間有効
関連項目:: setMaxAge(int)

setPath

public void setPath(String uri)

クライアントがこの Cookie を返さなくてはいけないパスを指定します。

この値を指定すると Cookie が該当するディレクトリ内、さらに、サブディレクトリに存在する全てのページから参照できるようになります。 Cookie のパスには Cookie をセットした Servlet が含まれていなければなりません。例えば、/catalog を指定したとします。このとき、サーバの /catalog 以下の全てのディレクトリから Cookie が見えるようになります。

Cookie のパス名指定についての詳細は RFC2109 (インターネットで公開されています。) を参照してください。

パラメータ:: uri - パスを指定するString
関連項目:: getPath()

getPath

public String getPath()

ブラウザが送り返してきた Cookie に含まれているサーバ上のパスを返します。 Cookie はサーバにおけるすべてのサブパスから参照できます。

戻り値:: Servlet の名前を含むパス名が指定されている String。例えば /catalog のようなパス名
関連項目:: setPath(java.lang.String)

setSecure

public void setSecure(boolean flag)

HTTPS や SSL のようなセキュアなプロトコルを使っている場合のみ Cookie を送り返すようにブラウザに指示します。

デフォルト値は false です。

パラメータ:: flag - true にすると、セキュアなプロトコルを使用しているときのみブラウザからサーバに Cookie を送り返す。一方、false にすると, どのようなプロトコルであっても送り返す。
関連項目:: getSecure()

getSecure

public boolean getSecure()

セキュアなプロトコルを使っている場合のみ、ブラウザが Cookie を送ってくるようになっているなら true を返します。また、どのようなプロトコルでもブラウザが Cookie を送れるようになっている場合は false を返します。

戻り値:: セキュアなプロトコルを使っているときのみ Cookie を送り返すように設定されている場合は true。その他のプロトコルでは false (訳注: 原文に誤りがあるので訂正した。)
関連項目:: setSecure(boolean)

getName

public String getName()

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

戻り値:: Cookie の名前を示す String

setValue

public void setValue(String newValue)

Cookie が生成された後で、新しい値を設定します。バイナリの値を設定する場合は BASE64 エンコードするといいでしょう。

バージョン0 の Cookie では、値は空白、山形かっこ、丸かっこ、等号、カンマ、二重引用符、スラッシュ、引用記号、アットマーク、コロン、セミコロンを含んでいてはいけません。空の値を設定した場合のふるまいはブラウザに依存します。
(訳注: 角かっこ、中かっこ、バックスラッシュ、疑問符、タブも含んではいけません。)

パラメータ:: newValue - 新しい値を指定するString
関連項目:: getValue(), Cookie

getValue

public String getValue()

Cookie の値を返します。

戻り値:: Cookie の現在の値を含む String
関連項目:: setValue(java.lang.String), Cookie

getVersion

public int getVersion()

それぞれの仕様に取り込まれた Cookie のプロトコルのバージョンを返します。バージョン1 は RFC2109 が採用されていますが、バージョン0 は Netscape が提案したオリジナルの Cookie の仕様に従ったものです。ブラウザから提供される Cookie は、ブラウザが採用している Cookie のバージョンを使用し、また、そのバージョンと一致します。

戻り値:: 採用されている Cookie が Netscape のオリジナル仕様にしたがったものである場合 0。または、 RFC2109 にしたがってる場合 1
関連項目:: setVersion(int)

setVersion

public void setVersion(int v)

この Cookie が採用しているプロトコルのバージョンを設定します。バージョン0 ならオリジナルの Netscpe Cookie の仕様にしたがったものです。バージョン1なら RFC2109 にしたがったものです。

RFC2109 は未だに新しいものと受け取られていて、バージョン1 は実験的な仕様と考えられています。商用サイトではまだ使わないでください。

パラメータ:: v - オリジナルの Netscape の仕様にしたがっているなら 0 を、また、RFC2109 にしたがっているなら 1 を指定
関連項目:: getVersion()

clone

public Object clone()

標準の java.lang.Object.clone メソッドをオーバライドしています。このメソッドは Cookie のコピーを返します。

オーバーライド:: クラス Object 内の clone

概要