アノテーションマッピング仕様

Bean

説明

Bean アノテーションには、読み込み・書込みを行うためのオブジェクトのタイプを指定します。
ユーザ作成のPOJO、またはそれを要素とした List / 配列、あるいは Map を指定した取得・書き込みができます。
ユーザ作成のPOJOで取得・書き込みを行う場合も、ユーザ作成のPOJOの配列として取得・書き込みを行う場合も、該当クラスに対してBeanアノテーションを付加します。
XMLの定義によるブリッジオブジェクトを作成した場合は、このアノテーションは無視されます。

パラメータ

属性	説明	必須
sheetName	シート名を指定	任意 この指定をしない場合はコーディング時の引数で指定
retrieveType	List、配列または Map で取得・書き込む際にExcelの検索タイプを指定 List、配列の場場合：RetrieveType.VERTICAL_REPEATS / RetrieveType.HORIZONTAL_REPEATS	任意
label	List あるいは配列で取得・書き込む際に、表の位置を検索する項目名を指定。 retrieveType=RetrieveType.VERTICAL_REPEATS / RetrieveType.HORIZONTAL_REPEATS と合わせて指定	任意 ただしretrieveType=RetrieveType.VERTICAL_REPEATS / RetrieveType.HORIZONTAL_REPEATS が指定された場合は、本属性かposition の指定が必要
position	List あるいは配列で取得・書き込む際に、表の位置を指定。 位置の指定は行、列をカンマ「,」で区切って「(」「)」で括る。 （12行目の8カラム目を指定する場合の例）position="(12, 8)" retrieveType=RetrieveType.VERTICAL_REPEATS / RetrieveType.HORIZONTAL_REPEATS と合わせて指定	任意 ただしretrieveType=RetrieveType.VERTICAL_REPEATS / RetrieveType.HORIZONTAL_REPEATS が指定された場合は、本属性か label の指定が必要
retrieveFrom	List あるいは配列で取得・書き込む際に、表の位置を検索する項目名に対して、どの位置（右・下）に表が存在するかを指定 RetrieveFrom.RIGHT / RetrieveFrom.BOTTOM	任意
terminate	表を読み込む際に、レコードの最終行として文字列を指定する際に使用。 本属性が指定されていない場合は、読み込んだレコードの値がすべて空だった際に表の最終行として動作する。	任意
margedRows	List あるいは配列で取得・書き込む際に、直前のレコードの該当項目と一致する際に、値が省略された場合に直前のレコードから値を取得するかどうかを指定。 行全体に対しての動作を指定 retrieveType=RetrieveType.VERTICAL_REPEATS / RetrieveType.HORIZONTAL_REPEATS と合わせて指定	任意 デフォルト=false
use	表の位置を検索した際の動作を指定 必須が指定されていた場合に、検索不一致の場合は CellNotFoundException を上げる。 必須=Use.REQUIRED / 任意=Use.OPTIONAL	任意 デフォルト=Use.OPTIONAL
listClass	retrieveType=RetrieveType.VERTICAL_REPEATS / RetrieveType.HORIZONTAL_REPEATS を指定した際に、List の実装クラスを指定、または配列の場合はPOJOの配列を指定	任意 retrieveType=RetrieveType.VERTICAL_REPEATS / RetrieveType.HORIZONTAL_REPEATS が指定された際に本属性が指定されていない場合は、java.util.ArrayList が指定されたこととして動作する。
range	retrieveType=RetrieveType.VERTICAL_REPEATS / RetrieveType.HORIZONTAL_REPEATS を指定した際に、表の先頭位置（ラベル位置）検索の範囲を指定する 範囲の指定は開始と終了の位置を「-」で連結した書式 開始と終了のセルを連結する「-」の間には空白文字を入れてはいけない 3行目の1カラム目から50行目の80カラム目を指定する場合の例）range="(3, 1)-(50, 80)"	任意

例

シート名を指定する場合
sheetName属性に設定します。

 @Bean(sheetName="会員リスト")
 public class UserList2 {
    ...
 }

ユーザ作成のPOJOの要素にもつ List として取得・書き込みを行う場合
「会員一覧」と記載さられたセルを検索し、レコードが縦方向・ヘッダが横方向にある表を指定します。
表は検索された項目の右側に位置している状態にあります。

 @Bean(retrieveType=RetrieveType.VERTICAL_REPEATS,
       label="会員一覧",
       retrieveFrom=RetrieveFrom.RIGHT)
 public class UserInfo3 {
    ...
 }

LabeledCell

説明

項目の文字列を指定して検索し、その位置から左右・下から値を取得・書き込む場合に、 該当フィールドに本アノテーションを付加します。

パラメータ

