h1. プロジェクトの立ち上げ

h2. <a>はじめに</a>

このチュートリアルでは、実際の web アプリケーションを始めから終わりまでコーディングすることによって、Play フレームワークについて学びます。このアプリケーションでは、Play アプリケーション開発の優れた実践を紹介する間、実際のプロジェクトで必要とするあらゆるものを使っていきたいと思います。

このチュートリアルは、いくつかの独立している部分に分かれています。それぞれの部分は、より複雑な特徴を紹介して、実際のプロジェクトが必要とするすべてのことを提供します: バリデーション、エラー処理、完全にセキュアなフレームワーク、自動化されたテストスイート、輝く web インタフェース、管理領域など。

p(note). このチュートリアルに含まれる **すべてのコード** は、あなたのプロジェクトに使用することができます。コードの断片をコピーアンドペーストするか、または全体をまるごと流用することを推奨します。

h2. <a>プロジェクト</a>

チュートリアルには、よくあるブログエンジンの作成を選びました。これは、とても想像的な選択ではありませんが、モダンな web アプリケーションで必要な機能のほとんどの部分を調査することができます。

チュートリアルをちょっと面白くするために、数人のユーザを異なる役割 (投稿者、管理者) で管理します。

このブログエンジンプロジェクトを **yabe** と呼ぶことにします。

!images/guide1-0!

p(note). このチュートリアルはサンプルアプリケーションとしても配布されています。最終的なコードは Play インストール先の @samples-and-tests/yabe@ ディレクトリにあります。

h2. <a>前提条件</a>

何よりも、まず Java がインストールされていることを確認してください。Play は **Java 5 以降** を必要とします。

私たちはコマンドラインを多用するので、Unix ライクな OS のほうが良いでしょう。もし Windows 上で動かす場合でも、問題なく動作します。ただコマンドプロンプトでいくつかのコマンドを実行しなければならないだけです。

このチュートリアルは、あなたが Java と Web 開発 (特に HTML, CSS, およびJavaScript) に関する知識を既に持つものとします。しかしながら、Java Enterprise Edition (JEE) のあらゆるコンポーネントに関する深い知識は必要としません。Play は 'フルスタック' な Java フレームワークであり、必要な Java API のすべての部分を提供するか、またはカプセル化します。JPA エンティティマネージャを設定する方法や、あるいは JEE コンポーネントをデプロイする方法を知っている必要はありません。

もちろんテキストエディタも必要です。もし Eclipse や Netbeans のようなフル機能の Java IDE に慣れているなら、もちろんそれを使用できます。しかし、Play であれば、Textmate, Emacs または VI のようにシンプルなテキストエディタでも楽しく作業できます。これは、フレームワーク自身がコンパイルとデプロイを管理するからです。間もなくその様子をご覧に入れます...

このチュートリアルの後半で、Lighttpd と MySql を使い、'production' モードの Play アプリケーションをデプロイする方法を示します。しかし、Play はこれらのコンポーネントなしでも動作することができるので、もしこれらをインストールできなくても問題ありません。

h2. <a>Play フレームワークのインストール</a>

インストールは非常に簡単です。 ダウンロードページから最新のバイナリパッケージをダウンロードして、任意のパスに展開してください。

p(note). Windows を使用している場合、パスにスペースを含めないのは一般的に良い案です。例えば、 @c:\play@ は @c:\Documents And Settings\user\play\@ よりも良い選択です。

効率的に作業するためには、作業パスに Play ディレクトリを加える必要があります。パスを追加することで、コマンドプロンプトでただ @play@ とタイプすれば、play ユーティリティを使用できるようになります。正常にインストールが完了したことを確認するには、新しいコマンドラインを開いて  @play@ とタイプしてください; このコマンドは Play の基本的なヘルプを表示します。

h2. <a>プロジェクトの作成</a>

Play が正しくインストールされたので、いよいよブログアプリケーションを作成します。Play アプリケーションの作成は、play コマンドラインユーティリティによって完全に管理されており、とても簡単です。play コマンドラインユーティリティは、すべての Play アプリケーション間において標準的なプロジェクトレイアウトを割り当てます。

