区分値

• ぱっと見イメージ
• 区分値とは？
  • 区分値のタイプ
  • 区分値要素の属性
  • 区分値の扱いの難しさ
• 区分値のタイプセーフ解決
• 区分値の設定(dfprop)
  • テーブル区分値
  • 暗黙の区分値
• ENUMクラス(CDef)の利用
• SchemaHTMLでの表示
• ネイティヴ型メソッドの削除
• 暗黙の区分値チェック
• デフォルトのジレンマ
• 区分値のグルーピング (GroupingMap)
  • グルーピングの概要
• 姉妹コードの利用 (SisterCode)
• 独自の属性を追加 (SubItemMap)
  • 独自の属性
• Exampleのススメ
• 面倒でも全体の利益のために

ぱっと見イメージ

e.g. テーブル区分値を利用する例 {MemberStatus} @classificationDefinitionMap.dfprop
map:{
    ; MemberStatus = list:{
        ; map:{topComment=入会から退会までの会員のステータスを示す; codeType=String}
        ; map:{
            ; table=MEMBER_STATUS; code=MEMBER_STATUS_CODE
            ; name=MEMBER_STATUS_NAME; comment=DESCRIPTION
            ; orderBy=DISPLAY_ORDER
        }
    }
    ...
}

e.g. 区分値の設定や判定、絞り込み条件設定 @Java
Member member = new Member();
member.setMemberStatusCode_Formalized(); // 設定メソッド (正式会員にする)
...
if (member.isMemberStatusCodeFormalized()) { // 判定メソッド (正式会員かどうか)
    ...
}
String statusCode = ... // リクエストなどから飛んで来たら
member.setMemberStatusCodeAsMemberStatus(
    CDef.MemberStatus.codeOf(statusCode)); // CDef型での設定メソッド

MemberCB cb = new MemberCB();
cb.query().setMemberStatusCode_Equal_Formalized(); // 条件メソッド (正式会員)

区分値とは？

dbfluteでは、あるカラムに格納される意味のある決まった値の集合(カテゴリ)を 区分値 と呼びます。例えば、MaihamaDBでは、会員ステータスコード(MEMBER_STATUS_CODE: 正式会員、仮会員、退会会員)、商品ステータスコード(PRODUCT_STATUS_CODE: 生産可能、販売可能、...) が該当します。 (区分値という言葉を、"区分わけするための値たち" というニュアンスとして捉えています)

また、その区分値のそれぞれの値 (例えば、正式会員) を 区分値要素 と呼びます。区分値と関連付けられたカラムには、その区分値で定義されていない要素は通常格納されませんが、実際に制約が存在するかどうかは区分値の実現方法次第です。 例えば、テーブルで管理していれば、FK制約により区分値に定義されていない値の登録を防ぐことができます。

ただし、区分値、区分値要素と明確に言葉を定義してはいますが、文脈から判断できるような場合は 区分値要素を単に区分値と呼ぶことも あります。 (というか、ほとんどの場合、文脈で判断して "区分値" としか言わないかも...するとでも時々会話がすれ違うことも)

区分値のタイプ

区分値には大きく二つのタイプがあります。

テーブル区分値

テーブル管理されていて定義がデータとして実際に存在する区分値。MaihamaDBでは、会員ステータスや商品ステータスが該当する。 FK制約によるチェックの恩恵を得ることができる。

MaihamaDB

this - 区分値の設定 - テーブル区分値

暗黙の区分値

ドキュメント上で決められているだけで、その定義は人しか知らない区分値。MaihamaDBでは、フラグ系のカラムが該当する。 別途チェック制約などを利用しない限り、DB上でのチェックは掛からない。

this - 区分値の設定 - 暗黙の区分値

前者の方が制約の恩恵を得ることもでき、明示的でわかりやすいため、全ての区分値がこの方式で扱えるのであればそれに越したことはありませんが、例えば "フラグ" (0 or 1) のような汎用的で統一的な区分値の場合は後者のやり方で実現することも多く、一つのアプリ内に混在することも想定されます。

