Reports.web Pure Java プログラマーズガイド／APIリファレンス

1. 最初に理解する3つのデータRM001

帳票を作るときは、「レイアウト」と「値」を分けて考えます。

それぞれを保存するファイルは次のとおりです。

通常の処理は次の3段階です。

1. ReportDefinitionIO でPREPDJを読み込む
2. ReportData に項目値と明細行を設定する
3. PdfExporter、SvgExporter、ReportRenderer、PrinterOutputのいずれかで出力する

PREPEJは、出力後の帳票を保存・受け渡しするときに使用します。PDFを1枚作るだけなら、最初からPREPEJを作る必要はありません。

2. 開発を始めるRM002

2.1 動作環境RM003

• JDK 21
• デスクトップのデザイナー／プレビュアーを使う場合はJavaFX 21以上
• WebサーバーだけでPDFやSVGを作る場合、JavaFXは不要

ZIPを展開したら、Native/Pure-Java/samples/01.あっという間に帳票出力 をエディターやIDEで開いてください。ここにはソース、帳票定義、ビルド設定、起動手順が揃っています。最初はこのサンプルを土台にすると、ライブラリの配置で迷わずに始められます。

エンジンと依存ライブラリは Native/Pure-Java/SDK/lib にあります。例えば、この01フォルダーに置いたGradleプロジェクトでは次のように参照します。同梱の build.gradle.kts は、この配置に対応済みです。

dependencies {
    implementation(fileTree("../../SDK/lib") { include("*.jar") })
}

自分のプロジェクトへ移す場合も、エンジンJARだけでなく、ここにある依存JARを一緒に参照します。相対パスは新しいプロジェクトの場所に合わせて変更してください。製品ソースの engine プロジェクトを用意する必要はありません。

2.2 パッケージRM004

通常の帳票出力で使用するパッケージは次の3つです。

3. 最初の帳票プログラムRM005

同梱の帳票定義を使い、タイトルと会社名を設定してPDFを1ページ作ってみましょう。

1. Native/Pure-Java/samples/01.あっという間に帳票出力 を開きます。
2. 元のソースを残したい場合は src/main/java/quickreport/QuickReport.java を別の場所へコピーします。同じソースフォルダーに別名の .java として残すと、クラスが重複するので注意してください。
3. QuickReport.java の内容を次のコードへ置き換えます。

package quickreport;

import com.pao.reports.engine.io.ReportDefinitionIO;
import com.pao.reports.engine.model.ReportData;
import com.pao.reports.engine.model.ReportDocument;
import com.pao.reports.engine.render.PdfExporter;

import java.nio.file.Files;
import java.nio.file.Path;

public class QuickReport {
    public static void main(String[] args) throws Exception {
        Path root = args.length == 0
                ? Path.of("").toAbsolutePath() : Path.of(args[0]).toAbsolutePath();
        Path definitionFile = root.resolve("definition/quick-report.prepdj");
        Path outputFile = root.resolve("output/first-report.pdf");
        Files.createDirectories(outputFile.toAbsolutePath().getParent());

        // 帳票のレイアウトを読み込む
        ReportDocument definition =
                new ReportDefinitionIO().read(definitionFile);

        // 帳票へ差し込む値を設定する
        ReportData data = new ReportData();
        data.values.put("Title", "はじめてのJava帳票");
        data.values.put("CustomerName", "株式会社サンプル");

        // この見本では、オブジェクト名と値のキーを結び付けます。
        for (var object : definition.objects) {
            if (data.values.containsKey(object.name)) object.binding = object.name;
        }

        // PDFを作る
        new PdfExporter().export(definition, data, outputFile);
        System.out.println("PDFを作成しました: " + outputFile);
    }
}

4. 01フォルダーのターミナルから、Windowsでは .\run.cmd、macOS／Linuxでは bash ./run.sh を実行します。詳しいJDKの準備は、01のREADMEをご覧ください。
5. 作成された output/first-report.pdf を開き、タイトルと会社名を確認します。文字列を変えてもう一度実行すると、同じPDFを更新できます。

この例はPDFだけを作ります。PREPEJ・ページ単位SVGも作る元の01とは、出力ファイルが異なります。

data.values のキーは、文字オブジェクトの binding（連結する項目）と対応します。この見本ではコードでその対応を設定しています。自作の定義で既に binding を設定してあれば、上の for 文は不要です。

以降は機能別のコード例です。第3章のような単独実行プログラムではなく、使用中の定義・データ・接続先に合わせて組み込む部分を示します。請求書の明細やDB取得を含む動く実装は、02～04のサンプルと併せて確認してください。