属性	説明	必須
label	項目を検索し、その位置を基点に値を取得する際の文字列を指定。	必須
retrieveFrom	検索されたセルに対して、どの位置（左右・下）から値を取得するかを指定 RetrieveFrom.LEFT / RetrieveFrom.RIGHT / RetrieveFrom.BOTTOM	任意 デフォルト=RetrieveFrom.BOTTOM
margedLabel	項目（ヘッダ）が結合されて複数のセルに情報が記載されている際に指定 項目から数えて何セル移動した先にあるかを数値で指定	任意 デフォルト=0
margedRows	表の要素に対して指定する際に使用 直前のレコードの該当項目と一致する際に、値が省略された場合に直前のレコードから値を取得するかどうかを指定。	任意 デフォルト=false
use	必須が指定されていた場合に、検索不一致の場合は CellNotFoundException を上げる。必須=Use.REQUIRED / 任意=Use.OPTIONAL	任意
range	検索の範囲を指定する 範囲の指定は開始と終了の位置を「-」で連結した書式 開始と終了のセルを連結する「-」の間には空白文字を入れてはいけない 3行目の1カラム目から50行目の80カラム目を指定する場合の例）range="(3, 1)-(50, 80)"	任意

例

項目が結合されたセルを検索して値を取得・書き込みを行う場合
右図のようなシートから firstName と lastName を取得したい場合、それぞれの label 属性に「氏名」を設定し、lastName には margedLabel 属性に１つ離れた位置から取得するように設定します。

 @Bean
 public class UserInfo3 {
   @LabeledCell(label = "氏名", retrieveFrom = RetrieveFrom.RIGHT)
   private String firstName;
   @LabeledCell(label = "氏名", margedLabel = 1, retrieveFrom = RetrieveFrom.RIGHT)
   private String lastName;
    ...
 }

PointedCell

説明

セル位置を指定して値を取得・書き込む場合に、本アノテーションを該当フィールドに付加します。

パラメータ

属性	説明	必須
position	取得するセルの位置を指定 位置の指定は行、列をカンマ「,」で区切って「(」「)」で括る。（12行目の8カラム目を指定する場合の例）position=(12, 8)	必須
use	必須が指定されていた場合に、検索不一致の場合は CellNotFoundException を上げる。必須=Use.REQUIRED / 任意=Use.OPTIONAL	任意

例

セル位置を指定して値を取得・書き込む場合
19行目、3列目のセルから値を取得します。

 @Bean
 public class UserList2 {
   @PointedCell(position = "(19, 3)")
   private String lastUpdate;
    ...
 }

ConstantValue

説明

読み込みの場合のみ機能します。
Excelから値を取得してPOJOへ詰めたいが、固定値を設定したい場合に、該当フィールドへ本アノテーションを付加します。
指定された値に対し、予約語の変換を行うことが可能。
予約語については下記を参照

パラメータ

属性	説明	必須
value	固定値となる値	必須

予約語

予約語	変換結果
%EXEC_DATE_YYYYMMDD%	処理された日付をフォーマットyyyyMMddの文字列で返す
%EXEC_DATE_SL_YMD%	処理された日付をフォーマットyyyy/MM/ddの文字列で返す
%EXEC_DATE_HP_YMD%	処理された日付をフォーマットyyyy-MM-ddの文字列で返す
%EXEC_DATE_HHMMSS%	処理された時刻をフォーマットHHmmssの文字列で返す

例

読み込み時に固定値として読み込む場合

 @Bean
 public class UserList2 {
   @ConstantValue("固定の値")
   private String someField;
    ...
 }

固定値に予約語を指定した場合
下記の設定で、実行日が２０１０年７月８日だった場合、「20100708」がセットされます。

 @Bean
 public class UserList2 {
   @ConstantValue("%EXEC_DATE_YYYYMMDD%")
   private String someField;
    ...
 }

VerticalRepeats

説明

Excelシートに表イメージで記載されている内容に対し、 List または配列として値の取得・書き込みを行うフィールドに、本アノテーションを付加します。
レコードが縦方向・ヘッダが横方向にある表の場合に使用します。

パラメータ

