play.mvc
Class Controller

java.lang.Object
  play.mvc.Controller

All Implemented Interfaces:

ControllersEnhancer.ControllerSupport, LocalvariablesNamesEnhancer.LocalVariablesSupport

public class Controller
extends java.lang.Object
implements ControllersEnhancer.ControllerSupport, LocalvariablesNamesEnhancer.LocalVariablesSupport

Application controller support: The controller receives input and initiates a response by making calls on model objects. This is the class that your controllers should extend.

Field Summary

static java.lang.ThreadLocal<Router.ActionDefinition>	_currentReverse Don't use this directly if you don't know why
protected static Scope.Flash	flash The current flash scope.
protected static Scope.Params	params The current HTTP params.
protected static Scope.RenderArgs	renderArgs The current renderArgs scope: This is a hash map that is accessible during the rendering phase.
protected static Http.Request	request The current HTTP request: the message sent by the client to the server.
protected static Http.Response	response The current HTTP response: The message sent back from the server after a request.
protected static Scope.RouteArgs	routeArgs The current routeArgs scope: This is a hash map that is accessible during the reverse routing phase.
protected static Scope.Session	session The current HTTP session.
protected static Validation	validation The current Validation object.

Constructor Summary

Controller()

Method Summary

protected static <T> T	await(java.util.concurrent.Future<T> future)
protected static <T> void	await(java.util.concurrent.Future<T> future, F.Action<T> callback)
protected static void	await(int millis)
protected static void	await(int millis, F.Action0 callback)
protected static void	await(java.lang.String timeout)
protected static void	await(java.lang.String timeout, F.Action0 callback)
protected static void	badRequest() Send a 400 Bad request
protected static void	checkAuthenticity() Check that the token submitted from a form is valid.
protected static void	error() Send a 500 Error response
protected static void	error(java.lang.Exception reason) Send a 500 Error response
protected static void	error(int status, java.lang.String reason) Send a 5xx Error response
protected static void	error(java.lang.String reason) Send a 500 Error response
protected static void	flash(java.lang.String key, java.lang.Object value) Add a value to the flash scope
protected static void	forbidden() Send a 403 Forbidden response
protected static void	forbidden(java.lang.String reason) Send a 403 Forbidden response
protected static <T extends java.lang.annotation.Annotation> T	getActionAnnotation(java.lang.Class<T> clazz) Retrieve annotation for the action method
protected static <T extends java.lang.annotation.Annotation> T	getControllerAnnotation(java.lang.Class<T> clazz) Retrieve annotation for the controller class
protected static java.lang.Class<? extends Controller>	getControllerClass() Retrieve the controller class
protected static <T extends java.lang.annotation.Annotation> T	getControllerInheritedAnnotation(java.lang.Class<T> clazz) Retrieve annotation for the controller class
protected static void	notFound() Send a 404 Not Found reponse
protected static void	notFound(java.lang.String what) Send a 404 Not Found response
protected static void	notFoundIfNull(java.lang.Object o) Send a 404 Not Found response if object is null
protected static void	notFoundIfNull(java.lang.Object o, java.lang.String what) Send a 404 Not Found response if object is null
protected static void	notModified() Send a 304 Not Modified response
protected static void	ok() Send a 200 OK response
protected static void	parent() Deprecated.
protected static void	parent(java.util.Map<java.lang.String,java.lang.Object> map) Deprecated.
protected static void	parent(java.lang.Object... args) Deprecated.
protected static void	redirect(java.lang.String url) Send a 302 redirect response.
protected static void	redirect(java.lang.String url, boolean permanent) Send a Redirect response.
protected static void	redirect(java.lang.String action, boolean permanent, java.lang.Object... args) Redirect to another action
static void	redirect(java.lang.String action, java.lang.Object... args) 302 Redirect to another action
protected static void	redirectToStatic(java.lang.String file) Send a 302 redirect response.
protected static void	render(java.lang.Object... args) Render the corresponding template (@see template()).
protected static void	renderBinary(java.io.File file) Return a 200 OK application/binary response
protected static void	renderBinary(java.io.File file, java.lang.String name) Return a 200 OK application/binary response with content-disposition attachment
protected static void	renderBinary(java.io.InputStream is) Return a 200 OK application/binary response
protected static void	renderBinary(java.io.InputStream is, long length) Return a 200 OK application/binary response.
protected static void	renderBinary(java.io.InputStream is, java.lang.String name) Return a 200 OK application/binary response with content-disposition attachment.
protected static void	renderBinary(java.io.InputStream is, java.lang.String name, boolean inline) Return a 200 OK application/binary response with content-disposition attachment.
protected static void	renderBinary(java.io.InputStream is, java.lang.String name, long length) Return a 200 OK application/binary response with content-disposition attachment.
protected static void	renderBinary(java.io.InputStream is, java.lang.String name, long length, boolean inline) Return a 200 OK application/binary response with content-disposition attachment.
protected static void	renderBinary(java.io.InputStream is, java.lang.String name, long length, java.lang.String contentType, boolean inline) Return a 200 OK application/binary response with content-disposition attachment.
protected static void	renderBinary(java.io.InputStream is, java.lang.String name, java.lang.String contentType, boolean inline) Return a 200 OK application/binary response with content-disposition attachment
protected static void	renderHtml(java.lang.Object html) Return a 200 OK text/html response
protected static void	renderJSON(java.lang.Object o) Render a 200 OK application/json response
protected static void	renderJSON(java.lang.Object o, JsonSerializer<?>... adapters) Render a 200 OK application/json response.
protected static void	renderJSON(java.lang.Object o, java.lang.reflect.Type type) Render a 200 OK application/json response
protected static void	renderJSON(java.lang.String jsonString) Render a 200 OK application/json response
protected static void	renderTemplate(java.util.Map<java.lang.String,java.lang.Object> args) Render the template corresponding to the action's package-class-method name (@see template()).
protected static void	renderTemplate(java.lang.String templateName, java.util.Map<java.lang.String,java.lang.Object> args) Render a specific template.
protected static void	renderTemplate(java.lang.String templateName, java.lang.Object... args) Render a specific template
protected static void	renderText(java.lang.CharSequence pattern, java.lang.Object... args) Return a 200 OK text/plain response
protected static void	renderText(java.lang.Object text) Return a 200 OK text/plain response
protected static void	renderXml(org.w3c.dom.Document xml) Return a 200 OK text/xml response
protected static void	renderXml(java.lang.Object o) Return a 200 OK text/xml response.
protected static void	renderXml(java.lang.Object o, com.thoughtworks.xstream.XStream xstream) Return a 200 OK text/xml response
protected static void	renderXml(java.lang.String xml) Return a 200 OK text/xml response
protected static Router.ActionDefinition	reverse()
protected static void	suspend(int millis) Deprecated.
protected static void	suspend(java.lang.String timeout) Deprecated.
protected static java.lang.String	template() Work out the default template to load for the invoked action.
protected static java.lang.String	template(java.lang.String templateName) Work out the default template to load for the action.
protected static boolean	templateExists(java.lang.String templateName)
protected static void	todo() Send a todo response
protected static void	unauthorized() Send a 401 Unauthorized response
protected static void	unauthorized(java.lang.String realm) Send a 401 Unauthorized response
protected static void	waitFor(java.util.concurrent.Future<?> task) Deprecated.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