4. 印刷データを設定するRM006

4.1 1帳票に1つの値を設定するRM007

顧客名、伝票番号、発行日、合計金額のような値は values に設定します。

ReportData data = new ReportData();
data.values.put("伝票番号", "INV-2026-0012");
data.values.put("顧客名", "株式会社サンプル");
data.values.put("発行日", LocalDate.of(2026, 9, 14));
data.values.put("合計金額", 120000);

値には文字列だけでなく、数値、真偽値、日付なども渡せます。画面へ表示される形式を固定したい場合は、業務プログラム側で文字列へ整形してから設定してください。

NumberFormat money = NumberFormat.getNumberInstance(Locale.JAPAN);
data.values.put("合計金額", money.format(120000) + " 円");

4.2 明細行を設定するRM008

商品一覧のように同じレイアウトを繰り返す値は、1行を Map<String, Object> として rows へ追加します。

Map<String, Object> row1 = new LinkedHashMap<>();
row1.put("商品名", "商品A");
row1.put("数量", 2);
row1.put("単価", 50000);
data.rows.add(row1);

Map<String, Object> row2 = new LinkedHashMap<>();
row2.put("商品名", "商品B");
row2.put("数量", 1);
row2.put("単価", 20000);
data.rows.add(row2);

帳票定義側で繰返しが設定されたオブジェクトには、rows の各行が順番に割り当てられます。1ページに収まらない場合は、エンジンが必要なページ数を計算します。

4.3 DBの検索結果から明細を作るRM009

try (PreparedStatement statement = connection.prepareStatement(
        "select product_name, quantity, unit_price from invoice_line where invoice_id = ?")) {
    statement.setLong(1, invoiceId);

    try (ResultSet result = statement.executeQuery()) {
        while (result.next()) {
            Map<String, Object> row = new LinkedHashMap<>();
            row.put("商品名", result.getString("product_name"));
            row.put("数量", result.getInt("quantity"));
            row.put("単価", result.getBigDecimal("unit_price"));
            data.rows.add(row);
        }
    }
}

SQL列名を帳票項目名と直接結び付けず、row.put(...) の箇所で明示的に対応付けると、DB変更の影響を帳票へ持ち込みにくくなります。

4.4 印刷時だけ位置や色を変更するRM010

帳票定義を変更せず、今回の印刷だけオブジェクトの表示、位置、色などを変えることもできます。キーは @オブジェクト名.プロパティ名 の形式です。

data.values.put("@合計金額.Bold", true);
data.values.put("@社内控え.Visible", false);
data.values.put("@タイトル.FontSize", 18);

明細行ごとに指定すれば、その行に対応する繰返しオブジェクトだけを変更できます。

Map<String, Object> row = new LinkedHashMap<>();
row.put("商品名", "特別値引き");
row.put("@商品名.Bold", true);
row.put("@商品枠.StrokeColor", "#CC0000");
data.rows.add(row);

指定できる主な動的プロパティは次のとおりです。先頭の @ は省略できますが、通常の項目名と区別しやすいため付けることを推奨します。

動的プロパティは一時的な出力変更です。元の ReportDocument やPREPDJは変更されません。

5. ローカルアプリケーションで出力するRM011

5.1 PDFを作るRM012

標準のPDF出力は次の1行です。

new PdfExporter().export(definition, data, Path.of("output", "invoice.pdf"));

この呼び出しは、互換性を重視した100 DPIのイメージPDFを作ります。

文字を検索できるベクターPDFを作る場合は、使用するフォントファイルを明示します。

List<Path> fonts = List.of(
        Path.of("fonts", "NotoSansJP-Regular.ttf"),
        Path.of("fonts", "NotoSansJP-Bold.ttf"));

PdfExporter.Result result = new PdfExporter().export(
        definition,
        data,
        Path.of("output", "invoice-vector.pdf"),
        PdfExporter.Options.vector(150, fonts),
        RenderControl.none());

result.diagnostics().forEach(System.out::println);

ベクターPDFで利用できない文字は、読めない文字へ置き換えず輪郭として出力され、diagnostics() に診断情報が返ります。その文字は表示できますが、PDF内検索の対象にはなりません。

5.2 SVGを作るRM013

1ページだけをSVGファイルへ保存します。

new SvgExporter().export(
        definition, data, Path.of("output", "invoice.svg"));

複数ページをページ別のSVGへ保存します。

List<Path> files = new SvgExporter().exportPages(
        definition, data, Path.of("output", "svg"), "invoice");

