Asakusa Framework Option系クラス

Asakusa FrameworkのOperator DSLで使うOption系クラスについて。

概要

ユーザー演算子をプログラマーが実装する際は、DMDLから生成されたモデルクラスのgetter/setterメソッドを使って値の移送や演算を行う。
これらのメソッドは、int・String等の“通常のJavaのプリミティブ型およびクラス”を扱うメソッドの他に、Option系クラス（AsakusaFW独自のクラス）で扱うメソッドが用意されている。

Option系クラスはint・String等を内包している感じのクラスで、モデルクラスのフィールドはOption系クラスを保持するようになっている。
また、Option系クラスはHadoopのWritableとの変換機能を持っている。

なお、Option系クラスは読み取るだけならマルチスレッドセーフ（MTセーフ）なので、Operatorクラスに定数のstaticフィールドとして保持する使い方は問題ない。[2015-07-06]

値の取得・設定（各Option共通）

DMDLから生成されたモデルクラスでは、intやlongといった普通のJavaの型を扱うメソッドと、Optionクラスそのものを返すメソッドが生成されている。

//データモデルsales_detailのINT型のプロパティーamountの例

	public void example(SalesDetail model) {
		int value = model.getAmount();
		model.setAmount(value * 2);
	}

↓↑同じ

import com.asakusafw.runtime.value.IntOption;

	public void example(SalesDetail model) {
		IntOption amountOption = model.getAmountOption();
		int value = amountOption.get();
		amountOption.modify(value * 2);
	}

モデルクラスの普通のJavaの型を扱うメソッドも、内部ではOptionクラスのメソッドを呼び出している。
なお、setterに相当するmodifyメソッドは、プログラマーが直接呼び出すのは非推奨になっている。
（OptionからOptionへコピーするcopyFromというメソッドもあるが、これも非推奨）
（Java8のOptionalやScalaのOptionは不変オブジェクトだが、AsakusaFWのOption系クラスは可変オブジェクトである。しかしなるべく変更させない（不変オブジェクトの様に扱わせたい）為に、setという名前を使わずmodifyという変わったメソッド名にし、またmodifyやcopyFromは非推奨にしているのだと思う）

※get()は値がnullだとNullPointerExceptionが発生するので注意。

→値を比較するために取得するなら、getメソッドでなくhasメソッドの方が便利かも。[2016-02-11]

nullの扱い（各Option共通）

Option系クラスでは、nullも保持できるようになっている。
もしnullを保持している状態でget()を呼び出すとNullPointerExceptionが発生するので、nullになる可能性があるプロパティーから値を読み出す場合はnullチェックをきちんと行う必要がある。

//データモデルsales_detailのINT型のプロパティーamountの例

	public void example(SalesDetail model) {
		int value;
		if (model.getAmountOption().isNull()) {
			value = 0;
		} else {
			value = model.getAmount();
		}

		model.setAmount(value * 2);
	}

↓↑同じ

	public void example(SalesDetail model) {
		int value = model.getAmountOption().or(0);

		model.setAmount(value * 2);
	}

保持している内容がnullのときに初期値を使うという場合は、orメソッドが便利。
orメソッドは、内容がnullの場合は与えられた引数を返し、null以外の場合は保持している内容を返す。

AsakusaFW 0.9.1で、isPresent（「! isNull()」と同等）、orOptionメソッドが追加になった。[2017-04-30]

→値を比較するためにnullチェックしているのなら、isNullメソッドでなくhasメソッドの方が便利かも。[2016-02-11]

AsakusaFWの思想としては、

1. バッチ全体の最初に入力データの精査を行い、データ形式が正しいかどうかをチェックする。つまりnullチェック等をきちんと行い、エラーにしたり変換したりして正しいデータだけを後続処理に渡す。
2. 後続処理では（正しいデータだけが来ているはずなので）（nullチェックはせずに）データを普通にgetする。

という事なのだと思う。

等値比較（各Option共通）

Option系クラスではhashCodeやequalsメソッドが実装されているので、Optionクラスのままでの比較も問題なく行える。

	private void example(SalesDetail model1, SalesDetail model2) {
		if (model1.getAmount() == model2.getAmount()) {	// int
			〜
		}
	}

↓↑ほぼ同じ

	private void example(SalesDetail model1, SalesDetail model2) {
		if (model1.getAmountOption().equals(model2.getAmountOption())) {
			〜
		}
	}

一見すると上の方式の方が短くて良さそうだが、値がnullの場合はNullPointerExceptionが発生するので注意。
下の方式だとお互いがnullの場合も真になる。

※特にStringOptionでは下の方式が良いと思う。

また、各Optionクラスにはhasメソッドが用意されている。[2016-02-11]
これは、Optionの中の値が一致しているかどうかを判定するもの。

	private boolean compare(StringOption option, String s) {
		if (option.isNull()) {
			return s == null;
		}
		return option.getAsString().equals(s);
	}

↓↑ほぼ同じ

	private boolean compare(StringOption option, String s) {
		return option.has(s);
	}

	private boolean compare(IntOption option, int n) {
		return option.isNull() ? false : option.get() == n;
	}

↓↑ほぼ同じ

	private boolean compare(IntOption option, int n) {
		return option.has(n);
	}

退避方法（各Option共通）