request

protected static Http.Request request

The current HTTP request: the message sent by the client to the server. Note: The ControllersEnhancer makes sure that an appropriate thread local version is applied. ie : controller.request - controller.request.current()

response

protected static Http.Response response

The current HTTP response: The message sent back from the server after a request. Note: The ControllersEnhancer makes sure that an appropriate thread local version is applied. ie : controller.response - controller.response.current()

session

protected static Scope.Session session

The current HTTP session. The Play! session is not living on the server side but on the client side. In fact, it is stored in a signed cookie. This session is therefore limited to 4kb. From Wikipedia: Client-side sessions use cookies and cryptographic techniques to maintain state without storing as much data on the server. When presenting a dynamic web page, the server sends the current state data to the client (web browser) in the form of a cookie. The client saves the cookie in memory or on disk. With each successive request, the client sends the cookie back to the server, and the server uses the data to "remember" the state of the application for that specific client and generate an appropriate response. This mechanism may work well in some contexts; however, data stored on the client is vulnerable to tampering by the user or by software that has access to the client computer. To use client-side sessions where confidentiality and integrity are required, the following must be guaranteed: Confidentiality: Nothing apart from the server should be able to interpret session data. Data integrity: Nothing apart from the server should manipulate session data (accidentally or maliciously). Authenticity: Nothing apart from the server should be able to initiate valid sessions. To accomplish this, the server needs to encrypt the session data before sending it to the client, and modification of such information by any other party should be prevented via cryptographic means. Transmitting state back and forth with every request is only practical when the size of the cookie is small. In essence, client-side sessions trade server disk space for the extra bandwidth that each web request will require. Moreover, web browsers limit the number and size of cookies that may be stored by a web site. To improve efficiency and allow for more session data, the server may compress the data before creating the cookie, decompressing it later when the cookie is returned by the client. Note: The ControllersEnhancer makes sure that an appropriate thread local version is applied. ie : controller.session - controller.session.current()

