kettle plugin 外掛程式開發

http://wiki.pentaho.com/display/COM/PDI+Plugin+Loading

svn://source.pentaho.org/svnkettleroot/plugins/S3CsvInput

<?xml version="1.0" encoding="UTF-8"?>
<plugin
   id="TemplatePlugin"
iconfile="icon.png"
description="Template Plugin"
tooltip="Only there for demonstration purposes"
category="Demonstration"
   classname="plugin.template.TemplateStepMeta">

   <libraries>
      <library name="templatestep.jar"/>
   </libraries>
</plugin>

ID:在kettle外掛程式中必須全域唯一，因為被kettle序列化了，所以不要隨便改變

Iconfile: kettle中外掛程式顯示的圖片，必須是png圖片

Description：外掛程式描敘，顯示在樹形菜單裡面。

Tooltip:樹形菜單中，滑鼠滑過的時候顯示的提示資訊

Category:外掛程式顯示的父目錄

Classname：中繼資料類

Library:指明了外掛程式需要載入所依賴的jar包

kettle轉換步驟工作群組件：

       這裡有四個類構成了這個kettle 步驟/節點，每一個類都有其特定的目的及所扮演的角色。

TemplateStep: 步驟類實現了StepInteface介面，在轉換運行時，它的執行個體將是資料實際處理的位置。每一個執行線程都表示一個此類的執行個體。

TemplateStepData: 資料類用來儲存資料，當外掛程式執行時，對於每個執行的線程都是唯一的。執行時裡面儲存的東西主要包括資料庫連接、檔案控制代碼、緩衝等等其他東西。

TemplateStepMeta: 中繼資料類實現了StepMetaInterface介面。它的職責是儲存和序列化特定步驟執行個體的配置，在我們這個例子中，它負責儲存使用者佈建的步驟名稱和輸出欄位的名稱。

TemplateStepDialog：對話方塊類實現了該步驟與使用者互動的介面，它顯示一對話方塊，通過對話方塊使用者可以自己的喜好設定步驟的操作。對話方塊類與中繼資料類別關係非常緊密，O(∩_∩)O~ 想想為什麼吧？ （中繼資料類可以追蹤使用者的設定）

除了上面的代碼，還有一個plugin.xml,它設定好了外掛程式的中繼資料，定義了步驟在kettle圖形工作台中的顯示效果。為了更好的讓大家理解，我將利用這個步驟設計一個轉換流程並執行它。對於外掛程式的開發，我們將從plugin.xml設定檔開始講起，然後講講中繼資料和對話方塊類，最後再講講步驟類和資料類。

 ======================================================================================

 

      在我們做ETL工作的時候，在某些項目中往往會遇到一些特別的流程任務，kettle原有的流程處理節點已經不能滿足我們的要求，這時 候我們就需要定製流程處理節點了。定製流程節點主要是針對資料的管理、資料的驗證和某些特別檔案資料的提取。大家通過查看kettle原始碼，就可以知道 怎樣去建立你自己的kettle外掛程式了。

 

這篇文章主要告訴大家在kettle 4.0版本上怎樣開發一個transformation類型的簡單外掛程式，這個外掛程式可以接受任何記錄流，然後在流後面再添加一個帶值的欄位，使用者能夠定義欄位的名稱，外掛程式非常簡單。O(∩_∩)O~ 我將儘可能簡潔的介紹開發外掛程式需要掌握的一些介面規範。

 

準備工作：

 1、下載pdi-ce-4.0.0-stable.zip，供案頭測試用。

2、下載eclipse，任何版本都可以，裝好SVN外掛程式，後面下載kettle原始碼之用。

3、  下載標準外掛程式原始碼模板工程。

 

建立外掛程式工程：

1、  將下載的“標準外掛程式原始碼模板工程”匯入到您的工作空間

2、  匯入後工程會有一些錯誤，那是因為依賴的包沒有匯入。這時，你需要解壓pdi-ce-4.0.0-stable.zip，進入解壓目錄將lib目錄下面 kettle打頭的所有jar包以及libswt/win32下面的swt.jar包（這個大家依賴作業系統匯入）加入工程環境變數裡面。

