Jaxcel

Jaxcelとは、JavaのExcelテンプレートエンジンです。
テンプレート式を書き込んだExcelファイルにデータを埋め込み、動的にExcelファイルを出力します。

2014-10-14
Jaxcel 1.00.00 初の正式版を公開しました。
2014-10-07
Jaxcel 1.00.00-beta を公開しました。
2014-09-10
Ver.1.00 Javadoc をプロジェクトWebページにアップしました。
2014-09-09
Jaxcel 1.00.00-alpha を公開しました。
  • Excelファイル自体にデータ埋め込み式を記述する為、専用ツールの知識や習得が不要。
  • フォントサイズや罫線等の装飾は、テンプレートとなるExcelファイルで設定可能。
  • チャートやピボットテーブルをテンプレートとして設定可能。
  • 複数シートが存在するブックに対応。
  • マクロ有効ブックに対応。
  • Excel97-2003ブック形式(.xls)、2007以降のブック形式(.xlsx .xlsm)に対応。
  • リストや配列等の繰り返し出力(foreach)、データによる出力・非出力(if)の制御構文が使用可能。
  • 制御構文は行/列全体のみでなく、矩形範囲での制御が可能。
  • 制御構文毎に、制御方向(行/列)の指定が可能。
  • 制御構文内では埋め込みデータ以外に、下記の繰返し生成(foreach句使用時)、非出力(if句使用時)が可能。
    • オートシェイプや画像等のオブジェクト※1
    • テーブル※1
    • 結合セル
    • オートフィルタ※2
  • 数式の参照範囲も制御構文に連動する為、特殊な記述は不要。
  • 埋め込みデータの解析にはApache Commons JEXLを使用。柔軟な式の記述が可能。

  • ※1:Excel2007以降のブック形式(.xlsx .xlsm)のみ対応。
  • ※2:if句による出力・非出力のみ対応。
  1. Excelテンプレートファイルの用意

    テンプレート式を埋め込んだExcelファイルを用意します。

  2. Javaコード

    埋め込みデータの生成、Excelファイルの出力を記述します。

    // 埋め込みデータとなるMapブジェクトの生成・データの投入
    HashMap<String, Object> parameter = new HashMap<>();
    parameter.put("data1", "Hello");
    parameter.put("data2", "Jaxcel");
    
    // Jaxcelレポートメーカーオブジェクトの生成
    ReportMaker jaxcel = new ReportMaker();
    
    // テンプレートExcelファイル、パラメータ、出力結果Excelファイルを指定。
    // result.xlsxファイルが出力される。
    jaxcel.makeReport(new File("template.xlsx"), parameter, new File("result.xlsx"));
  3. Excel出力結果

    テンプレート式にデータが埋め込まれたExcelファイルが出力されます。

Excelテンプレートファイルの作成方法を説明します。

値の出力

値の出力には"${"と"}"で囲まれたEL式(Expression Language)を使用します。
EL式の解析にはApache Commons JEXLを使用しているので、埋め込みデータの出力に限らず、柔軟な式の記述が可能です。
埋め込みデータは、ReportMakerクラスのmakeReportメソッドの引数となるMapオブジェクトにセットします。Excelテンプレートファイルには、MapオブジェクトのキーでEL式を記述します。

文字列の出力

// 埋め込みデータとなるMapブジェクトの生成・データの投入
HashMap<String, Object> parameter = new HashMap<>();
parameter.put("data1", "Java");
parameter.put("data2", "Excel");

1. 基本の埋め込み

テンプレート
出力結果
説明

文字列としてデータを埋め込む。


2. 文中への埋め込み

テンプレート
出力結果
説明

EL式以外の文字列は保持しデータを埋め込む。
同一セルへの複数EL式の記述も可能。


3. 数式への埋め込み

テンプレート
出力結果
説明

数式にデータを埋め込む。
出力結果のブックでも数式は保持される。


4. セルの書式について

テンプレート
出力結果
説明

フォント・配置・罫線・セル結合等、セルのスタイルは出力結果のブックでも保持される。

数値の出力

// 埋め込みデータとなるMapブジェクトの生成・データの投入
HashMap<String, Object> parameter = new HashMap<>();
parameter.put("data1", 12345);
parameter.put("data2", Math.PI);
parameter.put("data3", "0.25");  // String

1. 基本の埋め込み(セルの表示形式"標準")

テンプレート
出力結果
説明

数値として識別可能な文字列も数値として埋め込む。


2. セルの表示形式設定

テンプレート
出力結果
説明

セルの表示形式を保持しデータを埋め込む。


3. EL式内での計算