flash

protected static Scope.Flash flash

The current flash scope. The flash is a temporary storage mechanism that is a hash map You can store values associated with keys and later retrieve them. It has one special property: by default, values stored into the flash during the processing of a request will be available during the processing of the immediately following request. Once that second request has been processed, those values are removed automatically from the storage This scope is very useful to display messages after issuing a Redirect. Note: The ControllersEnhancer makes sure that an appropriate thread local version is applied. ie : controller.flash - controller.flash.current()

params

protected static Scope.Params params

The current HTTP params. This scope allows you to access the HTTP parameters supplied with the request. This is useful for example to know which submit button a user pressed on a form. Note: The ControllersEnhancer makes sure that an appropriate thread local version is applied. ie : controller.params - controller.params.current()

renderArgs

protected static Scope.RenderArgs renderArgs

The current renderArgs scope: This is a hash map that is accessible during the rendering phase. It means you can access variables stored in this scope during the rendering phase (the template phase). Note: The ControllersEnhancer makes sure that an appropriate thread local version is applied. ie : controller.renderArgs - controller.renderArgs.current()

routeArgs

protected static Scope.RouteArgs routeArgs

The current routeArgs scope: This is a hash map that is accessible during the reverse routing phase. Any variable added to this scope will be used for reverse routing. Useful when you have a param that you want to add to any route without add it expicitely to every action method. Note: The ControllersEnhancer makes sure that an appropriate thread local version is applied. ie : controller.routeArgs - controller.routeArgs.current()

validation

protected static Validation validation

The current Validation object. It allows you to validate objects and to retrieve potential validations errors for those objects. Note: The ControllersEnhancer makes sure that an appropriate thread local version is applied. ie : controller.validation - controller.validation.current()

_currentReverse

public static java.lang.ThreadLocal<Router.ActionDefinition> _currentReverse

Don't use this directly if you don't know why

Constructor Detail

Controller

public Controller()

Method Detail

renderText

protected static void renderText(java.lang.Object text)

Return a 200 OK text/plain response

Parameters:

text - The response content

renderHtml

protected static void renderHtml(java.lang.Object html)

Return a 200 OK text/html response

Parameters:

html - The response content

renderText

protected static void renderText(java.lang.CharSequence pattern,
                                 java.lang.Object... args)

Return a 200 OK text/plain response

Parameters:

pattern - The response content to be formatted (with String.format)

args - Args for String.format

renderXml

protected static void renderXml(java.lang.String xml)

Return a 200 OK text/xml response

Parameters:

xml - The XML string

renderXml

protected static void renderXml(org.w3c.dom.Document xml)

Return a 200 OK text/xml response

Parameters:

xml - The DOM document object

renderXml

protected static void renderXml(java.lang.Object o)

Return a 200 OK text/xml response. Use renderXml(Object, XStream) to customize the result.

Parameters:

o - the object to serialize

renderXml

protected static void renderXml(java.lang.Object o,
                                com.thoughtworks.xstream.XStream xstream)

Return a 200 OK text/xml response

Parameters:

o - the object to serialize

xstream - the XStream object to use for serialization. See XStream's documentation for details about customizing the output.

renderBinary

protected static void renderBinary(java.io.InputStream is)

Return a 200 OK application/binary response

Parameters:

is - The stream to copy

renderBinary

protected static void renderBinary(java.io.InputStream is,
                                   long length)

Return a 200 OK application/binary response. Content is streamed.

Parameters:

is - The stream to copy

length - Stream's size in bytes.

renderBinary

protected static void renderBinary(java.io.InputStream is,
                                   java.lang.String name)

Return a 200 OK application/binary response with content-disposition attachment.

Parameters:

is - The stream to copy

name - Name of file user is downloading.

renderBinary

protected static void renderBinary(java.io.InputStream is,
                                   java.lang.String name,
                                   long length)

Return a 200 OK application/binary response with content-disposition attachment.

Parameters:

is - The stream to copy. Content is streamed.

name - Name of file user is downloading.

length - Stream's size in bytes.

renderBinary

protected static void renderBinary(java.io.InputStream is,
                                   java.lang.String name,
                                   boolean inline)

Return a 200 OK application/binary response with content-disposition attachment.

