# XLSBeans - Excel to POJO Mapping

## TODO

- ダイナミックアノテーション
  - メソッド・アノテーションの指定方法（引数）
  - アノテーションの初期値
- マッピング
  - JXLを使うのをやめる？
- 全般
  - 英語のドキュメント。

## XLSBeansの使い方

XLSBeansはアノテーションを付与してJavaBeansとExcelをマッピングするライブラリ（プロトタイプ）です。 以下のアノテーションが利用可能です。

### @Sheet

読み込むシートをシート番号またはシート名で指定します。クラスに付与します。

    @Sheet(number=0)
    public class SheetObject {
      ...
    }

    @Sheet(name="Users")
    public class SheetObject {
      ...
    }

### @Cell

セルの列、行を指定してBeanのプロパティにマッピングします。setterメソッドに対して付与します。

    @Sheet(name="Users")
    public class SheetObject {
      @Cell(column=0, row=0)
      public void setTitle(String title){
        ...
      }
    }

### @LabelledCell

セルの文字列を指定し、その左右もしくは下側のセルの値をマッピングします。setterメソッドに対して付与します。

    @Sheet(name="Users")
    public class SheetObject {
      @LabelledCell(label="Title", type=LabelledCellType.Right)
      public void setTitle(String title){
        ...
      }
    }

rangeパラメータを指定すると、typeパラメータの方向に向かって指定したセル数分を検索し、 最初に発見した空白以外のセルの値を取得します。

    @Sheet(name="Users")
    public class SheetObject {
      @LabelledCell(label="Title", type=LabelledCellType.Right, range=3)
      public void setTitle(String title){
        ...
      }
    }

セルが見つからなかった場合はエラーとなりますが、`optional`パラメータに `true`を指定しておくと、無視して処理を続行します。

### @SheetName

シート名を`String`型のプロパティにマッピングします。

    @Sheet(name="Users")
    public class SheetObject {
      @SheetName
      public void setSheetName(String sheetName){
        ...
      }
    }

### @HorizontalRecords

水平方向に連続する行を`List`または配列にマッピングします。 表には最上部にテーブルの名称と列名を記述した行が必要になります。

    +------------------+-------
    |Horizontal Records|         <--- テーブルの名称
    +------------------+-------
    |ID                |Name     <--- 列名
    +------------------+-------
    |1                 |Naoki    <--- これ以降はデータ
    +------------------+-------
    |2                 |...
    +------------------+-------

`tableLabel`パラメータでテーブルの名称を指定します。 `List`型または配列の引数を1つだけ取るsetterメソッドに対して付与します。

    @Sheet(name="Users")
    public class SheetObject {
      @HorizontalRecords(tableLabel="Horizontal Records", recordClass=Record.class)
      public void setRecords(List<Record> records){
        ...
      }
    }

デフォルトでは行に1つもデータが存在しない場合、そのテーブルの終端となります。 行の一番左側の列のボーダーによってテーブルの終端を検出する方法もあります。 この場合は`@HorizontalRecords`の`terminal`パラメータに `RecordTerminal.Border`を指定してください。

    @Sheet(name="Users")
    public class SheetObject {
      @HorizontalRecords(tableLabel="Horizontal Records", recordClass=Record.class,
                terminal=RecordTerminal.Border)
      public void setRecords(List<Record> records){
        ...
      }
    }

セルが見つからなかった場合はエラーとなりますが、`optional`パラメータに `true`を指定しておくと、無視して処理を続行します。

### @VerticalRecords

垂直方向に連続する列を`List`または配列にマッピングします。 要するに`@HorizontalRecords`を縦方向にしたものです。 `@HorizontalRecords`と同じく`List`型の引数を1つだけ取るsetterメソッドに対して付与します。

    @Sheet(name="Users")
    public class SheetObject {
      @VerticalRecords(tableLabel="Vertical Records", recordClass=Record.class)
      public void setRecords(List<Record> records){
        ...
      }
    }

`@HorizontalRecords`と同じく`terminal`パラメータ、 および`optional`パラメータを指定することもできます。

### @Column

`@HorizontalRecords`または`@VerticalRecords`で指定されたクラスのプロパティをカラム名にマッピングします。 setterメソッドに対して付与します。

    public class Record {
      @Column(columnName="ID")
      public void setId(String id){
        ...
      }
    }

同じ値がグループごとに結合されているカラムの場合は`merged`パラメータを`true`に設定します。 こうしておくと、前の列の値が引き継がれて設定されます。

    public class Record {
      @Column(columnName="Gender", merged=true)
      public void setId(String id){
        ...
      }
    }