また一方で、テーブル区分値は (DB設計者としては) 面倒だと思われがちですが、そこから得られるメリットとは比べられるものではありません。

区分値要素の属性

(dbfluteにて定義する)区分値要素が持つ属性は以下の通りです。

コード (code)

区分値要素の実際のデータベース上で利用するコード値です。 char型の文字列だったり、数値だったりとDB設計次第でデータ型は変わります。必須の項目です。

名前(識別名) (name)

区分値要素を識別する名前です。基本的には英名を想定しており、メソッド名の一部やENUMの定数名などに利用されます。 よって、そういった場所での利用に適した文字列であることが求められます。必須の項目です。

別名(表示名) (alias)

区分値要素の別名(表示名)です。基本的には人が見るための表示用の名前を想定しており、リストボックスでのラベルやJavaDocコメントなどで利用されます。 ただ、テーブル区分値の場合は、そもそもカラムから取得できるため、あまりプログラム上で利用されることは少ないかもしれません(キャッシュとしてあえて利用することがありえるかも)。

国際化対応するときは、これ一つでは足りないので、subItemMapの機能を使て別途言語ごとに属性を追加していく必要があります。

SubItemMap

コメント(説明) (comment)

区分値要素のコメント(説明)です。SchemaHTMLやJavaDocなどのドキュメントなどで利用されます。プログラム上で取得することはできません。

区分値の扱いの難しさ

それぞれの区分値要素は、業務的に意味を持った値であるため、DBアクセスにおける検索条件やプログラム上での判定条件などに頻繁に利用されます。 もっとも単純で、区分値の取扱いにおける問題を何も解決していない区分値の利用例が以下の通りです。

e.g. 区分値の取扱いにおける問題を何も解決していない区分値の利用例 {MemberStatus} @Java
if ("FML".equals(member.getMemberStatusCode())) {
}

いわゆるハードコードというやり方で、以下のデメリットがあります。

• コードのタイプミスが発生する(発生してもなかなか気付かない)
• コード変更が発生した場合の影響範囲の特定が難しい

タイプミスもさることながら、コード変更も重要なポイントです。要はDB変更の亜種であり、どうしても将来的に必要なコード変更であったりする可能性も十分あります。 また、ステータスのような区分値は、運用開始後も追加されたり変更されたりする可能性が高い部類のものです。 プログラムとしてはぜひともコード変更に強いやり方で実装したいところです。

区分値のタイプセーフ解決

dbfluteでは、区分値はタイプセーフ、そして、コード変更にも強い をポリシーとしています。具体的には、区分値定義から区分値メソッドを自動生成して、プログラム上ではそのメソッド経由で区分値処理を行うようにします。 (コード変更が発生した場合は、メソッド名に影響が出ないレベルであれば影響なし、メソッド名に影響があるレベルであればコンパイルエラーとして検知)

Entity

区分値を設定するメソッド、区分値を判定するメソッド

ConditionBean

区分値で検索条件を設定するメソッド

ParameterBean

区分値でパラメータを設定するメソッド

e.g. 区分値の設定や判定、絞り込み条件設定 @Java
Member member = new Member();
member.setMemberStatusCode_Formalized(); // 設定メソッド (正式会員にする)
...
if (member.isMemberStatusCodeFormalized()) { // 判定メソッド (正式会員かどうか)
    ...
}

String statusCode = ... // リクエストなどから飛んで来たら
member.setMemberStatusCodeAsMemberStatus(
    CDef.MemberStatus.codeOf(statusCode)); // CDef型での設定メソッド

MemberCB cb = new MemberCB();
cb.query().setMemberStatusCode_Equal_Formalized(); // 条件メソッド (正式会員)

補完のとき、JavaDocコメントにも注目です。

図 : Entityでの区分値メソッドの補完

区分値の説明が表示されるので、"この区分値ってどういうものだっけ？" という疑問が生まれても、実装しながら理解することができます。