属性	説明	必須
label	項目から表の位置を検索する際に、文字列を指定。	任意 ただし、本属性か position の指定が必要
position	表の位置を座標で指定する際に、位置を指定。 位置の指定は行、列をカンマ「,」で区切って「(」「)」で括る。 （12行目の8カラム目を指定する場合の例）position=(12, 8)	任意 ただし、本属性か label の指定が必要
retrieveFrom	表の位置を検索する項目に対して、どの位置（右・下）に表が存在するかを指定 RetrieveFrom.RIGHT / RetrieveFrom.BOTTOM	任意
terminate	表を読み込む際に、レコードの最終行として文字列を指定する際に使用。 本属性が指定されていない場合は、読み込んだレコードの値がすべて空だった際に表の最終行として動作する。	任意 デフォルト=RetrieveFrom.BOTTOM
margedRows	直前のレコードの該当項目と一致する際に、値が省略された場合に直前のレコードから値を取得するかどうかを指定。 行全体に対しての動作を指定	任意 デフォルト=false
use	必須が指定されていた場合に、検索不一致の場合は CellNotFoundException を上げる。必須=Use.REQUIRED / 任意=Use.OPTIONAL	任意
listClass	retrieveType=RetrieveType.VERTICAL_REPEATS / RetrieveType.HORIZONTAL_REPEATS を指定した際に、List の実装クラスを指定、または配列の場合はPOJOの配列を指定	任意 retrieveType=RetrieveType.VERTICAL_REPEATS / RetrieveType.HORIZONTAL_REPEATS が指定された際に本属性が指定されていない場合は、java.util.ArrayList が指定されたこととして動作する。
succeedFields	retrieveType=verticalRepeats / horizontalRepeats を指定した際に、親クラスから値を引き継ぎたいフィールドがある場合に指定。 フォーマット："{ターゲットフィールド名=親フィールド名 [, ターゲットフィールド名=親フィールド名]* }"	任意
range	表の先頭位置（ラベル位置）検索の範囲を指定する 範囲の指定は開始と終了の位置を「-」で連結した書式 開始と終了のセルを連結する「-」の間には空白文字を入れてはいけない 3行目の1カラム目から50行目の80カラム目を指定する場合の例）range="(3, 1)-(50, 80)"	任意

例

ユーザ作成のPOJOの要素の List で値の取得・書き込みを行う場合
targetClass属性にPOJO（some.UserInfo2"）を指定し、label属性に検索する項目「会員一覧」を指定します。

 @Bean
 public class UserList2 {
   @VerticalRepeats(targetClass = "some.UserInfo2", 
                    label="会員一覧")
   private List<UserInfo2> userInfoList;
    ...
 }

親クラスからデータを引き継ぐフィールドを指定する場合
TableInfoクラスのcolumnListフィールドがカラム情報の表として保持している際に、
このフィールドの要素（ColumnInfo）が、親クラスのフィールド（tableName）からデータを引き継ぐ場合、 succeedFields属性を用いて指定します。
要素「ColumnInfo」のフィールド「tableName」はExcelから値を取得する定義をしません。
親クラス（TableInfo）の「tableName」フィールドの値を用いて設定されます。

 @Bean
 public class TableInfo {
   @LabeledCell(label="定義名称")
   private String tableName;  // ColumnInfoに値が引き継がれます
 
   @VerticalRepeats(targetClass = "some.ColumnInfo", label="会員一覧"
                    succeedFields="{tableName=tableName}")
   private List<ColumnInfo> columnInfoList;
    ...
 }
 public class ColumnInfo {
   private String tableName;  // 値取得の指定をしません
    ...
 }

HorizontalRepeats

説明

HorizontalRepeatsと同様、Excelシートに表イメージで記載されている内容に対し、 List または配列として値の取得・書き込みを行うフィールドに、本アノテーションを付加します。
レコードが横方向・ヘッダが縦方向にある表の場合に使用します。

パラメータ

属性	説明	必須
label	項目から表の位置を検索する際に、文字列を指定。	任意 ただし、本属性か position の指定が必要
position	表の位置を座標で指定する際に、位置を指定。 位置の指定は行、列をカンマ「,」で区切って「(」「)」で括る。 （12行目の8カラム目を指定する場合の例）position=(12, 8)	任意 ただし、本属性か label の指定が必要
retrieveFrom	表の位置を検索する項目に対して、どの位置（右・下）に表が存在するかを指定 RetrieveFrom.RIGHT / RetrieveFrom.BOTTOM	任意
terminate	表を読み込む際に、レコードの最終行として文字列を指定する際に使用。 本属性が指定されていない場合は、読み込んだレコードの値がすべて空だった際に表の最終行として動作する。	任意 デフォルト=RetrieveFrom.BOTTOM
margedRows	直前のレコードの該当項目と一致する際に、値が省略された場合に直前のレコードから値を取得するかどうかを指定。 行全体に対しての動作を指定	任意 デフォルト=false
use	必須が指定されていた場合に、検索不一致の場合は CellNotFoundException を上げる。必須=Use.REQUIRED / 任意=Use.OPTIONAL	任意
listClass	retrieveType=RetrieveType.VERTICAL_REPEATS / RetrieveType.HORIZONTAL_REPEATS を指定した際に、List の実装クラスを指定、または配列の場合はPOJOの配列を指定	任意 retrieveType=RetrieveType.VERTICAL_REPEATS / RetrieveType.HORIZONTAL_REPEATS が指定された際に本属性が指定されていない場合は、java.util.ArrayList が指定されたこととして動作する。
succeedFields	retrieveType=verticalRepeats / horizontalRepeats を指定した際に、親クラスから値を引き継ぎたいフィールドがある場合に指定。 フォーマット："{ターゲットフィールド名=親フィールド名 [, ターゲットフィールド名=親フィールド名]* }"	任意
range	表の先頭位置（ラベル位置）検索の範囲を指定する 範囲の指定は開始と終了の位置を「-」で連結した書式 開始と終了のセルを連結する「-」の間には空白文字を入れてはいけない 3行目の1カラム目から50行目の80カラム目を指定する場合の例）range="(3, 1)-(50, 80)"	任意

