Play Framework介紹:控制器層

作者：佚名 2012-02-24 10:57:43

開發后端

Controller層就是專門做這件事的：在模型層與傳輸層之間搭起一座橋梁。它使用與模型層同一種語言，以便訪問和修改模型對象，但同時它又跟HTTP接口一樣，是面向請求(Request)和響應(Response)的。

業務邏輯代碼通常位于模型(model)層。客戶端（比如瀏覽器）無法直接調用其中的代碼，所以模型對象提供的功能，必須作為資源以URI方式暴露給外部。

客戶端使用HTTP協議來操作這些資源，從而調用了內部的業務邏輯。但是，這種從資源到模型之間的映射是單向的：我們可以根據需要提供不同粒度的資源，可以虛擬出一些資源，還可以給某些資源起別名...

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這三個注解，都提供了 unless 和 only 參數。

@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中沒有數據的情況，并強迫我們的程序是完全無狀態的。

原文鏈接：http://play-framework.herokuapp.com/zh/controllers

【編輯推薦】

Play Framework介紹:HTTP路由
Play Framework框架安裝指南
Play Framework框架概述
Play Framework hotswap及源碼分析
Play Framework總結性介紹

責任編輯：林師授來源： Play Framework中文小站

Java Play Framework