1. 基本的な使い方

1.1. ダウンロード

Mavenを使用する場合は pom.xml に以下の記述を追加してください。

コード - 1.1.1 pom.xmlの依存関係
1<dependency>
2    <groupId>com.github.mygreen</groupId>
3    <artifactId>super-csv-annotation</artifactId>
4    <version>2.3</version>
5</dependency>

本ライブラリは、ロギングライブラリ SLF4j を使用しているため、好きな実装を追加してください。

コード - 1.1.2 ロギングライブラリの実装の追加（Lobbackの場合）
1<dependency>
2    <groupId>ch.qos.logback</groupId>
3    <artifactId>logback-classic</artifactId>
4    <version>1.2.11</version>
5    <scope>test</scope>
6</dependency>
コード - 1.1.3 logback.xml
 1<?xml version="1.0" encoding="UTF-8"?>
 2<configuration>
 3    <appender name="CONSOLE" class="ch.qos.logback.core.ConsoleAppender">
 4        <encoder>
 5            <Pattern>.%d{HH:mm:ss.SSS} [%thread] %-5level %logger{15} - %msg %n</Pattern>
 6        </encoder>
 7        <filter class="ch.qos.logback.classic.filter.ThresholdFilter">
 8            <level>TRACE</level>
 9        </filter>
10    </appender>
11    <logger name="com.github.mygreen.supercsv" level="DEBUG">
12        <appender-ref ref="CONSOLE" />
13    </logger>
14    <root>
15        <level value="WARN" />
16        <appender-ref ref="CONSOLE" />
17    </root>
18</configuration>

1.2. CSV用のBeanクラスの定義

CSVの1レコード分をマッピングするためのPOJOクラスを作成します。

  • CSV用のクラスは、 public である必要があります。

    • 引数なしの public なコンストラクタが必要です。

    • コンストラクタを定義しない場合は、デフォルトコンストラクタでもかまいません。

  • CSV用のクラスであることを示すために、アノテーション @CsvBean [ JavaDoc ] をクラスに付与します。

    • 属性 header をtrueとすると、 CsvAnnotationBeanReader#readAll(...) と CsvAnnotationBeanWriter#writeAll(...) メソッドの呼び出し時に、ヘッダー行がある前提として処理します。

  • カラムをフィールドにマッピングするために、アノテーション @CsvColumn [ JavaDoc ]をフィールドに付与します。

    • 属性 number で、マッピングするカラムの番号を指定します。カラムの番号は1から始まります。

    • 属性 label で、ヘッダー行のラベル名を指定することができます。省略した場合はフィールド名が適用されます。

  • フィールドに対応するgetter/setterのアクセッサメソッドを作成します。

コード - 1.2.1 Beanクラスのサンプル
 1import com.github.mygreen.supercsv.annotation.CsvBean;
 2import com.github.mygreen.supercsv.annotation.CsvColumn;
 3
 4
 5// レコード用のPOJOクラスの定義
 6@CsvBean(header=true)
 7public class UserCsv {
 8
 9    @CsvColumn(number=1)
10    private int no;
11
12    @CsvColumn(number=2, label="名前")
13    private String name;
14
15    // 引数なしのコンストラクタ
16    public UserCsv() {
17
18    }
19
20    // 以下、フィールドに対するsetter/getterメソッド
21    public int getNo() {
22        return no;
23    }
24
25    public void setNo(int no) {
26        this.no = no;
27    }
28
29    public String getName() {
30        return name;
31    }
32
33    public void setName(String name) {
34        this.naem = name;
35    }
36}

注釈

アクセッサメソッドを動的に生成する Lombok を使用すると、コード量を減らすことができます。

1.3. 読み込み方法

  • CSVファイルを読み込む場合は、クラス CsvAnnotationBeanReader [ JavaDoc ]を使用します。

  • 一度に全レコードを読み込む場合は、メソッド readAll(...) を使用します。

  • 1件ずつ読み込む場合は、メソッド read(...) を使用します。

  • Stream API による読み込みを行う場合は、メソッド lines(...) を使用します。 [v2.3+]

コード - 1.3.1 読み込むサンプル
 1import com.github.mygreen.supercsv.io.CsvAnnotationBeanReader;
 2
 3import java.nio.charset.Charset;
 4import java.nio.file.Files;
 5import java.io.File;
 6import java.util.ArrayList;
 7import java.util.List;
 8
 9import org.supercsv.prefs.CsvPreference;
