Skip to content

README.md

Latest commit

 

History

History
347 lines (254 loc) · 14.4 KB

README.md

File metadata and controls

347 lines (254 loc) · 14.4 KB
Raw

CTI Java版

バージョン 2.3.2

Javaを使ってCopper PDFにアクセスするためのプログラムです。 Copper PDF 2.1.0以降が必要です。 使用方法は付属のAPIドキュメント、サンプルプログラム、以下のオンラインマニュアルを参照してください。 http://dl.cssj.jp/docs/copper/3.2/html/3420_ctip2_java.html

API ドキュメント

ソースコードはGitHubで公開しています。 https://github.com/zamasoftnet/cti.java

関連ライブラリのソースコードは以下のリポジトリで公開しています。

インストール

Maven / Gradle（JitPack 経由）

JitPack リポジトリを追加した上で、com.github.zamasoftnet:cti.java:v2.3.2 を利用してください。

Gradle

repositories {
    mavenCentral()
    maven { url 'https://jitpack.io' }
}

dependencies {
    implementation 'com.github.zamasoftnet:cti.java:v2.3.2'
}

Maven

<repositories>
  <repository>
    <id>jitpack.io</id>
    <url>https://jitpack.io</url>
  </repository>
</repositories>

<dependency>
  <groupId>com.github.zamasoftnet</groupId>
  <artifactId>cti.java</artifactId>
  <version>v2.3.2</version>
</dependency>

GitHub Releases のアーカイブを使う方法

ビルド済みアーカイブは GitHub Releases から取得できます。

アーカイブにはドライバ本体の JAR、Javadoc、サンプル、コマンドラインツールが含まれます。展開後、そのまま cti-driver-*.jar をアプリケーションの classpath に追加して利用できます。

付属物

  • cti-driver-2.3.2.jar -- ドライバ本体（CTIP, REST, CLIが利用可能）
  • cti-driver-min-2.3.2.jar -- 最小構成のドライバ（REST, CLIは利用不可）
  • apidoc -- APIドキュメント(Javadoc)
  • lib -- サンプルのコンパイルに必要なライブラリ
  • examples -- サンプルプログラム
  • compile-examples.sh -- サンプルプログラムをコンパイルするスクリプト(Linux)
  • compile-examples.bat -- サンプルプログラムをコンパイルするスクリプト(Windows)
  • copper -- コマンドラインcopperプログラム(Linux)
  • copper.bat -- コマンドラインcopperプログラム(Windows)

コマンドラインプログラムについて

copper, copper.batについては、以下のドキュメントを参照して下さい。 http://dl.cssj.jp/docs/copper/3.2/html/2100_tools.html#admin-copper

複数の結果が相互参照する出力では、-outではなく-outdirを使います。 各結果に付いた相対URIを保ったまま、安全にディレクトリへ保存します。

copper -s ctip://localhost:8099/ -in book.epub \
  -if application/epub+zip \
  -p output.type=application/vnd.copper.paged-svg \
  -outdir book-pages

出力先は存在しないディレクトリ、または空のディレクトリを指定してください。 Paged SVGではmanifest.json、pages/、assets/fonts/、assets/images/が 生成されます。

TLS（ctips: と https:）

4.0.0 から、サーバー証明書を検証するのが既定です。

それ以前は検証しないのが既定で、しかも設定の名前が意味と反転していました （jp.cssj.driver.tls.trust の既定が true で、その true は「何でも通す」 という意味でした）。SNI も送らず、ホスト名も検証していませんでした。

設定

設定 既定 意味
jp.cssj.driver.tls.insecure false true にするとサーバー証明書を検証しません
jp.cssj.driver.tls.trust （廃止予定） 旧名。true は「検証しない」の意味

新しい名前が指定されていればそれだけを見ます。指定されていないときだけ 旧名を見ます。insecure=false が旧名の true に負けることはありません。 旧名を使うと JVM ごとに一度だけ警告が出ます。

コマンドラインでは --insecure（-t / --trust も同じ意味で残しています）。

copper -s ctips://cti.example.jp:8499/ --insecure -in doc.html -out doc.pdf

