WebCountServlet Java アクセスカウンタサーブレット取扱説明書

WebCountServlet
Java アクセスカウンタサーブレット取扱説明書
since Mar. 21 2005

汝はわが歩数を測る。

— ヨブ記，14 章 16 節．

概要

WebCountServlet パッケージは Web アクセスカウンタサーブレット一式である．当サイトのために作成したものを公開する．インターネットの CGI 配布サイトなどで普通に出回っているものとたいして変らない．

アクセス数を管理したい Web ページに <img> タグで WebCountServlet クエリを埋め込んでおくことにより，ブラウザはページを読み込んだ際, WebCountServlet を起動する．一方 WebCountServlet サーバ側は，クエリに含まれるカウンタ ID ファイルに格納された数値をインクリメントして，再度ファイルに格納するとともに要求元ページに送信する．以上が本システムの基本動作方式である．このとき WebCountServlet はリファラをチェックして管理対象のページからの要求かどうかを確認する．このため <img> タグを無視したり，リファラを送信しなかったりする HTTP クライアント (ブラウザ) からのページ要求はカウンタには反映されない．たとえばサーチエンジンのクローラーなどがこれに該当する．また，<img> タグによってサーブレット起動する方式なので，同じカウンタを複数のページで共有したりすると，ブラウザがキャッシュから画像を読む事態となって，意図するようにカウンタが更新されない場合がある．

WebCountServlet の機能は以下のとおり．

管理したいページ毎にカウンタ ID を指定できる．（当たり前）
ページに対して一意に対応するカウンタ ID ファイルでアクセスカウントを管理する．
カウンタ ID を格納するディレクトリ等を初期パラメータで指定できる．
初期パラメータはデプロイメント・ディスクリプタ (Tomcat では web.xml) に記述する．
カウンタの参照／更新を選択できる．
対象カウンタを呼出した時にカウントアップするか (更新モード) しないか (参照モード) を，リクエストパラメータで指定できる．参照モードは，管理者用のページで現在のカウンタ値を変更せずに参照のみしたい場合などを想定している．
カウンタ出力の仕方は4通りが可能である．
- システムフォント (12 ピクセルの Monospaced PLAIN) で生成した数値画像で出力する．
- 0 から 9 までの 10 個のカウンタ GIF 画像を合成して出力する．画像は初期パラメータで指定したディレクトリ (URL) に格納しておく．
- テキストで出力する．表示する場合, JSP もしくは SSI の機能でページに挿入する．
- カウンタ表示をしない．画像が存在しないエラーを回避するため, 1×1 ピクセルの白のダミー画像を送信する．
  (アクセス数を管理したいがカウンタ表示は醜い，あまりにアクセスがないので恥ずかしいと考えるひとのために．私のことである．)
同一 IP アドレスから同一カウンタ ID (ページ) へのアクセスについて，一定時間以内はカウントアップの対象としないことができる．
カウント対象としない時間間隔は初期パラメータで指定できる．
リファラのパターンマッチングチェック機能をもつ．
カウンタを表示すべきページはリファラによって取得できる．当該ページのカウンタ要求を処理すべきかどうかを，正規表現でパターンマッチングによって検証し，マッチしない場合は処理を行わない．これは他のサイトからのカウンタ資源利用を抑止することを目的としている．逆に制限を撤廃しカウンタ ID 付与基準を決めて，カウンタを提供するサイトを構築することも可能である．

設置

WebCountServlet は Java (SUN JDK 1.5) 言語で書かれている. FreeBSD, Mac OS X 環境で開発・テストしている関係で，以下設置方法については UNIX ベースで説明する. Tomcat 環境があり，添付 Ant build.xml を適切に変更すれば，おそらく Windows でも設置・運用は可能だと思う．

サーブレットコンテナのインストールと配備

Jakarta Tomcat などを予めインストール・調整をしておく．詳細はソフトウェア添付のドキュメントやインターネット・リソースを参照．