SVG文字列をWebレスポンスへ直接返す場合は svg(...) を使います。

String svg = new SvgExporter().svg(definition, data, 0);

ページ番号は0から始まります。最初のページは 0 です。

5.3 BufferedImageを作るRM014

BufferedImage image = new ReportRenderer().render(
        definition, data, RenderOptions.preview());

ImageIO.write(image, "png", Path.of("output", "invoice.png").toFile());
image.flush();

render(...) は先頭ページを返します。全ページが必要な場合は renderPages(...) を使用します。

List<BufferedImage> pages = new ReportRenderer().renderPages(
        definition, data, RenderOptions.preview());

大量ページを一度にメモリーへ置きたくない場合は、pageCount(...) でページ数を取得し、renderPage(...) を1ページずつ呼び出します。

ReportRenderer renderer = new ReportRenderer();
int count = renderer.pageCount(definition, data);

for (int page = 0; page < count; page++) {
    BufferedImage image = renderer.renderPage(
            definition, data, RenderOptions.preview(), page, RenderControl.none());
    try {
        ImageIO.write(image, "png",
                Path.of("output", "page-" + (page + 1) + ".png").toFile());
    } finally {
        image.flush();
    }
}

5.4 プリンターへ印刷するRM015

印刷ダイアログを表示して印刷します。

new PrinterOutput().print(definition, data, true);

ダイアログを表示せず、既定のプリンターへ送る場合は第3引数を false にします。

既存の印刷処理へ組み込む場合は Pageable を取得します。

Pageable pages = new PrinterOutput().createPageable(definition, data);

5.5 デスクトップでプレビューするRM016

製品付属のJavaFXプレビュアーは、ReportRenderer のページ画像を使用します。独自画面へ組み込む場合も、renderPage(...) で必要なページだけを描画し、SwingFXUtils.toFXImage(...) でJavaFX画像へ変換できます。

BufferedImage buffered = new ReportRenderer().renderPage(
        definition, data, RenderOptions.preview(), pageIndex, RenderControl.none());
WritableImage fxImage = SwingFXUtils.toFXImage(buffered, null);
imageView.setImage(fxImage);
buffered.flush();

ページ移動時には pageIndex を変更して再描画します。最初のページは0、最後のページは pageCount(...) - 1 です。

5.6 デスクトップの操作UIを外側から隠すRM017

02／04 Clientに同梱した SamplePreviewWindow のソースを利用する場合は、JavaFXのUIスレッドから次のように操作できます。

var preview = new SamplePreviewWindow(owner, "帳票", definition, data);
preview.setPreviewChromeVisible(false); // 帳票だけにする
preview.show();
// アプリ側の再表示ボタンから呼び出します。
preview.setPreviewChromeVisible(true);  // メニュー・全ツールバー・ステータス・ページ一覧を表示

通常の初期表示は変わりません。これは同梱サンプルWindowの公開メソッドであり、帳票エンジンSDKが独立したUIコントロールを提供する、という意味ではありません。OSのウィンドウ枠は残ります。Web用の ReportsWebNative や、そのPDF・検索APIとは別のものです。

6. 完成した帳票をPREPEJへ保存するRM018

PREPEJは、各ページの帳票定義と印刷データをまとめた自己完結ファイルです。元のPREPDJやDBへ接続しなくても、PREPEJだけで同じ帳票を再表示・再印刷できます。

6.1 PREPEJを作るRM019

PreviewJob job = new PreviewJob();
job.name = "請求書 INV-2026-0012";

ReportRenderer renderer = new ReportRenderer();
int pageCount = renderer.pageCount(definition, data);

for (int pageIndex = 0; pageIndex < pageCount; pageIndex++) {
    job.pages.add(new PreviewJob.Page(definition, data, pageIndex));
}

new PreviewJobIO().write(
        Path.of("output", "invoice.prepej"), job);

sourcePage は、元の帳票定義と印刷データの何ページ目を表示するかを示す0始まりの番号です。

6.2 PREPEJを読み、PDFへ再出力するRM020

PreviewJobIO.ReadResult loaded =
        new PreviewJobIO().read(Path.of("output", "invoice.prepej"));

if (!loaded.selfContained()) {
    throw new IOException("帳票定義を含むPREPEJではありません");
}

List<PdfExporter.Page> pages = loaded.job().pages.stream()
        .map(page -> new PdfExporter.Page(
                page.definition, page.data, page.sourcePage))
        .toList();

new PdfExporter().exportPages(
        pages,
        Path.of("output", "invoice-reprint.pdf"),
        PdfExporter.Options.image(),
        RenderControl.none());

