ひだまりソケットは壊れない

ソフトウェア開発に関する話を書きます。 最近は主に Android アプリ、Windows アプリ (UWP アプリ)、Java 関係です。

まじめなことを書くつもりでやっています。 適当なことは 「一角獣は夜に啼く」 に書いています。

Android の Java で時刻を扱う (Date、Calendar、DateFormat クラス)

Android アプリ Java

Java エンジニアの皆様は Java SE 8 で導入された Date-Time パッケージ (Date and Time API; JSR 310) を便利に使っていることと思います。 残念ながら Android プラットフォームにはそれらの API がありませんので、Android アプリ開発時に時刻を扱う場合は、古くからある API を使用することになります。

この記事では、Android アプリ開発時にお世話になる Date クラス、Calendar クラス、DateFormat クラスについて、それぞれの役割や使い方、気を付けるべきことをまとめます。

追記

(2020-06-03) Android での Date-Time パッケージ

Android の API Level 26 からは java.time パッケージが使えるようになっています。

Android 8.0 (API level 26) adds support for several additional OpenJDK Java APIs:

  • java.time from OpenJDK 8.
  • java.nio.file and java.lang.invoke from OpenJDK 7.
Android 8.0 Features and APIs  |  Android Developers

また、Android Gradle Plugin 4 からは、Java 8+ API desugaring support により、API Level 26 未満のプラットフォームでも java.time パッケージを使用するアプリをビルドできるようになったようです。

If you're building your app using Android Gradle plugin 4.0.0 or higher, the plugin extends support for using a number of Java 8 language APIs without requiring a minimum API level for your app.
(略)
The following set of APIs are supported when building your app using Android Gradle plugin 4.0.0 or higher:

  • (略)
  • A subset of java.time
Use Java 8 language features and APIs  |  Android Developers

(2016-02-18) JSR 310 の Android バックポート

JSR 310 の Android バックポートライブラリの存在を知りました。 Android ではこれを使うのがいいかもしれないですね。

ところで Time クラスは？

Android APIs には Time クラスってやつが含まれています。 API level 22 で非推奨 (deprecated) になったのでそっとしておきましょう。 (これまでありがとうございました。)

気を付けるべきことまとめ

記事が長いので、気を付けるべきことを最初に書いておきます。

  • Date オブジェクト自体はタイムゾーンを持ちません。
    • Calendar を使って指定の Date の年月日や時、分、秒などを取得するとき、あるいはそれらの値を設定したり計算したりするときは、Calendar に適切なタイムゾーンを設定しましょう。 ロケールも必要に応じて設定しましょう。
    • DateFormat を使って Web API などに投げるための時刻の文字列を生成するときは、DateFormat に適切なタイムゾーンを設定しましょう。 ロケールは Locale.US が良さそうです。 *1
  • DateFormat を使って Web API などから取得した時刻の文字列を解析する際は、必要であれば適切なタイムゾーンを設定しましょう。 (解析対象の文字列にタイムゾーンが含まれているのであれば必要ない。) ロケールは Locale.US が良さそうです。
  • Android *2 の SimpleDateFormat は、ISO 8601 や RFC 822 で定義されていて実際にしばしば使われる 「Z」 というタイムゾーン表記を解釈できない (Java SE 7 では X というフォーマット文字が導入されて解釈できるようになった) ので、気を付けましょう。
  • ユーザーに表示するための時刻の文字列を生成する際は、andorid.text.format.DateFormat オブジェクトを使うことで端末の設定を反映させると良いでしょう。

Date、Calendar、DateFormat、それぞれの役割

簡単にまとめると、Date クラスが 「時間軸上の特定の瞬間」 を表すもので、Calendar クラスが年月日や時、分、秒といった情報を扱うクラス、そして DateFormat が時刻を表す文字列と 「時間軸上の特定の瞬間」 の相互変換を行う、という感じです。 詳細は以下に述べます。

Date クラス

Date クラスは、時間軸上の特定の瞬間をミリ秒の精度で表現するクラスです。

純粋に 「時間軸上のある瞬間」 を表現するためのものなので、タイムゾーンを持ちませんし、自身が表現する時刻が何月何日の何時何分なのかを計算したりもしません。 時刻を表現する文字列をパースしたり、逆に時刻を表現する文字列を出力したりもしません。 (歴史的経緯によりそのような機能のメソッドが Date クラスに定義されていますが、非推奨です。)

Calendar クラス

Calendar クラスは、次の 2 つの機能を提供するクラスです。

  • 「時間軸上の特定の瞬間」 と 「何月なのかや何日なのか、何時なのかといった数値情報・カレンダー情報」 の相互変換
  • 何日なのかや何時なのかといった数値情報・カレンダー情報に対する計算。 (例えば、1 週間後の日時を取得する、など。)

Calendar オブジェクトで時刻を表現させようと思えば実際上は可能ではありますが、そういう使い方には Date オブジェクトを用いるべきみたいですね。 年月日などを扱うので、このクラスを使う際は当然 タイムゾーンを気にする必要があります。

GregorianCalendar クラス

Calendar クラスは抽象クラスで、変換や計算の処理は各種サブクラスが提供することになっています。 世界のほとんどの地域で使用される標準的な暦体系に対する実装として、GregorianCalendar が提供されています。

DateFormat クラス (java.text パッケージ)

「時間軸上の特定の瞬間」 を表す値から日付・時刻を表す文字列を生成したり、逆にそれらの文字列を解析する機能を持つクラスです。

年月日などを扱うので、このクラスを使う際は当然 タイムゾーンを気にする必要があります。

SimpleDateFormat クラス

DateFormat のサブクラスです。 自分で日付・時刻の文字列のフォーマットを指定する場合はこのクラスを使用することになります。