新しいコマンドラインを開いて、以下をタイプしてください:

bc. ~$ play new yabe

アプリケーションの完全な名前を入力するプロンプトが表示されます。 **Yet Another Blog Engine** とタイプしてください。

!images/guide1-1!

@play new@ コマンドは @yabe/@ ディレクトリを新規に作成し、一連のファイルやディレクトリをここに追加します。以下は、もっとも重要なディレクトリです:

@app/@ ディレクトリはアプリケーションの中心部であり、モデル、コントローラ、およびビュー用のディレクトリに分けられています。 他の Java パッケージを含むこともできます。 app/ ディレクトリは @.java@ ソースファイルを保存するディレクトリです。

@conf/@ ディレクトリは、特に重要な @application.conf@ ファイル、ルーティングを定義する @routes@ ファイル、国際化のための @messages@ ファイルなど、アプリケーションを設定する全てのファイルを保存します。

@lib/@ は標準的な @.jar@ ファイルとしてパッケージされたオプションの Java ライブラリを保存します。

@public/@ は JavaScript, スタイルシート、および画像ディレクトリを含む公的に利用可能なリソースを保存します。

@test/@ には、すべてのアプリケーションテストを保存します。テストは Java の JUnit として書かれるか、または Selenium テストとして書かれます。

p(note). **Play は UTF-8** 唯一のエンコーディングとして使用するので、これらのディレクトリでホスティングされたすべてのテキストファイルが UTF-8 でエンコードされていることは非常に重要です。テキストエディタの設定がこれに従っていることを確認してください。

もし、あなたが熟練した Java 開発者であれば、すべての .class ファイルがどこに行ってしまったのか不思議に思うことでしょう。実は、どこにもありません: Play はいかなる class ファイルも使用せず、Java ソースファイルを直接読み込みます。舞台裏では、実行中の Java ソースをコンパイルするために Eclipse コンパイラを使用しています。

これは、開発工程において 2 つの非常に重要なことを可能にします。最初の 1 つは、Play があなたが Java ソースファイルに加えたいかなる変更をも検出して、実行時にそれを自動的にリロードするということです。 2 番目は、Java の例外が発生したとき、Play がソースコードそのものを示しながらより良いエラーレポートを作成するということです。

p(note). 実際のところ、Play はアプリケーションの @/tmp@ ディレクトリにバイトコードのキャッシュを保持しますが、これは大きなアプリケーションの再起動を高速化するためだけのものです。必要であれば、 @play clean@ コマンドを使うことでこのキャッシュを破棄することができます。

h2. <a>アプリケーションの実行</a>

ここまで来れば、新しく作成したアプリケーションを試してみることができます。コマンドラインに戻り、新たに作成された @yabe/@ ディレクトリに移動したら、 @play run@ とタイプしてください。Play がアプリケーションをロードし、9000 番ポートで Web サーバを起動します。

ブラウザから "http://localhost:9000":http://localhost:9000 を開くことで、新しいアプリケーションを閲覧することができます。新しいアプリケーションは、それが首尾よく作成されたこと示す標準のウェルカムページを表示します。

!images/guide1-2!

新しいアプリケーションがどのようにしてこのページを表示するのかを見てみましょう。

アプリケーションのエントリーポイントは @conf/routes@ ファイルです。このファイルはアプリケーション上のアクセス可能な URL をすべて定義します。 生成された routes ファイルを開くと、最初の 'route' が確認できるでしょう:

bc. GET		/			Application.index

この設定は、web サーバが @/@ パスに対する **GET** リクエストを受け取った場合には @Application.index@ という Java メソッドをコールしなければならないことを Play に伝えています。この場合、 @controllers@ パッケージが暗黙的に指定されるので、 @Application.index@ は @controllers.Application.index@ のショートカットです。

スタンドアロンな Java アプリケーションを作成するとき、一般的に以下のようなメソッドを定義することで単一のエントリーポイントを設けます:

bc. public static void main(String[] args) {
  ... 
}

Play アプリケーションには、各 URL あたり 1 つのエントリーポイントがあります。 私たちは、これらのメソッドを @Action@ メソッドと呼びます。アクションメソッド @controller@ と呼ぶ特別なクラスで定義されます。

@controllers.Application@ コントローラがどのようなものか見てみましょう。 @yabe/app/controllers/Application.java@ ソースファイルを開いてください:

bc. package controllers;
 
import play.mvc.*;
 
public class Application extends Controller {
 
	public static void index() {
		render();
	}
 
}

コントローラクラスは @play.mvc.Controller@ クラスを継承します。このクラスは index アクションで使用した @render()@ メソッドのような、コントローラ向けの便利なメソッドを提供します。

index アクションは @public static void@ なメソッドとして定義されています。アクションメソッドはこのようにして定義されます。コントローラクラスは決してインスタンス化されないので、アクションメソッドは static です。アクションメソッドは、フレームワークがリクエストされた URL にレスポンスできるよう public として宣言されます。アクションメソッドは常に void を返します。

デフォルトの index アクションはシンプルです: Play にテンプレートをレンダリングするよう指示する @render()@ メソッドをコールします。テンプレートの使用は HTTP レスポンスを生成する最も一般的な (しかし、唯一ではない) 方法です。

テンプレートは @/app/views@ ディレクトリに存在するシンプルなテキストファイルです。今回はテンプレートを指定しなかったので、このアクション用のデフォルトのテンプレートが使用されます: @Application/index.html@ です。

テンプレートがどのようなものかを見るには、 @yabe/app/views/Application/index.html@ ファイルを開いてください:

bc. #{extends 'main.html' /}
#{set title:'Home' /}
 
#{welcome /}

テンプレートの内容はとても簡単に見えます。実際、ここにあるものはすべて Play のタグです。Play タグは JSP タグに似ています。 @#{welcome /}@ が、ブラウザに表示されたウェルカムメッセージを生成しています。

@#{extends /}@ タグは、このテンプレートが @main.html@ と呼ばれる別のテンプレートを継承することを Play に伝えます。テンプレートの継承は、共通化された部分を再利用することで複雑なウェブページを作成することができる強力な概念です。

@yabe/app/views/main.html@ テンプレートを開いていてください:

bc. <!DOCTYPE html>
<html>
  <head>
    <title>#{get 'title' /}</title>
    <meta charset="${_response_encoding}">
    <link rel="stylesheet" media="screen"
      href="@{'/public/stylesheets/main.css'}">
    #{get 'moreStyles' /}
    <link rel="shortcut icon" type="image/png"
      href="@{'/public/images/favicon.png'}">
    <script type="text/javascript" charset="${_response_encoding}"
      src="@{'/public/javascripts/jquery-1.5.2.min.js'}"></script>
    #{get 'moreScripts' /}
  </head>
  <body>
    #{doLayout /}
  </body>
</html>

下にある **#{doLayout /}** タグに気付きましたか？ここに **Application/index.html** の内容が挿入されます。

コントローラファイルを編集することで、Play がどのようにして自動的にこれをロードするのか試してみることができます。 @yabe/app/controllers/Application.java@ ファイルをテキストエディタで開いて、 @render()@ 呼び出しの後に続くセミコロンを削除することで間違いを埋め込んでください:

bc. public static void index() {
    render()
}

ブラウザに戻りページをリフレッシュしてください。Play が変更を検出して Application コントローラをリロードしようとする様子を見ることができます。しかし、間違いがあるためコンパイルエラーが発生します。

!images/guide1-3!

OK, エラーを修正して、実際の変更を加えましょう:

bc. public static void index() {
    System.out.println("Yop");
    render();
}

今度は、Play は適切にコントローラをリロードし、JVM 上の古いコードを置き換えました。 @/@ URL への各リクエストは、コンソールに 'Yop' メッセージを出力します。

