TOP RSS LOGIN

Community

Products

Eclipse Plug-Ins

Libs & Tools

Documents

SourceForge.jp

XLSBeans

XLSBeansの開発はGithubに移行しました。今後は以下のURLをご覧ください。

ExcelとJavaBeansをJava 5のアノテーションでマッピングするためのライブラリです。

MYCOMジャーナルに簡単な紹介記事が掲載されています。まずはこちらをご覧いただくとXLSBeansがどのようなものかをご理解いただけるのではないかと思います。

ダウンロード

Mavenから使用する場合は以下の依存関係をpom.xmlに追加してください。

<repositories>
  <repository>
    <id>amateras</id>
    <name>Project Amateras Maven2 Repository</name>
    <url>http://amateras.sourceforge.jp/mvn/</url>
  </repository>
</repositories>

<dependencies>
  <dependency>
    <groupId>jp.sf.amateras.xlsbeans</groupId>
    <artifactId>xlsbeans</artifactId>
    <version>1.2.1</version>
  </dependency>
</dependencies>

ライセンス

Apache License, Version 2.0に準じます。

使い方

 アノテーションによるマッピング

例えばこんなExcelシートがあったとします。

アノテーションを使用してExcelシートとPOJOをマッピングします。@HRecordsは水平方向の表(要するに普通の表)を配列またはListにマッピングします。tableLabelで表のタイトル部分の文字列、recordClassで1レコード分を表すクラスを指定します。また@LabelledCellではlabelで指定した文字列が格納されているセルの右側のセルをBeanのプロパティにマッピングしています。

@Sheet(name="Users")
public class UserList {
  
  @LabelledCell(label="Title", type=LabelledCellType.Right)
  public String title;

  @HorizontalRecords(tableLabel="User list", recordClass=User.class)
  public List<User> users;

}

以下が1行分のデータを表すクラスです。@Columnで列名とのマッピングを行います。merged=trueにしておくと、グループ化されてるっぽい列をよしなに取り計らってくれます。

public class User {
  
  @Column(columnName="ID")
  public int id;
     
  @Column(columnName="Name")
  public String name;
  
  @Column(columnName="Gender", merged=true)
  public String gender;

}

使うときはこんな感じです。

UserList userList = (UserList)XLSBeans.load(
  new FileInputStream("example.xls"), UserList.class);

アノテーションでは基本的にセル内の文字列をターゲットにしてマッピングするので行や列の挿入などによって位置が変わっても問題ありませんし、マッピング時に意識する必要もありません。

デフォルトではJavaExcel APIを使用してExcelファイルを読み込みますが、XLSBeans 1.2.0以降はApache POIを使用した読み込みにも対応しています。読み込み方法を指定するには以下のようにオプションを指定します。

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

読み込み時のオプションとして指定可能な値は以下の通りです。

  • WorkbookFinder.TYPE_JXL - Java Excel APIを使用してExcel2003形式(xls)のファイルを読み込み
  • WorkbookFinder.TYPE_HSSF - Apache POIを使用してExcel2003形式(xls)のファイルを読み込み
  • WorkbookFinder.TYPE_XSSF - Apache POIを使用してExcel2007形式(xlsx)のファイルを読み込み

 外部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>

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

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

更新履歴

 2011/07/05 - 1.2.1

  • POI使用時に数式のセルの値の取得時にエラーが発生する問題を修正。

 2010/07/03 - 1.2.0

  • Excel2007に対応しました。
  • JavaExcel APIでの文字化けに対応しました。

 2010/03/14 - 1.1.0

  • publicフィールドをサポートしました。
  • DynamicAnnotationBuilderにクラスローダがセットされていない場合、コンテキストクラスローダを使用するようにしました。

 2008/12/23 - 1.0.7

  • DynamicAnnotationBuilderにOGNLで使用するためのクラスローダを指定できるようにしました。
  • @LabelledCellにskip属性を追加しました。
  • @IterateTablesにoptional属性を追加しました。

 2008/11/24 - 1.0.6

  • @HorizontalRecordsと@VerticalRecordsの処理を高速化しました。
  • XMLによるアノテーションの指定時にJavassistではなくProxyを使うようにしました(Javassistは不要になりました)。
  • @HorizontalRecordsと@VerticalRecordsにheaderLimitパラメータを追加しました。

 2008/08/02 - 1.0.5

  • setterメソッド+Position()メソッドでセル位置を取得できるようにしました。
  • アノテーションに@Documentedを付与しました。

 2008/06/07 - 1.0.4

  • 繰り返し項目に配列を使った場合のバグ修正

 2007/07/04 - 1.0.3

  • @IterateTableアノテーションを追加。
  • @Columnで列が見つからない場合は例外を投げるようにした(optional=trueを指定すれば例外を投げずにスキップします)。
  • 既存のアノテーションにいくつかのパラメータを追加。

 2007/02/11 - 1.0.2

  • はじめての正式リリース。

 2006/05/18 - 1.0 beta1

  • とりあえず置いておきます。
  • エラー処理とか何もしていません。