DateFormat クラス (android.text.format パッケージ)

めちゃくちゃややこしいのですが、Android APIs には android.text.format.DateFormat というクラスも含まれています。 このクラス自身もフォーマット機能を持っていますし、java.text.DateFormat オブジェクトを返すファクトリメソッドも持っています。

API level 23 の実装だと、java.text.Date クラスの getDateInstance メソッドや getTimeInstance メソッドも端末の設定を見てくれるようですが、API level 10 では android.text.format.DateFormat の getDateFormat メソッドなどを使わないと端末の設定が反映されないようです。 (どこで変更されたかは調べてない。)

なので、端末の設定を反映させて日時や時刻を表示したい場合は、android.text.format.DateFormat クラスを使ってフォーマットを決める必要があるようです。

使い方

各種ユースケースにおいて、上で紹介したクラスをどのように使うかを簡単に紹介します。

Web API でやり取りする時刻の文字列と Date オブジェクトを相互変換する

Web API のレスポンスで "2016-01-01 00:00:00+0900" みたいな時刻を表す文字列を受け取ることがあると思いますが、そういった文字列を Date オブジェクトに変換するにはフォーマットを指定して SimpleDateFormat オブジェクトを作成しましょう。

java.text.DateFormat df = new SimpleDateFormat("yyyy-MM-dd HH:mm:ssZ", Locale.US);
// タイムゾーンが含まれていないような日付文字列を解析する場合は、適したタイムゾーンを指定しましょう。
// df.setTimeZone(TimeZone.getTimeZone("Asia/Tokyo"));

Date d = df.parse("2015-01-01 00:00:00+0900");

ロケールはタイムゾーンの処理にも関わってるぽいです (まじか……) し、Locale.US にしておくのが良さそうです。 例えば、パターン Z を使用してタイムゾーンを解析する場合、Locale.US ならば 「EDT」 を処理できますが、Locale.ROOT や Locale.JAPAN だとパースエラーになります。 (API level 23 で確認。 ロケールに関係なく RFC 822 で定義されているタイムゾーンは解析して欲しい……。 厳しい。) でも Locale.US でも 「Z」 を処理できないから、数値でなく名前で表現されるタイムゾーンの解析周りについてはそもそも信用しないのがいいかもしれないですね。

Web API などに送るための時刻文字列を生成する場合も、同様に SimpleDateFormat を使いましょう。 タイムゾーンは、受け取り側が期待するであろうものを設定しておくのが安全だと思います。

java.text.DateFormat df = new SimpleDateFormat("yyyy-MM-dd HH:mm:ssZ", Locale.US);
// タイムゾーンを出力するにしても Web API 側が期待するタイムゾーンを設定しておいた方が安全でしょう。
df.setTimeZone(TimeZone.getTimeZone("Asia/Tokyo"));

String currentTime = df.format(new Date());

ユーザーに表示するために Date オブジェクトから時刻の文字列を生成する

ユーザーに表示するための時刻文字列は、ユーザーの端末のロケールやタイムゾーンを使用すべきでしょう。 Java では DateFormat.getDateTimeInstance(DateFormat.SHORT, DateFormat.SHORT, Locale.getDefault()) という感じでデフォルトロケールの DateFormat を取得できますが、Android アプリの場合は、端末の設定を反映したフォーマットの DateFormat を取得するために android.text.format.DateFormat を使用するのが良さそうです。

詳細は以下のページを見てください。

(API level 23 では、DateFormat.getDateTimeInstance(DateFormat.SHORT, DateFormat.SHORT, Locale.getDefault()) みたいな感じで取得した DateFormat オブジェクトも端末の設定を反映しているようでしたが、API level 10 だと反映してなかったので、古い端末もサポートするなら android.text.format.DateFormat を使うべきっぽいです。)

Date オブジェクトが表す日の 1 年後、を計算する

例えば今日の 1 年後を表す日を計算したいとします。 そういうときは Calendar を使います。 *3

// 操作対象の Date オブジェクト。
// 日本時間で 2016 年 2 月 29 日の 00:00:00。
Date d = new Date(145667160_0000L);

// Calendar オブジェクトを使って 1 年後を計算して Date オブジェクトを取得。
Calendar c = Calendar.getInstance(TimeZone.getTimeZone("Asia/Tokyo"), Locale.JAPAN);
c.setTime(d);
c.add(Calendar.YEAR, 1); // 年に 1 加算。
Date dateOneYearAfter = c.getTime(); // 2017 年 2 月 28 日の 00:00:00 (日本時間)。

上の例では、タイムゾーンを Asia/Tokyo に設定しています。 タイムゾーンを適切に設定しないと、渡された Date オブジェクトが表す日付が変わる可能性がありますので、適切にタイムゾーンを設定しましょう。 ロケールも週の開始曜日などに影響するので必要に応じて設定しましょう。 (デフォルトタイムゾーン・デフォルトロケールが良い場合はもちろんデフォルトの値を使えば良いです。)

おわり

「時刻を扱うときはタイムゾーンに気を付けなさい」 ということはみんな耳にタコができるぐらい言われてきたと思うので大丈夫だと思いますが、タイムゾーンをちゃんと設定するように気を付けましょう。

*1:ドキュメントにも 『The main reason you'd create an instance this class directly is because you need to format/parse a specific machine-readable format, in which case you almost certainly want to explicitly ask for “US” to ensure that you get ASCII digits (rather than, say, Arabic digits).』 って書かれてる。

*2:少なくとも API level 23 までは。 それより後のバージョンは不明。

*3:単純に 365 日間に相当するミリ秒を加算する、みたいな方法だとうるう年などが考慮できないのでだめですよね。 「1 ヶ月後」 とかだと何日分加算すればいいのかわかんないし。