この役に立たない行を取り除いて、歓迎のメッセージを置き換えるために @yabe/app/views/Application/index.html@ テンプレートを編集することができます:

bc. #{extends 'main.html' /}
#{set title:'Home' /}
 
<h1>A blog will be there</h1>

Java コードの変更と同じように、変更内容を確認するには、ただブラウザでページをリフレッシュするだけです。

p(note). いよいよブログアプリケーションのコーディングを始めました。このままテキストエディタで作業し続けることも、Eclipse や NetBeans のような Java IDE でプロジェクトを開くことも可能です。Java IDE をセットアップする場合は、 "お好みの IDE を設定しよう":ide をチェックしてください。

h2. <a>データベースのセットアップ</a>

コーディングを始める前にもうひとつ。ブログエンジンにはデータベースが必要です。開発目的のために Play には H2 と呼ばれるスタンドアロンの SQL データベース管理システムを同梱しています。より堅牢なデータベースが必要になって切り替える前までは、これが開発を開始するにはベストな方法です。インメモリデータベースか、またはアプリケーションを再起動してもデータを保持するファイルシステムデータベースのいずれかを選ぶこともできます。

初めのうちは、アプリケーションモデルを何度もテストし、変更します。このため、常にフレッシュなデータセットで起動するインメモリデータベースはより良い方法です。

データベースを設定するためには、 @yabe/conf/application.conf@ ファイルを開き、次の行を非コメント化します:

bc. db=mem

見て分かる通り、どのような JDBC 対応データベースについても、そしてコネクションプールの設定すらも容易に構成することができます。

p(note). このチュートリアルはインメモリデータベースを使って動作するように設計されています。他のデータベースを JPA を使って操作する手順はこのチュートリアルには含まれていません。

さて、ブラウザに戻ってページをリフレッシュしてください。Play は自動的にデータベースを起動します。アプリケーションログに次の行があることを確認してください:

bc. INFO  ~ Connected to jdbc:h2:mem:play

h2. <a>バージョン管理システムを使った変更管理</a>

プロジェクトに従事する場合、ソースコードをバージョン管理システム (VCS) に保存することを強くお勧めします。VCS は、変更が何かを壊した場合に以前のバージョンに戻ることや、複数人で作業すること、そしてアプリケーションの連続したバージョンすべてにアクセスすることを可能にします。

Play アプリケーションを VCS に格納する場合、 @tmp/@, @modules/@, @lib/@, @test-result/@ そして @logs/@ ディレクトリを除外することは重要です。

Eclipse と @play eclipsify@ コマンドを使っている場合、 @.classpath@ と @eclipse/@ も除外すべきです。

h3. <a name="bazaar">Bazaar</a>

ここでは例として Bazaar を使用します。"Bazaar":http://bazaar-vcs.org/ は分散バージョン管理システムです。

Bazaar のインストールはこのチュートリアルの範囲を超えていますが、どのようなシステム上においても非常に簡単です。Bazaar をインストールしたら、ブログディレクトリに戻り、以下をタイプしてアプリケーションのバージョン管理を初期化してください:

bc. $ bzr init
$ bzr ignore tmp
$ bzr ignore modules
$ bzr ignore lib
$ bzr ignore test-result
$ bzr ignore logs

これでブログエンジンの最初のバージョンをコミットできます:

bc. $ bzr add
$ bzr commit -m "YABE initial version"

h3. <a>Git</a>

"Git":http://git-scm.com は、もうひとつの分散バージョンコントロールシステムです。詳細は Git のドキュメントを参照してください。

アプリケーションのルートディレクトリに git 作業リポジトリを作成します:

bc. $ git init

以下の内容を含む @.gitignore@ ファイルを作成します:

bc. /tmp
/modules
/lib
/test-result
/logs

アプリケーションのコンテンツを追加し、コミットします:

bc. $ git add .
$ git commit -m "YABE initial version"

バージョン 1 がコミットされ、我々のプロジェクトのための信頼できる基盤ができました。

p(note). %(next)"はじめてのモデル":guide2% に進みましょう。
