コンポーネントKMの概要

2.1 コンポーネントKMとは

コンポーネントKMは、KM開発の新しく改良されたスタイルであり、IKM、LKM、XKMに適用されます。マッピング用のKMには、従来の11gスタイルとコンポーネント・スタイルという、2つの異なる実装スタイルがあります。11gスタイルのKMは、モノリシックodiRef置換APIオブジェクトおよび構文をテンプレート・コマンドで使用できるように設計されています。コンポーネント・スタイルのKMは、新しいオブジェクト指向の置換APIオブジェクトおよび新しいテンプレート・フロー制御構文をテンプレート・コマンドで使用できるように設計されています。両方のスタイルのKMは、プロジェクトとグローバルKMツリーに、XKMという事前定義済のコンポーネント・スタイルのKMのセットを持つIKM、LKMおよびCKMとして表示されます。新しいすべてのLKM、IKMおよびXKMは、新しいコンポーネントKMスタイルを使用して設計およびコーディングする必要があります。コンポーネントKMはODI 12cの新機能であり、ODI Studioの12.2.1.2.1リリースで初めて公開されました。コンポーネントKMの機能は以前のKMと同じで、タスクとオプションが含まれます。ただし、新しく追加された次のような機能も含まれています。

抽象構文ツリー(AST)を作成することを目的とした、関連委譲スクリプト。作成されたASTオブジェクトは、特定の言語およびテクノロジ用のコードを生成するための使用に適した方法でマッピング・コンポーネントのメタデータを説明する、javaクラス・インスタンスのツリーです。
既存のソースおよびターゲット・テクノロジ・フィールドに類似した、KMおよびKMタスク・レベルのソースおよびターゲットの言語フィールド。
KMがタスク、オプションおよびフィールド値をベースKMから継承することを可能にする、KM継承のサポート。
KMタスクのソースおよびターゲット・コマンドのコード生成フローを制御するための、フロー制御構文要素のセット。
「グローバル・テンプレート」と呼ばれる、グローバルに共有可能なコード・テンプレート・スニペットを、KMタスクのソースまたはターゲット・コマンドの一部として含める機能。
新しい置換変数の定義を可能にする、各KMタスクに関連付けられたgroovy言語スクリプト。新しく定義された置換変数は、タスクのソースおよびターゲット・コマンドで使用できます。

コンポーネントKMには、IKM、LKM、XKM、CKMの4つのタイプのいずれかを指定できます。コンポーネントKMのタイプの詳細は、「ナレッジ・モジュールとは」を参照してください。

2.2 コンポーネントKMの構文要素

コンポーネントKMには、2つの新しい固有の基本構文があります。

