ソースの構造

The description below uses the variable name $CATALINA_HOME to refer to the directory into which you have installed Tomcat 4, and is the base directory against which most relative paths are resolved. However, if you have configured Tomcat 4 for multiple instances by setting a CATALINA_BASE directory, you should use $CATALINA_BASE instead of $CATALINA_HOME for each of these references.

以下の文章では Tomcat 4 をインストールしたディレクトリを指す $CATALINA_HOME 変数を使います。 これは大半の相対パスが解決されるときのベースディレクトリでもあります。 しかしながら、CATALINA_BASE ディレクトリをセットして複数のインスタンス用に Tomcat 4 を設定している場合は、 それぞれの参照において $CATALINA_HOME の代わりに $CATALINA_BASE を使用するべきでしょう。

A key recommendation of this manual is to separate the directory hierarchy containing your source code (described in this section) from the directory hierarchy containing your deployable application (described in the preceding section). Maintaining this separation has the following advantages:

このマニュアルで特に薦めたいことは、(この章で述べている) ソースコードのディレクトリ階層と(前の章で述べられている) 配備するアプリケーションのディレクトリ構造を分割することです。 このように分割すると以下のような利点があります。

• The contents of the source directories can be more easily administered, moved, and backed up if the "executable" version of the application is not intermixed.
  
  
• "実行可能な"バージョンのアプリケーションが混在していなければ、 ソースディレクトリの管理、移動、バックアップがより簡単になります。
  
  
• Source code control is easier to manage on directories that contain only source files.
  
  
• ソースファイルだけを含むディレクトリは、ソースコードの管理がより簡単です。
  
  
• The files that make up an installable distribution of your application are much easier to select when the deployment hierarchy is separate.
• 配備する階層が分けられていると、 アプリケーションのインストール可能な配布物を作成するためのファイルがより簡単に選択できます。

As we will see, the ant development tool makes the creation and processing of such directory hierarchies nearly painless.

これから見ていくように ant 開発ツールを使うと、 このようなディレクトリ階層の作成と処理をほとんど苦労無しに行うことができます。

The actual directory and file hierarchy used to contain the source code of an application can be pretty much anything you like. However, the following organization has proven to be quite generally applicable, and is expected by the example build.xml configuration file that is discussed below. All of these components exist under a top level project source directory for your application:

アプリケーションのソースコードを含む実際のディレクトリとファイルの階層については、 まったく好きなようにしても構いません。 しかしながら、以下に述べる構造は非常に一般的に使用できることが証明されています。 また、以下で議論されているbuild.xmlの例は、 この構造を想定しています。 これらのコンポーネントは全て、アプリケーションの トップレベルのプロジェクトソースディレクトリ の下に存在します。

• docs/ - Documentation for your application, in whatever format your development team is using.
  
  
• docs/ - アプリケーション用のドキュメント。 開発チームが使っているどんなフォーマットのものでも。
  
  
• src/ - Java source files that generate the servlets, beans, and other Java classes that are unique to your application. If your source code is organized in packages (highly recommended), the package hierarchy should be reflected as a directory structure underneath this directory.
  
  
• src/ - アプリケーションに固有な servlet、bean、そして他の Java クラスを生成するための Java ソースファイル。 ソースコードがパッケージに分割されている場合(強く推奨します) には、パッケージ階層をこのディレクトリ下のディレクトリ構成として反映するべきです。
  
  
• web/ - The static content of your web site (HTML pages, JSP pages, JavaScript files, CSS stylesheet files, and images) that will be accessible to application clients. This directory will be the document root of your web application, and any subdirectory structure found here will be reflected in the request URIs required to access those files.
  
  
• web/ - アプリケーションクライアントからアクセスされる、 ウェブサイトの静的内容(HTMLページ、JSPページ、JavaScriptファイル、 CSSスタイルシートファイル、画像)。 このディレクトリがアプリケーションの ドキュメントルートになり、 任意のサブディレクトリ構成はこれらのファイルにアクセスする URI に反映されるでしょう。
  
  
• web/WEB-INF/ - The special configuration files required for your application, including the web application deployment descriptor (web.xml), tag library descriptors for custom tag libraries you have created, and other resource files you wish to include within your web application. Even though this directory appears to be a subdirectory of your document root, the Servlet Specification prohibits serving the contents of this directory (or any file it contains) directly to a client request. Therefore, this is a good place to store configuration information that is sensitive (such as database connection usernames and passwords), but is required for your application to operate successfully.
• web/WEB-INF/ - アプリケーションに必要とされる特殊な設定ファイル。 これにはウェブアプリケーション配備記述子(web.xml)、 自分で作成したカスタムタグライブラリ用のタグライブラリ記述子、 そしてウェブアプリケーションに含めたいと思う他のリソースファイルが含まれます。 このディレクトリは ドキュメントルートのサブディレクトリのように見えますが、 サーブレット仕様ではこのディレクトリの内容(または含まれる任意のファイル) をクライアント要求に対して直接的に提供することを禁じています。 それゆえに、このディレクトリは (データベース接続のユーザ名とパスワードのような) 機密事項ではあるが アプリケーションから操作できなければならない設定情報を、 置く場所として適しています。

