Docurain Labo

Docurainサービス開発日記

TomcatをVirtualThreadで動作させる

前回の投稿から大分空いてしまいました、、、

本日は技術的なトピックを投稿してみます。

Java19になって仮想スレッド(かつてグリーンスレッドと呼ばれていたもの)が使えるようになりました。とはいえまだExperimentalですが。 JVMの起動パラメータに --enable-preview と付ければ関連APIを実行できるようになります。

(※23-01-10追記) グリーンスレッドとvirtual threadは大きく異なるものでした。 M:Nモデルというモデルです。詳しくはこちら。 https://stackoverflow.com/questions/74639116/what-is-the-difference-between-green-threads-and-virtual-threads

そこで、Tomcatを仮想スレッドで動作させられないか調べてみたら案外簡単に動きました。

まず、このようなクラスを用意します。

package jp.docurain.tomcat;

import java.util.concurrent.Executors;

import org.apache.catalina.LifecycleException;
import org.apache.catalina.LifecycleState;
import org.apache.catalina.util.LifecycleMBeanBase;

public final class VirtualThreadExecutor
    extends LifecycleMBeanBase
    implements org.apache.catalina.Executor {

    private java.util.concurrent.Executor es;

    private String name = "tomcat-vt";

    private String namePrefix = "tomcat-vt-";

    public void setName(final String x) { this.name = x; }

    @Override
    public String getName() { return this.name; }

    public void setNamePrefix(final String x) { this.namePrefix = x; }

    public String getNamePrefix() { return this.namePrefix; }

    @Override
    public void execute(final Runnable command) { this.es.execute(command); }

    @Override
    protected String getDomainInternal() { return null; }

    @Override
    protected String getObjectNameKeyProperties() { return "type=Executor,name=" + this.getName(); }

    @Override
    protected void startInternal() throws LifecycleException {
        this.es = Executors.newThreadPerTaskExecutor(Thread.ofVirtual().name(this.namePrefix, 0).factory());
        this.setState(LifecycleState.STARTING);
    }

    @Override
    protected void stopInternal() throws LifecycleException {
        this.setState(LifecycleState.STOPPING);
    }
}

次に、このクラスをコンパイルしてjarにして、Tomcatのインストールディレクトリのlibへ放り込みます。

つぎにserver.xmlを以下のようにするだけ。簡単ですね。

<Server port="8005" shutdown="SHUTDOWN">

  ...(略)

  <Service name="Catalina">

    <!-- 上記でコンパイルしたクラス -->
    <Executor name="vthread" className="jp.docurain.tomcat.VirtualThreadExecutor" />

    <!-- Executorのnameをexecutorへ指定 -->
    <Connector executor="vthread" port="8080" protocol="HTTP/1.1"
               connectionTimeout="20000"
               redirectPort="8443" />

  </Service>

  ...(略)

</Server>

で、起動して何かリクエストを投げてみると、これまでは

2022-11-27 16:47:32,099 INFO  [...] http-nio-8080-exec-1 何かのログ

のようなログだったのが、

2022-11-27 16:47:32,099 INFO  [...] tomcat-vt-1 何かのログ

のように変わっています。 起動中のスレッドを見てみても、TomcatのNioコネクター関連のスレッドが一つもありません。というわけで成功したようです。

実際に商用利用可能なレベルなのか、引き続き調査してみます。本日はここまで。

明細行を出力する際に利用する配列操作関数について

帳票はヘッダー、明細そしてフッターで構成されています。ヘッダーやフッターは各帳票で一度しか出力しないので簡単ですが、明細行は次のような機能が必要でしょう。

  1. 明細データから指定した行数分のデータを取り出す
  2. 明細データを指定した行数ごとに分割する

この記事では帳票を作る際に必要な配列操作について解説します。

今回利用するデータについて

今回利用するデータは次のような内容であることとします。

