XLSBeans - Excel to POJO Mapping

TODO

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には この他にもメソッド、フィールドに付与されたアノテーションを取得するためのメソッドも用意されています。