図 : ConditionBeanでの区分値メソッドの補完

区分値の設定(dfprop)

区分値メソッドを生成するための区分値定義に関する設定を、classificationDefinitionMap.dfprop にて定義を行います。設定方法は、区分値のタイプにより分かれます。

テーブル区分値

区分値要素がデータベース上に存在していますので(ReplaceSchemaなどでデータ登録されていることが前提)、 対応するテーブル名やカラム名を定義し、自動生成時に実際にそのテーブルのデータを検索して、区分値定義を取得します。

e.g. テーブル区分値を利用する例 {MemberStatus} @classificationDefinitionMap.dfprop
map:{
    ; MemberStatus = list:{
        ; map:{topComment=入会から退会までの会員のステータスを示す; codeType=String}
        ; map:{
            ; table=MEMBER_STATUS; code=MEMBER_STATUS_CODE
            ; name=MEMBER_STATUS_NAME; comment=DESCRIPTION
            ; orderBy=DISPLAY_ORDER
        }
    }
    ...
}

どのカラムがどの区分値に関連付くのか明確なため、classificationDeploymentMap.dfprop の設定は不要です。(dbfluteがFKの関連を辿って自動で判断します)

名前(識別名)に対応するカラムがない場合

区分値要素の名前(識別名)に対応するカラムがない場合は、業務的に表示用として利用するカラム(別名(alias)に対応するカラム)を代わりに name に定義します(その場合、そのカラムは識別名と表示名を兼任したカラムであると想定されます)。その場合は、alias の定義は省略できます(省略すると name と同じ値となります)。

どうしても、対応させる適切なカラムが存在しない場合は、コードに対応するカラム(と同じカラム)を指定します。 その場合、メソッド名にはコード値が利用されますが、タイプセーフであることに変わりはありません。 但し、コード値が区分値要素を見分けるのにわかりにくい表現である場合は、comment をしっかり定義して、JavaDocコメントでの補足を利用して実装しやすいようにする必要があるでしょう。

コメント(説明)に対応するカラムがない場合

コメント(説明)に対応するカラムがなくても業務上問題ない(可能性の高い)ものではありますが、 ディベロッパーの実装を助ける重要な補助要素ではありますので、テーブル区分値のテーブルに、相当するカラムを定義しておくことをお奨めします。 それは単にdbfluteにおける話だけではなく、開発全体の利益(区分値を管理する上でのドキュメントの充実)につながるものと考えられます。

テーブル区分値における別名(表示名)の扱い

テーブル区分値では、別名(表示名)を定義した場合、JavaDocなどのドキュメント上の充実だけの利用を想定しており、プログラム上での取得は想定されません。 厳密には取得できなくはないのですが、ディベロッパーからは取得しづらいような仕組みになっています。 テーブル区分値の場合は、実際のカラムから取得して利用することができ(また、そうするべきであると考えられる)、その必要性はほとんどないためです。

暗黙の区分値

定義が(dbfluteが参照できる世界の)どこにも存在していませんので、dbfluteプロパティ上に具体的な区分値要素を定義していきます。

e.g. 暗黙の区分値を利用する例 {MemberStatus} @classificationDefinitionMap.dfprop
map:{
    ; MemberStatus = list:{
        ; map:{topComment=入会から退会までの会員のステータスを示す; codeType=String}
        ; map:{code=PRV;name=Provisional;alias=仮会員  ;comment=入会直後のステータスで一部のサイトサービスが利用可能}
        ; map:{code=FML;name=Formalized ;alias=正式会員;comment=正式な会員としてサイトサービスが利用可能}
        ; map:{code=WDL;name=Withdrawal ;alias=退会会員;comment=退会が確定した会員でサイトサービスはダメ}
    }
    ...
}

また、区分値定義だけでは、どのテーブルのどのカラムにその区分値が関連付くものかも判断が付きませんので、その関連付けを classificationDeploymentMap.dfprop にて設定する必要があります。