{
    "items": [
        {"name": "商品1", "price": 100, "unit": 10},
        {"name": "商品2", "price": 200, "unit": 20},
        {"name": "商品3", "price": 300, "unit": 30},
        {"name": "商品4", "price": 400, "unit": 40},
        {"name": "商品5", "price": 500, "unit": 50},
        {"name": "商品6", "price": 600, "unit": 60},
        {"name": "商品7", "price": 700, "unit": 70},
        {"name": "商品8", "price": 800, "unit": 80},
        {"name": "商品9", "price": 900, "unit": 90},
        {"name": "商品10", "price": 1000, "unit": 100},
        {"name": "商品11", "price": 1100, "unit": 110},
        {"name": "商品12", "price": 1200, "unit": 120},
        {"name": "商品13", "price": 1300, "unit": 130},
        {"name": "商品14", "price": 1400, "unit": 140}
    ]
}

この items キーが明細データになります。

1ページ4明細の帳票の場合

今回のデータは明細が14件ありますので、1ページ4明細の場合は次のような帳票になります。

  • 全4ページ
  • 4ページ目が2件

こうした帳票を作る場合は、まず items キーの内容を次のように分割すれば良さそうです。

[
    [
            {"name": "商品1", "price": 100, "unit": 10},
            {"name": "商品2", "price": 200, "unit": 20},
            {"name": "商品3", "price": 300, "unit": 30},
            {"name": "商品4", "price": 400, "unit": 40}
    ],
    [
            {"name": "商品5", "price": 500, "unit": 50},
            {"name": "商品6", "price": 600, "unit": 60},
            {"name": "商品7", "price": 700, "unit": 70},
            {"name": "商品8", "price": 800, "unit": 80}
    ],
    [
            {"name": "商品9", "price": 900, "unit": 90},
            {"name": "商品10", "price": 1000, "unit": 100},
            {"name": "商品11", "price": 1100, "unit": 110},
            {"name": "商品12", "price": 1200, "unit": 120}
    ],
    [
            {"name": "商品13", "price": 1300, "unit": 130},
            {"name": "商品14", "price": 1400, "unit": 140}
    ]
]

このようにデータを分割するメソッドが chunk です。次のように実行します。

#set($pages = $ROOT.items.chunk(4))

この chunk メソッドは指定したデータ件数(今回は4)ごとにデータを分割して、配列にします。つまり $pages の内容は次のようになります。

[
    [
            {"name": "商品1", "price": 100, "unit": 10},
            {"name": "商品2", "price": 200, "unit": 20},
            {"name": "商品3", "price": 300, "unit": 30},
            {"name": "商品4", "price": 400, "unit": 40}
    ],
    [
            {"name": "商品5", "price": 500, "unit": 50},
            {"name": "商品6", "price": 600, "unit": 60},
            {"name": "商品7", "price": 700, "unit": 70},
            {"name": "商品8", "price": 800, "unit": 80}
    ],
    [
            {"name": "商品9", "price": 900, "unit": 90},
            {"name": "商品10", "price": 1000, "unit": 100},
            {"name": "商品11", "price": 1100, "unit": 110},
            {"name": "商品12", "price": 1200, "unit": 120}
    ],
    [
            {"name": "商品13", "price": 1300, "unit": 130},
            {"name": "商品14", "price": 1400, "unit": 140}
    ]
]

後はこの pages ごとにループ処理をすれば、ページごとの明細を出力できます。

#for ($page in $pages)  ## ページ単位のループ
  #for ($item in $page) ## 明細ごとのループ
    #end
#end

1ページ目が4件の明細、2ページ目以降は6件という帳票の場合

次は1ページ目を4件、2ページ目以降は6件の場合は、次のような帳票になります。明細データは先ほどと同じく14件とします。

  • 全3ページ
  • 1ページ目は4件、2ページ目は6件、3ページ目は4件

1ページ目用のデータを取得する

まず items キーの中から4件のデータを取得します。この時には take を使います。

#set($firstPage = $ROOT.items.take(4))

この時、$firstPage は次のような内容になっています。

[
        {"name": "商品1", "price": 100, "unit": 10},
        {"name": "商品2", "price": 200, "unit": 20},
        {"name": "商品3", "price": 300, "unit": 30},
        {"name": "商品4", "price": 400, "unit": 40}
]

1ページ目のテンプレートを作り、そのまま出力を行います。

2ページ目以降のデータを取得する

次に2ページ目以降、データを6件ずつに分割します。この時に使うのが drop です。 drop は指定した数字(今回は4)分、データをスキップします。そして残りのデータについて chunk で6件ずつに分割します。