selfContained() が true なら、そのファイルだけで出力できます。従来の値データだけを読み込んだ場合は false になり、legacyData() に値が返ります。その場合は別途PREPD／PREPDJが必要です。

6.3 値だけを保存するRM021

ReportDataIO は values と rows だけを保存します。帳票定義を含まないため、このファイルだけではプレビューや印刷はできません。

ReportDataIO dataIO = new ReportDataIO();
dataIO.write(Path.of("work", "invoice-data.json"), data);

ReportData restored =
        dataIO.read(Path.of("work", "invoice-data.json"));

一時保存、テストデータ、サーバー内部の受け渡しには ReportDataIO、利用者へ渡す再表示・再印刷用ファイルには PreviewJobIO を使用します。

7. Webアプリケーションで使うRM022

Pure Javaエンジンは、Spring Boot、Jakarta EE、Servletなどのサーバー側Javaから利用できます。ブラウザーへJavaエンジンを配布する方式ではありません。サーバーで帳票を作り、PDF、SVGまたはPREPEJをHTTPレスポンスとして返します。

7.1 業務データを受け取りPDFを返すRM023

次のSpring Boot例では、帳票定義をサーバーに置き、リクエストで受け取った値を設定してPDFを返します。

@RestController
@RequestMapping("/api/invoices")
public class InvoiceController {
    private final ReportDocument invoiceDefinition;

    public InvoiceController() throws IOException {
        invoiceDefinition = new ReportDefinitionIO().read(
                Path.of("reports", "invoice.prepdj"));
    }

    @PostMapping(value = "/pdf", produces = MediaType.APPLICATION_PDF_VALUE)
    public ResponseEntity<byte[]> createPdf(
            @RequestBody InvoiceRequest request) throws Exception {

        ReportData data = new ReportData();
        data.values.put("顧客名", request.customerName());
        data.values.put("請求日", request.invoiceDate());
        data.values.put("合計金額", request.total());

        for (InvoiceLine line : request.lines()) {
            Map<String, Object> row = new LinkedHashMap<>();
            row.put("商品名", line.productName());
            row.put("数量", line.quantity());
            row.put("単価", line.unitPrice());
            data.rows.add(row);
        }

        Path temporary = Files.createTempFile("invoice-", ".pdf");
        try {
            new PdfExporter().export(invoiceDefinition, data, temporary);
            byte[] body = Files.readAllBytes(temporary);

            return ResponseEntity.ok()
                    .header(HttpHeaders.CONTENT_DISPOSITION,
                            "inline; filename=invoice.pdf")
                    .contentType(MediaType.APPLICATION_PDF)
                    .body(body);
        } finally {
            Files.deleteIfExists(temporary);
        }
    }
}

公開APIでは、入力項目、文字数、明細件数、出力ページ数を検証してください。クライアントから任意のファイルパスやURLを受け取り、画像として読み込ませないでください。

7.2 SVGをWeb画面へ表示するRM024

@GetMapping(value = "/{id}/svg", produces = "image/svg+xml")
public ResponseEntity<String> createSvg(
        @PathVariable long id,
        @RequestParam(defaultValue = "0") int page) {

    ReportData data = invoiceService.createReportData(id);
    int pageCount = new ReportRenderer().pageCount(invoiceDefinition, data);
    if (page < 0 || page >= pageCount) {
        return ResponseEntity.badRequest().build();
    }

    String svg = new SvgExporter().svg(invoiceDefinition, data, page);
    return ResponseEntity.ok()
            .contentType(MediaType.parseMediaType("image/svg+xml"))
            .body(svg);
}

ブラウザー側では、通常の画像と同様にエンドポイントを表示できます。

<img src="/api/invoices/123/svg?page=0" alt="請求書プレビュー">

SVGへ含めるデータはHTMLと同様に信頼境界を意識し、認証・認可と入力検証を行ってください。

7.3 PREPEJをREST APIで受け取るRM025

クライアントが完成済みPREPEJを持っている場合は、PreviewJobIO で読み込み、各ページをPDFやSVGへ出力できます。

Path upload = Files.createTempFile("report-", ".prepej");
try {
    Files.write(upload, requestBody);
    PreviewJobIO.ReadResult loaded = new PreviewJobIO().read(upload);

    if (!loaded.selfContained()) {
        throw new IllegalArgumentException("自己完結PREPEJが必要です");
    }

    PreviewJob job = loaded.job();
    PreviewJob.Page first = job.pages.get(0);
    String svg = new SvgExporter().svg(
            first.definition, first.data, first.sourcePage);
} finally {
    Files.deleteIfExists(upload);
}