コンポーネントKMタスクで使用できる1つ目のメイン・コンポーネントKM構文要素は、次のようなコマンド構文です。{# command #}。{#...#}のエスケープ文字は、すべてのKMに存在するJSP-type <%...%>エスケープ・コマンドと似ていますが、エスケープされるテキストがjavaでないという点が異なります。コンポーネントKM固有のコマンド構文はApache Velocity Template Language (VTL)構文のコマンド構文に似ていますが、異種コード生成で厳密に必要とされる追加の文字がある点が異なります。ODIコード生成テンプレートで使用されるすべての構文は厳格である必要があり、それによって、ある言語/テクノロジの組合せで実際に生成されたテキストによって混乱が生じる可能性を最小化します。
コンポーネントKM固有のその他の構文要素は、置換変数およびAPIコールを逆参照するために使用するエスケープ構文です。構文は、$[variableName]または$[variable.methodName()]のようになります。

例 -

"tableName"という変数がgroovy変数定義スクリプトで作成されている場合、コマンドにはCREATE TABLE $[tableName]のようなテキストを含めます。コードが生成されると、これはCREATE TABLE MY_TABLEとしてレンダリングされます。これは、tableName変数がこのマッピングでMY_TABLEに評価される場合です。

たとえば、オブジェクト・タイプ変数に対するメソッドのコールは、コマンド・テキストをCREATE TABLE $[physicalNode.getName()]として定義します。このKMが割り当てられているノードのMapPhysicalNodeインスタンスには、組込み変数physicalNodeが設定されています。そのため、ターゲットの物理ノードの名前が"TGT_TABLE"であった場合、コードが生成されると、このコードはCREATE TABLE TGT_TABLEとしてレンダリングされます。

この構文もまた、${variableName}を使用するApache Velocity Template Language (VTL)構文に似ています。「{」は、すでにjavaやシェル・スクリプト構文、およびその他の言語で頻繁に使用されているため、「{」のかわりに角カッコ「[」を使用します。新しい置換API変数の逆参照構文が、<%=variableName%>などのJSPタイプの式構文と混同されないようにする必要があります。主な相違点は、エスケープされるテキストがjavaではないことです。任意の複雑なjava式ではなく、変数名または1つのメソッド・コールのみがサポートされます。複雑なjava式が必要な場合は、KMタスクまたはKMに関連付けられているgroovy変数定義スクリプトに新しい置換変数を定義し、それを複雑なjava式と等しくすることが、コンポーネントKMのベスト・プラクティスです。groovyスクリプトは複雑なjavaまたはgroovy式をサポートしていません。この方法では、固有のjavaまたはgroovyコードは実際のテンプレート・コマンドとは別に保持されます。
コンポーネントKM構文に関して注意する必要があるもう1つの重要な事項は、これがコード生成の実行フェーズにのみ適用されることです。山カッコを使用する従来のJSPタイプのテンプレート置換構文(例: (<%...%>))では、全体で4つの実行フェーズが定義されています。これらは次のとおりです。
- コード生成フェーズ<%...%>
- エージェント・フェーズ<?...?>
- エージェント後フェーズ<$...$>
- 実行前フェーズ<@...@>
これらは、置換実行時のコード生成と実行プロセスが発生する時間フェーズを定義します。ただし、コンポーネントKM構文要素については、置換は常に最初のコード生成フェーズで実行されます。コンポーネントKMの機能は、新しいエージェントや実行機能が存在しないため、その全体がコード生成機能です。エージェント・フェーズまたはエージェント後の置換(パスワード置換の遅延など)が必要な場合は、JSPタイプのエスケープを引き続き使用する必要があります。

2.3 コンポーネントKM - フロー制御コマンド

コンポーネントKMで使用されるフロー制御コマンドを次にリストします。

#IF

構文
{# IF condition #} text [{# ELSIF condition #} text [{# ELSIF condition #} text ...]] [{# ELSE #} text] {# ENDIF #}
説明

生成されたコードにテキストを条件付きで含めます。条件には、単純な置換変数の参照またはメソッド・コール、あるいは簡単な関係条件術語の組合せを指定できます。サポートされる関係演算子: [==、!=、<、>、!、OR、AND]。

例
```
{# INCLUDE = 'ConstantFromClauseText' #}
{# IF $[QUERY.isConstantQuery()] #}
{# ELSE #}FROM {#NL#}
{# LIST #}  $[QUERY.getFromList().foreach(getText())]{# SEP #} ,{#NL#} {# ENDLIST #}
{# ENDIF #}
```
#INCLUDE

構文
{# INCLUDE 'templateName' #}
説明

このテンプレート・テキストの一部として名前付きのグローバル共有テンプレートのテキストを含めます。

例
{# INCLUDE = 'PreInsertList' #}
#TEMPLATE

構文
{# TEMPLATE name='templateName' technology='technoName' #}
説明

指定された名前とテクノロジを使用して、ローカル・オーバーライド・テンプレートを作成するか、依存テンプレートを指定します。テクノロジにはGENERICを指定できます。

例
```
{# TEMPLATE name='ANSIJoinText' technology='GENERIC' #}
templateText...
{# ENDTEMPLATE #}
```
置換変数参照

構文
$[variableName[.methodName([primitiveArg[,primitiveArg...]]).methodName(primitiveArgs)]][.foreach(methodName())]]
説明

有効範囲内の変数またはメソッド・コールの結果の文字列値を、生成されたテンプレート・テキストに置換します。太字の角カッコはリテラル角カッコであり、その他の角カッコはオプションの構文インジケータです。プリミティブ型引数は、文字列や整数などの単純なリテラルjavaデータ型を持つ、メソッドのパラメータです。foreachメソッドは、#LISTコマンド・ブロックの内部でのみ使用できる特殊な構文であり、各リスト・アイテムに対して指定されたメソッドをコールし、生成されたテキストを返します。

例

UNION ALLセット操作の一部である2つの問合せ間のセット操作を生成します。
```
SELECT A, B FROM TAB1
$[QUERY.getSetOperation()]
SELECT C, D FROM TAB2
```
現在処理中のQUERYオブジェクトにUNION ALLタイプのセット操作が含まれている場合、このコマンドから生成されるコードは、次のようになります。
```
SELECT A, B FROM TAB1
UNION ALL
SELECT C, D FROM TAB2
```
デフォルト組込み変数の詳細は、SQL構造化置換APIリファレンス(付録の章)を参照してください。
#INDENT

構文
{# INDENT #}
説明

現在のインデント・レベルに応じて、タブまたは空白文字のセットを生成されたコードに置換します。

例
{# INDENT #}
#LIST

構文
{# LIST #} listVariablesAndListText {#SEP#}separatorChars{# ENDLIST #}
説明

リスト変数およびテキストのセットを生成されたコードに置換します。リスト・テキストには、1つ以上のリスト変数を含める必要があり、複数のリスト変数に加え、ランダム・テキストと非リスト置換変数を含めることができます。リスト・テキストには、他のテンプレート・コマンドを含めることができます。複数のリスト変数が存在する場合、各リストは同じサイズである必要があります。セパレータ文字が指定されている場合、それらは各リスト項目の後に生成されるコードで再作成されます。

例
{# LIST #} $[INSERT.getColumnList().foreach(getText())] {#SEP#},{#NL#}{# ENDLIST #}
#FOR

構文
{# FOR (listVar[, listVar ...]) IN ($[listItemAlias][,$[listItemAlias]]) SEP = 'separatorChars' #} text $[listItemAlias] [text $[listItemAlias]] {# ENDFOR #}
説明

リスト変数およびテキストのセットを生成されたコードに置換します。複数のリスト変数が存在する場合、各リストは同じサイズである必要があります。セパレータ文字が指定されている場合、それらは各リスト項目の後に生成されるコードで再作成されます。

例
{# FOR ($[QUERY.getSelectList()],$[QUERY.getAliasList()]) IN ($[SL],$[AL]) SEP = ',0x000A' #} $[SL] $[QUERY.getColumnAliasSeparator()] $[AL] {# ENDFOR #}
#INC_INDENT

構文
{# INC_INDENT #}
説明

現在のインデント数を増加させます。

例
{# INC_INDENT #}
#DEC_INDENT

構文
{# DEC_INDENT #}
説明

現在のインデント数を減少させます。

例
{# DEC_INDENT #}
#NL

構文
{#NL#}
説明

改行文字を生成されたコードに置換します。

ノート:
テンプレート・オプションのREPLICATE_NEWLINE がfalseに設定されている場合(デフォルトはtrue)、テンプレート内の実際の改行は、生成されたコードに再作成されないことがあります。

例
Hello world{#NL#}
#TEMPLATE_OPTIONS

構文
{# TEMPLATE OPTIONS optName='optValue'[ optName='optValue' ...]
説明

一部の名前付きテンプレート・オプションの値を設定します。オプションは、テンプレートのTEMPLATE_OPTIONSコマンドの直後に有効になります。

例
{# TEMPLATE_OPTIONS REPLICATE_NEWLINE='false' #}
行コメント

構文
## commentText
説明

生成されたコードに再作成されないテンプレート・コメント・テキスト。

例
## This is a comment.
複数行コメント

構文
#* commentText *#
説明

生成されたコードに再作成されない複数行のコメント・テキスト。

例
#* This is a comment. *#

2.4 グローバル・テンプレート

グローバル・テンプレートは、コンポーネントKMと密接に関連したODIオブジェクトの一種です。これらは、「グローバル・テンプレート」フォルダの下のグローバル・オブジェクト・ツリーにあります。グローバル・テンプレートは基本的に、任意のコンポーネントKMで再使用できるテンプレート・テキストのスニペットです。名前、および関連付けられた言語とテクノロジがあります。一部の事前シード済グローバル・テンプレートは、よく使用されるSQL問合せや挿入、Spark Pythonスクリプトなどのために、ODIのインストール時に提供されます。

グローバル・テンプレートは、テンプレート名を指定する{# INCLUDE #}コマンドを使用することによって、KMタスク・コマンド内で使用します。コードの生成中、{#INCLUDE#}コマンドが挿入されたテキスト位置に、テンプレート・テキストが生成されたテキストで置換されます。
KMコマンド・エディタで、テキストの左側にある「+」コード折りたたみボタンをクリックすると、#INCLUDE文を展開できます。それを行うと、コマンド・テキストの#INCLUDE文でグローバル・テンプレート・テキストが置換されます。#INCLUDE文はネストすることができ、それによってテンプレート・テキストの置換がネストされます。
コード・ジェネレータがセッションまたはシナリオ・タスク生成の一貫としてKMタスクのテキストを展開する際、#INCLUDE文で指定されたテンプレート名およびテンプレートのテクノロジと言語に基づいて、各#INCLUDE文に一致する適切なグローバル・テンプレートを見つけます。テクノロジと言語が異なっていれば、同じ名前の複数のグローバル・テンプレートを定義できます。実行テクノロジおよびKMタスク言語の設定と、グローバル・テンプレートのテクノロジおよび言語の設定を一致させることで、正しいものを選択します。#INCLUDE文に言語とテクノロジを指定すると、実行テクノロジと言語に関係なく、特定のグローバル・テンプレート・インスタンスを選択できます。

2.5 KM継承

KM継承によって、KMがタスク、オプションおよびフィールド値をベースKMから継承できるようになります。KM継承を使用するには、コンポーネントKMの「ベース・コンポーネントKM」フィールドを設定する必要があります。ベースKMを設定すると、導出されたKMは次のプロパティをベースKMから継承します。

すべてのKMオプション
ベースKM言語、テクノロジ、生成タイプ、生成スタイル設定、およびベースKM委譲スクリプト
次のルール・セットに基づいて、一部のベースKMタスクが継承されます。
1. タスク・タイプ(MAP_BEGIN、EX_UNIT_BEGINなど)ごとに、導出されたKMにそのタイプのタスクが直接所有されていない場合、およびベース・タスクが明示的に削除されていない場合は、そのタイプのすべてのベース・タスクが継承されます。通常、このルールは、ベースKMが設定され、新しく作成されたKMに適用されます。
2. 指定された行タイプの直接所有タスクが追加された場合は、KMエディタで「タスクを含める」ボタンを使用して明示的に追加しないかぎり、そのタイプのベース・タスクはデフォルトで継承されません。
3. KMエディタにある「タスクを含める」アイコンを使用してベース・タスクの任意のセットを個々に追加することで、導出されたKMにそれらを含めることができます。
4. KMエディタの「タスク」タブにある「削除」アイコンを使用して、含まれている任意のベース・タスクを削除できます。
5. 一部のシード済KMは、内部でのみ使用可能な、異なるタイプのタスク包含を使用する場合があります。これには、キーワードに基づくタスクの一致が含まれます。ただし、これらのKMを継承する任意のKMは、前述のようにタスクを包含および除外して、それ以降は標準のタスク包含ルールに従うように指定できます。

2.6 Groovy変数定義スクリプト

各コンポーネントKMタスクには、すべてのKMと同じように、ソースおよびターゲット・コマンド・テンプレートがあります。ただし、既存の組込み置換API変数を使用して新しい置換変数を定義するために使用できる、groovy変数定義スクリプトもあります。たとえば、SqlInsertStatementオブジェクトに含まれるSqlQueryオブジェクトに、さらに含まれるSelectItemオブジェクトをループして、列リスト文字列を作成できます。

さらに、KM自身が所有するgroovy変数定義スクリプトもあります。KMレベルの変数定義スクリプトで定義された変数は、KM内のすべてのタスクで再使用できます。これは、ある値がKM内の複数のタスクで使用される場合に便利です。

タスク・レベルとKMレベルのgroovy変数定義スクリプトはいずれも、KMタスク・コマンド・エディタで編集および表示できます。

2.7 構造化置換API

コンポーネントKMは、構造化置換APIにアクセスできる唯一のタイプのKMです。構造化置換APIオブジェクトには、すべてのKMで<%...%>エスケープ文字の内部で使用する「odiRef」変数に似た一連の組込み構造化API変数を使用してアクセスします。組込み変数には2つのタイプがあります。これらは次のとおりです。

組込みパブリックSDK変数 - これらの変数はKMに関係なく常に同じであり、コンポーネント・ノードとKMのマッピング・パブリックSDKオブジェクトを公開します。
組込み構造化置換API変数 - 置換APIの組込み変数は常に、すべて大文字であり、編集している特定のIKMまたはLKMで作成されたAPIオブジェクトを表します。すべての組込み置換API変数のリストは、KMソース/ターゲット・コマンド・エディタの右下隅にある有効範囲内ツリーから取得できます。

SQL IKMまたはLKMによって作成される標準的な置換APIオブジェクトのリストは、次のとおりです。

INSERT - ターゲットをロードする最上位INSERT DML文を表すSqlInsertStatementオブジェクト。挿入タイプのKMでのみ使用可能です。
UPDATE - ターゲットをロードする最上位update DML文を表すSqlUpdateStatementオブジェクト。更新タイプのKMでのみ使用可能です。
MERGE - ターゲットをロードするmerge文を作成するために使用する最上位MergeStatementオブジェクト。
QUERY - ロードするデータをフェッチする最上位抽出問合せを表すSqlQueryオブジェクト。
TABLE - ターゲット表をロードするKMの最上位ターゲット表オブジェクト。
FROMLIST - 最上位SqlQueryオブジェクトのFromClauseオブジェクトのリスト。
JOIN - 結合コードの生成時の現在の結合を表すJoinTableオブジェクト。JoinTableテンプレートなど、結合テキストを作成するために使用するグローバル・テンプレート内でのみ使用可能です。
ATTR - ソース属性のテキスト生成時の現在のソース属性SourceMapAttributeなど、ソース属性テキストを作成するために使用するグローバル・テンプレート内でのみ使用可能です。
COLLIST - 挿入文用に書式設定されたC$ステージング表の列のリスト。
SUBQUERY - フィルタ副問合せコンポーネントのフィルタを表すFilterSubQueryオブジェクト。

コンポーネントKMのソースおよびターゲット・コマンドで使用可能な組込み置換API変数のリストは、次のとおりです。

physicalNode - これは、コンポーネントKMの割当て先であるMapPhysicalNodeタイプのマッピング物理ノード・オブジェクトです。たとえば、IKMの場合、physicalNode組込み変数はターゲット・データストア・コンポーネントと関連付けられているノードへの参照です。物理ノードには、このIKMが自身のIKMとして割り当てられます。
component - コンポーネントKMの割当て先である物理ノードに関連付けられているマッピング論理コンポーネント。
connector - 物理ノードに関連付けられているマッピング・コネクタ・ポイント。APノードに割り当てられているLKMの場合は、このコネクタ・ポイントが、APノードが接続しているターゲット・コンポーネントの入力コネクタ・ポイントです。ターゲットに割り当てられているIKMの場合、これはデータソース出力コネクタ・ポイントです。XKMの場合、これは物理ノードの関連付けられている出力コネクタ・ポイントになります。これは、たとえば、スプリッタ・コンポーネントなどの場合、各出力コネクタに異なる物理ノードがあるため、どれがノードとXKMに関連付けられているかを認識できると便利です。
generatorContext - コンポーネントKMを使用するコード・ジェネレータに関連付けられているGeneratorContextオブジェクト。ジェネレータ・コンテキストは、コード・ジェネレータの実行に対してグローバルな名前付きプロパティを保持するコンテナです。
taskControl - これは、単一のコンポーネントKMタスク・ラインに生成された多数のセッションまたはシナリオ・タスクを制御するために使用できる、TaskControlオブジェクトへの参照です。このオブジェクトのメソッドはテンプレート置換文字列として使用できる文字列値を返さないため、このオブジェクトはgroovyスクリプトで使用する必要があります。
upstreamASTList - java.util.Listは、そのうちの1つからこのコンポーネントKMが割り当てられている、すべてのアップストリーム・ノードによって作成されたAST置換APIオブジェクトのリストが含まれるオブジェクトです。現在のコンポーネントが結合などのマルチ入力コンポーネントである場合は、複数のアイテムが含まれている可能性があります。その他の場合、リストには1つのアップストリーム置換APIオブジェクトのみが含まれます。たとえば、SQLの生成では、通常のアップストリームASTオブジェクトはSqlQueryオブジェクトです。
baseNode - マルチ接続IKMにのみ適用されます。マルチ接続IKMの割当て先であるデータストア・ターゲット・ノードに接続しているAPノードへの参照。
componentKM - テンプレート・コマンドまたはgroovy変数定義スクリプトで使用できる、所有しているコンポーネントKMオブジェクトへの参照。
componentGenerator - このコンポーネントKMが割り当てられているコンポーネントのコードの生成に使用されるComponentGeneratorインスタンス。
subtype - このコンポーネントKMのサブタイプ値、または、サブタイプが設定されていない場合はnull。サブタイプは、このコンポーネントKMのAST置換APIオブジェクトを作成するためにコールされる、コンポーネントKMジェネレータ委譲メソッドの名前の決定に使用される文字列値です。targetNameForLoadingTaskはIKMにのみ適用され、ターゲットの名前はこのIKMによってロードされます。
collTableName - LKM (PERSISTENTタイプのLKM)にのみ適用されます。ソース・データをステージングするために作成される一時ステージング表の名前に設定されます。

各組込みオブジェクトで使用される置換メソッドの詳細は、SQL構造化置換APIリファレンス(付録の章)を参照してください。

2.8 タスク制御オブジェクト

タスク制御オブジェクトはgroovy変数定義スクリプトで使用でき、組込み変数「taskControl」を使用してアクセスできます。このタスクから生成される多数のタスク・インスタンスを制御するためにコールできる、特定のメソッドがあります。これらのメソッドを次に示します。

skipTaskGeneration() - このメソッドをコールすると、コード・ジェネレータはこのタスクのメイン・インスタンスの生成をスキップします。instantiateTask()をコールすると、タスクの他のインスタンスを引き続き追加できます。
instantiateTask() - これをコールすると、コード・ジェネレータは生成されたセッションまたはシナリオのタスクの追加のインスタンスをインスタンス化します。メソッドを複数回コールすることによって、任意の数のタスク・インスタンスを生成できます。タスク生成のためにバインドされている変数の代替セットを含むハッシュ表は、パラメータとして渡せます。代替変数セットの変数の1つが標準の組込み変数と同じ名前を持つ場合は、標準のデフォルト値ではなく代替値が使用されます。タスクの各追加インスタンスには一意の名前が付けられ、これがベース・タスク名になり一意の接尾辞が付けられます。

2.9 シード済コンポーネントKM

組込みグローバル・コンポーネントXKM、LKMおよびIKMのセットが用意されています(ODIバージョン12.2.1.2.1以降)。これらは、グローバルKMツリーで表示できます。これらはシード済KMと呼ばれます。シード済KMはUI Studioでは削除または編集できません。ただし、シード済KMは複製でき、複製したKMのコピーは必要に応じて編集できます。また、新しいコンポーネントKMを作成し、シード済KMをそのベースKMとして設定できます。このようにして、新しいKMはシード済ベースKMの機能を継承し、必要に応じて特定の機能をオーバーライドできます。これが、組込みシード済KMのカスタマイズで使用する方法のベスト・プラクティスです。