OSのバックグラウンドで動作しているCopper PDFサーバー(copperd)をアプリケーションから呼び出すためには、ソケット通信を使います。 通信用のドライバは、各言語ごとに配布しています。 これは、一般的なデータベースサーバーと同様のしくみです。 また、Copper PDF 2.1以降ではHTTPによる接続をサポートしており、HTTPクライアントプログラムやライブラリを使用して接続することが出来ます。 いずれにしても、ネットワーク越しの接続が可能です。
通信方式には次の３種類があります。
ドライバとcopperdとの通信は、以下の手順が基本となります。
上記のうち、2～8の手順は省略されるか、順序が入れ替わっても構いません。 10は、ドキュメントの変換中に、処理を中止したいときに実行します。 CTIP 2.0では、通信の終了をせずに、2に戻って手順を再実行することが出来ます。 以下、各手順について順を追って説明します。
copperdにアクセスするためには、copperdのホスト名、ポート番号を知る必要があります。 これらの設定はcopperdの設定(copperd.properties)によります。 ローカルマシンで初期設定のままCopper PDFを動かしている場合、ホスト名はlocalhost(あるいは127.0.0.1(IPv4)または::1(IPv6))、 CTIPのポート番号は8099(CTIP 1.0, CTIP 2.0で共通)、HTTP/RESTのポート番号は8097です。
簡単なセキュリティ機能として、ユーザーIDとパスワードにより認証があります。 サーバーの初期設定の状態ではユーザーIDは"user"、パスワードは"kappa"ですが、 サーバー側でcopperdコマンドにより変更することが出来ます。
copprdはクライアントのIPアドレスによりアクセスを制限します。 初期設定の状態ではローカルマシン(127.0.0.1(IPv4)または::1(IPv6))からのアクセスだけが許可されています。 これはサーバー側のアクセス制御の設定(access.txt)を編集することで起動中に変更することが出来ます。
メッセージハンドラは、変換処理の過程で出力された警告やエラー、処理情報を受け取るためのインターフェースです (CTIP 1.0ではエラーハンドラ」という名前になっています)。
プログレスリスナはサーバー側でのデータの処理状況をプログラムが知るためのインターフェースです。 クライアント側で処理状況をユーザーに通知させ、待ち時間の目安にするためのものであるため、 データの処理状況は必ずしも正確なものではありません。 あるいは、一切処理状況が通知されないこともあります。
変換結果はストリーム、ファイル等に出力することが出来ます。 出力先の指定方法は、プログラミング言語によります。 Copper PDFはウェブ上での利用を重視しているため、クライアントのブラウザに送る方法は必ず用意されています。
ドキュメントを変換した結果得られるPDF、画像等のデータはクライアント側で受信してドライバにより構築されます。 出力結果はファイルに保存するか、あるいはウェブアプリケーションであればそのままユーザーに送り出すことができます。
CTIP 2.0では、複数の結果を受信することが出来ます。 例えば、複数ページの文書を複数の画像ファイルとしてクライアント側で保存することが出来ます。
ドキュメントの変換方法の詳細は入出力プロパティによって細かく指定することが出来ます。 利用可能な入出力プロパティのリストは入出力プロパティ一覧を参照してください。
Copper PDFで文書を変換する場合、CSSファイルや画像ファイルといったリソースがどこにあるかが問題となります。 リソースがサーバー側からアクセス出来る場所(例:copperdが動作しているマシンのディスク上)にある場合は、copperdが直接リソースを取得出来ます。 リソースがクライアント側(ドライバを使用するアプリケーションが動いているマシン)からアクセス出来、 サーバー側からアクセス出来ない場所にある場合は、ドライバがリソースをサーバーに送る必要があります。
文書内から画像などがURLによって参照されている場合、copperdはまず、そのURLで表されるリソースが既にドライバにより送られているかどうかを調べます。 送られている場合は、そのリソースを使います。 そうでない場合は、後で説明するソースリゾルバ2.1.0によって、クライアントからリソースを送るように要求します。 ソースリゾルバによってんもリソースを取得できない場合は、サーバー側でディスクやネットワーク等からリソースを取得しようと試みます。
ドライバがリソースをcopperdに送る際には、リソース本体のデータとリソースの仮想的なURLに加え、 リソースのMIME型およびキャラクタ・エンコーディングを送ることが出来ます。 MIME型とキャラクタ・エンコーディングは必須ではなく、 省略された場合は拡張子やファイルの内容をもとにサーバー側で自動的に判断されます。 また、画像などのバイナリデータではキャラクタ・エンコーディングは無意味です。
仮想的なURLは、file:///var/data/image.gifや、http://host/style.cssといった文字列です。 copperdはこれらのURLで表されるリソースが必要になった場合、 そのURLで表される実際の場所にアクセスすることはせず。 クライアント側から送られたデータを使います。
この方法は、事前に画像などのデータをサーバーに送り出す手間がかかる分、パフォーマンス上不利になります。 また、アプリケーションは、本文から参照されているリソースを事前に把握している必要があります。 ドライバには必要なリソースを自動的に判断する機能がないため、 事前にどのリソースを送るかはアプリケーション側に委ねられます。
一方で、変換対象やリソースを1つ1つアプリケーションで指定するため、 予期しなかったファイルにアクセスされてしまうといった、セキュリティ上の危険は少なくなります。
必要とするリソースがドライバから送られていなかった場合、 copperdは実際にそのURLで表される場所にアクセスしてデータを取得しようと試みます。
Copper PDFはHTTPクライアントを持っており、HTTP(https://で始まるURL)、SSL(https://で始まるURL)によりアクセス可能なデータを取得することが出来ます。 またCopper PDFが動作しているローカルマシン上のファイル(file://で始まる、ブラウザでローカルマシン上のファイルを開く場合のURL)へアクセスすることが出来ます。 データスキームURI(data:で始まる、URI中にデータを含むURI)もサポートしています。 その他のデータへはjava.net.URLを利用してアクセスするため、Java実行環境がサポートするコンテンツハンドラに依存します。
この方法の利点は、変換対象の文書から参照されているリソースを、 copperdその都度自動的に集めてくることです。 また、リソースがサーバーのディスク上にある場合は、 事前にドライバがリソースを送る(この作業は実質的には、copperdがアクセス出来る場所にファイルをコピーする作業です)手間が省けるため、 パフォーマンス上有利です。
欠点として、セキュリティの問題が挙げられます。 変換対象となる文書を誰でも編集出来る場合、そこにサーバー上のファイル名を指定することで、サーバー上のファイルが盗まれてしまう可能性があります。 また、http://で始まるURLを使うことで、他のサーバーへの不正なアクセスのための踏み台にされる恐れがあります。 そのため、ネットワークの構成を含めて十分に注意して運用することが必要となります。
無制限にサーバー上のリソースにアクセスされるのを防止するため、 copperdがアクセスするリソースを制限する簡単なセキュリティ機能が用意されています。 サーバー上のリソースを利用するには、適宜アクセス許可を行う必要があります。
リソースへのアクセス許可・制限は、URIパターンによって指定します。 本文の変換を始める前に、クライアントは、利用出来るURIと除外するURIのパターンを指定します。
URIパターンにはワイルドカードを使うことが出来ます。 "*"というワイルドカードは、'/'(スラッシュ)以外の任意の文字列を表します。 "**"というワイルドカードは、それに加えて'/'も含めることを表します。 ワイルドカードの例は以下の通りです。
アクセスの制御は指定された順に行われます。
例えば、最初に次のパターンへのアクセスを禁止したとします。
次に以下のパターンへのアクセスを許可したとします。
このとき、 http://www.company.com/style.css へのアクセスは許可されますが、 http://www.company.com/secret/image.jpeg へのアクセスは禁止されます。
逆に、最初に以下のパターンへのアクセスを許可したとします。
この場合は、後の指定に関係なく http://www.company.com/ 以下へのアクセスが全て許可されてしまいます。
http: または https: で始まるURIでは、%エスケープした文字は、デコードされたものとして比較されます。 また、パターンで * にマッチするようにするには、代わりに %2A を記述してください。 例えば http://www.company.com/%61bc %2A/*というパターンは http://www.company.com/a%62c*/defというURIにも http://www.company.com/ab%63%2A/defというURIにもマッチします。 2.1.7
クライアントからリソースを事前に送る方法と、サーバー側から積極的にリソースを取得する方法は、組み合わせて使うことが出来ます。 このとき、URIパターンによるアクセス制御はクライアントから送られたリソースには適用されません。 例えば、file:///var/data/*.gifへのアクセスが禁止されていたとしても、 クライアントから仮想URLfile:///var/data/image.gifとして送られたリソースは有効です。
ソースリゾルバは、指定したURIでアクセスできるデータを取得するインターフェースです。 ドキュメントから参照されるリソースは、事前にクライアントから送ることができますのが、そのためには、ドキュメントからどのリソースが参照されているのかを、クライアントが知っていることが前提となります。 しかし、例えば実際にHTMLファイルの内容を解析しなければ、必要なリソースが分からないということももあります。 CTIP 2.0では、サーバー側がドキュメントを解析しつつ、必要になったリソースをその都度クライアントが探すように要求し、ドライバはソースリゾルバで探し出したリソースをサーバーに送ります。
CTIP 2.0では、メッセージハンドラ、プログレスリスナ、入出力プロパティの設定と、サーバー側で受信済みのリソースを全てリセットすることが出来ます。 リセットにより、全ての状態は接続直後に戻ります。
最後にドキュメント本体をCopper PDFが変換するために必要な情報を送ります。 リソースの場合と同様、データをサーバーに送る方法と、サーバー側からデータを取得する方法があります。
リソースの場合と同様に、変換対象のドキュメント本体をサーバー側に送ることが出来ます。
このとき、ドキュメントの仮想的なURLを送る必要があります。
このURLは、ドキュメント中で使われる相対パスを解決するために使われます。
例えば、ドキュメントの仮想的なURLがhttp://copper-pdf.com/docs/document.htmlであった場合、
ドキュメント中に<img src="../images/photo.jpeg">という記述があれば、
http://copper-pdf.com/images/photo.jpegに存在する画像が使われます。
また、必須ではありませんが、ドキュメントのMIME型とキャラクタ・エンコーディングを明示することが出来ます。
サーバー側でのドキュメントの変換処理は、本体の送信と並行して行われます。
サーバーに変換対処のドキュメントのURLを送ることにより、サーバー側で変換対象の文書を取得することが出来ます。 ドキュメント中の相対パスは、ドキュメントのURLを基点に解決します。 ドキュメントのURLに対しては、URIパターンによるアクセス許可とは無関係にアクセス可能です。
ドキュメントのURLは、事前にサーバーに送ったリソースでも構いません。 ことのき、事前に送ったリソースがドキュメント本体となります。
リソースに対するアクセス禁止設定は、ドキュメント本体のURLには適用されません。
CTIP 2.0では、変換処理の最中に処理を中断することが出来ます。 クライアントから処理の中断を要求されてから、実際に処理が中断されるまでには、若干の遅れが生じます。 処理を中断する際には、なるべくきりのよいところまで処理を継続して、途中のページまでが含まれたPDFのようなファイルが生成されるようにするか、 ファイルが破壊されても強制的に停止する２つのモードを選ぶことが出来ますが、必ず要求どおりに処理が終わる保障はありません。
通信の終了をサーバーに通知すると、サーバーの方から接続を切断します。 CTIP 1.0では接続を切断して接続しなおさない限り、次のドキュメント変換処理は実行できませんが、 CTIP 2.0ではそのまま処理を繰り返すことができます。