Parameters:

is - The stream to copy

name - Name of file user is downloading.

inline - true to set the response Content-Disposition to inline

renderBinary

protected static void renderBinary(java.io.InputStream is,
                                   java.lang.String name,
                                   long length,
                                   boolean inline)

Return a 200 OK application/binary response with content-disposition attachment.

Parameters:

is - The stream to copy

name - The attachment name

length - Stream's size in bytes.

inline - true to set the response Content-Disposition to inline

renderBinary

protected static void renderBinary(java.io.InputStream is,
                                   java.lang.String name,
                                   java.lang.String contentType,
                                   boolean inline)

Return a 200 OK application/binary response with content-disposition attachment

Parameters:

is - The stream to copy

name - The attachment name

contentType - The content type of the attachment

inline - true to set the response Content-Disposition to inline

renderBinary

protected static void renderBinary(java.io.InputStream is,
                                   java.lang.String name,
                                   long length,
                                   java.lang.String contentType,
                                   boolean inline)

Return a 200 OK application/binary response with content-disposition attachment.

Parameters:

is - The stream to copy

name - The attachment name

length - Content's byte size.

contentType - The content type of the attachment

inline - true to set the response Content-Disposition to inline

renderBinary

protected static void renderBinary(java.io.File file)

Return a 200 OK application/binary response

Parameters:

file - The file to copy

renderBinary

protected static void renderBinary(java.io.File file,
                                   java.lang.String name)

Return a 200 OK application/binary response with content-disposition attachment

Parameters:

file - The file to copy

name - The attachment name

renderJSON

protected static void renderJSON(java.lang.String jsonString)

Render a 200 OK application/json response

Parameters:

jsonString - The JSON string

renderJSON

protected static void renderJSON(java.lang.Object o)

Render a 200 OK application/json response

Parameters:

o - The Java object to serialize

renderJSON

protected static void renderJSON(java.lang.Object o,
                                 java.lang.reflect.Type type)

Render a 200 OK application/json response

Parameters:

o - The Java object to serialize

type - The Type informations for complex generic types

renderJSON

protected static void renderJSON(java.lang.Object o,
                                 JsonSerializer<?>... adapters)

Render a 200 OK application/json response.

Parameters:

o - The Java object to serialize

adapters - A set of GSON serializers/deserializers/instance creator to use

notModified

protected static void notModified()

Send a 304 Not Modified response

badRequest

protected static void badRequest()

Send a 400 Bad request

unauthorized

protected static void unauthorized(java.lang.String realm)

Send a 401 Unauthorized response

Parameters:

realm - The realm name

unauthorized

protected static void unauthorized()

Send a 401 Unauthorized response

notFound

protected static void notFound(java.lang.String what)

Send a 404 Not Found response

Parameters:

what - The Not Found resource name

ok

protected static void ok()

Send a 200 OK response

todo

protected static void todo()

Send a todo response

notFoundIfNull

protected static void notFoundIfNull(java.lang.Object o)

Send a 404 Not Found response if object is null

Parameters:

o - The object to check

notFoundIfNull

protected static void notFoundIfNull(java.lang.Object o,
                                     java.lang.String what)

Send a 404 Not Found response if object is null

Parameters:

o - The object to check

what - The Not Found resource name

notFound

protected static void notFound()

Send a 404 Not Found reponse

checkAuthenticity

protected static void checkAuthenticity()

Check that the token submitted from a form is valid.

See Also:

play.templates.FastTags._authenticityToken()

forbidden

protected static void forbidden(java.lang.String reason)

Send a 403 Forbidden response

Parameters:

reason - The reason

forbidden

protected static void forbidden()

Send a 403 Forbidden response

error

protected static void error(int status,
                            java.lang.String reason)

Send a 5xx Error response

Parameters:

status - The exact status code

reason - The reason

error

protected static void error(java.lang.String reason)

Send a 500 Error response

Parameters:

reason - The reason

error

protected static void error(java.lang.Exception reason)

Send a 500 Error response

Parameters:

reason - The reason

error

protected static void error()

Send a 500 Error response

flash

protected static void flash(java.lang.String key,
                            java.lang.Object value)

Add a value to the flash scope

Parameters:

key - The key

value - The value

redirect

protected static void redirect(java.lang.String url)

Send a 302 redirect response.

Parameters:

url - The Location to redirect

redirectToStatic

protected static void redirectToStatic(java.lang.String file)

Send a 302 redirect response.

Parameters:

file - The Location to redirect

redirect

