XlsMapper.java

package com.gh.mygreen.xlsmapper;

import java.io.IOException;
import java.io.InputStream;
import java.io.OutputStream;

import com.gh.mygreen.xlsmapper.annotation.XlsColumn;
import com.gh.mygreen.xlsmapper.annotation.XlsDateTimeConverter;
import com.gh.mygreen.xlsmapper.annotation.XlsHorizontalRecords;
import com.gh.mygreen.xlsmapper.annotation.XlsLabelledCell;
import com.gh.mygreen.xlsmapper.annotation.XlsRecordOption;
import com.gh.mygreen.xlsmapper.annotation.XlsRecordOption.OverOperation;
import com.gh.mygreen.xlsmapper.annotation.XlsSheet;
import com.gh.mygreen.xlsmapper.validation.MultipleSheetBindingErrors;
import com.gh.mygreen.xlsmapper.validation.SheetBindingErrors;


/**
 * ExcelのシートとJavaオブジェクトをマッピングする機能を提供する。
 *
 * <h3 class="description">マッピングの基本</h3>
 * <p>次のような表のExcelシートをマッピングする例を説明します。</p>
 *
 * <div class="picture">
 *    <img src="doc-files/howto_load.png" alt="">
 *    <p>基本的なマッピング</p>
 * </div>
 *
 * <p>まず、シート1つに対して、POJOクラスを作成します。</p>
 * <ul>
 *   <li>シート名を指定するために、アノテーション {@link XlsSheet} をクラスに付与します。</li>
 *   <li>見出し付きのセル「Date」をマッピングするフィールドに、アノテーション {@link XlsLabelledCell} に付与します。</li>
 *   <li>表「User List」をマッピングするListのフィールドに、アノテーション {@link XlsHorizontalRecords} を付与します。</li>
 * </ul>
 *
 *
 * <pre class="highlight"><code class="java">
 * // シート用のPOJOクラスの定義
 * {@literal @XlsSheet(name="List")}
 * public class UserSheet {
 *
 *     {@literal @XlsLabelledCell(label="Date", type=LabelledCellType.Right)}
 *     Date createDate;
 *
 *     {@literal @XlsHorizontalRecords(tableLabel="User List")}
 *     {@literal List<UserRecord>} users;
 *
 * }
 * </code></pre>
 *
 *
 * <p>続いて、表「User List」の1レコードをマッピングするための、POJOクラスを作成します。</p>
 * <ul>
 *   <li>レコードの列をマッピングするために、アノテーション {@link XlsColumn} をフィールドに付与します。</li>
 *   <li>フィールドのクラスタイプが、intや列挙型の場合もマッピングできます。</li>
 * </ul>
 *
 * <pre class="highlight"><code class="java">
 * // レコード用のPOJOクラスの定義
 * public class UserRecord {
 *
 *     {@literal @XlsColumn(columnName="ID")}
 *     int no;
 *
 *     {@literal @XlsColumn(columnName="Class", merged=true)}
 *     String className;
 *
 *     {@literal @XlsColumn(columnName="Name")}
 *     String name;
 *
 *     {@literal @XlsColumn(columnName="Gender")}
 *     Gender gender;
 *
 * }
 *
 * // 性別を表す列挙型の定義
 * public enum Gender {
 *    male, female;
 * }
 * </code></pre>
 *
 *
 * <p>作成したPOJOを使ってシートを読み込むときは、XlsMapper#load メソッドを利用します。</p>
 *
 * <pre class="highlight"><code class="java">
 * // シートの読み込み
 * XlsMapper xlsMapper = new XlsMapper();
 * UserSheet sheet = xlsMapper.load(
 *         new FileInputStream("example.xls"), // 読み込むExcelファイル。
 *         UserSheet.class                     // シートマッピング用のPOJOクラス。
 *   );
 * </code></pre>
 *
 *
 * <h3 class="description">書き込み方の基本</h3>
 * <p>同じシートの形式を使って、書き込み方を説明します。
 *   <br>まず、書き込み先のテンプレートとなるExcelシートを用意します。 レコードなどは空を設定します。
 * </p>
 *
 * <div class="picture">
 *    <img src="doc-files/howto_save.png" alt="">
 *    <p>データが空のテンプレートファイル</p>
 * </div>
 *
 * <p>続いて、読み込み時に作成したシート用のマッピングクラスに、書き込み時の設定を付け加えるために修正します。</p>
 * <ul>
 *   <li>セル「Date」の書き込み時の書式を指定するために、アノテーション {@link XlsDateTimeConverter} に付与します。
 *     <br>属性 {@link XlsDateTimeConverter#excelPattern()} でExcelのセルの書式を設定します。
 *   </li>
 *   <li>表「User List」のレコードを追加する操作を指定するために、アノテーションの属性 {@link XlsRecordOption#overOperation()}を指定します。
 *     <br>テンプレート上は、レコードが1行分しかないですが、実際に書き込むレコード数が2つ以上の場合、足りなくなるため、その際のシートの操作方法を指定します。
 *     <br>今回の{@link OverOperation#Insert}は、行の挿入を行います。
 *   </li>
 * </ul>
 *
 * <pre class="highlight"><code class="java">
 * // シート用のPOJOクラスの定義
 * {@literal @XlsSheet(name="List")}
 * public class UserSheet {
 *
 *     {@literal @XlsLabelledCell(label="Date", type=LabelledCellType.Right)}
 *     {@literal @XlsDateTimeConverter(excelPattern="yyyy/m/d")}
 *     Date createDate;
 *
 *     {@literal @XlsHorizontalRecords(tableLabel="User List")}
 *     {@literal @XlsRecordOperation(overCase=OverOperation#Insert)}
 *     {@literal List<UserRecord>} users;
 *
 * }
 * </code></pre>
 *
 * <p>修正したPOJOを使ってシートを書き込むときは、 XlsMapper#save メソッドを利用します。</p>
 *
 * <pre class="highlight"><code class="java">
 * // 書き込むシート情報の作成
 * UserSheet sheet = new UserSheet();
 * sheet.createDate = new Date();
 *
 * {@literal List<UserRecord>} users = new {@literal ArrayList<>}();
 *
 * // 1レコード分の作成
 * UserRecord record1 = new UserRecord();
 * record1.no = 1;
 * record1.className = "A";
 * record1.name = "Ichiro";
 * record1.gender = Gender.male;
 * users.add(record1);
 *
 * UserRecord record2 = new UserRecord();
 * // ... 省略
 * users.add(record2);
 *
 * sheet.users = users;
 *
 * // シートの書き込み
 * XlsMapper xlsMapper = new XlsMapper();
 * xlsMapper.save(
 *     new FileInputStream("template.xls"), // テンプレートのExcelファイル
 *     new FileOutputStream("out.xls"),     // 書き込むExcelファイル
 *     sheet                                // 作成したデータ
 *     );
 * </code></pre>
 *
 * @version 2.0
 * @author T.TSUCHIE
 *
 */