Tomcat は Jakarta プロジェクトによって開発された JSP／サーブレット・コンテナのリファレンス実装であり，最も普及しているアプリケーションサーバソフトウェアのひとつである．オープンソースであり自由に利用できる．本説明では，Tomcat 5 を想定し，本アプリケーションが
$CATALINA_HOME/webapps/webcount/
下に配備されるものとしている. $CATALINA_HOME は Tomcat のインストール・トップディレクトリである．

[配備パス]
```
$CATALINA_HOME/webapps
 |
 +- /webcount 
     |
     +- /WEB-INF -+- web.xml
     |            +- classes -+- WebCountServlet.class
     |            |           +- WebCounter.class
     |            |           +- WebAccess.class
     |            +- lib     --- Acme.jar
     +- /img  ------------------ s0.gif ~ s9.gif
     +- /api  ------------------ documents
		  
```
アプリケーションの URL は
http://host/webcount/counter?リクエストパラメータ
とする．

もちろん配備は管理者がサイトの方針に従って決定できる．添付 web.xml, Tomcat サーバ設定ファイル server.xml を運用に合わせて変更すればよい. Apache, Tomcat のマニュアルを参照のこと. Tomcat Web アプリケーションはデフォルトでは 8080 などのポート番号を指定して起動する．本稿では 80 を使う前提になっている. Apache 2.2.3, Tomcat 5.5 を使用しているならば, httpd.conf に次のような設定を追加して mod_proxy_ajp モジュールをロードすれば，ポート番号 80 でアプリケーションを公開することができる．
```
LoadModule proxy_ajp_module →
  libexec/apache22/mod_proxy_ajp.so
ProxyPass /webcount ajp://localhost:8009/webcount
		  
```
Acme.JPM パッケージ
WebCountServlet は gif 画像生成のため ACME Labs の Acme.JPM パッケージ API を用いている. ACME Labs から Acme.tar.gz をダウンロードしておく．本説明では $HOME/tmp にダウンロードするものとする．
ダウンロード／解凍
WebCountServlet パッケージはダウンロード・サービスに最新版を置いている．これをダウンロードして, ZIPアーカイバで解凍する．本説明では $HOME/tmp に展開したものとする．
```
% cd $HOME/tmp
% unzip WebCountServlet-1.1.zip
		  
```
web.xml の修正
添付の web.xml (webcount/war/WEB-INF/ 下に格納されている) を運用条件に応じて修正する．初期パラメータ設定仕様は次項を参照．
Acme.jar の格納
ダウンロードした Acme.tar.gz を展開し，Acme.jar として固めて，webcount/war/WEB-INF/lib 下に格納する．
```
% cd $HOME/tmp
% tar zxvf Acme.tar.gz
% jar cvf Acme.jar ./Acme
% mkdir -p webcount/war/WEB-INF/lib
% cp Acme.jar webcount/war/WEB-INF/lib
		  
```
ビルド及びインストール
Apache Ant を前提としている．
```
% ant
% ant javadoc
# ant deploy
		  
```
deploy タスクを実行すると，クラスファイルのほか, web.xml や数字画像ファイルサンプル (s0.gif 〜 s9.gif), ドキュメント, Acme.jar が所定のディレクトリ下に配備 (インストール) される．ドキュメントは javadoc で整形したものである．
数字画像ファイルサンプルはテスト用の間に合わせのものでありダサイ．利用者自身の好みに合った画像ファイルを準備いただきたい．
ディスプレイ環境
Java awt API を用いて画像処理を行うため，サーバとしては通常行わないディスプレイ設定が必要である. UNIX では Tomcat 起動の前に以下のいずれかを行っておく必要がある．
- X ウィンドウ環境を準備し, X 起動後 "xhost +" を実行し, Tomcat の実行環境に対し DISPLAY 環境変数 (例 DISPLAY="localhost:0.0") を設定しておく．
- Xvfb を設定, 起動しておく．
Tomcat の再起動
以上の設定が完了し, Tomcat を再起動すると WebCountServlet が初期化され動作可能な状態となる. server.xml において WebCountServlet が書き換えられたらリロードする設定 (Context パラメータで reloadable="true") がなされていれば，上記 deploy タスクの実行によって WebCountServlet は初期化される. Tomcat のログに以下のようなメッセージが出力されていれば初期化が完了したことが分かる．
```
情報: WebCountServlet: Interval: 15 sec
情報: WebCountServlet: Map entry: 1
情報: WebCountServlet: Check URL: http://.*ホスト正規表現.*
情報: WebCountServlet: Log file: /tmp/wa/count/counter.log
		  
```
管理対象のページにアクセスすると，ログファイルには以下のような情報が出力される．
```
2008/MM/DD hh:mm:ss,053,39,nnn.nnn.nnn.nnn,→
http://yasuda.homeip.net/lan/webcount.html,→
Mozilla/5.0 (X11; U; FreeBSD i386; ja-JP; rv:1.7.13)...
		  
```
ここで 053 はカウンタ ID, 39 はカウンタ, nnn.nnn.nnn.nnn は要求元 (ブラウザ) の IP アドレス, http:// ... は対象ページ, Mozilla/5.0 ... は要求元の UserAgent (ブラウザ) である．

