テキストボックス: @Objects [
[date=Mon Jan 01 00:00:00 JST 1900,workStartHour=10.0,workEndHour=20.0,workContent=Aプロジェクト設計],
[date=Tue Jan 02 00:00:00 JST 1900,workStartHour=10.0,workEndHour=19.45,workContent=Aプロジェクト開発],
[date=Wed Jan 03 00:00:00 JST 1900,workStartHour=9.45,workEndHour=19.3,workContent=Bプロジェクト開発],
[date=Thu Jan 04 00:00:00 JST 1900,workStartHour=null,workEndHour=null,workContent=null]]

3. 標準TagParser仕様

3.1. TagParser共通情報

全ての標準TagParserが理解するパラメータ情報です。

パラメータ	定義例	必須/任意	説明
DataRowFrom	@List{DataRowFrom=1}	任意	タグが定義されたセルから見て何行目からデータ行が開始するか。未指定の場合はそれぞれのタグのデフォルト値を適用する。 ≪デフォルト値≫ ・@List … 1 ・@Map … 1 ・@Arrays … 1 ・@Maps … 2 ・@Objects … 2
DataRowTo	@List{DataRowTo=1}	任意	タグが定義されたセルから見て何行目までをデータ行として処理を行うか。未指定の場合は、シートの最終行（Apache POIのSheet.getLastRowNum()の取得値）までをデータ行とみなす
ResultKey	@List{ResultKey=UserList}	任意	処理結果に対応するキー。未指定の場合はタグ種別が使用される。

※ パラメータで指定する行・列の数値はタグが定義されたセルを基準（0, 0）とし、そのセルから見たときの相対値で表します。

3.2. ListParser

ListParserが理解するパラメータ情報です。

パラメータ

定義例

必須/任意

説明

ValueColumn

@List{ValueColumn=1}

任意

タグが定義されたセルからみて何列目を値として使用するか。

未指定の場合は0

3.3. MapParser

MapParserが理解するパラメータ情報です。

パラメータ	定義例	必須/任意	説明
Key	@Map{Key=XXX}	任意	キーに固定文字列を使用する場合に指定。
Value	@Map{Value=YYY}	任意	値に固定文字列を使用する場合に指定。
KeyColumn	@Map{KeyColumn=1}	任意	タグが定義されたセルからみて何列目をキーとして使用するか未指定の場合は0
ValueColumn	@Map{ValueColumn=2}	任意	タグが定義されたセルからみて何列目を値として使用するか未指定の場合は1
KeyCell	@Map{KeyCell=1:1}	任意	タグが定義されたセルから見て何行、何列目のセルをキーとして使用するか。
ValueCell	@Map{ValueCell=1:2}	任意	タグが定義されたセルから見て何行、何列目のセルを値として使用するか。

※ Key, KeyColumn, KeyCellの2つ以上が定義されていた場合は不正な定義としてParseExceptionがThrowされます

※ Value, ValueColumn, ValueCellの2つ以上が定義されていた場合は不正な定義としてParseExceptionがThrowされます

3.4. ArraysParser

ArraysParserが理解するパラメータ情報です。

パラメータ

定義例

必須/任意

説明

DataColumnFrom

@Arrays{DataColumnFrom=1}

任意

セルから見て何列目からをデータとして使用するか。

未指定の場合は1

DataColumnTo

@Arrays{DataColumnTo=4}

任意

セルから見て何列目までをデータとして使用するか。

未指定の場合は最終列まで。

3.5. MapsParser

MapsParserが理解するパラメータ情報です。

パラメータ

定義例

必須/任意

説明

KeyRow

@Maps{KeyRow=1}

任意

タグが定義されたセルから見て何行目をキーとするか

未指定の場合は1

3.6. ObjectsParser

ObjectsParserが理解するパラメータ情報です。

パラメータ

定義例

必須/任意

説明

Class

@Objects{Class=org.***}

必須

Listに詰めるオブジェクトのクラス。

PropertyRow

@Objects{PropertyRow=1}

任意

タグが定義されたセルからみて何行目をプロパティ行として使用するか

未指定の場合は1

※ プロパティ名の先頭を"-"にするとコメントとみなされ処理対象外になります。

ObjectsParserでは単純にオブジェクトに対してプロパティを設定するだけでなく、

特定のプロパティ(カスタムプロパティ)に対して任意の処理を差し込む事ができます。