3、  重新編譯一下工程，應該就沒有錯誤了。

 

kettle轉換步驟工作群組件：

       這裡有四個類構成了這個kettle 步驟/節點，每一個類都有其特定的目的及所扮演的角色。

TemplateStep:  步驟類實現了StepInteface介面，在轉換運行時，它的執行個體將是資料實際處理的位置。每一個執行線程都表示一個此類的執行個體。

 

TemplateStepData:  資料類用來儲存資料，當外掛程式執行時，對於每個執行的線程都是唯一的。執行時裡面儲存的東西主要包括資料庫連接、檔案控制代碼、緩衝等等其他東西。

 

TemplateStepMeta: 中繼資料類實現了StepMetaInterface介面。它的職責是儲存和序列化特定步驟執行個體的配置，在我們這個例子中，它負責儲存使用者佈建的步驟名稱和輸出欄位的名稱。

 

TemplateStepDialog：對話方塊類實現了該步驟與使用者互動的介面，它顯示一對話方塊，通過對話方塊使用者可以自己的喜好設定步驟的操作。對話方塊類與中繼資料類別關係非常緊密，O(∩_∩)O~ 想想為什麼吧？ （中繼資料類可以追蹤使用者的設定）

 

除了上面的代碼，還有一個plugin.xml,它設定好了外掛程式的中繼資料，定義了步驟在kettle圖形工作台中的顯示效果。為了更好的讓大家理解，我將利用這個步驟設計一個轉換流程並執行它。對於外掛程式的開發，我們將從plugin.xml設定檔開始講起，然後講講中繼資料和對話方塊類，最後再講講步驟類和資料類。

 

書寫你自己的plugin.xml：

       下面plugin.xml是我們這個外掛程式裡面的內容，它的功能是告訴kettle外掛程式的中繼資料類，外掛程式的名稱及描敘，還有需要載入的jar包。想要瞭解細節，可以查看文章：plug-in loading

<?xml version="1.0" encoding="UTF-8"?>
<plugin
   id="TemplatePlugin"
iconfile="icon.png"
description="Template Plugin"
tooltip="Only there for demonstration purposes"
category="Demonstration"
   classname="plugin.template.TemplateStepMeta">

   <libraries>
      <library name="templatestep.jar"/>
   </libraries>
</plugin>

ID:在kettle外掛程式中必須全域唯一，因為被kettle序列化了，所以不要隨便改變

Iconfile: kettle中外掛程式顯示的圖片，必須是png圖片

Description：外掛程式描敘，顯示在樹形菜單裡面。

Tooltip:樹形菜單中，滑鼠滑過的時候顯示的提示資訊

Category:外掛程式顯示的父目錄

Classname：中繼資料類

Library:指明了外掛程式需要載入所依賴的jar包

 

 

 

一、中繼資料類：

         下面顯示了中繼資料的幾個關鍵的方法,注意中繼資料類裡面用私人成員變數outputField 儲存了下一個步驟的輸出欄位。

 // keep track of the step settings
public String getOutputField()
public void setOutputField(…)
public void setDefault()

// serialize the step settings to and from xml
public String getXML()
public void loadXML(…)

// serialize the step settings to and from a kettle repository
public void readRep(…)
public void saveRep(…)

// provide information about how the step affects the field structure of processed rows
public void getFields(…)

// perform extended validation checks for the step
public void check(…)

// provide instances of the step, data and dialog classes to Kettle
public StepInterface getStep(…)
public StepDataInterface getStepData()
public StepDialogInterface getDialog(…) 

TemplateStepMeta中繼資料類其實還有很多方面，不過大多被他的父類BaseStepMeta給預設實現了，這些預設的實現足以使我們 的中繼資料類工作良好。想要瞭解更多，大家可以查查關於StepMetaInteface和BaseStepMeta的kettle官方文檔。

 