初期パラメータ

初期パラメータはデプロイメント・デイスクリプタで定義する. Tomcat では web.xml であり, WebCountServlet パッケージにもサンプルを添付している. <param-name> タグで指定したパラメータ名に対し, <param-value> タグで値を記述する．

cnt_dir
カウンタ ID ファイルを置くディレクトリ名を絶対パスで指定する．

例：

<init-param>
  <param-name>cnt_dir</param-name>
  <param-value>/tmp/wa/count/</param-value>
</init-param>

img_url
イメージファイル格納ディレクトリ URL を指定する. URL なのでネットワーク上のリソースでもよい．ここで指定したディレクトリの下にカウンタ値を画像合成するための GIF イメージファイルを格納しておく．
0 から 9 まで必ず 10 個揃いで準備する．これらのファイル名は，すべて「プレフィクス + 数字(1桁).gif」でなければならない．
このプレフィクス文字列をリクエストパラメータ ty で指定して，画像ファイルを特定することになる．

例：
```
<init-param>
  <param-name>img_url</param-name>
  <param-value>http://localhost/webcount/img</param-value>
</init-param>
		  
```
log_file
ログファイル名を絶対パス名で指定する．
ファイルを割当てる際はパーミションに注意．

例：
```
<init-param>
  <param-name>log_file</param-name>
  <param-value>/tmp/wa/count/counter.log</param-value>
</init-param>
		  
```
cnt_entries
HashMap エントリ数を指定する．この数値はサイトで管理するカウンタの総数に比例して大きく設定すべきである．ほぼカウンタ総数に合わせておくとよいと思われるが，カウンタのテーブルが大きくなり，メモリ条件もそれに応じ増大する．

例：
```
<init-param>
  <param-name>cnt_entries</param-name>
  <param-value>50</param-value>
</init-param>
		  
```
cnt_interval
同一 IP が同一カウンタにアクセスした時，ここで指定したインターバル (秒) 内ではカウントアップしない．短時間に同一ユーザが不必要にリロードして，意味のないカウントアップを抑止することが目的である．

例：
```
<init-param>
  <param-name>cnt_interval</param-name>
  <param-value>900</param-value>
</init-param>
		  
```
cnt_debug
"true" の時デバッグモードで動作する．指定してもしなくてもあまり変りがない．これは建築現場の足場の残骸と考えていただきたい．

例：
```
<init-param>
  <param-name>cnt_debug</param-name>
  <param-value>true</param-value>
</init-param>
		  
```
url_check
リファラ URL に含まれるべき正規表現を指定する．管理対象としたいページ，サイトの URL に特徴的な文字列を記述すべきである．
リファラが指定正規表現にマッチしないと，入り口で処理を中止し，リクエストを読み捨てる．
これで制限しないと，カウンタ資源が寄生される恐れがあるので注意．
スペースやタブ，改行で区切って複数の正規表現を指定することができる．
正規表現コンパイラは JDK 1.4 以降の Java API を使用している．
部分文字列でマッチさせたい場合は前後に ".*" を付加する．
正規表現は計算コストがかかる．指定数が増大するに従いパフォーマンスが低下するので必要最低限とする．