e.g. 暗黙の区分値のカラムとの関連付けをする例 {MemberStatus,Flg} @classificationDeploymentMap.dfprop
map:{
    ; $$ALL$$       = map:{suffix:_FLG = Flg} # 全テーブルの_FLGで終わるカラム
    ; MEMBER_STATUS = map:{MEMBER_STATUS_CODE = MemberStatus}
}

ENUMクラス(CDef)の利用

dbfluteの区分値機能の内部構造として、実は自動生成されるENUMが存在します。allcommonパッケージ配下の CDef というクラスです。このクラスの内部クラスとして全ての区分値に対応するENUMが存在します。 但し、基本的には実装上は区分値はメソッド解決されるため、あまり意識することはありません。

SchemaHTMLでの表示

Docタスクで自動生成される SchemaHTML では、設定された区分値の一覧が望むことができます。 また、テーブルのカラム情報の中に関連する区分値へのリンクがあり、どのカラムがどの区分値と関連するのかがすぐにわかるようになっています。

ネイティヴ型メソッドの削除

区分値メソッドを生成しても、ネイティヴ型の設定メソッドはデフォルトの設定では残っています。 そのメソッドを呼び出せないようにして区分値メソッドでの設定の強制力を高めたい場合は、 littleAdjustmentMap.dfprop の isForceClassificationSetting を true にすることで、ネイティヴ型の設定メソッドを不可視(protected)にすることが可能です。

また、こちらの設定を有効にした場合は、一緒に isCheckSelectedClassification も true にしておくと良いでしょう。ネイティヴ型の設定メソッドを不可視にしておきながら、このプロパティを true にしない理由は(ほぼ)ないでしょう。

多くの開発現場で、この設定を true に適用できるでしょう。"デフォルトのジレンマ" のコラムを読んで特に問題ないと思えるのであれば、積極的に設定していった方が良いでしょう。

暗黙の区分値チェック

暗黙の区分値は、データ登録時には何の制約もありません。 アプリ実装ではdbfluteの区分値メソッドを使ってタイプセーフにできますが、ReplaceSchemaのエクセルデータ作成ではケアレスミスが簡単に起きてしまいます。 そこで、dbfluteのオプションで登録時に自動チェックすることができます。

暗黙の区分値の定義の topComment の map の中で、isCheckImplicitSet を true に設定すると、ReplaceSchema のデータ登録時や、Entity の Setter にて、正しい区分値かどうかの存在チェックがされるようになります。

e.g. 暗黙の区分値チェックを設定する例 {MemberStatus} @classificationDefinitionMap.dfprop
map:{
    ; MemberStatus = list:{
        ; map:{
            ; topComment=入会から退会までの会員のステータスを示す; codeType=String
            ; isCheckImplicitSet=true
        }
        ; map:{code=PRV;name=Provisional;alias=仮会員  ;comment=...}
        ; map:{code=FML;name=Formalized ;alias=正式会員;comment=...}
        ; map:{code=WDL;name=Withdrawal ;alias=退会会員;comment=...}
    }
    ...
}

特に、エクセルデータの作成作業では、ケアレスミスで簡単に間違った値をついつい入力しがちです。間違った値でテストをしてもデバッグが大変なだけでいいことがありません。 テストデータ作成者の精神的負担を軽減する意味でも、積極的に設定していった方が良いでしょう。

区分値のグルーピング (GroupingMap)

グルーピングの概要

例えば、正式会員と仮会員とで "サービスが利用可能なステータス" というように複数のステータスに対して業務的な意味付けがある場合、プログラム上ではその複数のステータスを使った判定処理が想定されます。 その意味付けをあらかじめ定義(グルーピング)しておいて、その複数のステータスを使った判定メソッドを生成することができます。 @since 0.9.9.7A

e.g. サービスが利用可能なステータスのグルーピング判定 @classificationDefinitionMap.dfprop
Member member = ...
if (member.isMemberStatusCode_ServiceAvailable()) {
}

