Package play.mvc
Class Controller
- java.lang.Object
-
- play.mvc.Controller
-
- All Implemented Interfaces:
ControllersEnhancer.ControllerSupport
,LocalvariablesNamesEnhancer.LocalVariablesSupport
,PlayController
public class Controller extends java.lang.Object implements PlayController, 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 in most cases.
-
-
Nested Class Summary
Nested Classes Modifier and Type Class Description static interface
Controller.ITemplateNameResolver
This allow people that implements their own template engine to override the way template are resolved.
-
Field Summary
Fields Modifier and Type Field Description static java.lang.ThreadLocal<Router.ActionDefinition>
_currentReverse
Don't use this directly if you don't know whyprotected 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
Constructors Constructor Description Controller()
-
Method Summary
All Methods Static Methods Concrete Methods Deprecated Methods Modifier and Type Method Description 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 <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
badRequest()
Send a 400 Bad requestprotected static void
badRequest(java.lang.String msg)
Send a 400 Bad requestprotected static void
checkAuthenticity()
Check that the token submitted from a form is valid.protected static void
error()
Send a 500 Error responseprotected static void
error(int status, java.lang.String reason)
Send a 5xx Error responseprotected static void
error(java.lang.Exception reason)
Send a 500 Error responseprotected static void
error(java.lang.String reason)
Send a 500 Error responseprotected static void
flash(java.lang.String key, java.lang.Object value)
Add a value to the flash scopeprotected static void
forbidden()
Send a 403 Forbidden responseprotected static void
forbidden(java.lang.String reason)
Send a 403 Forbidden responseprotected static <T extends java.lang.annotation.Annotation>
TgetActionAnnotation(java.lang.Class<T> clazz)
Retrieve annotation for the action methodprotected static <T extends java.lang.annotation.Annotation>
TgetControllerAnnotation(java.lang.Class<T> clazz)
Retrieve annotation for the controller classprotected static java.lang.Class<? extends Controller>
getControllerClass()
Retrieve the controller classprotected static <T extends java.lang.annotation.Annotation>
TgetControllerInheritedAnnotation(java.lang.Class<T> clazz)
Retrieve annotation for the controller classprotected static void
notFound()
Send a 404 Not Found responseprotected static void
notFound(java.lang.String what)
Send a 404 Not Found responseprotected static void
notFoundIfNull(java.lang.Object o)
Send a 404 Not Found response if object is nullprotected static void
notFoundIfNull(java.lang.Object o, java.lang.String what)
Send a 404 Not Found response if object is nullprotected static void
notModified()
Send a 304 Not Modified responseprotected static void
ok()
Send a 200 OK responseprotected static void
parent()
Deprecated.protected static void
parent(java.lang.Object... args)
Deprecated.protected static void
parent(java.util.Map<java.lang.String,java.lang.Object> map)
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 actionstatic void
redirect(java.lang.String action, java.lang.Object... args)
302 Redirect to another actionprotected static void
redirectToStatic(java.lang.String file)
Send a 302 redirect response.static void
registerTemplateNameResolver(Controller.ITemplateNameResolver templateNameResolver)
Register a customer template name resolver.protected static void
render(java.lang.Object... args)
Render the corresponding template (@seetemplate()
).protected static void
renderBinary(java.io.File file)
Return a 200 OK application/binary responseprotected static void
renderBinary(java.io.File file, java.lang.String name)
Return a 200 OK application/binary response with content-disposition attachmentprotected 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 responseprotected static void
renderJSON(java.lang.Object o)
Render a 200 OK application/json responseprotected static void
renderJSON(java.lang.Object o, com.google.gson.Gson gson)
Render a 200 OK application/json response.protected static void
renderJSON(java.lang.Object o, com.google.gson.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 responseprotected static void
renderJSON(java.lang.String jsonString)
Render a 200 OK application/json responseprotected static void
renderTemplate(java.lang.String templateName, java.lang.Object... args)
Render a specific templateprotected 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.util.Map<java.lang.String,java.lang.Object> args)
Render the template corresponding to the action's package-class-method name (@seetemplate()
).protected static void
renderText(java.lang.CharSequence pattern, java.lang.Object... args)
Return a 200 OK text/plain responseprotected static void
renderText(java.lang.Object text)
Return a 200 OK text/plain responseprotected 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 responseprotected static void
renderXml(java.lang.String xml)
Return a 200 OK text/xml responseprotected static void
renderXml(org.w3c.dom.Document xml)
Return a 200 OK text/xml responseprotected 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 responseprotected static void
unauthorized()
Send a 401 Unauthorized responseprotected static void
unauthorized(java.lang.String realm)
Send a 401 Unauthorized responseprotected static void
waitFor(java.util.concurrent.Future<?> task)
Deprecated.
-
-
-
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 explicitly 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 final java.lang.ThreadLocal<Router.ActionDefinition> _currentReverse
Don't use this directly if you don't know why
-
-
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 serializexstream
- 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. Content is fully loaded in memory, so it should not be used with large data.- 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 copylength
- 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. Content is fully loaded in memory, so it should not be used with large data.- Parameters:
is
- The stream to copyname
- 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. Content is fully loaded in memory, so it should not be used with large data.- Parameters:
is
- The stream to copyname
- 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 copyname
- The attachment namelength
- 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. Content is fully loaded in memory, so it should not be used with large data.- Parameters:
is
- The stream to copyname
- The attachment namecontentType
- The content type of the attachmentinline
- 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 copyname
- The attachment namelength
- Content's byte size.contentType
- The content type of the attachmentinline
- 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 copyname
- 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 serializetype
- The Type information for complex generic types
-
renderJSON
protected static void renderJSON(java.lang.Object o, com.google.gson.JsonSerializer<?>... adapters)
Render a 200 OK application/json response.- Parameters:
o
- The Java object to serializeadapters
- A set of GSON serializers/deserializers/instance creator to use
-
renderJSON
protected static void renderJSON(java.lang.Object o, com.google.gson.Gson gson)
Render a 200 OK application/json response.- Parameters:
o
- The Java object to serializegson
- The GSON serializer object use
-
notModified
protected static void notModified()
Send a 304 Not Modified response
-
badRequest
protected static void badRequest(java.lang.String msg)
Send a 400 Bad request- Parameters:
msg
- The message
-
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 checkwhat
- The Not Found resource name
-
notFound
protected static void notFound()
Send a 404 Not Found response
-
checkAuthenticity
protected static void checkAuthenticity()
Check that the token submitted from a form is valid.
-
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 codereason
- 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 keyvalue
- 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 redirectpermanent
- 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 -> 302args
- 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 nameargs
- 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 (@seetemplate()
).- Parameters:
args
- The template data.
-
render
protected static void render(java.lang.Object... args)
Render the corresponding template (@seetemplate()
).- 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".- Returns:
- The template name
-
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".- Parameters:
templateName
- The template name to work out- Returns:
- The template name
-
getActionAnnotation
protected static <T extends java.lang.annotation.Annotation> T getActionAnnotation(java.lang.Class<T> clazz)
Retrieve annotation for the action method- Type Parameters:
T
- The class type- 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- Type Parameters:
T
- The class type- 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- Type Parameters:
T
- The class type- 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- Parameters:
args
- List of parameters
-
parent
@Deprecated protected static void parent()
Deprecated.Call the parent method * @deprecated
-
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- Parameters:
map
- List of objects to the params scop
-
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 completionImportant: 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:
task
- Taks to wait for
-
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()
- Returns:
- The ActionDefiniton
- To do:
- TODO - this "Usage" example below doesn't make sense.
Usage:
ActionDefinition action = reverse(); { Application.anyAction(anyParam, "toto"); } String url = action.url;
-
registerTemplateNameResolver
public static void registerTemplateNameResolver(Controller.ITemplateNameResolver templateNameResolver)
Register a customer template name resolver. That letter allows to override the way templates are resolved.- Parameters:
templateNameResolver
- The template resolver
-
-