アップロードサイズ、ページ数、項目数を制限し、一時ファイルは必ず削除してください。PDF生成には同時実行数、処理時間、キャンセルの上限を設けることを推奨します。

7.4 アプリ側からプレビュアーを操作するRM026

帳票だけを業務画面に置き、PDFや検索は自分のアプリのボタンから操作したい場合に使うインターフェースです。ツールバーを隠しても、プレビュアーの機能は停止しません。 設定ボタンまで隠せるため、再表示用のボタンはプレビュアーの外側に置きます。

03「全帳票をWebでプレビュー」と公開デモは、この使い方の実例です。最初はプレビューだけを表示し、帳票選択の横の「ツールバーを表示」を押すとPDF・検索・設定などを表示します。もう一度押すと、設定ボタンとステータスも含めて非表示になります。

表示・非表示を切り替えるコード

以下は03サンプルのプレビュアーを読み込んだ後に置く、アプリ側のコードです。サンプルの native-previewer.js、native-previewer.css、画面の初期化部分を一緒に利用してください。03を編集する場合は、既存の同じボタン・切り替え処理を置き換え、二重に追加しないでください。

<!-- プレビュアーの外側に置くアプリ側のボタン -->
<button type="button" id="togglePreviewToolbar"
        aria-controls="nativePreviewer" aria-expanded="false">
  ツールバーを表示
</button>

// native-previewer.js の読み込み後に実行します。
const previewer = window.ReportsWebNative;
const button = document.getElementById("togglePreviewToolbar");

function updateButton() {
  const visible = previewer.getState().chrome.toolbar;
  button.textContent = visible
    ? "ツールバーを非表示" : "ツールバーを表示";
  button.setAttribute("aria-expanded", String(visible));
}

button.addEventListener("click", () => {
  if (previewer.getState().chrome.toolbar) previewer.hideAll();
  else previewer.showAll();
});
const unsubscribe = previewer.subscribe("chrome-changed", updateButton);

previewer.hideAll(); // 初期画面は帳票だけ
updateButton();
// アプリ側の画面を破棄する場合は unsubscribe() で購読を解除します。

03サンプルでは、プレビュアーを初期化する前の ReportsNativeConfig に externalChromeControl: true を指定しています。この設定では、内部設定から全非表示にした場合も、設定を戻すための小さなボタンをプレビュアー内に残しません。必ず上のような外部ボタンを用意してください。chrome-changed を購読すると、内部設定から切り替えた場合も外部ボタンの文字が追従します。

ツールバーがなくても、PDF・検索・ページ移動を使える

await previewer.showPdfPreview(); // サーバーへPDFを要求し、同じ表示領域へ表示
await previewer.showSvgPreview(); // 通常の印刷プレビューへ戻る
previewer.goToPage(2);            // ページ番号は1から
previewer.setZoom("auto");       // 表示領域に合わせた倍率
previewer.search("請求");         // 通常の印刷プレビュー内を検索

ここでの showSvgPreview() はAPI名であり、利用者に見せるボタン名は「印刷プレビュー」で構いません。PDF表示中の検索などはブラウザー内蔵PDFビューアーの機能と区別します。非表示のままPDF表示へ切り替えることもできます。プレビューを最初に開いただけではPDFを要求しません。

非表示の対象はReports.webの操作UIです。PDF表示中にブラウザー内蔵PDFビューアーが表示する独自のボタンは、このAPIの制御対象ではありません。

このインターフェースは、3つのNative Webサンプルで使うブラウザー側の ReportsWebNative です。サーバーの帳票エンジンのクラスや、デスクトップ用Windowとは別です。WASM版にも一括表示・非表示の機能がありますが、初期化方法やAPIの所属はWASM版のガイドを参照してください。

8. 実行の中止と進捗通知RM027

時間のかかるPDFや画像の生成には RenderControl を渡せます。

AtomicBoolean cancelled = new AtomicBoolean(false);

RenderControl control = new RenderControl(
        cancelled::get,
        progress -> System.out.printf("%.0f%%%n", progress * 100));

new PdfExporter().export(
        definition,
        data,
        Path.of("output", "large-report.pdf"),
        PdfExporter.Options.image(150),
        control);

中止条件が true になると CancellationException が送出されます。Webアプリケーションでは、クライアント切断やタイムアウトと連携できます。

9. 帳票定義を変換・保存するRM028

通常の帳票出力ではPREPDJを読み込むだけです。この章は、Javaで帳票定義自体を編集・変換する場合に使用します。