テンプレート
出力結果
説明

EL式内で埋め込みデータ同士や、固定記述値を用いた計算が可能。計算結果を数値として埋め込む。


4. 数式への埋め込み

テンプレート
出力結果
説明

数式にデータを埋め込む。出力結果のブックでも数式は保持される。
数値を引数とする関数にEL式を埋め込む場合は、VALUE関数でEL式をラップする。

日付・時刻の出力

// 埋め込みデータとなるMapブジェクトの生成・データの投入
HashMap<String, Object> parameter = new HashMap<>();
parameter.put("data1", (new Date()));
Calendar cal = Calendar.getInstance();
cal.add(Calendar.DATE, 1);
parameter.put("data2", cal);
parameter.put("data3", "2013-01-02 03:04");  // String DateTime
parameter.put("data4", "2013-05-06");        // String Date
parameter.put("data5", "07:08:09");          // String Time
parameter.put("data6", "2014-10-11T12:13:14.15+09:00");          // String DateTime ISO8601 Style

1. 基本の埋め込み(セルの表示形式"標準")

テンプレート
出力結果
説明

文字列として埋め込む。
Dateクラス、Calendarクラスのオブジェクトは"yyyy-MM-dd HH:mm:ss.S"にフォーマットされる。


2. セルの表示形式"日付(短い日付形式)"での単純な埋め込み

テンプレート
出力結果
説明

日時データ(実数)として埋め込む。
時刻フォーマットの文字列はエクセルのエポック(1900/1/0)で表示される。


3. セルの表示形式"時刻(h:mm:ss)"での単純な埋め込み

テンプレート
出力結果
説明

日時データ(実数)として埋め込む。
日付フォーマットの文字列は0時0分で表示される。


4. セルの表示形式"日付(yyyy/mm/dd hh:mm:ss)"での単純な埋め込み

テンプレート
出力結果
説明

日時データ(実数)として埋め込む。


5. 文中への埋め込み

テンプレート
出力結果
説明

埋め込み後の文字列が日付・時刻と認識でき、表示形式が"標準"、"文字列"以外の場合は日時データ(実数)として埋め込む。
文中に埋め込む場合は、DateFormatクラス等を使用し、適切なフォーマットを行う。

Mapオブジェクトの出力

// 埋め込みデータとなるMapブジェクトの生成・データの投入
HashMap<String, Object> parameter = new HashMap<>();
// Mapデータ
HashMap<String, Object> mapData = new HashMap<>();
mapData.put("data1", "Map Data");
mapData.put("data2", 123);
mapData.put("data3", (new Date()));
// Mapデータを投入
parameter.put("mapData", mapData);
テンプレート(表示形式"標準")
出力結果
説明

例のように、"."でのキー名、"["と"]"でのキー名指定でデータを出力可能。
"[" "]"を用いる場合で且つ、キー名がString型の場合は、シングルクォートかダブルクォートで括る。
出力はセルの表示形式とデータ型に依存する。

配列・Listオブジェクトの出力

// 埋め込みデータとなるMapブジェクトの生成・データの投入
HashMap<String, Object> parameter = new HashMap<>();
// 配列データ
String[] aryData = new String[2];
aryData[0] = "Java";
aryData[1] = "Excel";
// 配列データを投入
parameter.put("aryData", aryData);

// Listデータ
ArrayList<Object> listData = new ArrayList<>();
listData.add("List Data");
listData.add(123);
// Listデータを投入
parameter.put("listData", listData);
テンプレート(表示形式"標準")
出力結果
説明

配列、リストともに"["と"]"でのインデックス指定でデータを出力可能。
出力はセルの表示形式とデータ型に依存する。

Javaオブジェクト(POJO)の出力

// Dataクラス
class DataClass {
  public String data1;
  private int data2;
  public void setData2(int data2) {
    this.data2 = data2;
  }
  public int getData2() {
    return data2;
  }
  public double getData2Half() {
    return data2 / 2.0;
  }
}             
            
// Dataクラスオブジェクト生成
DataClass dataObject = new DataClass();
dataObject.data1 = "Java";
dataObject.setData2(123);

// 埋め込みデータとなるMapブジェクトの生成・データの投入
HashMap<String, Object> parameter = new HashMap<>();
// Dataクラスオブジェクトを投入
parameter.put("objData", dataObject);
テンプレート(表示形式"標準")
出力結果
説明

例のように、"."、もしくは"["と"]"でのプロパティ名、Getterメソッド名(getを除いたローワーキャメルケース)指定でデータを出力可能。
"[" "]"を用いる場合は、プロパティ名、Getterメソッド名をシングルクォートかダブルクォートで括る。
完全なメソッド名指定の場合は"."メソッド名()。 出力はセルの表示形式とデータ型に依存する。