#set($pages = $ROOT.items.drop(4).chunk(6))

この時の $pages の内容は次のようになります。

[
    [
            {"name": "商品5", "price": 500, "unit": 50},
            {"name": "商品6", "price": 600, "unit": 60},
            {"name": "商品7", "price": 700, "unit": 70},
            {"name": "商品8", "price": 800, "unit": 80},
            {"name": "商品9", "price": 900, "unit": 90},
            {"name": "商品10", "price": 1000, "unit": 100},
 ],
    [
            {"name": "商品11", "price": 1100, "unit": 110},
            {"name": "商品12", "price": 1200, "unit": 120},
            {"name": "商品13", "price": 1300, "unit": 130},
            {"name": "商品14", "price": 1400, "unit": 140}
    ]
]

2ページ目以降のテンプレートを作り、出力します。

最後のページだけ出力内容が異なる場合

帳票において、最後のページだけ出力内容が異なるケースは良くあります。たとえば集計行の出力です。ループ処理の中で最後のページかどうか判別する際には $foreach.last を使います。

#for ($page in $pages)  ## ページ単位のループ
  #for ($item in $page) ## 明細ごとのループ
    #end
  #if ($foreach.last) ## 最後のページの場合
      ## 集計行の表示など
    #end
#end

$foreach.last を含め、次のようなデータがあります。

データ 意味
$foreach.first 真偽値 ループの先頭ならtrue
$foreach.last 真偽値 ループの最後ならtrue
$foreach.count 数値 ループの回数(1..)
$foreach.index 数値 ループのインデックス(0..)

なお、印刷範囲を3つにすることで「最初のページ」「2ページ目以降のページ」「最後のページ」に分けて印刷範囲を作成することもできます。この時、明細データの取得方法は次のようになります。 firstNum は最初のページの明細件数、 num は2ページ目以降の明細件数です。

  • 最初のページ
    #set($page = $e.items.take(firstNum))
  • 2ページ目以降のページ(最後のページを除く)
    #set($pages = $e.items.drop(firstNum).chunk(num).slice(0, -1))
  • 最後のページ
    #set($page = $e.items.drop(firstNum).chunk(num).slice(-1)[0])

この3つのパターンを使うことで、 $foreach を使わない形でも帳票を作成できます。

デバッグ

もし明細の内容がどのようになっているか気になった場合には B列 以降の列で %{page} のように指定した上で帳票出力してください。データの内容がダンプされるので、どういった項目があるのか確認できます。

まとめ

帳票で明細行を出力する処理は改ページにも繋がるので、処理が複雑になります。頭の中で出力結果を考えながら記述するのは難しいですが、慣れてしまえばすぐできるようになるでしょう。ぜひトライしてください。

Docurainを使って帳票作りにチャレンジ(その2:明細行、フッターの記述法)

DocurainはWeb APIを使って簡単に納品書や請求書をはじめとする、帳票を生成するサービスになります。今回はこのDocurainの使い方について、帳票を一から作成してみます。

前回は帳票のヘッダーについて解説しましたので、今回は注文などの繰り返し部分(明細行)やフッターの書き方を解説します。

テーブル定義を解除する

今回参照した帳票では、注文一覧部分がテーブルとして定義されています。Docurainではテーブル定義は利用できませんので、テーブル部分の適当なセルを選択した状態で、テーブルデザインの中にある 範囲に変換 を選びます。

f:id:moongift:20210719183614p:plain

確認ダイアログが出たら、そのまま はい を選択してください。

ロジック記述を追加する

今回の注文データは複数(可変)定義できることとします。つまり、データは次のように定義されていることとします。今回は3件ですが、4件や5件でも問題ありません。

"orders": [
  {
    "num": 100,
    "no": 1001,
    "unit": 100,
    "info": "ボールペン",
    "discount": 0
  },
  {
    "num": 300,
    "no": 1002,
    "unit": 200,
    "info": "カードケース",
    "discount": 5000
  },
  {
    "num": 200,
    "no": 1003,
    "unit": 100,
    "info": "付箋紙",
    "discount": 6000
  }
],