9.1 帳票定義を保存するRM029

ReportDefinitionIO definitionIO = new ReportDefinitionIO();
ReportDocument definition = definitionIO.read(Path.of("invoice.prepdj"));

definition.title = "請求書（社内控え）";
definitionIO.write(Path.of("invoice-copy.prepdj"), definition);

ReportDefinitionIO.write(...) は帳票定義の保存です。帳票項目へ印刷値を設定するメソッドではありません。値は ReportData.values と ReportData.rows に設定します。

9.2 読み込み時の診断を確認するRM030

従来形式の帳票定義には、Pure Javaモデルへ完全に対応付けられない設定が含まれる場合があります。移行確認では readWithDiagnostics(...) を使います。

ReportDefinitionIO.ReadResult result =
        new ReportDefinitionIO().readWithDiagnostics(
                Path.of("legacy-report.prepd"));

ReportDocument definition = result.document();

for (ReportDefinitionIO.ReadDiagnostic diagnostic : result.diagnostics()) {
    System.out.printf("%s %s: %s%n",
            diagnostic.code(), diagnostic.path(), diagnostic.message());
}

診断情報は「読み込みに失敗した」という意味ではありません。互換情報として保持した設定や、同じ見た目を保証できない設定を、移行担当者が確認するための情報です。新しく作成したPREPDJを通常利用する場合は read(...) で構いません。

9.3 JSON文字列として扱うRM031

ReportDefinitionIO definitionIO = new ReportDefinitionIO();

String json = definitionIO.toJson(definition);
ReportDocument restored = definitionIO.fromJson(json);

toJson(...) と fromJson(...) が扱うのは、帳票定義 ReportDocument です。印刷データやPREPEJではありません。

10. APIリファレンスRM032

ここからは、プログラム作成中にクラス、メソッド、プロパティを調べるためのリファレンスです。

10.1 ReportDefinitionIORM033

PREPD／PREPDJの読み書きを行います。

ReadResult のプロパティ：

ReadDiagnostic のプロパティ：

10.2 ReportDataRM034

帳票へ差し込む値を保持します。

10.3 ReportDataIORM035

帳票定義を含まない、値だけのデータを読み書きします。

10.4 PreviewJobIORM036

完成した印刷データであるPREPE／PREPEJを読み書きします。

ReadResult のプロパティ：

10.5 PreviewJobRM037

PreviewJob.Page：

10.6 PdfExporterRM038

PdfExporter.Options：

PdfExporter.Result：

10.7 SvgExporterRM039

10.8 ReportRendererRM040

RenderOptions：

10.9 PrinterOutputRM041

10.10 RenderControlRM042

11. 帳票モデルのプロパティRM043

通常はデザイナーでPREPDJを作成するため、Javaからこれらを直接設定する必要はありません。帳票定義を動的に変更する場合や、独自デザイナーを作る場合に参照してください。

11.1 ReportDocumentRM044

11.2 ReportObject 共通プロパティRM045

11.3 文字プロパティRM046

伸縮はtextElastic=trueで有効になります。しきい値と同じ長さでは通常表示し、超えた場合だけ伸縮します。文字数はUTF-16の単位数、バイト数は従来のReports.NETに合わせたCP932で数えます。文字数とバイト数は選択して使い、デザイナーでは一方を設定すると他方を解除します。通常の伸縮は縦横を枠に合わせ、高さ固定では指定フォントの高さを保ったまま横方向を合わせます。

11.4 線・図形・塗りのプロパティRM047

11.5 画像プロパティRM048

Webサーバーでは、外部入力をそのまま imagePath として使用しないでください。アプリケーションが管理するファイルまたは検証済みの埋め込み画像に限定します。

11.6 バーコードプロパティRM049

11.7 特定ページ・行・項目だけを変更するRM050

ReportPageBuilderは、帳票定義をコピーし、1ページ分の繰返しを展開してから、指定した項目の属性を変更するためのクラスです。フォント専用ではなく、文字色、位置、罫線、表示・非表示など、通常のReportObject属性を変更できます。

var pages = new java.util.ArrayList<ReportDocument>();
for (int pageNumber = 1; pageNumber <= 3; pageNumber++) {
    var builder = new ReportPageBuilder(definition);
    if (pageNumber == 2) {
        // オブジェクト名が「金額」の5行目だけを変更します。行番号は0始まりです。
        var target = builder.object("金額", 4);
        target.fontSizePt = 12;
        target.fontUnit = "Point";
        target.textColor = "#0000FF";
    }
    pages.add(builder.build());
}