public class XlsMapper {

    private Configuration configuration;

    private XlsLoader loader;

    private XlsSaver saver;

    /**
     * デフォルトコンストラクタ
     */
    public XlsMapper() {
        this.configuration = new Configuration();
        this.loader = new XlsLoader(getConfiguration());
        this.saver = new XlsSaver(getConfiguration());
    }

    /**
     * システム情報を取得します。
     * @return 現在のシステム情報
     */
    public Configuration getConfiguration() {
        return configuration;
    }

    /**
     * システム情報を設定します。
     * @param configuration システム情報
     */
    public void setConfiguration(Configuration configuration) {
        this.configuration = configuration;
        getLoader().setConfiguration(configuration);
        getSaver().setConfiguration(configuration);
    }

    /**
     * 読み込み用クラスを取得します。
     * @return 読み込み用クラス
     */
    public XlsLoader getLoader() {
        return loader;
    }

    /**
     * 保存用クラスを取得します。
     * @return 保存用クラス。
     */
    public XlsSaver getSaver() {
        return saver;
    }

    /**
     * Excelファイルの１シートを読み込み、任意のクラスにマッピングする。
     *
     * @param <P> シートをマッピングするクラスタイプ
     * @param xlsIn 読み込みもとのExcelファイルのストリーム。
     * @param clazz マッピング先のクラスタイプ。
     * @return シートをマッピングしたオブジェクト。
     *         {@link Configuration#isIgnoreSheetNotFound()}の値がtrueで、シートが見つからない場合、nullを返します。
     * @throws IllegalArgumentException {@literal xlsIn == null or clazz == null}
     * @throws XlsMapperException Excelファイルのマッピングに失敗した場合
     * @throws IOException ファイルの読み込みに失敗した場合
     *
     */
    public <P> P load(final InputStream xlsIn, final Class<P> clazz) throws XlsMapperException, IOException {
        return loader.load(xlsIn, clazz);
    }