自己署名の証明書を使うサーバーへ繋ぐ

--insecure は試験用の逃げ道です。本番では証明書を信頼する側に登録してください。

java -Djavax.net.ssl.trustStore=/path/to/truststore.p12      -Djavax.net.ssl.trustStorePassword=... ...

ctips:（CTIP）と https:（REST）で insecure=true の意味は違います。

insecure=true のとき
CTIP 何でも通します
REST 証明書チェーンが 1 つだけのものを信頼扱いにし、それ以外は通常の検証へ委ねます。ホスト名も検証しません

動かなくなったら

自己署名の証明書や、名前の合わない証明書のサーバーへ繋いでいた場合は 失敗するようになります。意図した変更です。上のいずれかで対処してください。

ctips: で version=1 は使えません

CTIP v1 は TLS に対応していません。以前は ctips://…?version=1 を指定すると 平文で接続していました。現在は接続前に拒否します。v2（既定）を使ってください。

Ant タスクを使う場合

cti-ant の変換用 <property> と JVM のシステムプロパティは別物です。 TLS の設定は JVM 側（ANT_OPTS など）で渡してください。

サンプルプログラムについて

javacコマンドが実行できるようにパスを設定しておいて下さい。 Linuxではcompile-examples.sh、Windowsではcompile-examples.batを実行するとコンパイルされます。

サンプルプログラムを実行するには、コンパイル後に以下のコマンドを実行してください。

Linux

java -cp cti-driver-2.3.2.jar:classes クラス名

Windows

java -cp cti-driver-2.3.2.jar;classes クラス名

Servlet/JSPのサンプル実行する場合は、examples/webappをサーブレットコンテナに配備して、以下のアドレスをブラウザで表示してください。 Tomcat 10 では examples/webapp/WEB-INF/web.xml を examples/webapp/WEB-INF/web-jakarta.xml で置き換えてください。

(Filterのテスト) http://ホスト:ポート/コンテキスト/source.jsp

(Servlet of the test) http://ホスト:ポート/コンテキスト/pdf/source.jsp

API概要

主要なクラス

クラス/インターフェース 説明
CTIDriverManager ドライバの取得、セッションの作成
CTISession 文書変換セッションの管理
CTIDriver サーバー接続ドライバ
Results 出力先の抽象化
SingleResult 単一結果の出力
DirectoryResults 複数ファイルの出力
ResourceDirectoryResults 結果の相対URIを保つ、安全なディレクトリ出力
MessageHandler メッセージ受信ハンドラ
ProgressListener 進捗リスナー
SourceResolver リソース解決

CTISession の主要メソッド

メソッド 説明
setResults(Results) 出力先の設定
setMessageHandler(MessageHandler) メッセージハンドラの設定
setProgressListener(ProgressListener) 進捗リスナーの設定
setSourceResolver(SourceResolver) リソースリゾルバの設定
property(String, String) プロパティの設定
transcode(MetaSource) 変換の実行（ストリーム）
transcode(URI) 変換の実行（URI）
setContinuous(boolean) 連続モードの設定
join() 結果の結合
reset() セッションのリセット
close() セッションのクローズ

テストの実行方法

テストにはCopper PDFサーバーへの接続が必要です。

  1. test-config.json をプロジェクトルートに作成:
{
  "host": "localhost",
  "port": 8099,
  "user": "user",
  "password": "kappa"
}
  1. Gradle でテストを実行:
./gradlew test

サーバーが起動していない場合、テストは自動的にスキップされます。

ドキュメント生成

Javadocを生成:

./gradlew javadoc

ビルド

./gradlew build

CTI Java は net.zamasoft:zstream-io と net.zamasoft:zstream-resolver に依存しています。ローカルで zstream の未リリース版とあわせて開発する場合は、zstream を隣接ディレクトリに clone するか、zstream.dir プロパティまたは ZSTREAM_DIR 環境変数でチェックアウト先を指定してください。

git clone https://github.com/zamasoftnet/zstream.git ../zstream
./gradlew build
./gradlew build -Pzstream.dir=/path/to/zstream