foreach - 値の繰返し出力

配列やListオブジェクト、Mapオブジェクトの繰返し出力にはforeach指示子を使用します。
プロパティにより、繰返し出力方向の指定や、繰返し回数、出力範囲以降のセルのシフト方法等を指定できます。

フォーマット

#foreach(${object in aryObject}[ rows:"number"][ cols:"number"][ direction:"row|col"][ style:"copy|^copy"][ shift:"true|false"][ block:"true|false"][ start:"number"][ end:"number"])

プロパティ詳細

属性説明
${object in aryObject} "${" 要素オブジェクト in 配列オブジェクト "}" のフォーマットで指定する。配列オブジェクトには配列、List、Mapが使用可能。
rows・colsオプションで指定した範囲内で、要素オブジェクトで指定した名称で各インデックスの要素が出力可能。
rows 繰返し元の行数を正の整数で指定する。"1"指定で#foreach指示子が記述された行のみとなる。省略すると規定値である "1"となる。
cols 繰返し元の列数を正の整数で指定する。"1"指定で#foreach指示子が記述された列のみとなる。省略すると規定値である "1"となる。
direction
繰返し処理の方向を指定する。省略すると規定値である"row"となる。
row行方向に繰返す。
col列方向に繰返す。
style
繰返し元範囲(rows・colsオプションで指定する範囲)のセルスタイルのコピーについて指定する。省略すると規定値である"copy"となる。
copyセルスタイルをコピーする。
copy以外セルスタイルをコピーしない。
shift
繰返し範囲より後方の範囲のシフト方法について指定する。省略すると規定値である"true"となる。
true繰返し範囲より後方の範囲をdirectionオプションで指定した方向にシフトする。
falseシフトしない。
block
矩形範囲での繰返し処理を行うかについて指定する。省略すると規定値である"true"となる。
true繰返し範囲を矩形範囲(rows・colsオプションで指定する範囲)とする。
false繰返し範囲を繰返し元範囲に含まれる行・列全体とする。
directionオプションが"row"の場合、繰返し元範囲に含まれる行全体が繰返し範囲となる。
directionオプションが"col"の場合、繰返し元範囲に含まれる列全体が繰返し範囲となる。
start 配列オブジェクトの出力開始インデックス(1起点)を正の整数、もしくは、正の整数を返却する関数で指定する。省略すると規定値である"1"となる。
end 配列オブジェクトの出力終了インデックス(1起点)を正の整数、もしくは、正の整数を返却する関数で指定する。省略すると配列オブジェクトの要素数となる。
startオプションよりendオプションの指定値が小さい場合、配列オブジェクトを降順で出力する。
配列オブジェクトの要素数は"size(配列オブジェクト)"関数で取得可能。

繰返し出力

// Dataクラス
class DataClass {
  public String data1;
  private int data2;
  public void setData2(int data2) {
    this.data2 = data2;
  }
  public int getData2() {
    return data2;
  }
}

// 埋め込みデータとなるMapブジェクトの生成
HashMap<String, Object> parameter = new HashMap<>();

// Dataクラスのリストオブジェクト生成
ArrayList<DataClass> listData = new ArrayList<>();

// Dataクラスオブジェクト生成・リストに追加
DataClass dataObject1 = new DataClass();
dataObject1.data1 = "Java";
dataObject1.setData2(123);
listData.add(dataObject1);
DataClass dataObject2 = new DataClass();
dataObject2.data1 = "Excel";
dataObject2.setData2(456);
listData.add(dataObject2);

// リストデータを投入
parameter.put("listData", listData);

// 配列データ
String[] aryData = new String[3];
aryData[0] = "Java";
aryData[1] = "Excel";
aryData[2] = "Jaxcel";

// 配列データを投入
parameter.put("aryData", aryData);

1. 基本のforech

テンプレート
出力結果
説明

配列データを行方向に出力する。
繰返し元範囲より後方のセルをシフトし、繰返し元範囲のセルスタイルがコピーされる。


2. 列方向のforech

テンプレート
出力結果
説明

directionオプションに"col"を指定することで配列データを列方向に出力する。
繰返し元範囲より後方のセルをシフトし、繰返し元範囲のセルスタイルがコピーされる。


3. 繰返し元範囲より後方のセルをシフトしない

テンプレート
出力結果
説明

shiftオプションに"false"を指定することで、繰返し元範囲より後方のセルをシフトせず、繰返し元範囲のセルスタイルが上書きコピーされる。