カスタムプロパティも通常のタグと同様にプロパティ行(PropertyRowで指定した行)のプロパティ名を

任意のタグで記述し、タグに対応するプロパティパーサを追加するとパーサの処理が実行されます。

Excel定義

カスタムプロパティパーサの追加

BookController controller = new BookController( args[0]);

// Objectsパーサの生成

ObjectsParser objectsParser = new ObjectsParser( "@Objects");

// カスタムプロパティパーサの追加

objectsParser.addPropertyParser( new CustomPropertyParser( "@CusotmProperty"));

// パーサの追加

controller.addTagParser( objectsParser);

// 解析の実行

controller.parseBook();

4. Tips

4.1. エラーファイルの出力

パース時に何らかのエラーが発生した際に、デバッグ用のエラーハンドラを設定しておくと、

エラー情報の追加されたExcelファイルが実行ディレクトリ直下に出力されます。

エラーとなったセルが特定可能な場合はエラーのセルの背景色が赤色になっていますので、

こちらのファイルを参照すると原因が特定できる可能性があります。

BookController controller = new BookController( args[0]);

// デバッグ用エラーハンドラの設定(エラー時はエラーファイルを作成)

controller.setErrorHandler( new DebugErrorHandler());

例）エラーファイル

※Ver1.4からセルコメントとして詳細なエラー内容が表示されるようになりました。(xlsのみ)

5. 技術情報

本章ではExCella Coreをカスタマイズする開発者向けの技術情報を紹介します。

5.1. 処理フロー/カスタマイズポイント

5.2. カスタムTagParserの使用

独自の解析処理を実現する場合には、TagParserを継承したクラスを作成し、任意のタグと関連付けて使用します。

5.2.1. カスタムTagParserの作成

例として、解析結果をList<String>で返すCustomTagParserを作成してみます。

TagParserを継承し、オーバーライドしたparseメソッドに解析処理を記述し、戻り値の型を

List<String>型にします。ここで返却したデータが解析結果データとしてSheetDataに格納されます。

