Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse files

API lifting and Java/Scala Doc

  • Loading branch information...
commit d1e0b691f9f673bd1c4f05f3ddeb2e4b5c02e33e 1 parent d41094c
Guillaume Bort guillaumebort authored
Showing with 3,066 additions and 934 deletions.
  1. +13 −13 README.md
  2. +7 −5 framework/project/Build.scala
  3. +10 −0 framework/src/play-test/src/main/java/play/test/FakeApplication.java
  4. +18 −3 framework/src/play-test/src/main/java/play/test/FakeRequest.java
  5. +113 −4 framework/src/play-test/src/main/java/play/test/Helpers.java
  6. +31 −0 framework/src/play-test/src/main/java/play/test/TestBrowser.java
  7. +9 −0 framework/src/play-test/src/main/java/play/test/TestServer.java
  8. +1 −1  framework/src/play-test/src/main/java/play/test/package-info.java
  9. +58 −4 framework/src/play-test/src/main/scala/play/api/test/Fakes.scala
  10. +68 −2 framework/src/play-test/src/main/scala/play/api/test/Helpers.scala
  11. +40 −6 framework/src/play-test/src/main/scala/play/api/test/Selenium.scala
  12. +6 −0 framework/src/play-test/src/main/scala/play/api/test/package.scala
  13. +8 −8 framework/src/play/src/main/java/play/Application.java
  14. +12 −0 framework/src/play/src/main/java/play/Configuration.java
  15. +6 −0 framework/src/play/src/main/java/play/Play.java
  16. +7 −1 framework/src/play/src/main/java/play/Plugin.java
  17. +9 −0 framework/src/play/src/main/java/play/Routes.java
  18. +2 −28 framework/src/play/src/main/java/play/cache/Cache.java
  19. +9 −3 framework/src/play/src/main/java/play/data/Form.java
  20. +1 −1  framework/src/play/src/main/java/play/data/validation/package-info.java
  21. +1 −1  framework/src/play/src/main/java/play/db/ebean/TransactionalAction.java
  22. +29 −0 framework/src/play/src/main/java/play/db/jpa/JPA.java
  23. +4 −0 framework/src/play/src/main/java/play/db/jpa/package-info.java
  24. +2 −15 framework/src/play/src/main/java/play/i18n/Messages.java
  25. +4 −0 framework/src/play/src/main/java/play/i18n/package-info.java
  26. +9 −0 framework/src/play/src/main/java/play/libs/Akka.java
  27. +24 −0 framework/src/play/src/main/java/play/libs/F.java
  28. +18 −15 framework/src/play/src/main/java/play/libs/Json.java
  29. +35 −2 framework/src/play/src/main/java/play/libs/Scala.java
  30. +23 −20 framework/src/play/src/main/java/play/libs/WS.java
  31. +9 −0 framework/src/play/src/main/java/play/libs/XML.java
  32. +11 −0 framework/src/play/src/main/java/play/libs/Yaml.java
  33. +38 −2 framework/src/play/src/main/java/play/mvc/BodyParser.java
  34. +12 −0 framework/src/play/src/main/java/play/mvc/Call.java
  35. +3 −0  framework/src/play/src/main/java/play/mvc/Content.java
  36. +3 −0  framework/src/play/src/main/java/play/mvc/HandlerRef.java
  37. +61 −7 framework/src/play/src/main/java/play/mvc/Http.java
  38. +20 −0 framework/src/play/src/main/java/play/mvc/PathBindable.java
  39. +20 −0 framework/src/play/src/main/java/play/mvc/QueryStringBindable.java
  40. +23 −0 framework/src/play/src/main/java/play/mvc/Results.java
  41. +36 −0 framework/src/play/src/main/java/play/mvc/WebSocket.java
  42. +1 −1  framework/src/play/src/main/resources/play.plugins
  43. +25 −5 framework/src/play/src/main/scala/play/api/Application.scala
  44. +49 −5 framework/src/play/src/main/scala/play/api/Configuration.scala
  45. +63 −13 framework/src/play/src/main/scala/play/api/Exceptions.scala
  46. +13 −4 framework/src/play/src/main/scala/play/api/Global.scala
  47. +31 −8 framework/src/play/src/main/scala/play/api/Logger.scala
  48. +33 −11 framework/src/play/src/main/scala/play/api/Play.scala
  49. +3 −1 framework/src/play/src/main/scala/play/api/Routes.scala
  50. +92 −83 framework/src/play/src/main/scala/play/api/cache/Cache.scala
  51. +0 −30 framework/src/play/src/main/scala/play/api/cache/CachePlugin.scala
  52. +6 −0 framework/src/play/src/main/scala/play/api/cache/package.scala
  53. +11 −0 framework/src/play/src/main/scala/play/api/controllers/Assets.scala
  54. +3 −1 framework/src/play/src/main/scala/play/api/controllers/package.scala
  55. +194 −23 framework/src/play/src/main/scala/play/api/data/Form.scala
  56. +207 −213 framework/src/play/src/main/scala/play/api/data/Forms.scala
  57. +21 −7 framework/src/play/src/main/scala/play/api/data/format/Format.scala
  58. +1 −1  framework/src/play/src/main/scala/play/api/data/format/package.scala
  59. +2 −4 framework/src/play/src/main/scala/play/api/data/package.scala
  60. +16 −6 framework/src/play/src/main/scala/play/api/data/validation/Validation.scala
  61. +23 −8 framework/src/play/src/main/scala/play/api/db/DB.scala
  62. +42 −16 framework/src/play/src/main/scala/play/api/db/evolutions/Evolutions.scala
  63. +38 −12 framework/src/play/src/main/scala/play/api/http/ContentTypeOf.scala
  64. +34 −1 framework/src/play/src/main/scala/play/api/http/StandardValues.scala
  65. +35 −10 framework/src/play/src/main/scala/play/api/http/Writeable.scala
  66. +3 −1 framework/src/play/src/main/scala/play/api/http/package.scala
  67. +16 −6 framework/src/play/src/main/scala/play/api/i18n/Messages.scala
  68. +12 −3 framework/src/play/src/main/scala/play/api/libs/Codecs.scala
  69. +17 −0 framework/src/play/src/main/scala/play/api/libs/Collections.scala
  70. +32 −1 framework/src/play/src/main/scala/play/api/libs/Comet.scala
  71. +9 −3 framework/src/play/src/main/scala/play/api/libs/Crypto.scala
  72. +12 −1 framework/src/play/src/main/scala/play/api/libs/Files.scala
  73. +6 −0 framework/src/play/src/main/scala/play/api/libs/JNDI.scala
  74. +3 −1 framework/src/play/src/main/scala/play/api/libs/MimeTypes.scala
  75. +29 −32 framework/src/play/src/main/scala/play/api/libs/{ → akka}/Akka.scala
  76. +20 −0 framework/src/play/src/main/scala/play/api/libs/akka/package.scala
  77. +1 −5 framework/src/play/src/main/scala/play/api/libs/{ → concurrent}/Promise.scala
  78. +10 −0 framework/src/play/src/main/scala/play/api/libs/concurrent/package.scala
  79. +0 −6 framework/src/play/src/main/scala/play/api/libs/{ → iteratee}/Iteratee.scala
  80. 0  framework/src/play/src/main/scala/play/api/libs/{ → iteratee}/TraversableIteratee.scala
  81. +10 −0 framework/src/play/src/main/scala/play/api/libs/iteratee/package.scala
  82. +7 −1 framework/src/play/src/main/scala/play/api/libs/json/Format.scala
  83. +5 −0 framework/src/play/src/main/scala/play/api/libs/json/Generic.scala
  84. +62 −13 framework/src/play/src/main/scala/play/api/libs/json/JsValue.scala
  85. +20 −1 framework/src/play/src/main/scala/play/api/libs/json/Json.scala
  86. +65 −4 framework/src/play/src/main/scala/play/api/libs/json/Reads.scala
  87. +66 −4 framework/src/play/src/main/scala/play/api/libs/json/Writes.scala
  88. +5 −12 framework/src/play/src/main/scala/play/api/libs/json/package.scala
  89. +25 −12 framework/src/play/src/main/scala/play/api/libs/{ → oauth}/OAuth.scala
  90. +6 −0 framework/src/play/src/main/scala/play/api/libs/oauth/package.scala
  91. +3 −1 framework/src/play/src/main/scala/play/api/libs/package.scala
  92. +100 −35 framework/src/play/src/main/scala/play/api/libs/{ → ws}/WS.scala
  93. +6 −0 framework/src/play/src/main/scala/play/api/libs/ws/package.scala
  94. +3 −1 framework/src/play/src/main/scala/play/api/models/package.scala
  95. +41 −3 framework/src/play/src/main/scala/play/api/mvc/Action.scala
  96. +133 −3 framework/src/play/src/main/scala/play/api/mvc/Binders.scala
  97. +9 −3 framework/src/play/src/main/scala/play/api/mvc/Content.scala
  98. +249 −14 framework/src/play/src/main/scala/play/api/mvc/ContentTypes.scala
  99. +145 −42 framework/src/play/src/main/scala/play/api/mvc/Http.scala
  100. +24 −2 framework/src/play/src/main/scala/play/api/mvc/Results.scala
  101. +6 −2 framework/src/play/src/main/scala/play/api/mvc/Security.scala
  102. +26 −5 framework/src/play/src/main/scala/play/api/mvc/WebSocket.scala
  103. +8 −0 framework/src/play/src/main/scala/play/api/mvc/package.scala
  104. +61 −20 framework/src/play/src/main/scala/play/api/templates/Templates.scala
  105. +3 −1 framework/src/play/src/main/scala/play/api/templates/package.scala
  106. +1 −1  framework/src/play/src/main/scala/play/core/j/JavaAction.scala
  107. +5 −5 framework/src/play/src/main/scala/play/core/j/JavaParsers.scala
  108. 0  framework/src/play/src/main/scala/play/core/{ → router}/Router.scala
  109. +1 −1  framework/src/play/src/main/scala/play/core/server/netty/PlayDefaultUpstreamHandler.scala
  110. +23 −23 framework/src/play/src/main/scala/play/core/{ → system}/ApplicationProvider.scala
  111. 0  framework/src/play/src/main/scala/play/core/{ → system}/Invoker.scala
  112. +1 −1  .../play/src/main/scala/play/core/{parsers/UrlFormEncodedParser.scala → utils/FormUrlEncodedParser.scala}
  113. +1 −0  framework/src/play/src/test/scala/play/api/JsonSpec.scala
  114. +0 −38 framework/src/play/src/test/scala/play/api/cache/CacheSpec.scala
  115. +1 −1  framework/src/play/src/test/scala/play/data/FormSpec.scala
  116. +3 −3 framework/src/sbt-plugin/src/main/scala/PlayReloader.scala
  117. +1 −1  framework/src/templates/src/main/scala/ScalaTemplates.scala
  118. +6 −9 framework/test/integrationtest/app/controllers/Application.scala
  119. +3 −3 framework/test/integrationtest/test/FunctionalSpec.scala
  120. +2 −2 samples/java/computer-database-jpa/test/FunctionalTest.java
  121. +2 −2 samples/java/computer-database/test/FunctionalTest.java
  122. +2 −2 samples/scala/computer-database/test/ApplicationSpec.scala