ReportPageBuilderとReportDocumentはcom.pao.reports.engine.modelにあります。この例では、definitionに「金額」という名前の項目があり、1ページ内で5行以上繰り返す設定になっているものとします。build()したページは独立したコピーです。後からBuilderを変更しても、元の定義、生成済みのページ、別ページには反映されません。

名前の重複、存在しない項目、範囲外の行・列はエラーになります。XY繰返しにはcell()を使用してください。生成した各ページはPdfExporter.Pageに渡し、exportPages()で1つのPDFにまとめられます。

12. フォント、性能、安全性RM051

フォントRM052

帳票で指定したフォントが実行環境にない場合は代替フォントが使われ、文字幅や改行位置が変わることがあります。開発PCだけでなく、本番サーバーにも使用フォントを配置して確認してください。

ＭＳ ゴシックがない環境での動作

ＭＳ ゴシック（MS Gothic、MS-Gothic）を指定した場合は、指定フォントを優先します。使えない場合は既存の等幅代替フォントを順に探し、それも使えない場合に、Javaエンジンに同梱した BIZ UDゴシック（比例幅のBIZ UDPゴシックではありません）を使用します。利用者による追加インストールやインターネットからの取得は不要です。WindowsでＭＳ ゴシックが使える場合は、従来どおりＭＳ ゴシックを使用します。

この代替はＭＳ ゴシック系の指定に限ります。ＭＳ Ｐゴシック・明朝体・未知のフォントに一律適用するものではなく、同梱フォントにない文字には従来の字形代替処理を使用します。標準・太字には同梱の各書体を使い、斜体はJavaの合成表示です。元のＭＳ ゴシックと字形・文字幅が完全に同一とは限らないため、使用する帳票のプレビューとPDFを確認してください。

同梱フォントとPDFへの埋込みは別です。 フォントがエンジンに同梱されていても、PDFへ自動的に埋め込まれるわけではありません。画像PDFの本文は画像です。ベクターPDFでは、フォントファイルを指定しない場合は文字を輪郭として描画し、その文字は検索・抽出できません。同梱BIZ UDゴシックが選択されている場合に、同じ公式TTFのパスをOptions.vector(dpi, fontFiles)へ明示すると、条件を満たす標準・太字を埋め込めます。合成斜体などは輪郭での出力になります。BIZのTTFを渡すだけで、使用中のＭＳ ゴシックがBIZに切り替わることはありません。

同梱の公式BIZ UDゴシックはSIL Open Font License 1.1による配布です。ライセンス全文と取得元はengine JAR内のcom/pao/reports/engine/fonts/biz-ud-gothic/OFL.txtとprovenance.jsonに収録しています。

ベクターPDFへフォントを埋め込む場合は、フォントのライセンスと再配布条件も確認してください。エンジンがインターネットからフォントを取得することはありません。

性能RM053

• 帳票定義は毎回読み直さず、変更されない間は安全にキャッシュできます。
• ReportData はリクエストや処理ごとに新しく作成してください。
• 大量ページは renderPages(...) で一括画像化せず、renderPage(...) で順次処理してください。
• WebサーバーではPDF生成の同時実行数、最大ページ数、処理時間を制限してください。
• 不要になった BufferedImage は flush() してください。

安全性RM054

• PREPDJ、PREPEJ、画像のファイルサイズと内容を入力時に検証してください。
• 外部入力から任意のローカルパスやURLを参照させないでください。
• 出力先はアプリケーション管理下のディレクトリに限定してください。
• 一時ファイルは finally またはtry-with-resources相当の管理で削除してください。
• 公開REST APIには認証、認可、レート制限を適用してください。

13. エラー処理の基本RM055

try {
    ReportDocument definition =
            new ReportDefinitionIO().read(definitionPath);
    new PdfExporter().export(definition, data, outputPath);
} catch (NoSuchFileException ex) {
    // 帳票定義が見つからない
} catch (CancellationException ex) {
    // 利用者またはタイムアウトにより中止された
} catch (IOException ex) {
    // PREPDJの解析、画像読込、PDF保存などに失敗した
} catch (IllegalArgumentException ex) {
    // ページ番号、DPI、帳票モデルなどの指定が不正
}

利用者向けのエラーメッセージと、調査用の例外・ログは分けてください。Web APIでは内部例外をそのままレスポンスへ返さず、要求IDとともにサーバーログへ記録します。

14. 目的別の早見表RM056

15. 付属サンプルを実行するRM057

ZIPを全体ごと展開し、Native/Pure-Java/samples/README.html を開いてください。開発者の作業フォルダーや、本製品全体のソースビルド環境は不要です。