4. 繰返し先範囲のセルスタイルを利用する

テンプレート
出力結果
説明

shiftオプションに"false"、styleオプションに"copy"以外を指定することで、繰返し元範囲より後方のセルをシフトせず、繰返し先範囲のセルスタイルが保持される。


5. 繰返し元範囲の矩形指定

テンプレート
出力結果
説明

rows・colsオプションを指定することで、繰返し元範囲を複数セルの矩形範囲に拡張可能。
繰返し元範囲内であれば、いずれのセルでも要素オブジェクトのEL式を記述可能。


6. 繰返し元範囲の行全体指定

テンプレート
出力結果
説明

directionオプションに"row"、blockオプションに"false"を指定することで、繰返し元範囲が行単位に拡張される。この場合、colsオプションは無効となる。
繰返し元範囲であれば、いずれのセルでも要素オブジェクトのEL式を記述可能。


7. 繰返し元範囲の列全体指定

テンプレート
出力結果
説明

directionオプションに"col"、blockオプションに"false"を指定することで、繰返し元範囲が列単位に拡張される。この場合、rowsオプションは無効となる。
繰返し元範囲であれば、いずれのセルでも要素オブジェクトのEL式を記述可能。


8. 配列オブジェクトの出力インデックス指定

テンプレート
出力結果
説明

start・endオプションを指定することで、配列オブジェクトの出力開始インデックス、終了インデックスの制御が可能。
startオプションよりendオプションの指定値が小さい場合、配列オブジェクトを降順で出力する。
配列オブジェクトの要素数は"size(配列オブジェクト)"関数で取得可能。


9. プロパティやメソッドを持つ要素オブジェクトの繰返し

テンプレート
出力結果
説明

例のように、要素オブジェクト+"."、もしくは"["と"]"でのプロパティ名、Getterメソッド名(getを除いたローワーキャメルケース)指定でデータを出力可能。
"[" "]"を用いる場合は、プロパティ名、Getterメソッド名をシングルクォートかダブルクォートで括る。完全なメソッド名指定の場合は"."メソッド名()。
繰返し元範囲であれば、いずれのセルでも要素オブジェクトのEL式を記述可能。


10. セルの書式等について

テンプレート
出力結果
説明

styleオプション"copy"指定の場合、繰返し元範囲のセルのスタイル(フォント・配置・罫線・セル結合等)、ならびにシェイプが繰返し先範囲にコピーされる。
※1:Excel2007以降のブック形式(.xlsx .xlsm)のみ対応。


11. 繰返し範囲の計算式について

テンプレート
出力結果
説明

繰返し出力により後方にシフトされるセルの計算式で使用されている相対参照の行・列は、移動距離分の加算・減算が行われれる。
例のテンプレート、C4セルの計算式は"=SUM($C$3:C3)"である。B2セルに設定されたforeach指示子により、C4セルは1行後方にシフトされる。
結果、計算式の相対参照"C3"は"C4"に置き換えられ、"=SUM($C$3:C4)"となる。

if - 範囲の表示・非表示制御

判定式がtrue判定の場合は指定範囲の出力、false判定の場合は指定の方法で範囲を削除します。

フォーマット

#if(${expression}[ rows:"number"][ cols:"number"][ delete:"left|up|clear"][ block:"true|false"])

プロパティ詳細

属性説明
${expression} 判定式。"${" 式 "}" のフォーマットで指定する。Bool値を返す式を指定する。Bool値を返さない式の場合は、値がnullでなければtrueと判断する。
rows 制御範囲の行数を正の整数で指定する。"1"指定で#if指示子が記述された行のみとなる。省略すると規定値である "1"となる。
cols 制御範囲の列数を正の整数で指定する。"1"指定で#if指示子が記述された列のみとなる。省略すると規定値である "1"となる。
delete
判定式がflse判定の場合の制御範囲に対する操作を指定する。省略すると規定値である"left"となる。
left制御範囲セルを削除し、左に詰める。
up制御範囲セルを削除し、上に詰める。
clear制御範囲セルの値・計算式をクリアするのみで詰めない。
block
矩形範囲での制御を行うかについて指定する。省略すると規定値である"true"となる。
true制御範囲を矩形範囲(rows・colsオプションで指定する範囲)とする。
false制御範囲を矩形範囲に含まれる行・列全体とする。
deleteオプションが"left"の場合、矩形範囲に含まれる列全体が制御範囲となる。
deleteオプションが"up"の場合、矩形範囲に含まれる行全体が制御範囲となる。
deleteオプションが"clear"の場合は無効。