During the development process, two additional directories will be created on a temporary basis:

開発プロセスの中で、2つの追加的なディレクトリが一時的に作られるでしょう。

• build/ - When you execute a default build (ant), this directory will contain an exact image of the files in the web application archive for this application. For containers like Tomcat that allow you to deploy unpacked directory structures, you need only copy this directory structure into a subdirectory of $CATALINA_HOME/webapps in order to deploy and test it.
  
  
• build/ - デフォルトビルドを実行(ant) した時に、 アプリケーションのウェブアプリケーションアーカイブ内ファイルの正確なイメージを含むでしょう。 Tomcat の様に解凍されたディレクトリ構成を配備できるコンテナでは、 このディレクトリ構成を $CATALINA_HOME/webapps にコピーするだけで配備とテストができるでしょう。
  
  
• dist/ - When you execute the ant dist target, this directory will be created. It will create an exact image of the binary distribution for your web application, including an license information, documentation, and README files that you have prepared.
• dist/ - ant distターゲットを実行した時に、 このディレクトリは生成されるでしょう。 これにより、 用意したライセンス情報、ドキュメント、READMEファイルを含んだ、 ウェブアプリケーションのバイナリ配布物の正確なイメージを生成するでしょう。

Note that these two directories should NOT be archived in your source code control system, because they are deleted and recreated (from scratch) as needed during development. For that reason, you should not edit any source files in these directories if you want to maintain a permanent record of the changes, because the changes will be lost the next time that a build is performed.

これらの2つのディレクトリはソースコード管理システムに保管される べきではないことに注意してください。 なぜならば、これらは開発中の必要に応じて削除されたり(スクラッチから) 再生成されたりするからです。 このような理由から、 変更を永久に記録したければこれらのディレクトリにあるどのようなソースファイルも編集すべきではありません。 ビルドが次に実行されると変更が失われてしまうからです。

外部依存

