play2.0文檔-面向java開發者(2)

HTTP routing

The built-in HTTP router (內置的HTTP router)

The router is the component that translates each incoming HTTP request to an action call (a static, public method in a controller class).

router 組件的功能是把收到的HTTP request 轉換成對action的調用(controller 裏的一個 static，public 方法).

An HTTP request is seen as an event by the MVC framework. This event contains two major pieces of information:

一個HTTP請求被MVC框架看做是一個事件，這個事件包含兩個主要的信息：

• the request path (such as /clients/1542, /photos/list), including the query string.
• the HTTP method (GET, POST, …).
• 
  
• 請求路徑（例如 /clients/1542, /photos/list),包括查詢字符串.
• HTTP 方法(GET, POST, ...).

Routes are defined in the conf/routes file, which is compiled. This means that you’ll see route errors directly in your browser:

Routes 是在 conf/routes 文件中定義的，它會被編譯，也就是說你能夠直接在瀏覽器中看到route的錯誤。

The routes file syntax (routes 文件語法）

conf/routes is the configuration file used by the router. This file lists all of the routes needed by the application. Each route consists of an HTTP method and URI pattern associated with a call to an action method.

conf/routes 是router使用的配置文件。這個文件列出了應用程序所須要的全部routes。每一個route由一個HTTP方法和一個與action調用相關聯的  URI pattern  組成。

Let’s see what a route definition looks like:

來看一下route是怎樣定義的：

GET /clients/:id controllers.Clients.show(id: Long) 

Note that in the action call, the parameter type comes after the parameter name, like in Scala.

注意在對action的調用中，參數類型在參數名稱的後面，這有點像scala的定義方式。

Each route starts with the HTTP method, followed by the URI pattern. The last element of a route is the call definition.

每一個route的開頭是 HTTP方法，後面跟着 URI pattern ，最後面定義了會調用哪一個action。

You can also add comments to the route file, with the # character:

你也能夠在route文件中添加評論，用 # 來標識:

# Display a client. GET /clients/:id controllers.Clients.show(id: Long) 

The HTTP method

The HTTP method can be any of the valid methods supported by HTTP (GET, POST,PUT, DELETE, HEAD).

HTTP方法能夠是HTTP支持的任何一種有效的方法(GET, POST,PUT, DELETE, HEAD).

The URI pattern

The URI pattern defines the route’s request path. Some parts of the request path can be dynamic.

URI pattern表示route的請求路徑. 這個請求路徑的某些部分能夠是動態的。

Static path(靜態路徑)

For example, to exactly match GET /clients/all incoming requests, you can define this route:

例如，爲了提取與 GET /clients/all 相匹配的請求，你能夠這樣定義：

GET /clients controllers.Clients.list()

Dynamic parts（動態部分）

If you want to define a route that, say, retrieves a client by id, you need to add a dynamic part:

若是你想定義一個經過id來獲取一個client的路由，你就須要添加一個動態的部分：

GET /clients/:id controllers.Clients.show(id: Long) 

Note that a URI pattern may have more than one dynamic part.

注意一個URI pattern 能夠有不止一個動態部分.

The default matching strategy for a dynamic part is defined by the regular expression [^/]+, meaning that any dynamic part defined as :id will match exactly one URI path segment.

對於動態部分的默認匹配策略是由正則表達式 [^/]+ 定義的，這意味着任何被定義成 :id 的動態部分將會被準確的匹配到一個URI的路徑部分。

Dynamic parts spanning several /（跨越多個/的動態部分）

If you want a dynamic part to capture more than one URI path segment, separated by forward slashes, you can define a dynamic part using the *id syntax, which uses the .* regular expression:

若是你想用一個動態部分來捕獲多個獨立的URI路徑段， 你可使用正則表達式的*id 語法來定義一個動態部分：

GET /files/*name controllers.Application.download(name) 

Here, for a request like GET /files/images/logo.png, the name dynamic part will capture the images/logo.png value.

對於一個像 GET /files/images/logo.png 的請求來講，name的動態部分將會捕獲 images/logo.png 這個值

Dynamic parts with custom regular expressions

自定義的正則表達式動態部分

You can also define your own regular expression for a dynamic part, using the$id<regex> syntax:

你也可使用$id<regex> 語法來爲動態部分定義本身的正則表達式：

GET /clients/$id<[0-9]+> controllers.Clients.show(id: Long) 

Call to action generator method

調用action的產生器方法

The last part of a route definition is the call. This part must define a valid call to an action method.

route定義的最後一部分是調用。這部分必須定義一個有效的對action方法的調用。

If the method does not define any parameters, just give the fully-qualified method name:

若是方法沒有定義任何參數，就只需給出一個合法的方法名：

GET / controllers.Application.homePage()

If the action method defines parameters, the corresponding parameter values will be searched for in the request URI, either extracted from the URI path itself, or from the query string.

若是action方法定義了參數，相對應的參數值須要從請求的URI中尋找，或者從URI路徑自己提取，或者從查詢字符串中提取。

# Extract the page parameter from the path. # i.e. http://myserver.com/index GET /:page controllers.Application.show(page)

Or:

# Extract the page parameter from the query string. # i.e. http://myserver.com/?page=index GET / controllers.Application.show(page)

Here is the corresponding show method definition in the controllers.Applicationcontroller:

這是一個 在 controllers.Application 中定義的與show方法對應的controller

public static Result show(String page) { String content = Page.getContentOf(page); response().setContentType("text/html"); return ok(content); }

Parameter types（參數類型）

For parameters of type  String, the parameter type is optional. If you want Play to transform the incoming parameter into a specific Scala type, you can add an explicit type:

對於String類型，參數類型是可選的。若是你想把收到的參數轉換成指定的scala類型，你能夠顯示的添加上。

GET /client/:id controllers.Clients.show(id: Long)

Then use the same type for the corresponding action method parameter in the controller:

而且在controller中相應的action方法參數也須要使用相同的類型。

public static Result show(Long id) {

Client client = Client.findById(id); 

return ok(views.html.Client.show(client));

}

Note: The parameter types are specified using a suffix syntax. Also The generic types are specified using the [] symbols instead of <>, as in Java. For example, List[String] is the same type as the Java List<String>.

注意：參數類型是使用後綴語法定義的，泛型是使用[] 符號定義，而不是像java同樣使用<>定義。例如，

List[String]和Java  List<String>是同一種類型

Parameters with fixed values(帶有固定值的參數)

Sometimes you’ll want to use a fixed value for a parameter:

有時候你可能想使用固定值做爲參數：

# Extract the page parameter from the path, or fix the value for / GET / controllers.Application.show(page = "home") GET /:page controllers.Application.show(page)

Parameters with default values(帶有默認值的參數)

You can also provide a default value that will be used if no value is found in the incoming request:

你也能夠提供一個默認值，若是收到的請求中沒找到參數的值就會使用這個默認值。

# Pagination links, like /clients?page=3 GET /clients controllers.Clients.list(page: Integer ?= 1)

Routing priority (路由優先級)

Many routes can match the same request. If there is a conflict, the first route (in declaration order) is used.

許多routes能夠匹配相同的請求，若是有衝突的話就會使用聲明中的第一個route。

Reverse routing(反轉路由)

The router can be used to generate a URL from within a Java call. This makes it possible to centralize all your URI patterns in a single configuration file, so you can be more confident when refactoring your application.

router能夠根據一個java調用來產生一個URL。這使得在一個配置文件裏集中配置全部你的URI pattern變得可能，這樣，當你作重構是就會更加自信。

For each controller used in the routes file, the router will generate a ‘reverse controller’ in the routes package, having the same action methods, with the same signature, but returning a play.mvc.Call instead of a play.mvc.Result.

對於routes文件中的每個controller，router都會在 routes 包裏生成一個'反轉controller', 它有相同的action方法，相同的特徵，可是返回的倒是一個 play.mvc.Call而不是 play.mvc.Result。

The play.mvc.Call defines an HTTP call, and provides both the HTTP method and the URI.

 play.mvc.Call 定義了一個HTTP 調用，並且還提供了HTTP方法和URI.

For example, if you create a controller like:

舉個例子，若是你建立一個像這樣的controller：

 public static Result hello(String name) {
 return ok("Hello " + name + "!");
 }
}
package controllers; import play.*; import play.mvc.*; public class Application extends Controller {  

And if you map it in the conf/routes file:

而後你在conf/routes文件中配置映射關係：

# Hello action GET /hello/:name controllers.Application.hello(name)

You can then reverse the URL to the hello action method, by using thecontrollers.routes.Application reverse controller:

你就能夠經過使用controllers.routes.Application 反轉 controller把 URL反轉到 hello action 方法

// Redirect to /hello/Bob 

public static Result index() { 

  return redirect(controllers.routes.Application.hello("Bob"));

}