使いたい番号フォルダーをエディターやIDEで開き、その中のREADMEの手順で起動します。READMEには、必要なJava環境、実行コマンド、読むソース、変更する箇所、停止方法をまとめています。Java 21を基準に、同梱SDKと同じ版のサンプルを使ってください。

03のWebアプリと04のRESTサーバーは、直接起動する方法に加えてDockerからの起動も選べます。04のデスクトップ画面はDockerに入れず、PC側で直接起動します。画面のURLとAPIのパスは、各サンプルのREADMEにあるものを使ってください。

最初は01のタイトルや会社名を書き換えて、帳票へ反映されることを確認してください。次に02以降へ進むと、同じ基本を明細帳票やWeb連携へ広げられます。

16. Reports.NET互換セッションAPIRM058

com.pao.reports.engine.ReportSession は、定義体を順に読み込み、ページを確定し、旧 Reports.net と交換可能な印刷データを保存する公開 API です。

• loadDefFile(InputStream, definitionName) は呼出し側のストリームを閉じません。definitionName は定義体の識別名として保持されます。
• getDefFileName(page) は旧 API の 1 始まりの挙動を維持します。ページ確定後はページ番号にかかわらず最初の定義体名を返します。物理ページ固有の名前には getPageDefinitionName(page) を使用します。
• saveData() / loadData(byte[]) は gzip や ZIP コンテナではなく、旧 ZipUtil と同じ zlib/DEFLATE 内の PrintData/Page/PrintDefine/Value XML を交換します。画像、XY 繰返し、DynamicAttrs、Drawing、literal null も保持します。既定の展開上限は 256 MiB です。正当な大容量データだけ loadData(bytes, maxExpandedBytes) で明示的に正の上限を指定してください。失敗時は既存ページを置換しません。
• CutByPage の既定値は false です。true は物理ページごとに別印刷ジョブを送る指定で、用紙レイアウトやカッター命令を変更しません。選択範囲は元文書の 1 始まりです。分割ジョブでは再採番により PageRanges だけを除き、部数、丁合い、用紙、両面などを保持します。離散した範囲は明示的に拒否します。
• SwapPdfImage の既定値は false です。true は画像 PDF とベクター PDF の PDFBox ストリームを一時ファイル専用キャッシュへ退避します。現在処理中のページ画像までゼロメモリにする機能ではありません。出力方式や DPI は切り替えません。

SaveXPS は Pure Java API の対象外です。ブラウザー版の CutByPage / SwapPdfImage と、サーバー版の画像スワップ指定は別の実行能力であり、言語別 PREPEJ builder の能力ではありません。

ページ単位の印刷：CutByPageRM059

レシート・ラベルプリンターで、ジョブ終了時のカットをページごとに行いたい場合に使います。Javaでは session.setCutByPage(true) で設定し、session.isCutByPage() で取得します。ReportSession.submitPrint(...) による印刷ジョブ作成に適用され、PDFの改ページや帳票寸法は変更しません。

false は選択したページをまとめて1ジョブ、true はページごとに別ジョブにします。実際に用紙をカットするには、プリンターとドライバー側のジョブ終端カット設定が必要です。カッターを持たないプリンターにカット機能を追加するものではありません。

画像の多いPDF：SwapPdfImageRM060

大きな画像を多数のページに配置する場合、PDF内部で保持する画像データが増えます。session.setSwapPdfImage(true) をPDF出力前に指定すると、一時ディスクを使って保持メモリーを抑えます。取得は session.isSwapPdfImage()、出力は session.savePdf(path, control) です。このセッションの出力は画像PDFです。

直接 PdfExporter を使う場合は、画像PDFに PdfExporter.Options.imageWithDiskSpill(dpi)、ベクターPDFに PdfExporter.Options.vectorWithDiskSpill(dpi, fontFiles) を指定します。退避の有無だけを比較する場合は、出力方式・DPI・フォントを同じにしてください。

一時領域への書込み権限と空き容量が必要です。入力画像や現在処理中の画像のメモリーまで不要になるわけではなく、必ず一定量に収まる保証はありません。一時データは通常終了・例外・取消時に閉じて削除しますが、プロセスの強制終了や電源断はこの後処理の保証外です。退避によってディスクI/Oが増えるため、通常の小さな帳票では既定の false を使用できます。

17. ライセンスRM061

本製品は商用ライセンスです。評価、開発環境、サーバー配置、再配布、組み込み利用の条件は、製品に付属するライセンス文書を確認してください。