What do you do if your application requires JAR files (or other resources) from external projects or packages? A common example is that you need to include a JDBC driver in your web application, in order to operate. アプリケーションが外部のプロジェクトやパッケージからの JAR ファイル(または他のリソース)を必要とする場合どうしますか? 一般的な例としては、 動作のためにウェブアプリケーション内に JDBCドライバを含める必要がある場合などです。 Different developers take different approaches to this problem. Some will encourage checking a copy of the JAR files you depend on into the source code control archives for every application that requires those JAR files. However, this can cause significant management issues when you use the same JAR in many applications - particular when faced with a need to upgrade to a different version of that JAR file. さまざまな開発者がこの問題に対してそれぞれのアプローチを取ります。 これらの JAR ファイルを要求するアプリケーション毎に、 ソースコードコントロールアーカイブ内に依存する JAR ファイルのコピーを 格納することを奨励する開発者もいるでしょう。 しかしながら、このやり方は多くのアプリケーションで同じ JAR ファイルを使っている時に重大な管理の問題を引き起こします。 特にその JAR ファイルの異なるバージョンへのアップグレードの必要に直面した時にです。 Therefore, this manual recommends that you NOT store a copy of the packages you depend on inside the source control archives of your applications. Instead, the external dependencies should be integrated as part of the process of deploying your application. In that way, you can always pick up the appropriate version of the JAR files from wherever your development system administrator has installed them, without having to worry about updating your application every time the version of the dependent JAR file is changed. それ故に、このマニュアルはアプリケーションのソースコントロールアーカイブ内に、 依存しているパッケージのコピーを格納 しないことを薦めます。 代わりに、外部依存はアプリケーションの配備 プロセスの一部として統合されるべきです。 この方法で、依存する JAR ファイルのバージョンが変わる度にアプリケーションの更新の心配をすることなく、 開発システムの管理者がインストールした場所から常に適当なバージョンの JAR ファイルをピックアップすることができます。 In the example Ant build.xml file, we will demonstrate how to define build properties that let you configure the locations of the files to be copied, without having to modify build.xml when these files change. The build properties used by a particular developer can be customized on a per-application basis, or defaulted to "standard" build properties stored in the developer's home directory. Ant build.xmlファイルの例の中で、 ビルドプロパティの定義の仕方をデモします。 これによりコピーされるファイル変わった時にbuild.xml を編集することなく、それらのファイルの場所を設定することができます。 特定の開発者から使われるビルドプロパティは、 アプリケーション毎の規則に基づいてカスタマイズすることができますし、 またデフォルトでは "標準の" ビルドプロパティが開発者のホームディレクトリの中に格納されます。

As mentioned earlier, it is highly recommended that you place all of the source files that comprise your application under the management of a source code control system like the Concurrent Version System (CVS). If you elect to do this, every directory and file in the source hierarchy should be registered and saved -- but none of the generated files. If you register binary format files (such as images or JAR libraries), be sure to indicate this to your source code control system.

前に述べたように、アプリケーションを構成する全てのソースファイルを Concurrent Version System (CVS) のようなソースコードコントロールシステム下に置くことは強く推奨されています。 そうすることを決定した場合には、 ソース階層内のすべてのディレクトリとファイルは登録、保存されるでしょう。 -- しかし生成されたファイルについてはどれも登録、保存されません。 バイナリ形式のファイル(画像や JAR ライブラリなど)を登録する場合には、 ソースコードコントロールシステムにそのことを確実に認識させてください。

We recommended (in the previous section) that you should not store the contents of the build/ and dist/ directories created by your development process in the source code control system. An easy way to tell CVS to ignore these directories is to create a file named .cvsignore (note the leading period) in your top-level source directory, with the following contents:

開発プロセスにより生成される build/とdist/ ディレクトリの内容は、 ソースコードコントロールシステムの中に格納するべきではないと (前の章で)推奨しました。 CVSにこれらのディレクトリを無視させる簡単な方法は、 トップレベルソースディレクトリ内に以下のような内容の .cvsignore(先頭のピリオドに注意) という名前のファイルを作ることです。

	build dist build.properties

The reason for mentioning build.properties here will be explained in the Processes section.

build.propertiesをここに書く理由は、 Processesの章で説明されています。

Detailed instructions for your source code control environment are beyond the scope of this manual. However, the following steps are followed when using a command-line CVS client:

ソースコードコントロール環境の詳細な解説については、 このマニュアルの範疇ではありません。 しかしながら、CVS のコマンドラインクライアントを使っているならば、 下のステップに従えば良いでしょう。