26 README.md
View
@@ -1,15 +1,15 @@
-_( Please [read this page] (https://github.com/playframework/Play20/wiki/Pullrequests) before sending pull requests )_
+# Play 2.0
-# Play 2.0 RC1
+Play 2.0 is a high productivity Java and Scala Web application framework, integrating all components and API needed for modern Web application development. It is based on a lightweight stateless Web friendly architecture and features predictable and minimal resources consumption (CPU, Memory, Threads) for highly scalable applications thanks to its reactive model based on Iteratee IO.
-Play 2.0 is a Java and Scala Web application framework (http://www.playframework.org/2.0).
+http://www.playframework.org/2.0
## Installing
For convenience, you should add the framework installation directory to your system PATH. On UNIX systems will be something like:
```bash
-export PATH=$PATH:/path/to/play20
+export PATH=$PATH:/path/to/play2.0
```
On windows systems you'll need to set it in the global environment variables.
@@ -20,21 +20,21 @@ On windows systems you'll need to set it in the global environment variables.
Enter any existing Play 2.0 application directory and use the `play` command to launch the development console:
-```bash
+```
$ cd ~/workspace/myApplication
$ play
```
You can also directly use `play run` to run the application:
-```bash
+```
$ cd ~/workspace/myApplication
$ play run
```
Use `play new yourNewApplication` to create a new application:
-```bash
+```
$ cd ~/workspace
$ play new myNewApplication
```
@@ -48,17 +48,17 @@ $ play
## Running the sample applications
-There are several samples applications included in the `samples/` directory. For example, to run the included ZenTask sample application:
+There are several samples applications included in the `samples/` directory. For example, to run the included Scala Hello World application:
-```bash
-$ cd ~/workspace/play2/samples/scala/zentasks/
+```
+$ cd ~/workspace/play2.0/samples/scala/helloworld/
$ play run
```
-> The application will be available on port 9000. On first run, it will notify you that database evolutions are required. Click "Apply this script now" and you're away!
+> The application will be available on port 9000.
## Documentation
-The temporary documentation is available at https://github.com/playframework/Play20/wiki.
+The edge documentation is available at https://github.com/playframework/Play20/wiki.
## Contributors
@@ -68,7 +68,7 @@ Check for all contributors at https://github.com/playframework/Play20/contributo
This software is licensed under the Apache 2 license, quoted below.
-Copyright 2011 Zenexity (http://www.zenexity.com).
+Copyright 2012 Typesafe (http://www.typesafe.com).
Licensed under the Apache License, Version 2.0 (the "License"); you may not use this project except in compliance with the License. You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0.
12 framework/project/Build.scala
View
@@ -187,9 +187,9 @@ object PlayBuild extends Build {
"com.jolbox" % "bonecp" % "0.7.1.RELEASE",
"org.yaml" % "snakeyaml" % "1.9",
"org.hibernate" % "hibernate-validator" % "4.2.0.Final",
- "org.springframework" % "spring-context" % "3.0.7.RELEASE" notTransitive(),
- "org.springframework" % "spring-core" % "3.0.7.RELEASE" notTransitive(),
- "org.springframework" % "spring-beans" % "3.0.7.RELEASE" notTransitive(),
+ "org.springframework" % "spring-context" % "3.0.7.RELEASE" notTransitive(),
+ "org.springframework" % "spring-core" % "3.0.7.RELEASE" notTransitive(),
+ "org.springframework" % "spring-beans" % "3.0.7.RELEASE" notTransitive(),
"joda-time" % "joda-time" % "2.0",
"javassist" % "javassist" % "3.12.1.GA",
"commons-lang" % "commons-lang" % "2.6",
@@ -198,10 +198,12 @@ object PlayBuild extends Build {
"com.codahale" %% "jerkson" % "0.5.0",
"org.reflections" % "reflections" % "0.9.5",
"javax.servlet" % "javax.servlet-api" % "3.0.1",
+ "javax.transaction" % "jta" % "1.1",
"tyrex" % "tyrex" % "1.0.1",
"org.specs2" %% "specs2" % "1.7.1" % "test",
+ "net.sf.ehcache" % "ehcache-core" % "2.5.0",
"com.novocode" % "junit-interface" % "0.7" % "test",
- "fr.javafreelance.fluentlenium" % "fluentlenium" % "0.5.3" % "test"
+ "fr.javafreelance.fluentlenium" % "fluentlenium" % "0.5.3" % "test"
)
val sbtDependencies = Seq(
@@ -300,7 +302,7 @@ object PlayBuild extends Build {
(file("src/play/src/main/scala/play/api") ** "*.scala").get ++
(file("src/play-test/src/main/scala") ** "*.scala").get ++
(file("src/play/src/main/scala/views") ** "*.scala").get ++
- (file("src/play/target/scala-2.9.1/src_managed/main/views") ** "*.scala").get
+ (file("src/play/target/scala-2.9.1/src_managed/main/views/html/helper") ** "*.scala").get
new Scaladoc(10, cs.scalac)("Play 2.0 Scala API", sourceFiles, classpath.map(_.data), file("../documentation/api/scala"), Nil, s.log)
// Javadoc
10 framework/src/play-test/src/main/java/play/test/FakeApplication.java
View
@@ -5,10 +5,20 @@
import play.libs.*;
+/**
+ * A Fake application.
+ */
public class FakeApplication {
final play.api.test.FakeApplication wrappedApplication;
+ /**
+ * A Fake application.
+ *
+ * @param path The application path
+ * @param classloader The application classloader
+ * @param additionalConfiguration Additional configuration
+ */
public FakeApplication(File path, ClassLoader classloader, Map<String,String> additionalConfiguration) {
wrappedApplication = new play.api.test.FakeApplication(
path,
21 framework/src/play-test/src/main/java/play/test/FakeRequest.java
View
@@ -4,30 +4,45 @@
import java.util.*;
+/**
+ * Fake HTTP request implementation.
+ */
public class FakeRequest {
play.api.test.FakeRequest fake;
+ /**
+ * Constructs a new GET / fake request.
+ */
public FakeRequest() {
this.fake = play.api.test.FakeRequest.apply();
}
+ /**
+ * Constructs a new request.
+ */
public FakeRequest(String method, String path) {
this.fake = play.api.test.FakeRequest.apply(method, path);
}
+ /**
+ * Add addtional headers to this request.
+ */
public FakeRequest withHeader(String name, String value) {
fake = fake.withHeaders(Scala.varargs(Scala.Tuple(name, value)));
return this;
}
- public FakeRequest withUrlFormEncodedBody(java.util.Map<String,String> data) {
+ /**
+ * Set a Form url encoded body to this request.
+ */
+ public FakeRequest withFormUrlEncodedBody(java.util.Map<String,String> data) {
List<scala.Tuple2<String,String>> args = new ArrayList<scala.Tuple2<String,String>>();
for(String key: data.keySet()) {
scala.Tuple2<String,String> pair = Scala.Tuple(key, data.get(key));
args.add(pair);
}
- fake = fake.withUrlFormEncodedBody(Scala.toSeq(args));
+ fake = fake.withFormUrlEncodedBody(Scala.toSeq(args));
return this;
}
@@ -35,7 +50,7 @@ public FakeRequest withUrlFormEncodedBody(java.util.Map<String,String> data) {
return ((play.api.test.FakeRequest<play.api.mvc.AnyContent>)fake).map(new scala.runtime.AbstractFunction1<play.api.mvc.AnyContent, play.mvc.Http.RequestBody>() {
public play.mvc.Http.RequestBody apply(play.api.mvc.AnyContent anyContent) {
return new play.core.j.JavaParsers.DefaultRequestBody(
- anyContent.asUrlFormEncoded(),
+ anyContent.asFormUrlEncoded(),
anyContent.asRaw(),
anyContent.asText(),
anyContent.asJson(),
117 framework/src/play-test/src/main/java/play/test/Helpers.java
View
@@ -11,6 +11,9 @@
import java.util.*;
+/**
+ * Helper functions to run tests.
+ */
public class Helpers implements play.mvc.Http.Status, play.mvc.Http.HeaderNames {
public static String GET = "GET";
@@ -19,14 +22,12 @@
public static String DELETE = "DELETE";
public static String HEAD = "HEAD";
- //
+ // --
public static Class<? extends WebDriver> HTMLUNIT = HtmlUnitDriver.class;
public static Class<? extends WebDriver> FIREFOX = FirefoxDriver.class;
- public static Result callAction(HandlerRef actionReference) {
- return callAction(actionReference, fakeRequest());
- }
+ // --
private static Result invokeHandler(play.api.mvc.Handler handler, FakeRequest fakeRequest) {
if(handler instanceof play.core.j.JavaAction) {
@@ -48,61 +49,112 @@ public String toString() {
}
}
+ // --
+
+ /**
+ * Call an action method while decorating it with the right @With interceptors.
+ */
+ public static Result callAction(HandlerRef actionReference) {
+ return callAction(actionReference, fakeRequest());
+ }
+
+ /**
+ * Call an action method while decorating it with the right @With interceptors.
+ */
public static Result callAction(HandlerRef actionReference, FakeRequest fakeRequest) {
play.api.mvc.HandlerRef handlerRef = (play.api.mvc.HandlerRef)actionReference;
return invokeHandler(handlerRef.handler(), fakeRequest);
}
+ /**
+ * Build a new GET / fake request.
+ */
public static FakeRequest fakeRequest() {
return new FakeRequest();
}
+ /**
+ * Build a new fake request.
+ */
public static FakeRequest fakeRequest(String method, String uri) {
return new FakeRequest(method, uri);
}
+ /**
+ * Build a new fake application.
+ */
public static FakeApplication fakeApplication() {
return new FakeApplication(new java.io.File("."), Helpers.class.getClassLoader(), new HashMap<String,String>());
}
+ /**
+ * Constructs a in-memory (h2) database configuration to add to a FakeApplication.
+ */
public static Map<String,String> inMemoryDatabase() {
return inMemoryDatabase("default");
}
+ /**
+ * Constructs a in-memory (h2) database configuration to add to a FakeApplication.
+ */
public static Map<String,String> inMemoryDatabase(String name) {
return Scala.asJava(play.api.test.Helpers.inMemoryDatabase(name));
}
+ /**
+ * Build a new fake application.
+ */
public static FakeApplication fakeApplication(Map<String,String> additionalConfiguration) {
return new FakeApplication(new java.io.File("."), Helpers.class.getClassLoader(), additionalConfiguration);
}
+ /**
+ * Extracts the Status code of this Result value.
+ */
public static int status(Result result) {
return play.core.j.JavaResultExtractor.getStatus(result);
}
+ /**
+ * Extracts the Location header of this Result value if this Result is a Redirect.
+ */
public static String redirectLocation(Result result) {
return header(LOCATION, result);
}
+ /**
+ * Extracts the Flash values of this Result value.
+ */
public static play.mvc.Http.Flash flash(Result result) {
return new play.mvc.Http.Flash(
Scala.asJava(play.api.test.Helpers.flash(result.getWrappedResult()).data())
);
}
+ /**
+ * Extracts an Header value of this Result value.
+ */
public static String header(String header, Result result) {
return play.core.j.JavaResultExtractor.getHeaders(result).get(header);
}
+ /**
+ * Extracts all Headers of this Result value.
+ */
public static Map<String,String> headers(Result result) {
return play.core.j.JavaResultExtractor.getHeaders(result);
}
+ /**
+ * Extracts the Content-Type of this Content value.
+ */
public static String contentType(Content content) {
return content.contentType();
}
+ /**
+ * Extracts the Content-Type of this Result value.
+ */
public static String contentType(Result result) {
String h = header(CONTENT_TYPE, result);
if(h == null) return null;
@@ -113,6 +165,9 @@ public static String contentType(Result result) {
}
}
+ /**
+ * Extracts the Charset of this Result value.
+ */
public static String charset(Result result) {
String h = header(CONTENT_TYPE, result);
if(h == null) return null;
@@ -123,18 +178,30 @@ public static String charset(Result result) {
}
}
+ /**
+ * Extracts the content as bytes.
+ */
public static byte[] contentAsBytes(Result result) {
return play.core.j.JavaResultExtractor.getBody(result);
}
+ /**
+ * Extracts the content as bytes.
+ */
public static byte[] contentAsBytes(Content content) {
return content.body().getBytes();
}
+ /**
+ * Extracts the content as String.
+ */
public static String contentAsString(Content content) {
return content.body();
}
+ /**
+ * Extracts the content as String.
+ */
public static String contentAsString(Result result) {
try {
String charset = charset(result);
@@ -149,6 +216,9 @@ public static String contentAsString(Result result) {
}
}
+ /**
+ * Use the Router to determine the Action to call for this request and executes it.
+ */
public static Result routeAndCall(FakeRequest fakeRequest) {
try {
return routeAndCall((Class<? extends play.core.Router.Routes>)FakeRequest.class.getClassLoader().loadClass("Routes"), fakeRequest);
@@ -159,6 +229,9 @@ public static Result routeAndCall(FakeRequest fakeRequest) {
}
}
+ /**
+ * Use the Router to determine the Action to call for this request and executes it.
+ */
public static Result routeAndCall(Class<? extends play.core.Router.Routes> router, FakeRequest fakeRequest) {
try {
play.core.Router.Routes routes = (play.core.Router.Routes)router.getClassLoader().loadClass(router.getName() + "$").getDeclaredField("MODULE$").get(null);
@@ -174,14 +247,23 @@ public static Result routeAndCall(Class<? extends play.core.Router.Routes> route
}
}
+ /**
+ * Starts a new application.
+ */
public static void start(FakeApplication fakeApplication) {
play.api.Play.start(fakeApplication.getWrappedApplication());
}
+ /**
+ * Stops an application.
+ */
public static void stop(FakeApplication fakeApplication) {
play.api.Play.stop();
}
+ /**
+ * Executes a block of code in a running application.
+ */
public static void running(FakeApplication fakeApplication, final Runnable block) {
try {
start(fakeApplication);
@@ -191,22 +273,37 @@ public static void running(FakeApplication fakeApplication, final Runnable block
}
}
+ /**
+ * Creates a new Test server.
+ */
public static TestServer testServer(int port) {
return new TestServer(port, fakeApplication());
}
+ /**
+ * Creates a new Test server.
+ */
public static TestServer testServer(int port, FakeApplication app) {
return new TestServer(port, app);
}
+ /**
+ * Starts a Test server.
+ */
public static void start(TestServer server) {
server.start();
}
+ /**
+ * Stops a Test server.
+ */
public static void stop(TestServer server) {
server.stop();
}
+ /**
+ * Executes a block of code in a running server.
+ */
public static void running(TestServer server, final Runnable block) {
try {
start(server);
@@ -216,6 +313,9 @@ public static void running(TestServer server, final Runnable block) {
}
}
+ /**
+ * Executes a block of code in a running server, with a test browser.
+ */
public static void running(TestServer server, Class<? extends WebDriver> webDriver, final Callback<TestBrowser> block) {
TestBrowser browser = null;
try {
@@ -232,10 +332,16 @@ public static void running(TestServer server, Class<? extends WebDriver> webDriv
}
}
+ /**
+ * Creates a Test Browser.
+ */
public static TestBrowser testBrowser() {
return new TestBrowser(new HtmlUnitDriver());
}
+ /**
+ * Creates a Test Browser.
+ */
public static TestBrowser testBrowser(Class<? extends WebDriver> webDriver) {
try {
return new TestBrowser(webDriver);
@@ -246,6 +352,9 @@ public static TestBrowser testBrowser(Class<? extends WebDriver> webDriver) {
}
}
+ /**
+ * Creates a Test Browser.
+ */
public static TestBrowser testBrowser(WebDriver of) {
return new TestBrowser(of);
}
31 framework/src/play-test/src/main/java/play/test/TestBrowser.java
View
@@ -8,16 +8,32 @@
import fr.javafreelance.fluentlenium.core.*;
+/**
+ * A test browser (Using Selenium WebDriver) with the FluentLenium API (https://github.com/Fluentlenium/FluentLenium).
+ */
public class TestBrowser extends Fluent {
+ /**
+ * A test browser (Using Selenium WebDriver) with the FluentLenium API (https://github.com/Fluentlenium/FluentLenium).
+ *
+ * @param webDriver The WebDriver instance to use.
+ */
public TestBrowser(Class<? extends WebDriver> webDriver) throws Exception {
this(webDriver.newInstance());
}
+ /**
+ * A test browser (Using Selenium WebDriver) with the FluentLenium API (https://github.com/Fluentlenium/FluentLenium).
+ *
+ * @param webDriver The WebDriver instance to use.
+ */
public TestBrowser(WebDriver webDriver) {
setDriver(webDriver);
}
+ /**
+ * Open an URL.
+ */
public void goTo(String url) {
if (url == null) {
throw new IllegalArgumentException("Url is mandatory");
@@ -25,22 +41,37 @@ public void goTo(String url) {
getDriver().get(url);
}
+ /**
+ * The current page URL.
+ */
public String url() {
return super.url();
}
+ /**
+ * The current page HTML source.
+ */
public String pageSource() {
return super.pageSource();
}
+ /**
+ * Retrieves all cookies.
+ */
public Set<Cookie> getCookies() {
return getDriver().manage().getCookies();
}
+ /**
+ * Retrieves a cookie.
+ */
public Cookie getCookieNamed(String name) {
return getDriver().manage().getCookieNamed(name);
}
+ /**
+ * Quits the browser
+ */
public void quit() {
getDriver().quit();
}
9 framework/src/play-test/src/main/java/play/test/TestServer.java
View
@@ -2,8 +2,17 @@
import java.io.*;
+/**
+ * A test Netty web server.
+ */
public class TestServer extends play.api.test.TestServer {
+ /**
+ * A test Netty web server.
+ *
+ * @param port HTTP port to bind on.
+ * @param application The FakeApplication to load in this server.
+ */
public TestServer(int port, FakeApplication application) {
super(port, application.getWrappedApplication());
}
2  framework/src/play-test/src/main/java/play/test/package-info.java
View
@@ -1,4 +1,4 @@
/**
- * Provides testing support
+ * Contains test helpers.
*/
package play.test;
62 framework/src/play-test/src/main/scala/play/api/test/Fakes.scala
View
@@ -2,40 +2,94 @@ package play.api.test;
import play.api.mvc._
+/**
+ * Fake HTTP headers implementation.
+ *
+ * @param data Headers data.
+ */
case class FakeHeaders(data: Map[String, Seq[String]] = Map.empty) extends Headers {
+
+ /**
+ * All header keys.
+ */
lazy val keys = data.keySet
- def getAll(key: String) = data.get(key).getOrElse(Seq.empty)
+
+ /**
+ * Get all header values defined for this key.
+ */
+ def getAll(key: String): Seq[String] = data.get(key).getOrElse(Seq.empty)
+
}
+/**
+ * Fake HTTP request implementation.
+ *
+ * @tparam A The body type.
+ * @param method The request HTTP method.
+ * @param uri The request uri.
+ * @param headers The request HTTP headers.
+ * @param body The request body.
+ */
case class FakeRequest[A](method: String, uri: String, headers: FakeHeaders, body: A) extends Request[A] {
+ /**
+ * The request path.
+ */
lazy val path = uri.split('?').take(1).mkString
- lazy val queryString = play.core.parsers.UrlFormEncodedParser.parse(rawQueryString)
+
+ /**
+ * The request query String
+ */
+ lazy val queryString: Map[String, Seq[String]] = play.core.parsers.FormUrlEncodedParser.parse(rawQueryString)
+ /**
+ * Constructs a new request with additional headers.
+ */
def withHeaders(newHeaders: (String, String)*): FakeRequest[A] = {
copy(headers = FakeHeaders(
headers.data ++ newHeaders.groupBy(_._1).mapValues(_.map(_._2))
))
}
- def withUrlFormEncodedBody(data: (String, String)*) = {
- copy(body = AnyContentAsUrlFormEncoded(data.groupBy(_._1).mapValues(_.map(_._2))))
+ /**
+ * Set a Form url encoded body to this request.
+ */
+ def withFormUrlEncodedBody(data: (String, String)*) = {
+ copy(body = AnyContentAsFormUrlEncoded(data.groupBy(_._1).mapValues(_.map(_._2))))
}
}
+/**
+ * Helper utilities to build FakeRequest values.
+ */
object FakeRequest {
+ /**
+ * Constructs a new GET / fake request.
+ */
def apply(): FakeRequest[play.api.mvc.AnyContent] = {
FakeRequest("GET", "/", FakeHeaders(), AnyContentAsEmpty)
}
+ /**
+ * Constructs a new request.
+ */
def apply(method: String, path: String): FakeRequest[play.api.mvc.AnyContent] = {
FakeRequest(method, path, FakeHeaders(), AnyContentAsEmpty)
}
}
+/**
+ * A Fake application.
+ *
+ * @param path The application path
+ * @param classloader The application classloader
+ * @param additionalPlugins Additional plugins class names loaded by this application
+ * @param withoutPlugins Plugins class names to disable
+ * @param additionalConfiguration Additional configuration
+ */
case class FakeApplication(
override val path: java.io.File = new java.io.File("."),
override val classloader: ClassLoader = classOf[FakeApplication].getClassLoader,
70 framework/src/play-test/src/main/scala/play/api/test/Helpers.scala
View
@@ -10,6 +10,9 @@ import org.openqa.selenium._
import org.openqa.selenium.firefox._
import org.openqa.selenium.htmlunit._
+/**
+ * Helper functions to run tests.
+ */
object Helpers extends Status with HeaderNames {
val GET = "GET"
@@ -21,6 +24,9 @@ object Helpers extends Status with HeaderNames {
val HTMLUNIT = classOf[HtmlUnitDriver]
val FIREFOX = classOf[FirefoxDriver]
+ /**
+ * Executes a block of code in a running application.
+ */
def running[T](fakeApp: FakeApplication)(block: => T): T = {
try {
Play.start(fakeApp)
@@ -30,6 +36,9 @@ object Helpers extends Status with HeaderNames {
}
}
+ /**
+ * Executes a block of code in a running server.
+ */
def running[T](testServer: TestServer)(block: => T): T = {
try {
testServer.start()
@@ -39,6 +48,9 @@ object Helpers extends Status with HeaderNames {
}
}
+ /**
+ * Executes a block of code in a running server, with a test browser.
+ */
def running[T, WEBDRIVER <: WebDriver](testServer: TestServer, webDriver: Class[WEBDRIVER])(block: TestBrowser => T): T = {
var browser: TestBrowser = null
try {
@@ -52,24 +64,45 @@ object Helpers extends Status with HeaderNames {
testServer.stop()
}
}
+
/**
- * running evolution for the given db
- * @param dbName
+ * Apply pending evolutions for the given DB.
*/
def evolutionFor(dbName: String) = play.api.db.evolutions.OfflineEvolutions.applyScript(new java.io.File("."), this.getClass.getClassLoader, dbName)
+ /**
+ * Extracts the Content-Type of this Content value.
+ */
def contentType(of: Content): String = of.contentType
+ /**
+ * Extracts the content as String.
+ */
def contentAsString(of: Content): String = of.body
+ /**
+ * Extracts the content as bytes.
+ */
def contentAsBytes(of: Content): Array[Byte] = of.body.getBytes
+ /**
+ * Extracts the Content-Type of this Result value.
+ */
def contentType(of: Result): Option[String] = header(CONTENT_TYPE, of).map(_.split(";").take(1).mkString.trim)
+ /**
+ * Extracts the Charset of this Result value.
+ */
def charset(of: Result): Option[String] = header(CONTENT_TYPE, of).map(_.split("; charset=").drop(1).mkString.trim)
+ /**
+ * Extracts the content as String.
+ */
def contentAsString(of: Result): String = new String(contentAsBytes(of), charset(of).getOrElse("utf-8"))
+ /**
+ * Extracts the content as bytes.
+ */
def contentAsBytes(of: Result): Array[Byte] = of match {
case r @ SimpleResult(_, bodyEnumerator) => {
var readAsBytes = Enumeratee.map[r.BODY_CONTENT](r.writeable.transform(_)).transform(Iteratee.consume[Array[Byte]]())
@@ -78,15 +111,27 @@ object Helpers extends Status with HeaderNames {
case r => sys.error("Cannot extract the body content from a result of type " + r.getClass.getName)
}
+ /**
+ * Extracts the Status code of this Result value.
+ */
def status(of: Result): Int = of match {
case Result(status, _) => status
case r => sys.error("Cannot extract the status from a result of type " + r.getClass.getName)
}
+ /**
+ * Extracts the Cookies of this Result value.
+ */
def cookies(of: Result): Cookies = Cookies(header(SET_COOKIE, of))
+ /**
+ * Extracts the Flash values of this Result value.
+ */
def flash(of: Result): Flash = Flash.decodeFromCookie(cookies(of).get(Flash.COOKIE_NAME))
+ /**
+ * Extracts the Location header of this Result value if this Result is a Redirect.
+ */
def redirectLocation(of: Result): Option[String] = of match {
case Result(FOUND, headers) => headers.get(LOCATION)
case Result(SEE_OTHER, headers) => headers.get(LOCATION)
@@ -96,17 +141,29 @@ object Helpers extends Status with HeaderNames {
case r => sys.error("Cannot extract the headers from a result of type " + r.getClass.getName)
}
+ /**
+ * Extracts an Header value of this Result value.
+ */
def header(header: String, of: Result): Option[String] = headers(of).get(header)
+ /**
+ * Extracts all Headers of this Result value.
+ */
def headers(of: Result): Map[String, String] = of match {
case Result(_, headers) => headers
case r => sys.error("Cannot extract the headers from a result of type " + r.getClass.getName)
}
+ /**
+ * Use the Router to determine the Action to call for this request and executes it.
+ */
def routeAndCall[T](request: FakeRequest[T]): Option[Result] = {
routeAndCall(this.getClass.getClassLoader.loadClass("Routes").asInstanceOf[Class[play.core.Router.Routes]], request)
}
+ /**
+ * Use the Router to determine the Action to call for this request and executes it.
+ */
def routeAndCall[T, ROUTER <: play.core.Router.Routes](router: Class[ROUTER], request: FakeRequest[T]): Option[Result] = {
val routes = router.getClassLoader.loadClass(router.getName + "$").getDeclaredField("MODULE$").get(null).asInstanceOf[play.core.Router.Routes]
routes.routes.lift(request).map {
@@ -114,10 +171,19 @@ object Helpers extends Status with HeaderNames {
}
}
+ /**
+ * Block until a Promise is redeemed.
+ */
def await[T](p: play.api.libs.concurrent.Promise[T]): T = await(p, 5000)
+ /**
+ * Block until a Promise is redeemed with the specified timeout.
+ */
def await[T](p: play.api.libs.concurrent.Promise[T], timeout: Long, unit: java.util.concurrent.TimeUnit = java.util.concurrent.TimeUnit.MILLISECONDS): T = p.await(timeout, unit).get
+ /**
+ * Constructs a in-memory (h2) database configuration to add to a FakeApplication.
+ */
def inMemoryDatabase(name: String = "default") = {
Map(
("db." + name + ".driver") -> "org.h2.Driver",
46 framework/src/play-test/src/main/scala/play/api/test/Selenium.scala
View
@@ -12,34 +12,42 @@ import fr.javafreelance.fluentlenium.core._
import collection.JavaConverters._
+/**
+ * A test browser (Using Selenium WebDriver) with the FluentLenium API (https://github.com/Fluentlenium/FluentLenium).
+ *
+ * @param webDriver The WebDriver instance to use.
+ */
case class TestBrowser(webDriver: WebDriver) extends Fluent(webDriver) {
+ /**
+ * Open an URL.
+ */
def goTo(url: String) {
getDriver.get(url)
}
/**
- * @return url
+ * The current page URL.
*/
override def url = super.url
/**
- * @return current page's source
+ * The current page HTML source.
*/
override def pageSource = super.pageSource
/**
- * @return cookies
+ * Retrieves all cookies.
*/
def getCookies() = getDriver().manage().getCookies().asScala
/**
- * @param name
+ * Retrieves a cookie.
*/
def getCookieNamed(name: String) = getDriver().manage().getCookieNamed(name)
/**
- * quits the browser
+ * Quits the browser
*/
def quit() {
getDriver.quit()
@@ -47,18 +55,41 @@ case class TestBrowser(webDriver: WebDriver) extends Fluent(webDriver) {
}
+/**
+ * Helper utilities to build TestBrowsers
+ */
object TestBrowser {
+ /**
+ * Creates an in-memory WebBrowser (using HtmlUnit)
+ */
def default() = TestBrowser(new HtmlUnitDriver)
+
+ /**
+ * Creates a firefox WebBrowser.
+ */
def firefox() = TestBrowser(new FirefoxDriver)
+
+ /**
+ * Creates a WebBrowser of the specified class name.
+ */
def of[WEBDRIVER <: WebDriver](webDriver: Class[WEBDRIVER]) = TestBrowser(webDriver.newInstance)
}
+/**
+ * A test Netty web server.
+ *
+ * @param port HTTP port to bind on.
+ * @param application The FakeApplication to load in this server.
+ */
case class TestServer(port: Int, application: FakeApplication = FakeApplication()) {
- var server: play.core.server.NettyServer = _
+ private var server: play.core.server.NettyServer = _
+ /**
+ * Starts this server.
+ */
def start() {
if (server != null) {
sys.error("Server already started!")
@@ -66,6 +97,9 @@ case class TestServer(port: Int, application: FakeApplication = FakeApplication(
server = new play.core.server.NettyServer(new play.core.TestApplication(application), port, mode = Mode.Test)
}
+ /**
+ * Stops this server.
+ */
def stop() {
if (server == null) {
sys.error("Server is not started!");
6 framework/src/play-test/src/main/scala/play/api/test/package.scala
View
@@ -0,0 +1,6 @@
+package play.api
+
+/**
+ * Contains test helpers.
+ */
+package object test
16 framework/src/play/src/main/java/play/Application.java
View
@@ -32,17 +32,14 @@ public File path() {
return application.path();
}
+ /**
+ * Retrieves the application configuration/
+ * <p>
+ * @return the application path
+ */
public Configuration configuration() {
return new Configuration(application.configuration());
}
-
- /**
- * Returns the Messages-instance used to access the message API for the application
- * @return a Messages instance
- */
- public Messages messages() {
- return Messages.current();
- }
/**
* Retrieves the application classloader.
@@ -83,6 +80,9 @@ public InputStream resourceAsStream(String relativePath) {
return Scala.orNull(application.resourceAsStream(relativePath));
}
+ /**
+ * Retrieve the plugin instance for the class.
+ */
public <T> T plugin(Class<T> pluginClass) {
return Scala.orNull(application.plugin(pluginClass));
}
12 framework/src/play/src/main/java/play/Configuration.java
View
@@ -59,10 +59,22 @@ public String getString(String key) {
return Scala.orNull(conf.getString(key, scala.Option.<scala.collection.immutable.Set<java.lang.String>>empty()));
}
+ /**
+ * Retrieves a configuration value as a <code>Milliseconds</code>.
+ *
+ * @param key configuration key (relative to configuration root key)
+ * @return a configuration value or <code>null</code>
+ */
public Long getMilliseconds(String key) {
return (Long)Scala.orNull(conf.getMilliseconds(key));
}
+ /**
+ * Retrieves a configuration value as a <code>Bytes</code>.
+ *
+ * @param key configuration key (relative to configuration root key)
+ * @return a configuration value or <code>null</code>
+ */
public Long getBytes(String key) {
return (Long)Scala.orNull(conf.getBytes(key));
}
6 framework/src/play/src/main/java/play/Play.java
View
@@ -1,7 +1,13 @@
package play;
+/**
+ * High-level API to access Play global features.
+ */
public class Play {
+ /**
+ * Returns the currently running application, or `null` if not defined.
+ */
public static Application application() {
play.api.Application app = play.api.Play.unsafeApplication();
if(app == null) {
8 framework/src/play/src/main/java/play/Plugin.java
View
@@ -17,5 +17,11 @@ public void onStart() {
public void onStop() {
}
- public boolean enabled() { return true;}
+ /**
+ * Is this plugin enabled.
+ */
+ public boolean enabled() {
+ return true;
+ }
+
}
9 framework/src/play/src/main/java/play/Routes.java
View
@@ -4,12 +4,21 @@
import play.libs.Scala;
+/**
+ * Helper utilities related to `Router`.
+ */
public class Routes {
+ /**
+ * Generates a JavaScript router.
+ */
public static String javascriptRouter(String name, play.core.Router.JavascriptReverseRoute... routes) {
return javascriptRouter(name, "jQuery.ajax", routes);
}
+ /**
+ * Generates a JavaScript router.
+ */
public static String javascriptRouter(String name, String ajaxMethod, play.core.Router.JavascriptReverseRoute... routes) {
return play.api.Routes.javascriptRouter(
name, Scala.Option(ajaxMethod), Scala.toSeq(routes)
30 framework/src/play/src/main/java/play/cache/Cache.java
View
@@ -11,26 +11,7 @@
* @return object
*/
public static Object get(String key) {
- return play.api.cache.Cache.getAsJava(key,play.api.Play.unsafeApplication());
- }
-
- /**
- * Retrieves an object by key.
- *
- * @return generic type T
- */
- @SuppressWarnings("unchecked")
- public static <T> T get(String key, Class<T> clazz) {
- return (T) play.api.cache.Cache.getAsJava(key,play.api.Play.unsafeApplication());
- }
-
- /**
- * Retrieves an object by keys - provides multi-value access to Play's cache store.
- *
- * @return a key value list of cache keys and corresponding values
- */
- public static java.util.Map<String,Object> get(String... keys) {
- return play.api.cache.Cache.getAsJava(keys, play.api.Play.unsafeApplication());
+ return play.api.cache.Cache.get(key,play.api.Play.unsafeApplication());
}
/**
@@ -39,14 +20,7 @@ public static Object get(String key) {
* @param expiration expiration in seconds
*/
public static void set(String key, Object value, int expiration) {
- play.api.cache.Cache.set(key,value,expiration, play.api.Play.unsafeApplication());
- }
-
- /**
- * Sets a value, with expiration set to 1800 seconds (30 minutes) by default.
- */
- public static void set(String key, Object value) {
- play.api.cache.Cache.set(key,value, 1800,play.api.Play.unsafeApplication());
+ play.api.cache.Cache.set(key,value,expiration, play.api.Play.unsafeApplication());
}
}
12 framework/src/play/src/main/java/play/data/Form.java
View
@@ -83,13 +83,13 @@ public Form(String rootName, Class<T> clazz, Map<String,String> data, Map<String
protected Map<String,String> requestData() {
Map<String,String[]> urlFormEncoded = new HashMap<String,String[]>();
- if(play.mvc.Controller.request().body().asUrlFormEncoded() != null) {
- urlFormEncoded = play.mvc.Controller.request().body().asUrlFormEncoded();
+ if(play.mvc.Controller.request().body().asFormUrlEncoded() != null) {
+ urlFormEncoded = play.mvc.Controller.request().body().asFormUrlEncoded();
}
Map<String,String[]> multipartFormData = new HashMap<String,String[]>();
if(play.mvc.Controller.request().body().asMultipartFormData() != null) {
- multipartFormData = play.mvc.Controller.request().body().asMultipartFormData().asUrlFormEncoded();
+ multipartFormData = play.mvc.Controller.request().body().asMultipartFormData().asFormUrlEncoded();
}
Map<String,String[]> queryString = play.mvc.Controller.request().queryString();
@@ -509,6 +509,9 @@ public String valueOr(String or) {
return format;
}
+ /**
+ * Return the indexes available for this field (for repeated fields ad List)
+ */
public List<Integer> indexes() {
List<Integer> result = new ArrayList<Integer>();
if(form.value().isDefined()) {
@@ -538,6 +541,9 @@ public String valueOr(String or) {
return result;
}
+ /**
+ * Get a sub-field, with a key relative to the current field.
+ */
public Field sub(String key) {
String subKey = null;
if(key.startsWith("[")) {
2  framework/src/play/src/main/java/play/data/validation/package-info.java
View
@@ -1,4 +1,4 @@
/**
- * Provides the validation API used by <code>Form</code> classes.
+ * Provides the JSR 303 validation constraints.
*/
package play.data.validation;
2  framework/src/play/src/main/java/play/db/ebean/TransactionalAction.java
View
@@ -6,7 +6,7 @@
import com.avaje.ebean.*;
/**
- * Wraps an action in am Ebean transaction.
+ * Wraps an action in an Ebean transaction.
*/
public class TransactionalAction extends Action<Transactional> {
29 framework/src/play/src/main/java/play/db/jpa/JPA.java
View
@@ -7,10 +7,16 @@
import javax.persistence.*;
+/**
+ * JPA Helpers.
+ */
public class JPA {
static ThreadLocal<EntityManager> currentEntityManager = new ThreadLocal<EntityManager>();
+ /**
+ * Get the EntityManager for specified persistence unit for this thread.
+ */
public static EntityManager em(String key) {
Application app = Play.application();
if(app == null) {
@@ -30,6 +36,9 @@ public static EntityManager em(String key) {
return em;
}
+ /**
+ * Get the default EntityManager for this thread.
+ */
public static EntityManager em() {
EntityManager em = currentEntityManager.get();
if(em == null) {
@@ -38,14 +47,27 @@ public static EntityManager em() {
return em;
}
+ /**
+ * Bind an EntityManager to the current thread.
+ */
public static void bindForCurrentThread(EntityManager em) {
currentEntityManager.set(em);
}
+ /**
+ * Run a block of code in a JPA transaction.
+ *
+ * @param block Block of code to execute.
+ */
public static <T> T withTransaction(play.libs.F.Function0<T> block) throws Throwable {
return withTransaction("default", false, block);
}
+ /**
+ * Run a block of code in a JPA transaction.
+ *
+ * @param block Block of code to execute.
+ */
public static void withTransaction(final play.libs.F.Callback0 block) {
try {
withTransaction("default", false, new play.libs.F.Function0<Void>() {
@@ -59,6 +81,13 @@ public Void apply() throws Throwable {
}
}
+ /**
+ * Run a block of code in a JPA transaction.
+ *
+ * @param name The persistence unit name
+ * @param readOnly Is the transaction read-only?
+ * @param block Block of code to execute.
+ */
public static <T> T withTransaction(String name, boolean readOnly, play.libs.F.Function0<T> block) throws Throwable {
EntityManager em = null;
EntityTransaction tx = null;
4 framework/src/play/src/main/java/play/db/jpa/package-info.java
View
@@ -0,0 +1,4 @@
+/**
+ * Provides JPA ORM integration.
+ */
+package play.db.jpa;
17 framework/src/play/src/main/java/play/i18n/Messages.java
View
@@ -6,23 +6,10 @@
/**
* High-level internationalisation API.
- *
- * For example:
- * {{{
- * String msgString = Messages.current().get("items.found", items.size)
- * }}}
*/
public class Messages {
/**
- * Returns the Messages-instance used to access the message API for the application
- * @return a Messages instance
- */
- public static Messages current() {
- return new Messages();
- }
-
- /**
* Translates a message.
*
* Uses `java.text.MessageFormat` internally to format the message.
@@ -31,8 +18,8 @@ public static Messages current() {
* @param args the message arguments
* @return the formatted message or a default rendering if the key wasn't defined
*/
- public String get(String key, Object... args) {
- Buffer scalaArgs = scala.collection.JavaConverters.asScalaBufferConverter( Arrays.asList(args)).asScala();
+ public static String get(String key, Object... args) {
+ Buffer scalaArgs = scala.collection.JavaConverters.asScalaBufferConverter(Arrays.asList(args)).asScala();
return play.api.i18n.Messages.apply(key, scalaArgs);
}
}
4 framework/src/play/src/main/java/play/i18n/package-info.java
View
@@ -0,0 +1,4 @@
+/**
+ * Provides the i18n API.
+ */
+package play.i18n;
9 framework/src/play/src/main/java/play/libs/Akka.java
View
@@ -6,14 +6,23 @@
import play.api.*;
import play.libs.F.*;
+/**
+ * Helper to access the application defined Akka Actor system.
+ */
public class Akka {
+ /**
+ * Transform this Akka future to a Play Promise.
+ */
public static <A> Promise<A> asPromise(Future<A> akkaFuture) {
return new Promise<A>(
new play.api.libs.akka.AkkaPromise<A>(akkaFuture)
);
}
+ /**
+ * Retrieve the application Akka Actor system.
+ */
public static ActorSystem system() {
return play.api.libs.akka.Akka.system(Play.current());
}
24 framework/src/play/src/main/java/play/libs/F.java
View
@@ -22,34 +22,58 @@
*/
public class F {
+ /**
+ * A Callback with no arguments.
+ */
public static interface Callback0 {
public void invoke() throws Throwable;
}
+ /**
+ * A Callback with a single argument.
+ */
public static interface Callback<A> {
public void invoke(A a) throws Throwable;
}
+ /**
+ * A Callback with 2 arguments.
+ */
public static interface Callback2<A,B> {
public void invoke(A a, B b) throws Throwable;
}
+ /**
+ * A Callback with 3 arguments.
+ */
public static interface Callback3<A,B,C> {
public void invoke(A a, B b, C c) throws Throwable;
}
+ /**
+ * A Function with no arguments.
+ */
public static interface Function0<R> {
public R apply() throws Throwable;
}
+ /**
+ * A Function with a single argument.
+ */
public static interface Function<A,R> {
public R apply(A a) throws Throwable;
}
+ /**
+ * A Function with 2 arguments.
+ */
public static interface Function2<A,B,R> {
public R apply(A a, B b) throws Throwable;
}
+ /**
+ * A Function with 3 arguments.
+ */
public static interface Function3<A,B,C,R> {
public R apply(A a, B b, C c) throws Throwable;
}
33 framework/src/play/src/main/java/play/libs/Json.java
View
@@ -7,26 +7,14 @@
import org.codehaus.jackson.node.*;
/**
- * provides helpers to deal with JSON
+ * Helper functions to handle JsonNode values.
*/
-
public class Json {
/**
- * provides a simple way to serialize into JSON.
+ * Convert an object to JsonNode.
*
- * usage (in a controller):
- *
- * {{{
- * public static Result index() {
- * Map<String,String> d = new HashMap<String,String>();
- * d.put("peter","foo");
- * d.put("yay","value");
- * return ok(toJson(d));
- * }
- * }}}
- *
- * @param data to be serialized
+ * @param data Value to convert in Json.
*/
public static JsonNode toJson(final Object data) {
try {
@@ -36,6 +24,12 @@ public static JsonNode toJson(final Object data) {
}
}
+ /**
+ * Convert a JsonNode to a Java value
+ *
+ * @param json Json value to convert.
+ * @param clazz Expected Java value type.
+ */
public static <A> A fromJson(JsonNode json, Class<A> clazz) {
try {
return new ObjectMapper().treeToValue(json, clazz);
@@ -44,14 +38,23 @@ public static JsonNode toJson(final Object data) {
}
}
+ /**
+ * Creates a new empty ObjectNode.
+ */
public static ObjectNode newObject() {
return new ObjectMapper().createObjectNode();
}
+ /**
+ * Convert a JsonNode to its string representation.
+ */
public static String stringify(JsonNode json) {
return json.toString();
}
+ /**
+ * Parse a String representing a json, and return it as a JsonNode.
+ */
public static JsonNode parse(String src) {
try {
return new ObjectMapper().readValue(src, JsonNode.class);
37 framework/src/play/src/main/java/play/libs/Scala.java
View
@@ -2,11 +2,14 @@
import java.util.*;
-/*
- * class that contains useful java <-> scala conversion helpers
+/**
+ * Class that contains useful java <-> scala conversion helpers.
*/
public class Scala {
+ /**
+ * Wrap a Scala Option, handling None as null.
+ */
public static <T> T orNull(scala.Option<T> opt) {
if(opt.isDefined()) {
return opt.get();
@@ -14,44 +17,74 @@
return null;
}
+ /**
+ * Converts a Scala Map to Java.
+ */
public static <K,V> java.util.Map<K,V> asJava(scala.collection.Map<K,V> scalaMap) {
return scala.collection.JavaConverters.asJavaMapConverter(scalaMap).asJava();
}
+ /**
+ * Converts a Java Map to Scala.
+ */
public static <A,B> scala.collection.immutable.Map<A,B> asScala(Map<A,B> javaMap) {
return play.utils.Conversions.newMap(
scala.collection.JavaConverters.asScalaMapConverter(javaMap).asScala().toSeq()
);
}
+ /**
+ * Converts a Scala List to Java.
+ */
public static <T> java.util.List<T> asJava(scala.collection.immutable.List<T> scalaList) {
return scala.collection.JavaConverters.asJavaListConverter(scalaList).asJava();
}
+ /**
+ * Converts a Java List to Scala Seq.
+ */
public static <T> scala.collection.Seq<T> toSeq(java.util.List<T> list) {
return scala.collection.JavaConverters.asScalaBufferConverter(list).asScala().toList();
}
+ /**
+ * Converts a Java Array to Scala Seq.
+ */
public static <T> scala.collection.Seq<T> toSeq(T[] array) {
return toSeq(java.util.Arrays.asList(array));
}
+ /**
+ * Converts a Java varargs to Scala Seq.
+ */
public static <T> scala.collection.Seq<T> varargs(T... array) {
return toSeq(java.util.Arrays.asList(array));
}
+ /**
+ * Wrap a value into a Scala Option.
+ */
public static <T> scala.Option<T> Option(T t) {
return scala.Option.apply(t);
}
+ /**
+ * Create a Scala Tuple2.
+ */
public static <A,B> scala.Tuple2<A,B> Tuple(A a, B b) {
return new scala.Tuple2(a, b);
}
+ /**
+ * Creates an empty Scala Seq.
+ */
public static <T> scala.collection.Seq<T> emptySeq() {
return (scala.collection.Seq<T>)toSeq(new Object[] {});
}
+ /**
+ * Creates an empty Scala Map.
+ */
public static <A,B> scala.collection.immutable.Map<A,B> emptyMap() {
return new scala.collection.immutable.HashMap<A,B>();
}
43 framework/src/play/src/main/java/play/libs/WS.java
View
@@ -32,25 +32,17 @@
import org.codehaus.jackson.map.ObjectMapper;
/**
- * Asynchronous API to to query web services, as an http client
- *
- * Usage example:
- * import play.libs.WS;
- * WS.url("http://example.com/feed").get()
- * WS.url("http://mysite.com/post")
- * .setHeader("Content-Type","application/x-www-form-urlencoded")
- * .post("param1=foo")
- *
- * The value returned is a Promise<Response>,
- * and you should use Play's asynchronous mechanisms to use this response.
+ * Asynchronous API to to query web services, as an http client.
*
+ * The value returned is a Promise<Response>, and you should use Play's asynchronous mechanisms to use this response.
*/
public class WS {
- private static AsyncHttpClient client = play.api.libs.WS.client();
+ private static AsyncHttpClient client = play.api.libs.ws.WS.client();
/**
* Prepare a new request. You can then construct it by chaining calls.
+ *
* @param url the URL to request
*/
public static WSRequestHolder url(String url) {
@@ -58,7 +50,7 @@ public static WSRequestHolder url(String url) {
}
/**
- * provides the bridge between Play and the underlying ning request
+ * Provides the bridge between Play and the underlying ning request
*/
public static class WSRequest extends RequestBuilderBase<WSRequest> {
@@ -101,8 +93,9 @@ public void onThrowable(Throwable t) {
return new Promise(scalaPromise);
}
}
+
/**
- * provides the user facing API for WS
+ * provides the User facing API for building WS request.
*/
public static class WSRequestHolder {
@@ -119,7 +112,8 @@ public WSRequestHolder(String url) {
}
/**
- * sets a header with the given name, this can be called repeatedly
+ * Sets a header with the given name, this can be called repeatedly
+ *
* @param name
* @param value
*/
@@ -136,7 +130,8 @@ public WSRequestHolder setHeader(String name, String value) {
}
/**
- * sets a query parameter with the given name,this can be called repeatedly
+ * Sets a query parameter with the given name,this can be called repeatedly
+ *
* @param name
* @param value
*/
@@ -152,8 +147,9 @@ public WSRequestHolder setQueryParameter(String name, String value) {
return this;
}
- /**
- * sets the authentication header for the current request
+ /**
+ * Sets the authentication header for the current request.
+ *
* @param username
* @param password
* @param scheme authentication scheme
@@ -174,6 +170,7 @@ public WSRequestHolder setAuth(String username, String password, AuthScheme sche
/**
* Perform a POST on the request asynchronously.
+ *
* @param body represented as String
*/
public Promise<Response> post(String body) {
@@ -182,7 +179,8 @@ public WSRequestHolder setAuth(String username, String password, AuthScheme sche
/**
* Perform a PUT on the request asynchronously.
- * @param body represented as String
+ *
+ * @param body represented as String
*/
public Promise<Response> put(String body) {
return executeString("PUT", body);
@@ -190,6 +188,7 @@ public WSRequestHolder setAuth(String username, String password, AuthScheme sche
/**
* Perform a POST on the request asynchronously.
+ *
* @param body represented as an InputStream
*/
public Promise<Response> post(InputStream body) {
@@ -198,6 +197,7 @@ public WSRequestHolder setAuth(String username, String password, AuthScheme sche
/**
* Perform a PUT on the request asynchronously.
+ *
* @param body represented as an InputStream
*/
public Promise<Response> put(InputStream body) {
@@ -206,6 +206,7 @@ public WSRequestHolder setAuth(String username, String password, AuthScheme sche
/**
* Perform a POST on the request asynchronously.
+ *
* @param body represented as a File
*/
public Promise<Response> post(File body) {
@@ -214,6 +215,7 @@ public WSRequestHolder setAuth(String username, String password, AuthScheme sche
/**
* Perform a PUT on the request asynchronously.
+ *
* @param body represented as a File
*/
public Promise<Response> put(File body) {
@@ -282,8 +284,9 @@ public WSRequestHolder setAuth(String username, String password, AuthScheme sche
}
+
/**
- * provides Response for all WS.url calls
+ * A WS response.
*/
public static class Response {
9 framework/src/play/src/main/java/play/libs/XML.java
View
@@ -13,8 +13,14 @@
import org.xml.sax.InputSource;
import org.xml.sax.SAXException;
+/**
+ * XML utilities.
+ */
public class XML {
+ /**
+ * Parse an XML string as DOM.
+ */
public static Document fromString(String xml) {
try {
return fromInputStream(
@@ -26,6 +32,9 @@ public static Document fromString(String xml) {
}
}
+ /**
+ * Parse an InputStream as DOM.
+ */
public static Document fromInputStream(InputStream in, String encoding) {
DocumentBuilderFactory factory = null;
DocumentBuilder builder = null;
11 framework/src/play/src/main/java/play/libs/Yaml.java
View
@@ -6,8 +6,14 @@
import org.yaml.snakeyaml.*;
import org.yaml.snakeyaml.constructor.*;
+/**
+ * Yaml utilities.
+ */
public class Yaml {
+ /**
+ * Load a Yaml file from the classpath.
+ */
public static Object load(String resourceName) {
return load(
play.Play.application().resourceAsStream(resourceName),
@@ -15,6 +21,11 @@ public static Object load(String resourceName) {
);
}
+ /**
+ * Load the specified InputStream as Yaml.
+ *
+ * @param classloader The classloader to use to instantiate Java objects.
+ */
public static Object load(InputStream is, ClassLoader classloader) {
org.yaml.snakeyaml.Yaml yaml = new org.yaml.snakeyaml.Yaml(new CustomClassLoaderConstructor(classloader));
return yaml.load(is);
40 framework/src/play/src/main/java/play/mvc/BodyParser.java
View
@@ -4,10 +4,16 @@
import play.api.libs.iteratee.*;
+/**
+ * A body parser parses the HTTP request body content.
+ */
public interface BodyParser {
play.api.mvc.BodyParser<Http.RequestBody> parser(int maxLength);
+ /**
+ * Specifiy the body parser to use for an Action method.
+ */
@Target({ElementType.TYPE, ElementType.METHOD})
@Retention(RetentionPolicy.RUNTIME)
public @interface Of {
@@ -15,60 +21,90 @@
int maxLength() default Integer.MAX_VALUE;
}
+ /**
+ * Guess the body content by checking the Content-Type header.
+ */
public static class AnyContent implements BodyParser {
public play.api.mvc.BodyParser<Http.RequestBody> parser(int maxLength) {
return play.core.j.JavaParsers.anyContent(maxLength);
}
}
+ /**
+ * Parse the body as Json if the Content-Type is text/json or application/json.
+ */
public static class Json implements BodyParser {
public play.api.mvc.BodyParser<Http.RequestBody> parser(int maxLength) {
return play.core.j.JavaParsers.json(maxLength);
}
}
+ /**
+ * Parse the body as Json without checking the Content-Type.
+ */
public static class TolerantJson implements BodyParser {
public play.api.mvc.BodyParser<Http.RequestBody> parser(int maxLength) {
return play.core.j.JavaParsers.tolerantJson(maxLength);
}
}
+ /**
+ * Parse the body as Xml if the Content-Type is text/xml.
+ */
public static class Xml implements BodyParser {
public play.api.mvc.BodyParser<Http.RequestBody> parser(int maxLength) {
return play.core.j.JavaParsers.xml(maxLength);
}
}
+ /**
+ * Parse the body as Xml without checking the Content-Type.
+ */
public static class TolerantXml implements BodyParser {
public play.api.mvc.BodyParser<Http.RequestBody> parser(int maxLength) {
return play.core.j.JavaParsers.tolerantXml(maxLength);
}
}
+ /**
+ * Parse the body as text if the Content-Type is text/plain.
+ */
public static class Text implements BodyParser {
public play.api.mvc.BodyParser<Http.RequestBody> parser(int maxLength) {
return play.core.j.JavaParsers.text(maxLength);
}
}
+ /**
+ * Parse the body as text without checking the Content-Type.
+ */
public static class TolerantText implements BodyParser {
public play.api.mvc.BodyParser<Http.RequestBody> parser(int maxLength) {
return play.core.j.JavaParsers.tolerantText(maxLength);
}
}
+ /**
+ * Store the body content in a RawBuffer.
+ */
public static class Raw implements BodyParser {
public play.api.mvc.BodyParser<Http.RequestBody> parser(int maxLength) {
return play.core.j.JavaParsers.raw(maxLength);
}
}
- public static class UrlFormEncoded implements BodyParser {
+ /**
+ * Parse the body as form url encoded if the Content-Type is application/x-www-form-urlencoded.
+ */
+ public static class FormUrlEncoded implements BodyParser {
public play.api.mvc.BodyParser<Http.RequestBody> parser(int maxLength) {
- return play.core.j.JavaParsers.urlFormEncoded(maxLength);
+ return play.core.j.JavaParsers.formUrlEncoded(maxLength);
}
}
+ /**
+ * Parse the body as form url encoded without checking the Content-Type.
+ */
public static class MultipartFormData implements BodyParser {
public play.api.mvc.BodyParser<Http.RequestBody> parser(int maxLength) {
return play.core.j.JavaParsers.multipartFormData(maxLength);
12 framework/src/play/src/main/java/play/mvc/Call.java
View
@@ -17,18 +17,30 @@
*/
public abstract String method();
+ /**
+ * Transform this call to an absolute URL.
+ */
public String absoluteURL(Http.Request request) {
return absoluteURL(request, false);
}
+ /**
+ * Transform this call to an absolute URL.
+ */
public String absoluteURL(Http.Request request, boolean secure) {
return "http" + (secure ? "s" : "") + "://" + request.host() + this.url();
}
+ /**
+ * Transform this call to an WebSocket URL.
+ */
public String webSocketURL(Http.Request request) {
return webSocketURL(request, false);
}
+ /**
+ * Transform this call to an WebSocket URL.
+ */
public String webSocketURL(Http.Request request, boolean secure) {
return "ws" + (secure ? "s" : "") + "://" + request.host() + this.url();
}
3  framework/src/play/src/main/java/play/mvc/Content.java
View
@@ -1,5 +1,8 @@
package play.mvc;
+/**
+ * Generic type representing content to be sent over an HTTP response.
+ */
public interface Content extends play.api.mvc.Content {
}
3  framework/src/play/src/main/java/play/mvc/HandlerRef.java
View
@@ -1,5 +1,8 @@
package play.mvc;