プログラムインターフェース(ドライバ)の概要

Copper PDF自体はJavaによるプログラムですが、 Java以外にも各プログラミング言語向けのドライバが用意されています。 ドライバは動作中のCopper PDFサーバー(copperd)にソケット通信により接続します (一般的なデータベースサーバーと同様のしくみです)。

ドライバとCopper PDFとの通信は、以下の流れが基本となります。

  1. サーバーへの接続・認証
  2. エラーハンドラ・プログレスリスナの設定
  3. 変換結果の出力先の設定
  4. プロパティの設定
  5. リソースの送信・アクセス許可
  6. ドキュメント本体の送信
  7. 通信の終了

上記のうち、2,3,4は順序が入れ替わっても構いませんが、他の手順は正しい順序で実行することが必要です。 各手順について順を追って説明します。

サーバーへの接続・認証

copperdにアクセスするためには、copperdのホスト名、ポート番号を知る必要があります。 これらはcopperdの設定(copperd.properties)によります。 ローカルマシンで初期設定のままのCopper PDFを動かしている場合、 ホスト名はlocalhost(あるいは127.0.0.1(IPv4)または::1(IPv6))、ポート番号は8099です。

簡単なセキュリティ機能として、ユーザーIDとパスワードにより認証があります。 ユーザーIDは"user"で固定です。 サーバーの初期設定の状態ではパスワードは"kappa"ですが、 サーバー側でcopperdコマンドにより変更することができます。

copprdはクライアントのIPアドレスによりアクセスを制限します。 初期設定の状態ではローカルマシン(127.0.0.1(IPv4)または::1(IPv6))からのアクセスだけが許可されています。 これはサーバー側のアクセス制御の設定(access.txt)を編集することで起動中に変更することができます。

エラーハンドラ・プログレスリスナの設定

エラーハンドラ

エラーハンドラは、変換処理の過程で出力された警告やエラー、処理情報を受け取るためのインターフェースです (処理情報を受け取る機能は後で追加されたため「エラーハンドラ」という名前になっています)。 エラーハンドラが受け取ることができるメッセージは以下の4つに分類されます。

種類 コード 説明
警告 1 処理の続行が可能なエラーです。
エラー 2 処理の続行が不可能になるか、出力結果を得られなくなるエラーです。
致命的エラー 3 通信障害など、システムの問題に起因する深刻なエラーです。
処理情報 4 これはエラーメッセージではありません。 出力済みのページ数、処理中のセクションなどの情報です。

プログレスリスナ

プログレスリスナはサーバー側でのデータの読み込み状況や最終的なデータサイズをプログラムが知るためのインターフェースです。

プログレスリスナには、サーバー側で処理済の入力データのバイト数が渡されます。 また、プログレスリスナが要求した場合は、変換結果の先頭が得られる前に、結果全体のデータのバイト数が渡されます。 前者はプログレスバーなどでユーザーに進行状況を伝えるために利用できます。 後者はHTTPのContent-Lengthヘッダを送るために利用できます。

出力先の設定

変換結果はストリーム、ファイル等に出力することができます。 出力先の指定方法は、プログラミング言語によります。 Copper PDFはウェブ上での利用を重視しているため、クライアントのブラウザに送る方法は必ず用意されています。

入出力プロパティの設定

ドキュメントの変換方法の詳細は入出力プロパティによって細かく指定することができます。 利用可能なプロパティのリストはプロパティ一覧を参照してください。

リソースの送信・アクセス許可

Copper PDFで文書を変換する場合、CSSファイルや画像ファイルといったリソースがどこにあるかが問題となります。 リソースがサーバー側からアクセスできる場所(例:copperdが動作しているマシンのディスク上)にある場合は、 copperdが直接リソースを取得できます。 リソースがクライアント側(ドライバを使用するアプリケーションが動いているマシン)からアクセスでき、 サーバー側からアクセスできない場所にある場合は、 ドライバが事前にリソースをサーバーに送る必要があります。

文書内から画像などがURLによって参照されている場合、copperdはまず、 そのURLで表されるリソースが既にドライバにより送られているかどうかを調べます。 送られている場合は、そのリソースを使います。 そうでない場合は、サーバー側でディスクやネットワーク等からリソースを取得しようと試みます。

リソースをサーバーに送る

ドライバがリソースをcopperdに送る際には、リソース本体のデータとリソースの仮想的なURLに加え、 リソースのMIME型およびキャラクタ・エンコーディングを送ることができます。 MIME型とキャラクタ・エンコーディングは必須ではなく、 省略された場合は拡張子やファイルの内容をもとにサーバー側で自動的に判断されます。 また、画像などのバイナリデータではキャラクタ・エンコーディングは無意味です。

