指南, 教程 & 参考手册

Browse

Contents

好书推荐

国内书籍(将于2012年出版)

国外书籍(电子图书)

控制器层(Controllers)

本章译者:@freewind

业务逻辑代码通常位于模型(model)层。客户端(比如浏览器)无法直接调用其中的代码,所以模型对象提供的功能,必须作为资源以URI方式暴露给外部。

客户端使用HTTP协议来操作这些资源,从而调用了内部的业务逻辑。但是,这种从资源到模型之间的映射是单向的:我们可以根据需要提供不同粒度的资源,可以虚拟出一些资源,还可以给某些资源起别名...

Controller层就是专门做这件事的:在模型层与传输层之间搭起一座桥梁。它使用与模型层同一种语言,以便访问和修改模型对象,但同时它又跟HTTP接口一样,是面向请求(Request)和响应(Response)的。

Controller层减少了HTTP与模型层之间的“阻抗不匹配”。

注意

不同的模型方案使用了不同的策略。有一些可以让我们直接访问模型对象,比如EJB或者Corba协议,它们使用RPC(远程过程调用)。这种交互方式与web很难兼容。

另一些技术如SOAP,尝试通过Web来访问模型层,但它也是一种PRC风格的协议,只是以HTTP为传输协议。它也不是一种程序协议。

Web的理念在根本上与面向对象不同,所以我们需要一个层来协调。

Controller综述

一个Controller就是一个位于 controllers 包中的类,其继承于 play.mvc.Controller

示例:

package controllers;
 
import models.Client;
import play.mvc.Controller;
 
public class Clients extends Controller {
 
    public static void show(Long id) {
        Client client = Client.findById(id);
        render(client);
    }
 
    public static void delete(Long id) {
        Client client = Client.findById(id);
        client.delete();
    }
 
}

Controller中每一个public static方法都被称为一个action。它的签名形如:

public static void action_name(params...);

你可以在action的方法签名中定义各种参数。Play会自动从相应的HTTP参数中,取出对应的值赋过去(并进行恰当的转换),这一点非常方便。

通常一个action不需要返回值。当我们在action中调用了一个能产生“结果”的方法后,action就退出了。在本例中, render(…) 就是一个显示一个模板的可产生结果的方法。

获取HTTP参数

HTTP请求中可包含数据,这些数据可位于:

  • URI路径中: 如 /clients/1541, 1541就是一个动态产生的参数.
  • Query String: /clients?id=1541.
  • request body: 如果提交了一个HTML表彰,将request body中将包含以 x-www-urlform-encoded 方式转换过的数据。

对于这些情况,Play都可以取得数据,并生成一个 Map<String, String[]> 。Key是参数名,来源于:

  • 在conf/routes文件中定义的规则中的动态参数名
  • Query String中的name=value
  • 通过表单提交的数据的name.

使用参数map

在所有的Controller类中都可以直接使用 params 这个对象。它是在 play.mvc.Controller 中定义的。这个对象中,包含了当前请求的所有数据。

示例:

public static void show() {
    String id = params.get("id");
    String[] names = params.getAll("names");
}

你还可以转换参数值的类型:

public static void show() {
    Long id = params.get("id", Long.class);
}

其实,还有更好的办法来转换 :)

直接利用action方法的参数类型定义来转换

我们可以直接从action方法的参数定义中,直接拿到对应的参数值。方法中的参数名必须跟http传过来的参数名相同。

比如,对于如下的URL:

/clients?id=1451

我们可以定义一个包含 id 参数的action:

public static void show(String id) {
    System.out.println(id); 
}

我们还可以使用其它的类型,play会自动进行转换:

public static void show(Long id) {
    System.out.println(id);  
}

如果同一个参数有多个值,还可以把它声明为数组:

public static void show(Long[] id) {
    for(String anId : id) {
        System.out.println(anid); 
    }
}

甚至集合:

public static void show(List<Long> id) {
    for(String anId : id) {
        System.out.println(anid); 
    }
}

这一功能非常方便,其它的框架都很少提供(有一些提供了,但要求每个参数前都要加一个annotation,不太方便)。

内部原理是,Play会对每个action进行扫描,得到其参数信息(包括类型与参数名)。能过反射很容易得到参数类型,但得不到参数名,因为javac在编译java代码时,会忽略参数名信息。而Play内置了eclipse的编译器,并在编译时打开相关选项以记录参数名信息,所以才能成功取到。

异常

如果action方法中定义的某个参数,在http请求中找不到对应的数据,则将会把它设为默认值(对象类型设为null,基础数字类型设为0,boolean类型设为false)。如果找到了,但是其值无法转换为指定的Java类型,则会将这一错误记录在validation对象中,并使用默认值代替。

HTTP to Java 高级绑定

简单类型

Java中所有基础和常用类型,都可以自动绑定:

int, long, boolean, char, byte, float, double, Integer, Long, Boolean, Char, String, Byte, Float, Double.

注意如果某个参数HTTP请求中没有提供,或者自动转换失败,则Object类型会被设为null,而基础类型会被设为它们的默认值。

Date

如果一个日期格式如下,则它可以自动转换并绑定:

  • yyyy-MM-dd’T’hh:mm:ss’Z' // ISO8601 + timezone
  • yyyy-MM-dd’T’hh:mm:ss" // ISO8601
  • yyyy-MM-dd
  • yyyyMMdd’T’hhmmss
  • yyyyMMddhhmmss
  • dd'/‘MM’/'yyyy
  • dd-MM-yyyy
  • ddMMyyyy
  • MMddyy
  • MM-dd-yy
  • MM'/‘dd’/'yy

使用@As注解,我们可以指定日期格式。

例如:

archives?from=21/12/1980
public static void articlesSince(@As("dd/MM/yyyy") Date from) {
    List<Article> articles = Article.findBy("date >= ?", from);
    render(articles);
}

我们可还以对不同的语种定义不同的格式,例如:

public static void articlesSince(@As(lang={"fr,de","*"}, 
        value={"dd-MM-yyyy","MM-dd-yyyy"}) Date from) {
    List<Article> articles = Article.findBy("date >= ?", from);
    render(articles);
}

在这个例子中,我们将法国和德国的日期定义为 dd-MM-yyyy ,其它都为 MM-dd-yyyy. 注意语种可用逗号分隔。注意参数lang的个数必须与value的个数相等。

如果没有使用@As注解,则Play将使用你的区域对应的默认日期格式。我们可在“conf/application.conf”中使用“date.format”为key来配置该格式.

日历(Calendar)

Calendar的绑定与date几乎完全一样,除了play将会根据你的区域设置选择相应的Calendar对象。@Bind注解也可在这里使用。

文件(File)

在Play中处理文件上传非常简单。使用经 multipart/form-data 编码的请求将文件post到服务器端,同时使用 java.io.File 来获取文件:

public static void create(String comment, File attachment) {
    String s3Key = S3.post(attachment);
    Document doc = new Document(comment, s3Key);
    doc.save();
    show(doc.id);
}

Play将先取得上传的文件,保存在临时目录下,并使用上传的文件名。当这个request结束后,该文件将被删除,所以我们必须将它拷贝到一个安全的目录中,否则就找不到了。

上传的文件的MIME类型通常应该在HTTP request的head中,以 Content-type 方式指定。但当我们通过浏览器上传文件时,一些不常见类型的文件不会指定。在这种情况下,我们可以使用 play.libs.MimeTypes 类将该文件的后缀名映射到一个MIME类型上。

String mimeType = MimeTypes.getContentType(attachment.getName()); 

play.libs.MimeTypes 类在 $PLAY_HOME/framework/src/play/libs/mime-types.properties 中以文件的后缀为来寻找对应的MIME类型。