MemberCB cb = new MemberCB();
cb.query().setMemberStatusCode_InScope_ServiceAvailable();

姉妹コードの利用 (SisterCode)

指定されたコード値とは別のコード値を取り扱いたいときがあります。例えば、フラグ系の区分値において、1/0 だけでなく、true/false でも扱えるようになど。その場合、CDef の codeOf() で true や false でも識別できるようになります。@since 0.9.9.4B

e.g. 暗黙の区分値で姉妹コードを利用する例 {Flg} @classificationDefinitionMap.dfprop
map:{
    ; Flg = list:{
        ; map:{topComment=フラグ; codeType=Number}
        ; map:{
            ; code=1; name=True; alias=Checked; comment=フラグが立っている
            ; sisterCode=true
        }
        ; map:{
            ; code=0; name=False; alias=Unchecked; comment=フラグが立っていない
            ; sisterCode=false
        }
    }
    ...
}

また、フラグ系の区分値(要素が二つ固定)で、姉妹コードに true と false が指定されている場合は、Entity や ConditionBean に Boolean 型で設定できるメソッドが追加されます。

e.g. 姉妹コードによる Boolean 型設定メソッドの例 {Flg} @Java
MemberLogin login = new MemberLogin();
login.setMobileLoginFlgAsBoolean(isMobileLogin());

※テーブル区分値でも利用できます。@since 1.0.5N patch at 2015/01/27, @since 1.1.0-sp1

独自の属性を追加 (SubItemMap)

区分値に独自の属性を追加することができます。 @since 0.9.9.3C

それぞれの区分値要素のmapの中で、subItemMapというプロパティで独自の属性を指定します。

独自の属性

e.g. 暗黙の区分値で独自の属性を追加する例 @classificationDefinitionMap.dfprop
map:{
    ; MaihamaStatus = list:{
        ; map:{topComment=独自の属性のExample; codeType=String}
        ; map:{
            ; code=SEA; name=Sea; alias=海だよ; comment=DocksideとかHangarとか
            ; subItemMap=map:{
                ; priceType=MYS ; rank=2
            }
        }
        ; map:{
            ; code=LND; name=Land; alias=陸だよ; comment=ShowbaseとかOrleansとか
            ; subItemMap=map:{
                rank=5
            }
        }
    }
    ...
}

この場合、priceType と rank という独自の属性が追加されています。 CDefでは、subItemMap()というメソッドで設定されたmapをそのまま取得することができます。 まず、一部の区分値要素にしか設定されていない priceType は、必ずこの方法で取得します。

e.g. 独自の属性をCDefから取得する(基本) @classificationDefinitionMap.dfprop
String priceType = (String)CDef.MaihamaStatus.Sea.subItemMap().get("priceType");

一方で、rank の方は全ての区分値要素に設定されています。 このような場合は、既にそのキー名のメソッドが CDef に追加されています。

e.g. 独自の属性をCDefから取得する(要素) @classificationDefinitionMap.dfprop
String rank = CDef.MaihamaStatus.Sea.rank();

属性の値は、基本的に全て文字列(String型)として扱われます。 数字を指定しても、true/falseを指定しても String です。精度などの自動判別が正確にできないため、アプリ側でパースする必要があります。

属性の値に、map型やlist型を指定することもできますが、こちらも単なる文字列として扱われます。 dbfluteランタイムの MapListString クラスなどを利用してパースして利用します。 ただ、全ての要素に設定した場合のメソッドの戻り値は String ではなく、Object になります。 これは、将来の拡張のために Object にしていますが、既に破綻しているように思えます。

こちらテーブル区分値でも利用できます。その場合は、キャッシュ的な意味合いでの利用となります。 subItemMapのキーに対して、対応するカラムを指定すればOKです。

Exampleのススメ

dbflute-basic-example では、テストケースの中で区分値メソッドが利用できるように設定されています。 (他のほとんどのExampleでも同様に利用されています)

SiteMap Author's BlogBTS