そこで、まず帳票のテーブル部分の1行目にあたる部分のA列(ロジック記述用の列)に、次のように記述します。

#foreach($o in $e.orders)

これは、JSON内の orders を繰り返し処理するという命令になります。そして3行目には次のように記述します。

#end

これは繰り返し処理部分の終わりを指定しています。つまり #foreach から #end で囲まれた行の処理を繰り返すという意味になります。実際の記述内容は次の通りです。

f:id:moongift:20210719183649p:plain

繰り返し行部分の記述

繰り返し処理で $o と記述しています。繰り返し処理時には、この $o の中に注文データが繰り返し入ってきます。つまり最初の $o の内容は次のようになります。

{
  "num": 100,
  "no": 1001,
  "unit": 100,
  "info": "ボールペン",
  "discount": 0
}

これに従って、明細行の内容を記述していきます。今回は次のようになります。

f:id:moongift:20210719183707p:plain

データがない場合について

たとえば備考など、必ずしもデータがない場合もあるでしょう。そうした時には $!{o.info} のように ! を付けておきます。こうすることで、データが場合には空白になります。

繰り返し行内での計算処理について

通常のExcelではセルの値を参照した計算処理は =A5*E5 のように書きます。しかし、繰り返し処理部分では行番号が変わってしまいます。そこで、Docurainでは %= という行頭記号を使います。今回の小計計算は次のように記述します。

%= $o.unit * $o.num - $o.discount

%= を記述しておくことで、テンプレートとして処理されます。つまり1行目の場合には %= $o.unit * $o.num - $o.discount=100*100-0 と変換されます。これで正しく計算処理されるようになります。

フッターの処理について

帳票のフッターでは合計金額を出すことが多いでしょう。合計金額は明細行の集計結果になりますので、セルが可変の場合に書くのが困難です。そこでDocurainではセルに名前を定義して対応します。今回は割引の合計金額を例に紹介します。

まず、割引金額(上下のセルを含めて)を範囲選択します。

f:id:moongift:20210719183741p:plain

そして、その範囲に名前を付けます。今回は 値引き としています。

f:id:moongift:20210719183751p:plain

今は3行が名前の範囲ですが、繰り返し処理が行われると自動的に拡張されます。そこで、割引合計のセルは =SUM(値引き) とすることで、集計された金額が入力されるようになります。小計も同様です。

f:id:moongift:20210719183802p:plain

消費税や集計金額についても同じように明細行を使うこともできますが、小計セルの名前を 小計 などと名前を付けて、そのセルを対象として =小計*1.1 とした方が分かりやすいでしょう。

f:id:moongift:20210719183812p:plain

後は、他にも置き換えられる文字列をJSONで定義し、置き換え文字列として定義すれば完成です。

f:id:moongift:20210719183825p:plain

今回のJSONデータは次のようになりました。

{
  "company": {
    "name": "ルート42株式会社",
    "message": "クラウド帳票開発のドキュレイン"
  },
  "customer": {
    "name": "ドキュメント 太郎",
    "company": "帳票株式会社",
    "address1": "〒110-0012 東京都台東区",
    "address2": "竜泉1-10-6 秋田屋ビル2F",
    "tel": "03-000-0000"
  },
  "billing": {
    "no": "100010",
    "date": "2021-07-19"
  },
  "orders": [
    {
      "num": 100,
      "no": 1001,
      "unit": 100,
      "info": "ボールペン",
      "discount": 0
    },
    {
      "num": 300,
      "no": 1002,
      "unit": 200,
      "info": "カードケース",
      "discount": 5000
    },
    {
      "num": 200,
      "no": 1003,
      "unit": 100,
      "info": "付箋紙",
      "discount": 6000
    }
  ],
  "charge": {
    "name": "ルート 花子",
    "tel": "03-111-1111",
    "email": "info@docurain.jp"
  }
}

実行する

今回もコマンドラインで実行します。OSによってコマンドが多少変わるので注意してください。 YOUR_TOKEN はDocurainのトークン | Docurainにて取得できるトークンになります。

Windowsの場合

Windowsではコマンドプロンプトを利用してください。テンプレートのXLSXファイル、上記JSONデータファイルがあるフォルダ内でコマンドを実行します。