你也可以 通过 自定义MIME类型 来增加你自己的类型。

数组或集合

所有支持的类型,都可以通过数组或集合的形式取得:

public static void show(Long[] id) {
    …
}

或者:

public static void show(List<Long> id) {
    …
}

或者:

public static void show(Set<Long> id) {
    …
}

Play还可以处理像Map<String, String>这样的绑定:

public static void show(Map<String, String> client) {
    …
}

一个如下的query string:

?client.name=John&client.phone=111-1111&client.phone=222-2222

将会把变量client绑定到一个含有两个元素的map上。第一个元素的key是 name ,值是 John ,第二个key是 phone 值是 111-1111, 222-2222.

POJO对象绑定

Play还可以使用简单的命名约定将参数绑定到一个pojo对象上。

public static void create(Client client ) {
    client.save();
    show(client);
}

可以使用像下面这样的query string,来调用该action以创建一个client对象:

?client.name=Zenexity&client.email=contact@zenexity.fr

Play创建一个Client的实例,然后将HTTP参数中与Client对象属性同名的值赋过去。无法处理的参数将被安全的忽略,类型不匹配的也将安全忽略。

参数绑定是递归的,我们可以通过query string来创建一个完全的对象图:

?client.name=Zenexity
&client.address.street=64+rue+taitbout
&client.address.zip=75009
&client.address.country=France

如果我们想更新一列对象,我们可以使用数组形式来引用对象的ID。举例来说,假设Client模型有一列Customer模型,并声明为 List<Customer> customers 形式。为了更新这一列Customers,我们应该提供一个如下的query string:

?client.customers[0].id=123
&client.customers[1].id=456
&client.customers[2].id=789

JPA对象绑定

我们可以将一个JPA对象与HTTP自动绑定起来。

我们可以在HTTP参数中提供 user.id 字段。当Play发现这个字段时,它会先到数据库中取出相应的实例,然后把HTTP请求中其它的参数赋过去。所以我们可以直接save它。

public static void save(User user) {
    user.save(); // ok with 1.0.1
}

我们可以使用同样的方式来更新完整的对象图,但是必须对每一个子对象提供ID:

user.id = 1
&user.name=morten
&user.address.id=34
&user.address.street=MyStreet 

自定义绑定

绑定系统还支持自定义。

@play.data.binding.As

首先要讲的是@play.data.binding.As这个新注解,使用它,我们可以配置一个绑定。看下面的例子,我们使用它来指定一个Date的格式(该格式将被 DateBinder 使用):

public static void update(@As("dd/MM/yyyy") Date updatedAt) {
    …
}

@As注解同样支持国际化,我们可以这样使用:

public static void update(
        @As(
            lang={"fr,de","en","*"},
            value={"dd/MM/yyyy","dd-MM-yyyy","MM-dd-yy"}
        )
        Date updatedAt
    ) {
    …
}

@As注解可以与所有支持它的binder一起使用,包括你自己的定义的。例如,使用 ListBinder:

public static void update(@As(",") List<String> items) {
    …
}

它将会把一个以逗号分隔的字符串绑定到一个 List 上。

@play.data.binding.NoBinding

新的@play.data.binding.NoBinding注解允许我们定义一些“不应该被绑定”的字段,以防出现安全问题。例如:

public class User extends Model {
    @NoBinding("profile") public boolean isAdmin;
    @As("dd, MM yyyy") Date birthDate;
    public String name;
}
 
public static void editProfile(@As("profile") User user) {
    …
}

在这种情况下, 在 editProfile action中,就算某个居心不良的用户通过伪造请求提交了一个包含 user.isAdmin=true 的字段, isAdmin 字段也不会被绑定.

play.data.binding.TypeBinder

@As 注解同样允许我们自定义一个完整的binder. 一个自定义的binder是 TypeBinder 的子类,我们可以在自己的项目中定义它。例如:

public class MyCustomStringBinder implements TypeBinder<String> {
public Object bind(String name, Annotation[] anns, String value, Class clazz) { return "!!"; } }

我们可以在任意一个action中使用它:

public static void anyAction(@As(binder=MyCustomStringBinder.class) 
String name) {
    …
}

@play.data.binding.Global

我们还可以自定义一个全局的binder来处理某一个特定的类型。比如,我们给 java.awt.Point 类定义了一个这样的binder:

@Global
public class PointBinder implements TypeBinder<Point> {
public Object bind(String name, Annotation[] anns, String value, Class class) { String[] values = value.split(“,”); return new Point( Integer.parseInt(values0), Integer.parseInt(values1) ); } }

你可以看到这个全局binder是一个典型的binder,只是使用了*@play.data.binding.Global*注解。我们在外部模块中定义这种binder,以在不同的项目中复用。

结果类型

一个action方法必须产生一个HTTP响应。最简单的方式就是生成一个Result对象。一旦某一个Result对象生成,该方法将立刻返回(后面的代码将不会被执行)。

举例:

public static void show(Long id) {
    Client client = Client.findById(id);
    render(client);
    System.out.println("This message will never be displayed !");
}

render(…) 方法产生了一个Result对象,后面的代码都不会被执行。

返回一些文本内容

renderText(…) 方法将产生一个简单的Result事件,该事件将直接向HTTP Response中写入一些文本数据。

举例:

public static void countUnreadMessages() {
    Integer unreadMessages = MessagesBox.countUnreadMessages();
    renderText(unreadMessages);
}

你还可以使用Java的标准格式化语法来格式化文本信息:

public static void countUnreadMessages() {
    Integer unreadMessages = MessagesBox.countUnreadMessages();
    renderText("There are %s unread messages", unreadMessages);
}

返回二进制内容

为了处理如 存储在服务器上的文件 这样的二进制数据,我们可使用 renderBinary 方法。例如,如果我们有一个 User 模型,它有一个 play.db.jpa.Blob photo 属性, 我们可以使用以下方式使用保存的MIME类型向客户端发送图片数据:

public static void userPhoto(long id) { 
   final User user = User.findById(id); 
   response.setContentTypeIfNotSet(user.photo.type());
   java.io.InputStream binaryData = user.photo.get();
   renderBinary(binaryData);
} 

把文件当作附件下载

我们可以通过设置HTTP头,来指导浏览器把二进制数据当作“附件”来保存。我们只需要在 renderBinary 方法中传入一个文件名即可。Play会自动在响应头中把文件名设给 Content-Disposition 。举例来说,前面例子中的 User 模型有一个 photoFileName 属性:

renderBinary(binaryData, user.photoFileName); 

执行一个模板

如果需要产生的内容很复杂,我们通常会在模板中来创建内容:

public class Clients extends Controller {
public static void index() { render(); } }

这里有一个命名约定,Play会根据controller名和action名来寻找默认的模板路径。对于上例是:

app/views/Clients/index.html

把数据加入到模板域中

模板通常都需要数据。我们可以把这些数据放在 renderArgs 对象中:

public class Clients extends Controller {
public static void show(Long id) { Client client = Client.findById(id); renderArgs.put(“client”, client); render(); } }

当执行模板的时候,会自动创建 client 变量。

例如,我们可在模板中使用client变量:

<h1>Client ${client.name}</h1>

将数据加入到模板类中的更简单的方法

我们可以直接将数据传入到 render(...) 中:

public static void show(Long id) {
    Client client = Client.findById(id);
    render(client);    
}

在这种情况下,模板中也将有一个与action中的局部变量名一样的变量(client)。

我们还可以传入更多的变量:

public static void show(Long id) {
    Client client = Client.findById(id);
    render(id, client);    
}

重要!

你只能通过这种方式来传入 局部变量