10
11public class Sample {
12
13    // 全レコードを一度に読み込む場合
14    public void sampleReadAll() {
15
16        CsvAnnotationBeanReader<UserCsv> csvReader = new CsvAnnotationBeanReader<>(
17                UserCsv.class,
18                Files.newBufferedReader(new File("sample.csv").toPath(), Charset.forName("Windows-31j")),
19                CsvPreference.STANDARD_PREFERENCE);
20
21        List<UserCsv> list = csvReader.readAll();
22
23        csvReader.close();
24    }
25
26    // レコードを1件ずつ読み込む場合
27    public void sampleRead() {
28
29        CsvAnnotationBeanReader<UserCsv> csvReader = new CsvAnnotationBeanReader<>(
30                UserCsv.class,
31                Files.newBufferedReader(new File("sample.csv").toPath(), Charset.forName("Windows-31j")),
32                CsvPreference.STANDARD_PREFERENCE);
33
34        List<UserCsv> list = new ArrayList<>();
35
36        // ヘッダー行の読み込み
37        String headers[] = csvReader.getHeader(true);
38
39        UserCsv record = null;
40        while((record = csvReader.read()) != null) {
41            list.add(record);
42        }
43
44        csvReader.close();
45    }
46
47    // Stream APIによる読み込む場合
48    public void sampleReadStream() {
49
50        CsvAnnotationBeanReader<UserCsv> csvReader = new CsvAnnotationBeanReader<>(
51                UserCsv.class,
52                Files.newBufferedReader(new File("sample.csv").toPath(), Charset.forName("Windows-31j")),
53                CsvPreference.STANDARD_PREFERENCE);
54
55        // ヘッダー行の読み込み
56        String headers[] = csvReader.getHeader(true);
57
58        List<UserCsv> list = new ArrayList<>();
59
60        // Streamによる読み込み
61        csvReader.lines().forEach(record -> {
62            list.add(record);
63        });
64
65        csvReader.close();
66
67    }
68
69}

1.4. 書き込み方法

  • CSVファイルを書き込む場合は、クラス CsvAnnotationBeanWriter [ JavaDoc ]を使用します。

  • 一度に全レコードを書き込む場合は、メソッド writeAll(...) を使用します。

  • 1件ずつ書き込む場合は、メソッド write(...) を使用します。

コード - 1.4.1 書き込むサンプル
 1import com.github.mygreen.supercsv.io.CsvAnnotationBeanWriter;
 2
 3import java.nio.charset.Charset;
 4import java.nio.file.Files;
 5import java.io.File;
 6import java.util.ArrayList;
 7import java.util.List;
 8
 9import org.supercsv.prefs.CsvPreference;
10
11public class Sample {
12
13    // 全レコードを一度に書き込む場合
14    public void sampleWriteAll() {
15
16        CsvAnnotationBeanWriter<UserCsv> csvWriter = new CsvAnnotationBeanWriter<>(
17                UserCsv.class,
18                Files.newBufferedWriter(new File("sample.csv").toPath(), Charset.forName("Windows-31j")),
19                CsvPreference.STANDARD_PREFERENCE);
20
21        // 書き込み用のデータの作成
22        List<UserCsv> list = new ArrayList<>();
23        UserCsv record1 = new UserCsv();
24        record1.setNo(1);
25        record1.setName("山田太郎");
26        liad.add(record1);
27
28        UserCsv record2 = new UserCsv();
29        record2.setNo(2);
30        record2.setName("鈴木次郎");
31        liad.add(record2);
32
33        // ヘッダー行と全レコードデータの書き込み
34        csvWriter.writeAll(list);
35
36        csvWriter.close();
37    }
38
39    // レコードを1件ずつ書き込む場合
40    public void sampleWrite() {
41
42        CsvAnnotationBeanWriter<UserCsv> csvWriter = new CsvAnnotationBeanWriter<>(
43                UserCsv.class,
44                Files.newBufferedWriter(new File("sample.csv").toPath(), Charset.forName("Windows-31j")),
45                CsvPreference.STANDARD_PREFERENCE);
46
47        // ヘッダー行の書き込み
48        csvWriter.writeHeader();
49
50        // レコードのデータの書き込み
51        UserCsv record1 = new UserCsv();
52        record1.setNo(1);
53        record1.setName("山田太郎");
54        csvWriter.write(record1);
55
56        UserCsv record2 = new UserCsv();
57        record2.setNo(2);
58        record2.setName("鈴木次郎");
59        csvWriter.write(record2);
60
61        csvWrier.flush();
62        csvWrier.close();
63
64    }
65}