curl -X POST https://api.docurain.jp/api/instant/pdf ^
     -H "Authorization:token YOUR_TOKEN" ^
     -H "Content-Type:multipart/form-data" ^
     -F "template=@./receipt.xlsx;type=application/vnd.ms-excel" ^
     -F "entity=@./data.json;type=application/json" ^
     -o receipt.pdf

macOS/Linuxの場合

macOSやLixuxはターミナルを利用してください。Windowsと同じく、テンプレートのXLSXファイル、上記JSONデータファイルがあるフォルダ内でコマンドを実行します。

curl -X POST https://api.docurain.jp/api/instant/pdf  \
     -H "Authorization:token YOUR_TOKEN" \
     -H "Content-Type:multipart/form-data" \
     -F "template=@./receipt.xlsx;type=application/vnd.ms-excel" \
     -F "entity=@./data.json;type=application/json" \
     -o receipt.pdf

これで明細行含め、正しくPDFが得られるか確認してください。

f:id:moongift:20210719183848p:plain

まとめ

今回は新しい帳票ファイルを使って、Docurainのテンプレートにしていく過程を紹介しました。コマンドや表示方法は他にも多数ありますので、Excelテンプレート リファレンス | Docurainを参照してください。

マクロを使って帳票のメンテナンス性を高めましょう

マクロを使って帳票のメンテナンス性を高めましょう!

帳票では細かなカスタマイズが不定期に求められるので、メンテナンス性高い状態に維持するのが大事なポイントになります。そのためにできることは幾つかありますが、一つはコピー&ペーストで場当たり的な対応をしないことです。

例えば自社の情報やヘッダー情報、フッターに記載した連絡先に関する情報などを全ての帳票に直書きしていると、いざその情報が変わった時に変更漏れが発生したり、幾つも修正する手間が発生します。かといって、それをシステム側から出力するのも面倒でしょう。

そこで使って欲しいのがDocurainのマクロ機能です。共通処理を部品化し、再利用性を高めます。

続きを読む

明細行を集計して合計金額を算出する方法を理解する

帳票はヘッダーとフッター、そして明細行の組み合わせで作成されます。それぞれ、次のような区別があるでしょう。

  • ヘッダー
    帳票の上の部分に掲載される情報。全ページまたは最初のページだけに表示される。
  • フッター
    帳票の下の部分に掲載される情報。全ページまたは最後のページだけに表示される。
  • 明細
    購入した商品情報など、帳票の中で動的に繰り返される情報。帳票によって数が異なる。

この時、多くの帳票では明細行に記載された金額を集計して、ヘッダーやフッターに表示します。明細行は帳票によって行数が異なるので、増減に合わせて計算範囲が変わります。さらに言えば、帳票が単ページ、または複数ページによっても変わります。

今回はDocurainにおける明細行の集計方法をいくつかのパターンに分けて紹介します。

帳票について

今回は分かりやすくするためにヘッダー、フッターに数字以外の情報は載せていません。

f:id:moongift:20211222184153p:plain

データについて

データは次のようなJSONです。明細ごとに単価、数量が記載されています。項目数は可変です。

{
  "items" :  [
    {
      "note":  "商品1",
      "unit": 100,
      "amount": 5
    },
    {
      "note":  "商品2",
      "unit": 500,
      "amount": 3
    },
    {
      "note":  "商品3",
      "unit": 1500,
      "amount": 10
    },
  :
  ]
}

1ページの場合

f:id:moongift:20211222183350p:plain

帳票が必ず1ページの場合 #EASY_SHIFT_FORMULA を指定するのが最も簡単です。A1セルで次のように記述します。

#EASY_SHIFT_FORMULA
#set($e = $ROOT) ## 変数用

#EASY_SHIFT_FORMULA を記述しておけば、数式の簡易自動シフトモードになり、自動で計算範囲を調整してくれるようになります。そして、明細部分を次のように記述します。

A B C D E
10 詳細 単価 数量 金額
11 #foreach($line in $e.items)
12 ${line.note} ${line.unit} ${line.amount} =D12*E12
13 #end

さらにフッター部分の集計では次のように記述します。10%はExcelのパーセント表示を使っていますので、実際には0.1になります。