h4. 使用其它模板

如果你不想使用默认模板,可以通过在 renderTemplate(…) 中的第一个参数中指定另一个模板名称。

举例:

public static void show(Long id) {
    Client client = Client.findById(id);
    renderTemplate("Clients/showClient.html", id, client);    
}

重定向到另一个URL

redirect(…) 方法会产生一个重定向事件,接着会产生一个HTTP Redirect响应。

public static void index() {
    redirect("http://www.zenexity.fr");
}

Action链

在play中没有Servlet API forward 的等价物。每一个HTTP request只能调用一个action。如果我们需要调用另一个,必须通过重定向,让浏览器访问另一个URL来访问它。这样的话,浏览器的URL始终与被执行的action保持一致,实现 Back/Forward/Refresh 的管理就容易多了。

你可以发送到任何一个action的Redirect,只需要直接在Java中调用该action即可。该调用将会自动被Play拦截,并生成一个HTTP重定向。

举例:

public class Clients extends Controller {
public static void show(Long id) { Client client = Client.findById(id); render(client); } public static void create(String name) { Client client = new Client(name); client.save(); show(client.id); } }

With these routes:

GET    /clients/{id}            Clients.show
POST   /clients                 Clients.create 
  • 浏览器向 /clients URL发送一个POST。
  • Router调用 Clients controller的 create action.
  • Action方法直接调用 show 方法
  • 该Java调用被拦截,Router根据它产生一个调用Clients.show(id)所需要的新URL。
  • HTTP响应为 302 Location:/clients/3132.
  • 浏览器接着发送 GET /clients/3132.

自定义编码集

Play强调使用UTF-8,但有时候某些响应,或者整个应用的响应,都必须使用一个不同的编码集。

给当前response定义encoding

要改变当前response的编码集,我们需要在controller中这样做:

response.encoding = "ISO-8859-1";

如果要使用一个与服务器默认的不同的编码集,我们必须在form中包含两次encoding/charset。一次在 accept-charset 属性中,一次在一个hidden类型的字段 _charset_ 中。 accept-charset 告诉浏览器使用哪种字符集,而 _charset_ 告诉play使用哪种字符集:

<form action="@{application.index}" method="POST" accept-charset="ISO-8859-1">
    <input type="hidden" name="_charset_" value="ISO-8859-1">
</form>

自定义整个程序的编码集

配置application.web_encoding 来指定Play使用哪种编码集。

拦截器(Interceptions)

一个controller可以定义多个拦截器方法。拦截器作用于一个controller及其所有子类的所有action方法上。对于定义一些所有action共用的操作时,使用拦截器非常有用,比如:检查用户是否已经登录(有没有访问权),截入request范围内的数据,等等。

这些方法必须为 static ,但不一定是 public 。你必须给它们增加合适的注解以表明它们是拦截器。

@Before

如果方法上有@Before注解,则它将在该controller中的每一个action被调用前被执行。

所以可以进行一下安全检查:

public class Admin extends Application {
@Before static void checkAuthentification() { if(session.get(“user”) == null) login(); } public static void index() { List users = User.findAll(); render(users); } … }

如果你想给某些方法开绿灯,可按下面的方法排除一些action:

public class Admin extends Application {
@Before(unless=“login”) static void checkAuthentification() { if(session.get(“user”) == null) login(); } public static void index() { List users = User.findAll(); render(users); } … }

或者仅对于某些方法调用该拦截器,可使用“only”:

public class Admin extends Application {
@Before(only={“login”,“logout”}) static void doSomething() { … } … }

@After, @Before@Finally这三个注解,都提供了 unlessonly 参数。

@After

使用@After注解的方法,将在该Controller中的每一个action之后被调用。

public class Admin extends Application {
@After static void log() { Logger.info(“Action executed ...”); } public static void index() { List users = User.findAll(); render(users); } … }

@Catch