ライセンス

Apache License 2.0 （全文はリポジトリの LICENSE）

Copyright (c) 2012-2026 座間ソフト

Apache License Version 2.0に基づいてライセンスされます。 あなたがこのファイルを使用するためには、本ライセンスに従わなければなりません。 本ライセンスのコピーは下記の場所から入手できます。

http://www.apache.org/licenses/LICENSE-2.0

適用される法律または書面での同意によって命じられない限り、本ライセンスに基づいて頒布されるソフトウェアは、明示黙示を問わず、いかなる保証も条件もなしに「現状のまま」頒布されます。 本ライセンスでの権利と制限を規定した文言については、本ライセンスを参照してください。

Copyright (c) 2012-2026 Zamasoft.

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

変更履歴

v2.3.2 2026-09-20

(v2.3.1 は JitPack の POM が多モジュール扱いで壊れていたため、公開物を 1 つに絞った v2.3.2 で出し直しました。)

  • Maven / Gradle(JitPack)で入るようになりました。com.github.zamasoftnet:cti.java:<タグ> は v2.2.3 の時点から POM だけで jar が無く、一度も解決できていませんでした(ルートが何も 公開しておらず、モジュール座標はリポジトリ名のドットでパスが割れます)。v2.3.0 は JitPack でのビルド自体が失敗していました(zstream 未チェックアウト)。ルートから ドライバ本体(cti-driver の全部入り jar。zstream 同梱、依存なし)を公開します。 ライブラリ自体の変更はありません。

v2.3.0 2026-09-10

CTIP over TLS(ctips:)を作り直しました。

  • **TLS 1.3 のハンドシェイクが完了しませんでした。**待ち合わせの状態を エンジンではなく共有の結果オブジェクトから読んでおり、FINISHED が 現在の状態ではなく一度きりの通知であることも見ていなかったため、 CPU を 100% 使ったまま進みませんでした。送信側も、暗号文が残っているのに 平文を送り切った時点で終わっていたため取りこぼしていました。
  • SNI を送るようになりました。createSSLEngine() をホストとポート無しで 呼んでいたためです。IP で繋ぐときは RFC 6066 のとおり送りません。 ホスト名の照合も行います。
  • **サーバー証明書を既定で検証します。**従来は検証していませんでした。 設定名 jp.cssj.driver.tls.trust は意味が逆で、既定の true が 「何でも通す」でした。新しい名前は jp.cssj.driver.tls.insecure(既定 false)です。 旧名は新名が無いときだけ見て、使うと JVM ごとに一度警告します。 CLI には --insecure を足しました(-t / --trust も同じ意味で残ります)。
  • ctips: に version=1 を指定した接続を、繋ぐ前に断るようにしました。 v1 に TLS は無く、黙って平文へ落ちていました。
  • 互換性に関する注意: 自己署名や名前の違う証明書のサーバーへ繋いでいた場合、 このバージョンからは失敗します。逃げ道と、私設 CA を登録する方法は README の「TLS」の節にあります。

そのほか。

  • CTIP で 32KB を超える文字列を送ると接続が壊れる欠陥を修正しました。
  • REST: 出力開始後に中断した変換が、壊れた PDF を成功として返していたのを直しました。
  • REST: 結果が無いときに 404 を返し、Authorization: Basic を受け付けるようにしました。
  • cti-cli の -p オプションが全く効いていなかったのを直しました。
  • Apache License 2.0 の表示を追加しました。

v2.2.3 2024-03-27

  • サーブレットでContent-Typeを出力する際に、空の charset= パラメータが追加されてしまうバグに対応しました。

v2.2.2 2024-03-14

  • javax.servlet 4 に対応しました。
  • jakarta.servlet 5 に対応しました。

v2.2.1 2023-04-04

v2.2.0 2018-04-26

  • Closableを利用可能になる等Java 8のコーディングに対応しました。

v2.1.5 2017-02-19

  • http:プロトコルが使用できないバグを修正しました。

v2.1.4 2014-04-14

  • ctip:プロトコルでタイムアウトを設定できるようになりました。