仮想的なURLは、file:///var/data/image.gifや、http://host/style.cssといった文字列です。 copperdはこれらのURLで表されるリソースが必要になった場合、 そのURLで表される実際の場所にアクセスすることはせず。 クライアント側から送られたデータを使います。

この方法は、事前に画像などのデータをサーバーに送り出す手間がかかる分、パフォーマンス上不利になります。 また、アプリケーションは、本文から参照されているリソースを事前に把握している必要があります。 ドライバには必要なリソースを自動的に判断する機能がないため、 事前にどのリソースを送るかはアプリケーション側に委ねられます。

一方で、変換対象やリソースを1つ1つアプリケーションで指定するため、 予期しなかったファイルにアクセスされてしまうといった、セキュリティ上の危険は少なくなります。

リソースにサーバーからアクセスする場合

必要とするリソースがドライバから送られていなかった場合、 copperdは実際にそのURLで表される場所にアクセスしてデータを取得しようと試みます。

この方法の利点は、変換対象の文書から参照されているリソースを、 copperdその都度自動的に集めてくることです。 また、リソースがサーバーのディスク上にある場合は、 事前にドライバがリソースを送る(この作業は実質的には、copperdがアクセスできる場所にファイルをコピーする作業です)手間が省けるため、 パフォーマンス上有利です。

欠点として、セキュリティの問題が挙げられます。 変換対象となる文書を誰でも編集できる場合、そこにサーバー上のファイル名を指定することで、サーバー上のファイルが盗まれてしまう可能性があります。 また、http://で始まるURLを使うことで、他のサーバーへの不正なアクセスのための踏み台にされる恐れがあります。 そのため、ネットワークの構成を含めて十分に注意して運用することが必要となります。

無制限にサーバー上のリソースにアクセスされるのを防止するため、 copperdがアクセスするリソースを制限する簡単なセキュリティ機能が用意されています。 サーバー上のリソースを利用するには、適宜アクセス許可を行う必要があります。

デフォルトの状態では、サーバーから全てのリソースへのアクセスが禁止されています copperdが文書に関連するCSSや画像等にアクセスするためにはアプリケーションで明示的に許可する必要があります。
URLパターン

リソースへのアクセス許可・制限は、URLパターンによって指定します。 本文の変換を始める前に、クライアントは、利用できるURLと除外するURLのパターンを指定します。

URLパターンにはワイルドカードを使うことができます。 "*"というワイルドカードは、'/'(スラッシュ)以外の任意の文字列を表します。 "**"というワイルドカードは、それに加えて'/'も含めることを表します。 ワイルドカードの例は以下の通りです。

  • http://www.company.com/* というパターンは、 http://www.company.com/ 直下の全てのリソースを現します。
  • http://www.company.com/image/** は、 http://www.company.com/image/ 以下の全てのリソースを表します。
  • http://www.company.com/**.css は、 http://www.company.com/ 以下の全てのCSSファイルを表します。

アクセスの制御は指定された順に行われます。

例えば、最初に次のパターンへのアクセスを禁止したとします。

  • http://www.company.com/secret

次に以下のパターンへのアクセスを許可したとします。

  • http://www.company.com/**

このとき、 http://www.company.com/style.css へのアクセスは許可されますが、 http://www.company.com/secret/image.jpeg へのアクセスは禁止されます。

逆に、最初に以下のパターンへのアクセスを許可したとします。

  • http://www.company.com/**

この場合は、後の指定に関係なく http://www.company.com/ 以下へのアクセスが全て許可されてしまいます。

両者の組み合わせ

クライアントからリソースを事前に送る方法と、サーバー側から積極的にリソースを取得する方法は、組み合わせて使うことができます。 前に説明した通り、copperdはまず、クライアントから送られたリソースを利用しようと試みるため、前者の方法が優先されます。 従って、URLパターンによるアクセス制御はクライアントから送られたリソースには適用されません。 例えば、file:///var/data/*.gifへのアクセスが禁止されていたとしても、 クライアントから仮想URLfile:///var/data/image.gifとして送られたリソースは有効です。

ドキュメント本体の送信

最後に変換対象となるドキュメント本体の送信を行います。 リソースの場合と同様に、ドキュメントの仮想的なURLを送る必要があります。 このURLは、文書中で使われる相対パスを解決するために使われます。 また、同様に必須ではありませんが、文書のMIME型とキャラクタ・エンコーディングを明示することができます。 サーバー側での文書の変換処理は、本体の送信と並行して行われます。

あるいは、ドライバから対象となる文書のURLだけを送って、 リソースのときと同様にサーバー側で変換対象の文書を取得することもできます。

通信の終了

最後に通信を完了する操作を実行する必要があります。 このとき、copperdは全ての変換結果をドライバに送り返し、接続を切断します。