使用了@Catch注解的方法,将会在某个抛出了它所指定的异常时,被调用。异常类型将被传入到@Catch方法的参数中。

public class Admin extends Application {
@Catch(IllegalStateException.class) public static void logIllegalState(Throwable throwable) { Logger.error(“Illegal state %s…”, throwable); } public static void index() { List users = User.findAll(); if (users.size() == 0) { throw new IllegalStateException(“Invalid database - 0 users”); } render(users); } }

与Java的异常处理一样,我们可以使用一个超类来捕获更多的异常类型。如果我们有多个catch方法,可以通过指定其 priority 来定义它们的执行顺序(priority为1的最先执行)。

public class Admin extends Application {
@Catch(value = Throwable.class, priority = 1) public static void logThrowable(Throwable throwable) { // Custom error logging… Logger.error(“EXCEPTION %s”, throwable); } @Catch(value = IllegalStateException.class, priority = 2) public static void logIllegalState(Throwable throwable) { Logger.error(“Illegal state %s…”, throwable); } public static void index() { List users = User.findAll(); if(users.size() == 0) { throw new IllegalStateException(“Invalid database - 0 users”); } render(users); } }

@Finally

使用@Finally注解的方法,总是在该Controller中每一个action执行完之后再执行。不论action执行成功或者失败,它都将会被执行。跟Java中finally的意思相同。

public class Admin extends Application {
@Finally static void log() { Logger.info(“Response contains : ” + response.out); } public static void index() { List users = User.findAll(); render(users); } … }

如果@Finally方法有一个Throwable类型的参数,则异常对象会被传入(如果有的话):

public class Admin extends Application {
@Finally static void log(Throwable e) { if( e == null ){ Logger.info(“action call was successful”); } else{ Logger.info(“action call failed”, e); } } public static void index() { List users = User.findAll(); render(users); } … }

Controller继承

如果一个Controller类是另一个的子类,则父类中定义的拦截器同样对子类有效。

通过@With注解,加入更多的拦截器

因为Java中没有多重继承,所以通过Controller继承来共用拦截器很难。但是通过@With注解,我们可以把一些拦截器定义在一个完全不同的类中,然后在当前Controller中使用它们。

举例:

public class Secure extends Controller {
@Before static void checkAuthenticated() { if(!session.containsKey(“user”)) { unAuthorized(); } } }

把它加到另一个Controller中:

@With(Secure.class)
public class Admin extends Application {
… }

Session和Flash scopes

如果你打算在多个HTTP请求之间共用数据,可以把它们保存在Session或Flash域中。保存在Session中的数据,对于整个user session都可用,而保存在flash域中的数据,则仅仅在下一个请求可用。

有一点非常重要,需要理解的是,在play中,Session和Flash数据并没有保存在服务器端,而是通过Cookie被加入到每一个HTTP请求中。所以能保存的数据量非常小(不超过4KB),并且只能保存字符串。

当然,cookies都使用了一个密钥进行了加密,所以客户端无法修改cookie数据(否则该数据将无效)。Play的session不是用来当作数据缓存。如果我们需要缓存与session相关的某些数据,可以使用Play内置的缓存机制,并使用 session.getId() 作为key来保存。

举例:

public static void index() {
    List messages = Cache.get(session.getId() + "-messages", List.class);
    if(messages == null) {
        // Cache miss
        messages = Message.findByUser(session.get("user"));
        Cache.set(session.getId() + "-messages", messages, "30mn");
    }
    render(messages);
}

当我们关闭浏览器时,session数据将过期,除非我们通过 application.session.maxAge 进行了配置。

缓存使用了与传统Servlet HTTP session不同的定义,所以我们不能假设这些数据只是在cache中。这将强迫我们处理cache中没有数据的情况,并强迫我们的程序是完全无状态的。

继承讨论

MVC中下一个重要的层是视图(View)层,Play通过 模板引擎 实现了一个高效的模板系统。