A B C
14 小計 =SUM(E12:E12)
15 税率 10%
16 集計 =C14 + C14*F15

この状態で帳票を作成すると、明細部分では行ごとにD12(またはE)がD13やD14に自動的にシフトします。これが簡易自動シフトモードです。フッターについても =SUM(F12:F12)=SUM(F10:F12) へ自動的に変更されます(明細が3つの場合)。もちろん、最後の計算についても =F13+F13*F14 となり、正しい計算結果が得られます。

f:id:moongift:20211222183650p:plain

複数ページの場合

複数ページの帳票(改ページがある帳票)を作成する場合には数式の簡易自動シフトモードは利用できません。範囲がページをまたぐので、どの範囲をシフトすれば良いのか自動では定義できないからです。そこで利用するのがスコープになります。

スコープの使い方

スコープはまず #scope("全て")#end の形で定義します。"全て" は自分で定義したものを利用できます。このスコープで区切られた範囲について、数式がシフトしたり、集計を行えるようになります。スコープは複数用いてネストさせられます。

帳票の作り方

では帳票を作ってみましょう。今回は1ページあたり10明細とします。そこでデータを10明細ごとに分割します。

#set($e = $ROOT)
#set($pages = $e.items.chunk(10))

例えば items が5行分のデータを持っていたとして、chunk(3) と指定すると、 $pages は次のようなデータになります。

[
    {
        items: [
        {"note":  "商品1", "unit": 100, "amount": 5},
        {"note":  "商品2", "unit": 200, "amount": 3},
        {"note":  "商品3", "unit": 300, "amount": 1}
        ]
    },
    {
        items: [
        {"note":  "商品4", "unit": 400, "amount": 5},
        {"note":  "商品5", "unit": 500, "amount": 3}
        ]
    }
]

そして、この $pages を繰り返し処理しますが、この時、全体に対してscopeを定義します。

#scope("全て")
  #foreach($page in $pages)
      : 省略
    #end
#end

そして、明細行を記述します。単ページの場合は $e.items でしたが、今度は $pages ごとに処理します。

A B C D E
14 詳細 単価 数量 金額
15 #foreach($line in $page)
16 ${line.note} ${line.unit} ${line.amount} =D16*E16
17 #end

フッター行では DR.SHIFT_FORMULA を使います。これはDocurain独自の仕組みで、スコープに合わせた計算式のシフトを行うための記述です。この時のスコープとして、先ほど定義した名前を指定します。

A B C
18 小計 =DR.SHIFT_FORMULA(SUM(E16),"scope=全て, target=all")
19 税率 10%
20 集計 =C19+C19*C20

targetall または nearest を指定します。 nearest はスコープ内の最近傍範囲になります。デフォルトは nearest です。

f:id:moongift:20211222183821p:plain

生成される帳票

明細は単ページの時と同じく計算されます。そして、フッターでは次のように変換が行われます(一例です)。

=SUM(F10:F19,F28:F33)

f:id:moongift:20211222183849p:plain

ページごとの計算対象範囲を自動的に判別し、SUM関数に複数の範囲を指定してくれます。これによって正しい集計結果が得られます。

ページごとの集計を出したい場合

帳票全体の集計もありつつ、ページ単位でも小計を出したい場合はスコープを複数定義します。スコープ名はページごとにユニークなものになっていなければならないので、#scope("ページ-$foreach.count") のように変数を使って定義します。

A B C D E
13 詳細 単価 数量 金額
14 #scope("ページ-$foreach.count")
15 #foreach($line in $page)
16 ${line.note} ${line.unit} ${line.amount} =D16*E16
17 #end
18 #end

そしてページ計を下に記述します。この時もスコープの範囲について、変数を用いて指定します。

A B C
19 ページ計 =DR.SHIFT_FORMULA(SUM(E16),"scope=ページ-$foreach.count, target=all")

このようにスコープを2つ使うことで、ページ内での集計と帳票全体での集計を同時に行えます。

f:id:moongift:20211222183943p:plain

まとめ

単ページの場合は数式の簡易自動シフトモードで解決できるでしょう。複数ページの場合にはスコープとDR.SHIFT_FORMULAを利用してください。スコープを使いこなせば、複雑な帳票も作成できるようになるでしょう。