二、對話方塊類：

         TemeplateStepDialog為步驟實現了對話方塊的設定，kettle的使用者介面組件是使用的eclipse的swt架構，如果要開發比較複雜的對話方塊，你還必須熟悉大部分swt代碼。 Swt文檔大家可以從eclipse上的協助菜單點擊線上擷取。 在開發過程中，一個對話方塊對象擁有一個中繼資料對象，它記錄了應該從哪裡讀取配置？應該把設定好的配置儲存在哪裡？ 它僅僅設定了輸出欄位的名稱在我們這個模板步驟裡面。一個繼承自BaseStepDialog特定的對話方塊類必須提供open(…)方法，這個方法必須返 回這個步驟的名稱（發生改變時）或NULL（對話方塊被取消時）

 

 

三、步驟類：

         步驟類是實際的處理和轉換工作的地方。因為大部分樣本代碼已經由父類BaseStep提供了，大多數外掛程式僅僅關注下面幾個特定的方法就行。

 // initialization and teardown
public boolean init(…)
public void dispose(..)

// processing rows
public void run()
public boolean processRow(..)

Init()方法在轉換執行前被kettle調用，轉換必須在所有步驟初始化成功時才真正執行。我們這個模板步驟沒有做任何事情，這裡僅僅是拿出來讓大家瞭解瞭解。

dispose()方法是在步驟執行完之後執行（非轉換執行完哈），它完成資源的關閉，像檔案控制代碼、緩衝等等。

run()方法在實際處理記錄集的時候調用。裡面其實是個調用processRow()方法處理記錄的小迴圈，當此步驟再沒有資料處理或轉換被停止時退出迴圈。

processRow()方法在處理單條記錄的時候被調用。這個方法通常通過調用getRow()來擷取需要處理的單條記錄。 這個方法如果有需要將會被阻塞，例如當此步驟希望放慢腳步處理資料時。processRow()隨後的流程將執行轉換工作並調用putRow()方法將處 理過的記錄放到它的下遊步驟。

注意：你的步驟可能會變記錄的結構，為了安全起見，一定要多熟悉包org.pentaho.di.core.row，特別是類RowMetaInterface和RowDataUtil。

  基類BaseStep對處理的記錄提供了第一次訪問的標識，在某些代碼只執行一次的時候可能非常有用，例如某個費時的尋找，其實這就是緩衝。

 

四、資料類:

         大多數步驟都需要臨時的緩衝或者臨時的資料。資料類就是這些資料合適的存放位置。每一個執行線程將得到其擁有的資料類執行個體，所以它能在獨立的空間裡面運 行。TemplateStepData繼承自BaseStepData，作為一個經驗法則，不要將non-constant欄位放置 BaseStepData類裡面，如果你必須，請將它最好放置TemplateStepData資料類裡面.

 

我們的步驟僅僅使用了一個資料對象來儲存記錄集輸出的結構，沒有用到其他的儲存介質，例如檔案等等。

 

總結:

         一個kettle步驟外掛程式包括4個類，每一個類都有自己的角色和職責，中繼資料、對話方塊、步驟和資料類很好的結合在一起工作，特別是因為很多樣板代碼和通用的方法已經被父類實現，使得kettle的外掛程式開發非常容易，若有需要討論的，大家可以在http://www.ahuoo.com上給我留言，歡迎打擾！下一篇我們將具體講解的外掛程式開發及調試。O(∩_∩)O~

=================================debug=====================================================

 

kettle外掛程式調試比較麻煩，因為是兩個不同工程的依賴，但是大家如果掌握方法，其實也很簡單，回顧JAVA常用的調試手法，如Link Source、JAVA遠端偵錯，如果大家瞭解maven，甚至可以直接依賴調試，下面我來作重講講前面兩種調試手法。

準備工作：

1、通過eclipse上的svn外掛程式下載kettle4.0源碼，地址是：http://source.pentaho.org/svnkettleroot/Kettle/branches/4.0.0 

下載完成之後，發現eclipse裡面存在兩個工程：TemplateStepPlugin，Kettle 4.0.0，若有不同，請參見文章ETL工具——kettle外掛程式開發（基礎篇）

2、下載我這裡給你準備的測試轉換檔test.ktr

一、Link Source調試：

1、在Kettle4.0工程下面，進入plugins->steps目錄，發現裡面有個DummyPlugin目錄，其就是kettle官 方提供的外部轉換外掛程式，細心地讀者發現裡面僅用三個檔案DPL.png、dummy.jar、plugin.xml，其實它就是一個完整外掛程式所需要的東 西。