• To refresh the state of your source code to that stored in the the source repository, go to your project source directory, and execute cvs update -dP.
  
  
• あなたのソースコードをソースレポジトリに格納されているものの状態にするには、 プロジェクトソースディレクトリに行き cvs update -dP を実行します。
  
  
• When you create a new subdirectory in the source code hierarchy, register it in CVS with a command like cvs add {subdirname}.
  
  
• ソースコード階層内に新しいサブディレクトリを作成した場合は、 cvs add {サブディレクトリ名} の様なコマンドでCVSに登録をします。
  
  
• When you first create a new source code file, navigate to the directory that contains it, and register the new file with a command like cvs add {filename}.
  
  
• 最初に新しいソースコードファイルを作成した場合は、 それを含むディレクトリに移動して cvs add {ファイル名} の様なコマンドで新しいファイルを登録します。
  
  
• If you no longer need a particular source code file, navigate to the containing directory and remove the file. Then, deregister it in CVS with a command like cvs remove {filename}.
  
  
• 特定のソースコードファイルがもう必要なくなった場合には、 それを含むディレクトリに移動してファイルを削除します。 それからcvs remove {ファイル名} のようなコマンドでCVSから登録を削除します。
  
  
• While you are creating, modifying, and deleting source files, changes are not yet reflected in the server repository. To save your changes in their current state, go to the project source directory and execute cvs commit. You will be asked to write a brief description of the changes you have just completed, which will be stored with the new version of any updated source file.
• ソースファイルを作ったり編集したり削除したりしている間、 変更はサーバレポジトリには反映されていません。 現在の状態で変更を保存するには、プロジェクトソースディレクトリに移動して cvs commitを実行します。 その時完了した変更についての簡単な記述を書くように求められるでしょうが、 これは更新した全てのソースファイルの新しいバージョンと共に格納されます。

CVS, like other source code control systems, has many additional features (such as the ability to tag the files that made up a particular release, and support for multiple development branches that can later be merged). See the links and references in the Introduction for more information.

他のソースコードコントロールシステムのように、 CVS はたくさんの追加的機能 (特定のリリースを構成するファイルにタグを付ける能力や、 あとでマージすることのできる複数の開発ブランチのサポートなど) を持っています。 より詳しい情報についてははじめに 内のリンクとリファレンスを見てください。

We will be using the ant tool to manage the compilation of our Java source code files, and creation of the deployment hierarchy. Ant operates under the control of a build file, normally called build.xml, that defines the processing steps required. This file is stored in the top-level directory of your source code hierarchy, and should be checked in to your source code control system.

私たちは Java ソースコードファイルのコンパイル管理、 および配備階層の作成にantツールを使うでしょう。 Antは通常 build.xmlと呼ばれるビルドファイルの制御下で実行されます。 このファイルは必要とされるプロセスステップを定義しています。 このファイルはソースコード階層のトップレベルディレクトリ内に格納され、 ソースコードコントロールシステムにチェックインされるべきです。