protected static void redirect(java.lang.String url,
                               boolean permanent)

Send a Redirect response.

Parameters:

url - The Location to redirect

permanent - true -> 301, false -> 302

redirect

public static void redirect(java.lang.String action,
                            java.lang.Object... args)

302 Redirect to another action

Parameters:

action - The fully qualified action name (ex: Application.index)

args - Method arguments

redirect

protected static void redirect(java.lang.String action,
                               boolean permanent,
                               java.lang.Object... args)

Redirect to another action

Parameters:

action - The fully qualified action name (ex: Application.index)

permanent - true -> 301, false -> 302

args - Method arguments

templateExists

protected static boolean templateExists(java.lang.String templateName)

renderTemplate

protected static void renderTemplate(java.lang.String templateName,
                                     java.lang.Object... args)

Render a specific template

Parameters:

templateName - The template name

args - The template data

renderTemplate

protected static void renderTemplate(java.lang.String templateName,
                                     java.util.Map<java.lang.String,java.lang.Object> args)

Render a specific template.

Parameters:

templateName - The template name.

args - The template data.

renderTemplate

protected static void renderTemplate(java.util.Map<java.lang.String,java.lang.Object> args)

Render the template corresponding to the action's package-class-method name (@see template()).

Parameters:

args - The template data.

render

protected static void render(java.lang.Object... args)

Render the corresponding template (@see template()).

Parameters:

args - The template data

template

protected static java.lang.String template()

Work out the default template to load for the invoked action. E.g. "controllers.Pages.index" returns "views/Pages/index.html".

template

protected static java.lang.String template(java.lang.String templateName)

Work out the default template to load for the action. E.g. "controllers.Pages.index" returns "views/Pages/index.html".

getActionAnnotation

protected static <T extends java.lang.annotation.Annotation> T getActionAnnotation(java.lang.Class<T> clazz)

Retrieve annotation for the action method

Parameters:

clazz - The annotation class

Returns:

Annotation object or null if not found

getControllerAnnotation

protected static <T extends java.lang.annotation.Annotation> T getControllerAnnotation(java.lang.Class<T> clazz)

Retrieve annotation for the controller class

Parameters:

clazz - The annotation class

Returns:

Annotation object or null if not found

getControllerInheritedAnnotation

protected static <T extends java.lang.annotation.Annotation> T getControllerInheritedAnnotation(java.lang.Class<T> clazz)

Retrieve annotation for the controller class

Parameters:

clazz - The annotation class

Returns:

Annotation object or null if not found

getControllerClass

protected static java.lang.Class<? extends Controller> getControllerClass()

Retrieve the controller class

Returns:

Annotation object or null if not found

parent

@Deprecated
protected static void parent(java.lang.Object... args)

Deprecated.

Call the parent action adding this objects to the params scope

parent

@Deprecated
protected static void parent()

Deprecated.

Call the parent method

parent

@Deprecated
protected static void parent(java.util.Map<java.lang.String,java.lang.Object> map)

Deprecated.

Call the parent action adding this objects to the params scope

suspend

@Deprecated
protected static void suspend(java.lang.String timeout)

Deprecated.

Suspend the current request for a specified amount of time.

Important: The method will not resume on the line after you call this. The method will be called again as if there was a new HTTP request.

Parameters:

timeout - Period of time to wait, e.g. "1h" means 1 hour.

suspend

@Deprecated
protected static void suspend(int millis)

Deprecated.

Suspend the current request for a specified amount of time (in milliseconds).

Important: The method will not resume on the line after you call this. The method will be called again as if there was a new HTTP request.

Parameters:

millis - Number of milliseconds to wait until trying again.

waitFor

@Deprecated
protected static void waitFor(java.util.concurrent.Future<?> task)

Deprecated.

Suspend this request and wait for the task completion

Important: The method will not resume on the line after you call this. The method will be called again as if there was a new HTTP request.

Parameters:

tasks -

await

protected static void await(java.lang.String timeout)

await

protected static void await(java.lang.String timeout,
                            F.Action0 callback)

await

protected static void await(int millis)

await

protected static void await(int millis,
                            F.Action0 callback)

await

protected static <T> T await(java.util.concurrent.Future<T> future)

await

protected static <T> void await(java.util.concurrent.Future<T> future,
                                F.Action<T> callback)

reverse

protected static Router.ActionDefinition reverse()

To do:

- this "Usage" example below doesn't make sense. Usage: ActionDefinition action = reverse(); { Application.anyAction(anyParam, "toto"); } String url = action.url;