2、在與DummyPlugin同級目錄裡面，建立檔案夾TemplateStep, 將TemplateStepPlugin工程下面的icon.png、plugin.xml檔案拷貝至此，jar包就不用了

否則調試時會關聯不上源碼，O(∩_∩)O~ 想想為什麼吧？？

3、最重要的一步來了，大家右擊工程Kettle 4.0.0，選擇屬性Properties, 然後在左手邊選擇Java Build Path, 然後在上面的選項卡裡面選擇Source，此時右邊就有幾個按鈕，

點擊Link Source按鈕，設定好你的外掛程式源碼目錄以及目錄名字，見：

4、運行。 關聯好之後，咱們找到kettle的入口運行類Spoon.java，大家可以通過快速鍵ctrl+shift+R找出此類選擇調試運行即可，進入kettle工作台，開啟測試檔案test.ktr，

查看是否能正常運行，此時大家就可以在外掛程式類TemplateStep裡面打斷點調試了，其他情況不再多說了

 

二、kettle遠端偵錯

遠端偵錯的關鍵是首先你的在kettle啟動配置裡面設定遠端偵錯參數，然後在eclipse裡面設定遠端偵錯監控的連接埠號碼，這樣就ok了。

1、進入pdi-ce-4.0.0-stable.zip解壓出來的目錄（上一篇文章：ETL工具——kettle外掛程式開發（基礎篇）），編輯啟動設定檔Spoon.bat，linux下當然是spoon.sh

 在檔案裡面加入這麼一句話：

set OPT=-Xdebug -Xnoagent -Djava.compiler=NONE -Xrunjdwp:transport=dt_socket,server=y,suspend=n,address=8285

位置參見：

 

 

 

2、點擊Spoon.bat，進入kettle工作台

3、開啟eclipse，進入菜單Run——>Debug Configurations，選擇左邊的Remote Java Application，右鍵建立一個遠端偵錯應用程式，設定如，

連接埠就是上面參數裡面的連接埠8285，一切ok，選擇選擇下面的debug按鈕。

4、在kettle工作台，運行剛才的測試轉換檔 test.ktr，eclipse開始監聽調試了，大家斷點設定就可。

======================================================================================

//複製輸入行的中繼資料，並設定為輸出行的中繼資料。

RowMetaInterface outputRowMeta = getInputRowMeta().clone();

//構造一個新的輸出資料行。方法一

RowMetaInterface rowMeta = new RowMeta();

Object[] rowData = new Object[1];

int valtype = ValueMeta.getType("String");

ValueMetaInterface valueMeta = new ValueMeta( “FieldName1”, valtype); valueMeta .setLength(-1);

rowMeta.addValueMeta(valueMeta);

RowMetaAndData metaAndData = new RowMetaAndData(rowMeta, rowData);

RowMetaInterface newMeta = metaAndData.getRowMeta();

outputRowMeta.mergeRowMeta(newMeta);

//構造一個新的輸出資料行。方法二

RowMetaInterface outputRowMeta = getInputRowMeta().clone();
int valtype = ValueMeta.getType("String");
ValueMetaInterface valueMeta = new ValueMeta( “FiledName1”, valtype);
valueMeta.setLength(-1);
outputRowMeta.addValueMeta(valueMeta);

//從上一個步驟獲得一行資料。

Object[] r = null;

r = getRow();

//獲得一行資料裡，某一個欄位的值

String fieldname = “MyOldField”;

int fieldIndex = this.getInputRowMeta().indexOfValue(fieldName);

Object value = r[fieldIndex];

//將新的資料追加到原來的行資料的後面，成為新的輸出行：(轉載請註明：http://pdi.itpub.net)

Object[] values = new Object[1];

values[0]=”new value”;

r = RowDataUtil.addRowData(r, getInputRowMeta().size(),values);

//將輸出行的中繼資料和資料放到緩衝裡，這樣下一個步驟可以讀取了，注意中繼資料的個數和資料的個數要相等。：(轉載請註明：http://pdi.itpub.net)

putRow(outputRowMeta, r);