public class CustomTagParser extends TagParser<List<String>> {

/**

* コンストラクタ

* @param tag タグ

public CustomTagParser( String tag) {

super( tag);

}

/**

* パース処理

* @param sheet 対象シート

* @param tagCell タグが定義されたセル

* @param data BookControllerのparseBook(), parseSheet()メソッド、

* SheetParserのparseSheetメソッドで引数を渡した場合に

* TagParserまで引き継がれる処理データ

* @return 解析結果

* @throws ParseException パース例外

@Override

public List<String> parse( Sheet sheet, Cell tagCell, Object data)

throws ParseException {

List<String> result = new ArrayList<String>();

// 解析処理を記述

：

// 解析結果を返す

return result;

}

5.2.2. タグとの関連付け

上記で作成したCustomTagParserを“@Custom”タグに関連付けます。

全てのシートでCustomTagParserを使用する場合

BookController controller = new BookController( args[0]);

// @CustomタグにCustomTagParserを関連付ける

controller.addTagParser( new CustomTagParser( "@Custom"));

：

controller.parseBook();

Sheet1のみでCustomTagParserを使用する場合

BookController controller = new BookController( args[0]);

// Sheet1の@CustomタグにCustomTagParserを関連付ける

controller.addTagParser( "Sheet1", new CustomTagParser( "@Custom"));

：

controller.parseBook();

5.3. カスタムSheetParseListenerの使用

解析処理の実行前後に任意の処理を実行する場合には、SheetParseListenerを実装したクラスを作成し、BookControllerに追加して使用します。

5.3.1. カスタムSheetParseListenerの作成

例として、解析処理の実行前と実行後にコンソールに文字列を出力するCustomParseListenerを作成します。

SheetParseListenerを実装し、preParse()、postParse()にそれぞれコンソールに文字列を出力する処理を記述します。

postParse()では、引数で渡されるsheetDataを使用して、解析結果データに対して処理を行うことができます。

public class CustomSheetParseListener implements SheetParseListener {

/**

* 解析処理前に実行する処理

* @param sheet 対象シート

* @param sheetParser シートパーサ

* @throws ParseException パース例外

public void preParse( Sheet sheet, SheetParser sheetParser) throws ParseException {

System.out.println( "preParseの実行");

}

/**

* 解析処理後に実行する処理

* @param sheet 対象シート

* @param sheetParser シートパーサ

* @param sheetData解析結果データ

* @throws ParseException パース例外

public void postParse( Sheet sheet, SheetParser sheetParser, SheetData sheetData) throws ParseException {

System.out.println( "postParseの実行");

}

5.3.2. カスタムSheetParseListenerの追加

上記で作成したCustomSheettParseListenerをBookControllerに追加します。

全てのシートでCustomSheetParseListenerを使用する場合

BookController controller = new BookController( args[0]);

// CustomSheetParseListenerをブックに追加

controller.addSheetParseListener ( new CustomSheetParseListener ());

：

controller.parseBook();

Sheet1のみでCustomSheetParseListenerを使用する場合

BookController controller = new BookController( args[0]);

// CustomSheetParseListenerをブックに追加

controller.addSheetParseListener ( "Sheet1", new CustomSheetParseListener ());

：

controller.parseBook();

5.4. カスタムBookExporterの使用

ブック単位で独自の出力処理を実現する場合には、BookExporterを実装したクラスを作成し、BookControllerに追加して使用します。

5.4.1. カスタムBookExporterの作成

例として、コンソールに文字列を表示するCustomBookExporterを作成してみます。

BookExporterを実装し、setup()メソッド、export()メソッド、tearDown()メソッドにそれぞれ処理を記述します。

public class CustomBookExporter implements BookExporter {

/**

* 初期化処理

public void setup() {

System.out.println( "初期化処理の実行");

}

/**

* 出力処理

* @param book ワークブック

* @param bookdata ブック単位の解析結果データ

* @throws ExportException 出力処理例外

public void export( Workbook book, BookData bookdata)

throws ExportException {

// コンソールにsheetdataの内容を表示

Collection<SheetData> sheetDatas = bookdata.getSheetDatas();

for ( SheetData sheetdata : sheetDatas) {

System.out.println( sheetdata.toString());

}

/**

* 終了処理

public void tearDown() {

System.out.println( "終了処理の実行");

}

5.4.2. カスタムBookExporterの追加

上記で作成したCustomBookExporterをBookControllerに追加します。

CustomBookExporterを使用する場合

BookController controller = new BookController( args[0]);

// Exporterをブックに追加

controller.addBookExporter( new CustomBookExporter());

：

controller.parseBook();

5.5. カスタムSheetExporterの使用

シート単位で独自の出力処理を実現する場合には、SheetExporterを実装したクラスを作成し、BookControllerに追加して使用します。

5.5.1. カスタムSheetExporterの作成

例として、コンソールに文字列を表示するCustomSheetExporterを作成してみます。

SheetExporterを実装し、setup()メソッド、export()メソッド、tearDown()メソッドにそれぞれ処理を記述します。

public class CustomSheetExporter implements SheetExporter {

/**

* 初期化処理

public void setup() {

System.out.println( "初期化処理の実行");

}

/**

* 出力処理

* @param sheet シート

* @param sheetdata シート単位の解析結果データ

* @throws ExportException 出力処理例外

public void export( Sheet sheet, SheetData sheetdata) throws ExportException {

// コンソールにsheetdataの内容を表示

System.out.println( sheetdata.toString());

}

/**

* 終了処理

public void tearDown() {

System.out.println( "終了処理の実行");

}

5.5.2. カスタムSheetExporterの追加

上記で作成したCustomSheetExporterをBookControllerに追加します。

Sheet1でCustomSheetExporterを使用する場合

BookController controller = new BookController( args[0]);

// Sheet1の解析結果を処理するExporterをシートに追加

controller.addSheetExporter( "Sheet1", new CustomSheetExporter());

：

controller.parseBook();

5.6. ユーティリティクラス

カスタマイズに利用できるユーティリティクラスを紹介します。ユーティリティクラスはorg.bbreak.excella.core.util下にあります。

5.6.1. PoiUtil

POI操作のユーティリティクラスです。

セルの値をセルのタイプに応じた型で取得するメソッドやセルに値をセットするメソッド等、POI操作関連のメソッドが用意されています。

より詳細な情報は、ExCella CoreのJavadocを参照してください。

5.6.2. TagUtil

タグ定義操作のユーティリティクラスです。

タグ定義からパラメータ部分をマップ型で取得するメソッドやタグ定義からパラメータ部分を除いた文字列を取得するメソッド等、タグ操作関連のメソッドが用意されています。

より詳細な情報は、ExCella CoreのJavadocを参照してください。