### @MapColumns

`@HorozintalRecord`もしくは`@VerticalRecord`でカラム数が可変の場合に、 それらのカラムを`Map`として設定します。Beanには`Map`を引数に取る セッターメソッドを用意し、このアノテーションを記述します。

    @MapColumns(previousColumnName="Previous Column")
    public void setAttributes(Map attributes){
      this.attributes = attributes
    }

`previousColumnName`パラメータで指定された次のカラム以降、カラム名をキーとした `Map`が生成され、Beanにセットされます。

### @PostProcess

`@Sheet`を付与したクラス、もしくは`@HorizontalRecords`や`@VerticalRecords` で指定したレコードクラスのメソッドに付与しておくと、シートの読み込みが終了した時点で呼び出されます。 なお、このアノテーションを付与するメソッドは引数を取らないpublicメソッドである必要があります。

    @Sheet(name="Users")
    public class SheetObject {
      @PostProcess
      public void postProcess(){
        ...
      }
    }

### 読み込み方

以下のようにして読み込みを行います。

    SheetObject sheet = new XLSBeans.load(
        new FileInputStream("example.xls"), SheetObject.class);

なお、`@Cell`, `@LabelledCell`, `@Column`アノテーションで マッピングするプロパティに関しては、現時点では`String`型、プリミティブ型、プリミティブ型の ラッパー型のいずれかである必要があります。より具体的な使用例はexampleフォルダ内のソースコードをご覧ください。

## XMLファイルによるマッピング

アノテーションだけではなく、外部XMLファイルでマッピングを行うことも可能です。 これはダイナミック・アノテーションという、アノテーションと同様の情報をXMLファイルで定義することで行います。 以下にクラスに対してアノテーションを付与するXMLファイルの例を示します。

    <?xml version="1.0" encoding="utf-8"?>
    <annotations>
      <class name="net.java.amateras.xlsbeans.example.SheetObject">
        <annotation name="net.java.amateras.xlsbeans.annotation.Sheet">
          <attribute name="name">'Users'</attribute>
        </annotation>
      </class>
    </annotations>

アノテーションの属性値の指定にはOGNL式を使用します。メソッドにアノテーションを付与する場合は次のようになります。

    <?xml version="1.0" encoding="utf-8"?>
    <annotations>
      <class name="net.java.amateras.xlsbeans.example.SheetObject">
        <annotation name="net.java.amateras.xlsbeans.annotation.Sheet">
          <attribute name="name">'Users'</attribute>
        </annotation>
        <method name="setTitle">
          <annotation name="net.java.amateras.xlsbeans.annotation.LabelledCell">
            <attribute name="label">'Title'</attribute>
            <attribute name="type">@net.java.amateras.xlsbeans.annotation.LabelledCellType@Right</attribute>
          </annotation>
        </method>
      </class>
    </annotations>

XLSBeansでは使用しませんが、フィールドにアノテーションを付与することも可能です。

    <?xml version="1.0" encoding="utf-8"?>
    <annotations>
      <class name="net.java.amateras.xlsbeans.example.SheetObject">
        <field name="setTitle">
          <annotation name="...">
            ...
          </annotation>
        </field>
      </class>
    </annotations>

外部XMLファイルを使う場合、ハードコードされたアノテーションを外部XMLファイルの内容でオーバーライドすることが可能です。 読み込み時は以下のようにExcelファイルとXMLファイルの両方をXMLBeans#load()メソッドに渡します。

    SheetObject sheet = XLSBeans.load(
      new FileInputStream("example.xls"),
      new FileInputStream("example.xml"), SheetObject.class);

なお、AnnotationReaderクラスを使用することで、XLSBeansのダイナミック・アノテーション 機能を別のプログラムでも利用することが可能です。

    // XMLファイルの読み込み
    XMLInfo info = XMLLoader.load(new FileInputStream("example.xml"));

    // AnnotationReaderのインスタンスを作成
    AnnotationReader reader = new AnnotationReader(info);

    // SheetObjectクラスに付与されたSheetアノテーションを取得
    Sheet sheet = reader.getAnnotation(SheetObject.class, Sheet.class);

`Class`や`Method`、`Field`オブジェクトから直接アノテーションを 取得する代わりに`AnnotationReader`を使えば、XMLで宣言されたアノテーションと、クラスに 埋め込まれているアノテーションを区別せずに取得することができます。`AnnotationReader`には この他にもメソッド、フィールドに付与されたアノテーションを取得するためのメソッドも用意されています。