値を保存（退避）しておきたい場合、Option系クラスでは注意が必要。[2014-12-21]

OptionやTextを取得すると、モデルオブジェクト内で使っているインスタンスがそのまま返ってくる。
AsakusaFWのOption系クラスやTextは可変オブジェクトなので、モデルオブジェクトの値を変更すると、取得したOptionやTextも同じく変わってしまう。
Stringやint等のOption内部の値（不変オブジェクト）で取得すれば、（インスタンスは別になるので）モデルオブジェクトの値を変更しても影響を受けない。

プロパティーへの値のセット（StringOption同士やIntOption同士の値の受け渡し）は値のコピーなので（インスタンスの共有ではないので）、影響を受け合うことは無い。

数値系Option

IntOption・LongOptionやDecimalOptionといった数値を扱うOptionクラスでは、値を加算するaddメソッドが用意されている。

	public void example(SalesDetail model) {
		model.setAmount(model.getAmount() + 123);
	}

↓↑同じ

	public void example(SalesDetail model) {
		model.getAmountOption().add(123);
	}

↓↑同じ

	private static final IntOption INT123 = new IntOption(123);

	public void example(SalesDetail model) {
		model.getAmountOption().add(INT123);
	}

addメソッドも（get()と同じく）足される側の値がnullだったらNullPointerExceptionが発生する。
足す側を足される側と同じOptionクラスとすることも出来るが、その場合、足す側の値がnullだとNullPointerExceptionは起きず、何も処理されない。
（上記の例のINT123の中身がもしnullだったら、amountには何も加算されず、NPEも発生しない。（その場合でも、足される側（amount）がnullだとNPEが発生する））

値がnullだったら0として加算したいような場合は、orメソッドと組み合わせる。

// DecimalOption（BigDecimal）の例

import java.math.BigDecimal;

	private void example(HogeModel model1, HogeModel model2) {
		model1.setAmount(model1.getAmountOption().or(BigDecimal.ZERO).add(model2.getAmountOption().or(BigDecimal.ZERO)));
	}

↓↑同じ

import com.asakusafw.runtime.value.DecimalOption;

	private void example(HogeModel model1, HogeModel model2) {
		add(model1.getAmountOption(), model2.getAmountOption());
	}

	@SuppressWarnings("deprecation")
	private static void add(DecimalOption decimal1, DecimalOption decimal2) {
		decimal1.modify(decimal1.or(BigDecimal.ZERO).add(decimal2.or(BigDecimal.ZERO)));
	}

Option系クラスは内部で値を保持している為、Optionオブジェクトを渡して演算することも出来る。
こういったメソッドを集めたユーティリティークラスを用意しておくと便利かも。

DateOption・DateTimeOption

DateOptionは日付（年月日）、DateTimeOptionは日時（年月日時分秒）を保持するOptionクラス。

IntOptionがint、StringOptionがText（一応String）を保持しているのでDateOptionはDateを保持している…と思ったら、java.util.Dateではなく独自のcom.asakusafw.runtime.value.Dateを使っている＾＾；
DateTimeもAsakusaFW独自のクラスで、秒までしか保持しない。（ミリ秒以下は扱えない）
どうでもいいが、DateクラスのJavadocに民法へのリンクが張ってあるのは違和感があるな(爆)

DateやDateTimeクラスには年・月・日などの要素を個別に指定できるコンストラクターがあったり、それらを個別に取得するgetterがあったりして、便利。
ただ、要素を個別に設定するsetterや、差分を取ったり時間を加算したりするメソッドは無い。
com.asakusafw.runtime.value.DateUtilに似たことをやっているメソッドがあるので、それを参考にして自分で作ることは出来るが…。

import com.asakusafw.runtime.value.Date;
import com.asakusafw.runtime.value.DateTime;
import com.asakusafw.runtime.value.DateUtil;

値は、Dateはint（基準日0001/01/01からの経過日数）、DateTimeはlong（基準日時0001/01/01 00:00:00からの経過秒数）で保持している。
（Java標準のjava.util.Date等とは基準日が異なるので注意）

String（文字列）からの変換は専用のvalueOfメソッドが提供されているので、その書式を使う場合はSimpleDateFormatよりも実行効率が良い。
（少なくとも、SimpleDateFormatをstaticフィールドに定義するのはやめた方がよい。→マルチスレッドの注意 [2015-06-21]）

AsakusaFWのDateやDateTimeは（基準時点からの経過日数・秒数で値を保持しているので）（java.util.Dateと同様に）タイムゾーンは保持していない。[2016-05-30]
一方、SimpleDateFormatやCalendarはタイムゾーンを保持しているので、変換の際には考慮が必要。

AsakusaFWのDateUtilのgetFromCalendar系メソッドでは、Calendarのgetメソッドを呼んで値を取得しているので、Calendarのタイムゾーンが考慮された値が使われることになる。
setToCalendar系メソッドでもCalendarのsetメソッドを呼んで値を設定しているので、Calendarのタイムゾーンの値としてセットされることになる。

DateUtilでjava.util.Dateを引数にとるgetFromDate系メソッドでは内部でCalendarインスタンスが使われるが、このCalendarはデフォルトタイムゾーンとなるので、注意が必要。

Scalaとの類似

AsakusaFWのOption系クラスは、ScalaのOptionクラスと似ている部分がある。