    /**
     * Excelファイルの１シートを読み込み、任意のクラスにマッピングする。
     *
     * @param <P> シートをマッピングするクラスタイプ
     * @param xlsIn 読み込みもとのExcelファイルのストリーム。
     * @param clazz マッピング先のクラスタイプ。
     * @return シートのマッピング結果。
     *         {@link Configuration#isIgnoreSheetNotFound()}の値がtrueで、シートが見つからない場合、nullを返します。
     * @throws IllegalArgumentException {@literal xlsIn == null or clazz == null}
     * @throws XlsMapperException Excelファイルのマッピングに失敗した場合
     * @throws IOException ファイルの読み込みに失敗した場合
     */
    public <P> SheetBindingErrors<P> loadDetail(final InputStream xlsIn, final Class<P> clazz) throws XlsMapperException, IOException {
        return loader.loadDetail(xlsIn, clazz);
    }

    /**
     * Excelファイルの複数シートを読み込み、任意のクラスにマップする。
     * <p>{@link XlsSheet#regex()}により、複数のシートが同じ形式で、同じクラスにマッピングすする際に使用します。</p>
     *
     * @param xlsIn 読み込み元のExcelファイルのストリーム。
     * @param clazz マッピング先のクラスタイプ。
     * @return マッピングした複数のシート。
     *         {@link Configuration#isIgnoreSheetNotFound()}の値がtrueで、シートが見つからない場合、マッピング結果には含まれません。
     * @throws IllegalArgumentException {@literal xlsIn == null or clazz == null}
     * @throws XlsMapperException マッピングに失敗した場合
     * @throws IOException ファイルの読み込みに失敗した場合
     */
    public <P> P[] loadMultiple(final InputStream xlsIn, final Class<P> clazz) throws XlsMapperException, IOException {
        return loader.loadMultiple(xlsIn, clazz);
    }

    /**
     * XMLによるマッピングを指定し、Excelファイルの複数シートを読み込み、任意のクラスにマップする。
     * <p>{@link XlsSheet#regex()}により、複数のシートが同じ形式で、同じクラスにマッピングすする際に使用します。</p>
     *
     * @param <P> シートをマッピングするクラスタイプ
     * @param xlsIn 読み込み元のExcelファイルのストリーム。
     * @param clazz マッピング先のクラスタイプ。
     * @return 複数のシートのマッピング結果。
     *         {@link Configuration#isIgnoreSheetNotFound()}の値がtrueで、シートが見つからない場合、マッピング結果には含まれません。
     * @throws IllegalArgumentException {@literal xlsIn == null or clazz == null}
     * @throws XlsMapperException マッピングに失敗した場合
     * @throws IOException ファイルの読み込みに失敗した場合
     */
    public <P> MultipleSheetBindingErrors<P> loadMultipleDetail(final InputStream xlsIn, final Class<P> clazz)
            throws XlsMapperException, IOException {
        return loader.loadMultipleDetail(xlsIn, clazz);
    }

    /**
     * Excelファイルの複数シートを読み込み、任意のクラスにマップする。
     * <p>複数のシートの形式を一度に読み込む際に使用します。</p>
     *
     * @param xlsIn 読み込み元のExcelファイルのストリーム。
     * @param classes マッピング先のクラスタイプの配列。
     * @return マッピングした複数のシート。
     *         {@link Configuration#isIgnoreSheetNotFound()}の値がtrueで、シートが見つからない場合、マッピング結果には含まれません。
     * @throws IllegalArgumentException {@literal xlsIn == null or classes == null}
     * @throws IllegalArgumentException {@literal calsses.length == 0}
     * @throws XlsMapperException マッピングに失敗した場合
     * @throws IOException ファイルの読み込みに失敗した場合
     */
    public Object[] loadMultiple(final InputStream xlsIn, final Class<?>[] classes) throws XlsMapperException, IOException {
        return loader.loadMultiple(xlsIn, classes);
    }