Like a Makefile, the build.xml file provides several "targets" that support optional development activities (such as creating the associated Javadoc documentation, erasing the deployment home directory so you can build your project from scratch, or creating the web application archive file so you can distribute your application. A well-constructed build.xml file will contain internal documentation describing the targets that are designed for use by the developer, versus those targets used internally. To ask Ant to display the project documentation, change to the directory containing the build.xml flie and type:

Makefile のようにbuild.xml ファイルは選択的な開発動作 (関連した Javadoc ドキュメントの生成や、 スクラッチからプロジェクトをビルドできるように配備ホームディレクトリの削除、 アプリケーションを配布できるようにウェブアプリケーションアーカイブファイルの生成など) をサポートするいくつかの"ターゲット"を提供します。 良く構成されたbuild.xmlファイルは、 内部的に使用されるターゲットに対して、 開発者が使う用に設計したターゲットを記述した内部ドキュメントを含みます。 Ant にプロジェクトドキュメントを表示させるには、 build.xmlを含むディレクトリに移動して以下のコマンドをタイプします。

	ant -projecthelp

To give you a head start, a basic build.xml file is provided that you can customize and install in the project source directory for your application. This file includes comments that describe the various targets that can be executed. Briefly, the following targets are generally provided:

すぐ使用できるように、 基本的なbuild.xmlファイルが用意されています。 これをカスタマイズして、 アプリケーションのプロジェクトソースディレクトリにインストールすることができます。 このファイルは実行可能な様々なターゲットについて記述したコメントを含んでいます。 簡単に言えば、以下のターゲットが一般的に提供されます。

• clean - This target deletes any existing build and dist directories, so that they can be reconstructed from scratch. This allows you to guarantee that you have not made source code modifications that will result in problems at runtime due to not recompiling all affected classes.
  
  
• clean - このターゲットは、 buildとdistディレクトリが再構成されるように、 存在するbuildとdistディレクトリを削除します。 影響のある全てのクラスを再コンパイルしなかったために実行時に問題が起こる様なソースコードの変更を、 あなたが行っていないことを保証することができます。
  
  
• prepare - This target "prepares" the build directory, creating subdirectories as required. A common use of this target is to copy static files (documentation, HTML pages, and JSP pages) from the source directory to the build directory. When executed, this target will only create directories if they do not exist, and only copy files if the destination file does not exist, or the source version of the file is newer. This target is generally invoked indirectly, by virtue of a depends attribute on some other task.
  
  
• prepare - このターゲットは必要なサブディレクトリを生成し、 buildディレクトリを"準備"します。 このターゲットの標準的な使用法は、静的ファイル (ドキュメント、HTMLページ、JSPページ) をソースディレクトリからビルドディレクトリにコピーすることです。 実行された時に、このターゲットはそれが存在しない時にディレクトリを作成し、 目的のファイルが存在しない時やソースバージョンの方が新しい時にファイルをコピーするだけです。 このターゲットは一般的に他のタスクのdepends 属性によって間接的に呼び出されます。
  
  
• compile - This target is used to compile any source code that has been changed since the last time compilation took place. The resulting class files are created in the build directory, so that they can be executed when the application is deployed. Because this command is executed so often during development, it is normally made the "default" target so that a simple ant command will execute it.
  
  
• compile - このターゲットは、 最後にコンパイルを実行した時から変更されたすべてのソースコードをコンパイルするために使用されます。 アプリケーションが配備された時に実行することができるように、 結果としてできるクラスファイルはbuildディレクトリに生成されます。 このコマンドは開発中にとても頻繁に実行されるため、 単にantコマンドで実行できるように "default"ターゲットするのが普通です。
  
  
• all - This target is a short cut for running the clean target, followed by the compiile target. Thus, it guarantees that you will recompile the entire application, to ensure that you have not unknowingly introduced any incompatible changes.
  
  
• all - このターゲットは cleanターゲット、続けてcompiile ターゲットを実行するショートカットです。 よって、 知らず知らずの内に矛盾した変更を取り入れてしまうことが無いことを確認するために、 アプリケーション全体を再コンパイルすることが保証されるでしょう。
  
  
• deploy - This target is used to install your application into a servlet container (we will continue to use Tomcat in our examples) so that it can be tested. If your application requires external JAR files, they will be copied to the /WEB-INF/lib directory at deployment time.
  
  
• deploy - このターゲットはアプリケーションがテスト出来るように servlet コンテナ(例の中では Tomcat を使いつづけます) にインストールするのに使われます。 もしアプリケーションが外部 JAR ファイルを要求するなら、配備時に /WEB-INF/libディレクトリにコピーされるでしょう。
  
  
• javadoc - This target creates Javadoc API documentation for the Java classes in this web application. The example build.xml file assumes you want to include the API documentation with your app distribution, so it generates the docs in a subdirectory of the dist directory. Because you normally do not need to generate the Javadocs on every compilation, this target is usually a dependency of the dist target, but not of the compile target.
  
  
• javadoc - このターゲットはウェブアプリケーション内の Java クラス用の Javadoc API ドキュメントを生成します。 例のbuild.xmlファイルではアプリケーション配布物に API ドキュメントを含めたいものとしていますので、dist ディレクトリのサブディレクトリ内に docs を生成します。 コンパイル毎に Javadoc を生成する必要は普通無いので、 このターゲットは通常はcompileターゲットに依存せず distターゲットに依存します。
  
  
• dist - This target creates a distribution directory for your application, including any required documentation, the Javadocs for your Java classes, and a web application archive (WAR) file that will be delivered to system administrators who wish to install your application. Because this target also depends on the deploy target, the web application archive will have also picked up any external dependencies that were included at deployment time.
• dist - このターゲットはアプリケーションの配布物ディレクトリを生成します。 これには要求されるドキュメント、Java クラス用の Javadoc、 そしてアプリケーションをインストールしたいと願うシステム管理者に届けられるウェブアプリケーションアーカイブ(WAR)ファイルが含まれます。 このターゲットは常にdeployターゲットに依存するので、 ウェブアプリケーションアーカイブは配備時に含められた任意の外部依存を持つことになります。