例

ユーザ作成のPOJOの配列で値の取得・書き込みを行う場合
targetClass属性にPOJO（some.UserInfo2"）を指定し、label属性に検索する項目「会員一覧」を指定します。

 @Bean
 public class UserList2 {
   @HorizontalRepeats(targetClass = "some.UserInfo2", 
                    label="会員一覧",
                    listClass="some.UserInfo2[]")
   private UserInfo2[] userInfoList;
    ...
 }

MappedCell

説明

Map を指定した取得・書き込みを行う場合に、該当フィールドに本アノテーションを付加します。
ヘッダがキー、内容が値となる表の場合に使用します。

パラメータ

属性	説明	必須
previousLabel	項目から表の位置を検索する際に、文字列を指定。	任意 ただし、本属性か position の指定が必要
position	表の位置を座標で指定する際に、位置を指定。 位置の指定は行、列をカンマ「,」で区切って「(」「)」で括る。 （12行目の8カラム目を指定する場合の例）position=(12, 8)	任意 ただし、本属性か previousLabel の指定が必要
retrieveFrom	表の位置を検索する項目に対して、どの位置（右・下）に表が存在するかを指定 RetrieveFrom.RIGHT / RetrieveFrom.BOTTOM	任意
dataDirection	データの行方向が縦（下）か横（右）かを指定 DataDirection.DOWN / DataDirection.RIGHT	任意 デフォルト=DataDirection.RIGHT
use	必須が指定されていた場合に、検索不一致の場合は CellNotFoundException を上げる。必須=Use.REQUIRED / 任意=Use.OPTIONAL	任意
range	表の先頭位置（ラベル位置）検索の範囲を指定する 範囲の指定は開始と終了の位置を「-」で連結した書式 開始と終了のセルを連結する「-」の間には空白文字を入れてはいけない 3行目の1カラム目から50行目の80カラム目を指定する場合の例）range="(3, 1)-(50, 80)"	任意

例

値の取得・書き込みを行う場合
下図のようなヘッダ（月）がキー、内容（作業時間）が値となるような Map を指定します。
表の位置を検索する文字列「作業時間」をpreviousLabel属性に指定し、検索位置の右から取得するようretrieveFrom属性に指定します。

 @Bean
 public class UserList2 {
   @MappedCell(previousLabel="作業時間", 
               retrieveFrom=RetrieveFrom.RIGHT)
   private Map<String, String> workingHours;
    ...
 }

Converter

説明

ExcelのセルとPOJOのフィールドで変換が必要な際にコンバータを指定します。
コンバータの指定は、各読み込み指定アノテーションのあと、またはXMLでの読み込み指定を行った後に指定してください。
先に指定した場合は、読み込み指定が存在しないと認識して例外をあげます。
パラメータ'

属性	説明	必須
converterClass	CellFieldConverterをインプリメントしたクラス名を指定	必須
constractorArgs	コンストラクタに引数が必要な場合に指定 フォーマット：値をカンマ「,」で区切った文字列で指定 カンマと値のあいだにある空白文字は無視されます。 例）constractorArgs="value1, value2" ※現在の仕様では値にカンマを指定することはできません。	任意
parameters	インスタンスにパラメータを指定したい場合に指定 フォーマット：パラメータ名=値のセットを「,」で区切った文字列で指定カンマと値のあいだにある空白文字は無視されます。 例）parameters="cellType=java.util.Date, fieldFormat=yyyy/MM/dd" ※現在の仕様では値にカンマを指定することはできません。	任意

例

位置指定で読み込むフィールドに対し、日付⇔文字列の相互変換を行う場合
位置指定で読み込みをまず定義します。（@PointedCell）
そのあとに変換の指定を行います。
日付⇔文字列の変換のため、クラスにはStringDateConverterを指定します。
デフォルトの状態では使用できないので、プロパティを指定します。
Excel側のタイプにData型を指定し、POJO側のフィールドフォーマットにyyyy年MM月dd日と指定します。
※Excel側の型指定（cellType）には、日付型の場合はDate型を、文字列型の場合はString型を指定してください。

   @PointedCell(position="(1, 2)")
   @Converter(converterClass="net.w_horse.excelpojo.converter.StringDateConverter",
              parameters="cellType=java.util.Date, fieldFormat=yyyy年MM月dd日")
   private String dateStr1;