    /**
     * Excelファイルの複数シートを読み込み、任意のクラスにマップする。
     * <p>複数のシートの形式を一度に読み込む際に使用します。</p>
     *
     * @param xlsIn 読み込み元のExcelファイルのストリーム。
     * @param classes マッピング先のクラスタイプの配列。
     * @return マッピングした複数のシートの結果。
     *         {@link Configuration#isIgnoreSheetNotFound()}の値がtrueで、シートが見つからない場合、マッピング結果には含まれません。
     * @throws IllegalArgumentException {@literal xlsIn == null or classes == null}
     * @throws IllegalArgumentException {@literal calsses.length == 0}
     * @throws IOException ファイルの読み込みに失敗した場合
     * @throws XlsMapperException マッピングに失敗した場合
     */
    public MultipleSheetBindingErrors<Object> loadMultipleDetail(final InputStream xlsIn, final Class<?>[] classes)
            throws XlsMapperException, IOException {
        return loader.loadMultipleDetail(xlsIn, classes);
    }

    /**
     * JavaのオブジェクトをExeclファイルに出力する。
     * <p>出力するファイルは、引数で指定した雛形となるテンプレート用のExcelファイルをもとに出力する。</p>
     *
     * @param templateXlsIn 雛形となるExcelファイルの入力
     * @param xlsOut 出力先のストリーム
     * @param beanObj 書き込むBeanオブジェクト
     * @throws IllegalArgumentException {@literal templateXlsIn == null or xlsOut == null or beanObj == null}
     * @throws XlsMapperException マッピングに失敗した場合
     * @throws IOException テンプレｰトのファイルの読み込みやファイルの出力に失敗した場合
     */
    public void save(final InputStream templateXlsIn, final OutputStream xlsOut, final Object beanObj) throws XlsMapperException, IOException {
        saver.save(templateXlsIn, xlsOut, beanObj);
    }

    /**
     * JavaのオブジェクトをExeclファイルに出力する。
     * <p>出力するファイルは、引数で指定した雛形となるテンプレート用のExcelファイルをもとに出力する。</p>
     *
     * @param <P> マッピング対象のクラスタイプ
     * @param templateXlsIn 雛形となるExcelファイルの入力
     * @param xlsOut 出力先のストリーム
     * @param beanObjs 書き込むBeanオブジェクト
     * @return マッピング結果。
     *         {@link Configuration#isIgnoreSheetNotFound()}の値がtrueで、シートが見つからない場合、nullを返します。
     * @throws IllegalArgumentException {@literal templateXlsIn == null or xlsOut == null or beanObj == null}
     * @throws XlsMapperException マッピングに失敗した場合
     * @throws IOException テンプレｰトのファイルの読み込みやファイルの出力に失敗した場合
     */
    public <P> SheetBindingErrors<P> saveDetail(final InputStream templateXlsIn, final OutputStream xlsOut, final P beanObjs) throws XlsMapperException, IOException {
        return saver.saveDetail(templateXlsIn, xlsOut, beanObjs);
    }

    /**
     * 複数のオブジェクトをそれぞれのシートへ保存する。
     * @param templateXlsIn 雛形となるExcelファイルの入力
     * @param xlsOut xlsOut 出力先のストリーム
     * @param beanObj 書き込むオブジェクトの配列。
     * @throws IllegalArgumentException {@literal templateXlsIn == null or xlsOut == null or beanObjs == null}
     * @throws IllegalArgumentException {@literal }
     * @throws XlsMapperException マッピングに失敗した場合
     * @throws IOException テンプレｰトのファイルの読み込みやファイルの出力に失敗した場合
     */
    public void saveMultiple(final InputStream templateXlsIn, final OutputStream xlsOut, final Object[] beanObj) throws XlsMapperException, IOException {
        saver.saveMultiple(templateXlsIn, xlsOut, beanObj);
    }

    /**
     * 複数のオブジェクトをそれぞれのシートへ保存する。
     * @param templateXlsIn 雛形となるExcelファイルの入力
     * @param xlsOut xlsOut 出力先のストリーム
     * @param beanObjs 書き込むオブジェクトの配列。
     * @return マッピング結果。
     *         {@link Configuration#isIgnoreSheetNotFound()}の値がtrueで、シートが見つからない場合、結果に含まれません。
     * @throws IllegalArgumentException {@literal templateXlsIn == null or xlsOut == null or beanObjs == null}
     * @throws IllegalArgumentException {@literal }
     * @throws XlsMapperException マッピングに失敗した場合
     * @throws IOException テンプレｰトのファイルの読み込みやファイルの出力に失敗した場合
     */
    public MultipleSheetBindingErrors<Object> saveMultipleDetail(final InputStream templateXlsIn, final OutputStream xlsOut, final Object[] beanObjs) throws XlsMapperException, IOException {
        return saver.saveMultipleDetail(templateXlsIn, xlsOut, beanObjs);
    }

}