if制御

// 埋め込みデータとなるMapブジェクトの生成・データの投入
HashMap<String, Object> parameter = new HashMap<>();
parameter.put("data1", true);
parameter.put("data2", false);
parameter.put("data3", 123);
parameter.put("data4", null);

1. 基本のif制御 - 判定 true

テンプレート
出力結果
説明

判定式がtrue判定の場合、if制御範囲を出力する。


2. 基本のif制御 - 判定 false

テンプレート
出力結果
説明

判定式がfalse判定の場合、if制御範囲を削除し列方向の後方セルを左に詰める。
例のようにコメントも削除される。


3. 基本のif制御 - bool値でなくnullでない

テンプレート
出力結果
説明

判定式がboole値でなくnullでない場合はtrue判定とみなす。


4. 基本のif制御 - bool値でなくnull

テンプレート
出力結果
説明

判定式がboole値でなくnullの場合はfalse判定とみなす。


5. 比較式を用いた判定

テンプレート
出力結果
説明

埋め込みデータ同士や、固定記述値を用いた判定式の記述が可能。
比較演算子(">",">=","<","<=","==","!=")、論理演算子("&&","||")が使用可能。括弧を用いた記述も可能。
Stringについても比較演算子での比較が可能。大小は辞書順での比較となる。


6. 行方向の削除

テンプレート
出力結果
説明

deleteオプションに"up"を指定することで、判定式がfalse判定の場合、if制御範囲を削除し行方向の後方セルを上に詰める。


7. if制御範囲のクリア

テンプレート
出力結果
説明

deleteオプションに"clear"を指定することで、判定式がfalse判定の場合、if制御範囲のセルの書式以外をクリアする。


8. if制御範囲の矩形指定

テンプレート
出力結果
説明

rows・colsオプションを指定することで、if制御範囲を複数セルの矩形範囲に拡張可能。


9. if制御範囲の行全体指定

テンプレート
出力結果
説明

deleteオプションに"up"、blockオプションに"false"を指定することで、if制御範囲が行単位に拡張される。この場合、colsオプションは無効となる。


10. if制御範囲の列全体指定

テンプレート
出力結果
説明

deleteオプションに"left"、blockオプションに"false"を指定することで、if制御範囲が列単位に拡張される。この場合、rowsオプションは無効となる。


11. シェイプ・セル結合について

テンプレート
出力結果
説明

結合セルの削除、後方セルに含まれる結合セルを詰めるための移動も可能。シェイプについても削除、詰めるための移動が可能。
※1:Excel2007以降のブック形式(.xlsx .xlsm)のみ対応。

Jaxcelは、Javaのコーディング無しでデータ埋め込みを行えるコマンドラインツール備えています。 テンプレートの動作確認や、タスクスケジューラやcron等での定期実行に利用できます。
テンプレートとなるExcelファイルと、データとなるJSONフォーマットのテキストファイルを用意することで、結果のExcelファイルを出力できます。

  1. Excelテンプレートファイルの用意

    テンプレート式を埋め込んだExcelファイルを用意します。

  2. JSONファイルの用意

    埋め込みデータとなる、JSONフォーマットのテキストファイルを用意します。なお、JSONのトップレベルはオブジェクト形式である必要があります。文字コードはUTF-8で保存します。

    {
      "data1": "Hello",
      "data2": "Jaxcel"
      "aryData": [
        {"mapData1": 123, "mapData2": "Java", "mapData3": "2014-09-30T01:02:03Z", "mapData4": true},
        {"mapData1": 456, "mapData2": "で", "mapData3": "2014-09-30T01:02:03.456+09:00", "mapData4": false},
        {"mapData1": 789, "mapData2": "Excel", "mapData3": "2014-09-30 01:02:03", "mapData4": null}
      ]
    }
  3. コマンド実行

    javaコマンドにてMakeReportToolを実行します。
    第1引数はテンプレートファイル、第2引数はJSONファイル、第3引数は出力結果のファイル名となります。

    java org.hanei.jaxcel.util.MakeReportTool "template.xlsx" "data.json" "result.xlsx"
    output complate: result.xlsx

    結果のExcelファイルの正常出力完了で"output complate: "に続き出力結果ファイル名がコマンドラインに表示されます。

    引数となる各ファイルは相対パス、絶対パスでの指定が可能です。
    また、ライブラリおよび、Log4J2プロパティファイルへのクラスパスの指定は環境に合わせて指定ください。

  4. Excel出力結果

    テンプレート式にデータが埋め込まれたExcelファイルが出力されます。