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"));

}