例：
```
<init-param>
  <param-name>url_check</param-name>
  <param-value>
  .*www.ceres.dti.ne.jp/~i-yasuda.*
  .*yasuda.homeip.net.*
  </param-value>
</init-param>
		  
```

利用方法

［画像出力の場合］

カウンタを表示したい Web ページにサーブレットを起動する <img> タグ記述を埋め込む．：
<img src="http://host/webcount/counter?id=xxx&ty=y&md=z">
たとえば本 Web ページのソース最後尾には，
<img src="/wa/counter?id=053&md=n">
とある．これは，カウンタ ID 053 を指定し，カウンタ非表示の設定である．ただし配備ディレクトリは標準の webcount ではなく wa に変更しているので注意．

［テキスト出力の場合 (JSP)］

JSP のカウンタを設置したいところに以下のような記述を挿入する．

<jsp:include page="counter" flush="true">
    <jsp:param name="id" value="xxx" />
    <jsp:param name="md" value="z" />
</jsp:include>

［リクエストパラメータの指定］

id=xxx [必須]
xxx にカウンタ ID を指定する．カウンタ ID は初期パラメータ cnt_dir で指定したディレクトリ下に同名で保持される．
要求時カウンタ ID ファイルが存在しない場合はカウンタ値 1 で新規作成される．

移行などの必要性から，初期値は必ずしも 1 にしたいとは限らない．この時は WebCountServlet によって当該カウンタが初期化される前か，あるいは WebCountServlet が停止した状態で，予めカウンタ ID と同名のファイルを作成し，テキスト形式で任意の数値をセットしておく．ただし，スペースや改行など数字以外のコードは記述してはならない．パッケージ添付の初期化ユーティリティ initCounter により，安全に初期値を設定することができる．
カウンタファイルはサーブレットが書き込めるようにパーミションを設定する．
ty=y [任意]
y に画像プレフィクスを指定する．
- * が指定された場合はシステムフォントを用いてカウンタ数値画像を生成する．
- * 以外が指定された時，「指定文字列 + 数字.gif」ファイル名で img_url 初期パラメータ値が示すディレクトリ下から画像ファイルを読込み，カウンタ画像を合成する．
- ty そのものが省略された場合，テキストでカウンタ値を出力する. <img> タグではなく, JSP か SSI でページにカウンタ値を挿入する．
  添付 war/sample.jsp は JSP の例である．
md=z [必須]
z に一文字を指定する．
- r: 参照モード (カウントアップしない／カウンタ表示あり)
- n: 更新モード (カウントアップする／カウンタ表示なし)
- 上記以外: 更新モード (カウントアップする／カウンタ表示あり)

その他

利用条件
本ソフトウェアは無償で利用できます．
BSD ライセンスを適用します．
導入／運用結果について，いかなる責任も負いません．
いかなる保証もいたしません．
利用者の責任でご利用ください．
参考文献
Javaサーブレットプログラミング第2版
Jason Hunter, William Crawford 著，中田秀基訳
オライリー・ジャパン (2002/01)
カウンタ画像合成方法などの参考にさせていただいた．
Amazon.co.jp で詳細を見る

JavaServer Pages 第2版
Hans Bergsten 著，光田秀訳
オライリー・ジャパン (2003/05/26)
Amazon.co.jp で詳細を見る
開発／テスト／最新動作確認環境 (2008.1.11)
- FreeBSD 6.2-RELEASE, Mac OS X Tiger 10.4.11
- JDK 1.5.0
- Tomcat 5.5.17-1
- Apache 2.2.3 with mod_proxy_ajp

更新履歴

—	Mar.	17,	2005	1.0 リリース．
—	Jan.	12,	2008	1.1 Ant に変更．
—	Feb.	10,	2008	Acme パッケージ・インストール方法