1.5. 値の加工方法

本ライブラリには、様々なアノテーションが用意されており、書式の指定 、トリムなどの値の変換 、 値の検証 を行うことができます。 もちろん、独自のアノテーションを作成することもできます。

また、値を変換するアノテーションと検証を行うアノテーションにおいては、適用順や読み込み／書き込み時に適用するケースを指定する属性がそれぞれ order 、 cases にて可能です。

コード - 1.5.1 値を加工するアノテーションのサンプル
 1import java.time.LocalDate;
 2
 3import com.github.mygreen.supercsv.annotation.CsvBean;
 4import com.github.mygreen.supercsv.annotation.CsvColumn;
 5import com.github.mygreen.supercsv.annotation.constraint.CsvNumberMin;
 6import com.github.mygreen.supercsv.annotation.constraint.CsvRequire;
 7import com.github.mygreen.supercsv.annotation.constraint.CsvUnique;
 8import com.github.mygreen.supercsv.annotation.conversion.CsvDefaultValue;
 9import com.github.mygreen.supercsv.annotation.conversion.CsvNullConvert;
10import com.github.mygreen.supercsv.annotation.format.CsvDateTimeFormat;
11import com.github.mygreen.supercsv.annotation.format.CsvNumberFormat;
12import com.github.mygreen.supercsv.builder.BuildCase;
13
14@CsvBean
15public class SampleCsv {
16
17    @CsvColumn(number=1, label="ID")
18    @CsvRequire                        // 必須チェックを行う
19    @CsvUnique(order=1)                // 全レコード内で値がユニークか検証する(順番指定)
20    @CsvNumberMin(value="0", order=2)  // 下限値以上か検証する(順番指定)
21    private Integer id;
22
23    @CsvColumn(number=2, label="名前")
24    private String name;
25
26    @CsvColumn(number=3, label="誕生日")
27    @CsvDateTimeFormat(pattern="yyyy年MM月dd日")   // 日時の書式を指定する
28    private LocalDate birthday;
29
30    @CsvColumn(number=4, label="給料")
31    @CsvNumberFormat(pattern="#,##0")                    // 数値の書式を指定する
32    @CsvDefaultValue(value="N/A", cases=BuildCase.Write)  // 書き込み時に値がnull(空)の場合、「N/A」として出力します。
33    @CsvNullConvert(value="N/A", cases=BuildCase.Read)    // 読み込み時に値が「N/A」のとき、nullとして読み込みます。
34    private Integer salary;
35
36    // getter/setterは省略
37
38}

1.6. タブ区切りCSVファイルへの対応

本ライブラリは、CSVの処理はSuper CSVの機能をそのまま使用しているため、 CsvAnnotationBeanReader/CsvAnnotationBeanWriter に渡す CsvPreference をカスタマイズすることで、タブ区切りなどに対応できます。

コード - 1.6.1 CSVの書式を変更するサンプル
 1import com.github.mygreen.supercsv.io.CsvAnnotationBeanReader;
 2
 3import java.nio.charset.Charset;
 4import java.nio.file.Files;
 5import java.io.File;
 6import java.util.ArrayList;
 7import java.util.List;
 8
 9import org.supercsv.prefs.CsvPreference;
10import org.supercsv.quote.AlwaysQuoteMode;
11
12public class Sample {
13
14    // 書き込む場合
15    public void sampleWrite() {
16
17        // CsvPreferencesのカスタマイズ
18        // タブ区切り、改行コード「LF」、必ずダブルクウォートで囲む設定
19        final CsvPreference preference = new CsvPreference.Builder('\"', '\t', "\n")
20            .useQuoteMode(new AlwaysQuoteMode())
21            .build();
22
23        CsvAnnotationBeanWriter<UserCsv> csvReader = new CsvAnnotationBeanWriter<>(
24                UserCsv.class,
25                Files.newBufferedReader(new File("sample.csv").toPath(), Charset.forName("Windows-31j")),
26                preference);
27
28        // 省略
29    }
30
31}