0
# Play Framework Java API
1

2
Play Framework is a high-velocity web framework for Java that combines productivity and performance for building scalable web applications. The Java API provides a comprehensive programming interface that allows developers to create RESTful web applications with built-in support for form handling, validation, dependency injection, streaming, and asynchronous processing.
3

4
## Package Information
5

6
- **Package Name**: com.typesafe.play:play-java_2.10
7
- **Package Type**: maven
8
- **Language**: Java
9
- **Installation**: Add to Maven `pom.xml`:
10
  ```xml
11
  <dependency>
12
    <groupId>com.typesafe.play</groupId>
13
    <artifactId>play-java_2.10</artifactId>
14
    <version>2.4.11</version>
15
  </dependency>
16
  ```
17
- **SBT Installation**: `libraryDependencies += "com.typesafe.play" %% "play-java" % "2.4.11"`
18

19
## Core Imports
20

21
```java
22
import play.data.Form;
23
import play.data.DynamicForm;
24
import play.data.validation.Constraints;
25
import play.inject.guice.GuiceApplicationBuilder;
26
import play.inject.guice.GuiceInjectorBuilder;
27
import play.inject.guice.Guiceable;
28
import play.libs.*;
29
import play.routing.RoutingDsl;
30
```
31

32
## Basic Usage
33

34
```java
35
import play.data.Form;
36
import play.data.DynamicForm;
37
import play.mvc.Controller;
38
import play.mvc.Result;
39
import static play.mvc.Results.*;
40

41
// Form handling
42
public class UserController extends Controller {
43
    
44
    // Dynamic form for unstructured data
45
    public Result handleDynamicForm() {
46
        DynamicForm form = Form.form().bindFromRequest();
47
        if (form.hasErrors()) {
48
            return badRequest(form.errorsAsJson());
49
        }
50
        String name = form.get("name");
51
        String email = form.get("email");
52
        return ok("User: " + name + ", " + email);
53
    }
54
    
55
    // Typed form for structured data
56
    public Result handleTypedForm() {
57
        Form<User> userForm = Form.form(User.class).bindFromRequest();
58
        if (userForm.hasErrors()) {
59
            return badRequest(userForm.errorsAsJson());
60
        }
61
        User user = userForm.get();
62
        return ok("Created user: " + user.name);
63
    }
64
}
65

66
// Simple routing DSL
67
public class MyRoutes {
68
    RoutingDsl routingDsl = new RoutingDsl();
69
    
70
    public play.api.routing.Router createRouter() {
71
        return routingDsl
72
            .GET("/users/:id").routeTo((String id) -> 
73
                ok("User ID: " + id))
74
            .POST("/users").routeTo(() -> 
75
                ok("Created user"))
76
            .build();
77
    }
78
}
79
```
80

81
## Architecture
82

83
Play Framework Java API is built around several key components:
84

85
- **Form Processing**: Both dynamic and typed form handling with automatic data binding
86
- **Validation Framework**: JSR-303 validation with built-in constraints and custom validators
87
- **Dependency Injection**: Guice integration with builder patterns for application configuration
88
- **Utility Libraries**: Comprehensive utilities for crypto, time parsing, XML/YAML processing, and streaming
89
- **Routing DSL**: Programmatic route definition with type-safe parameter handling
90
- **Streaming Support**: Server-Sent Events and Comet messaging for real-time applications
91

92
## Capabilities
93

94
### Form Handling and Data Binding
95

96
Core form processing capabilities for handling HTML forms, data binding, and validation. Supports both dynamic forms for unstructured data and typed forms for model binding.
97

98
```java { .api }
99
public class Form<T> {
100
    public static DynamicForm form();
101
    public static <T> Form<T> form(Class<T> clazz);
102
    public static <T> Form<T> form(String name, Class<T> clazz);
103
    public Form<T> bindFromRequest(String... allowedFields);
104
    public Form<T> bindFromRequest(Http.Request request, String... allowedFields);
105
    public Form<T> bind(Map<String,String> data, String... allowedFields);
106
    public Form<T> bind(com.fasterxml.jackson.databind.JsonNode data, String... allowedFields);
107
    public boolean hasErrors();
108
    public List<ValidationError> globalErrors();
109
    public ValidationError globalError();
110
    public Field apply(String key);
111
    public String name();
112
    public Form<T> discardErrors();
113
    public T get();
114
}
115

116
public class DynamicForm extends Form<DynamicForm.Dynamic> {
117
    public String get(String key);
118
    public DynamicForm bindFromRequest(String... allowedFields);
119
}
120
```
121

122
[Form Processing](./form-processing.md)
123

124
### Validation Framework
125

126
Comprehensive validation system with built-in constraints, custom validators, and detailed error reporting. Integrates with JSR-303 Bean Validation.
127

128
```java { .api }
129
public class Constraints {
130
    public static Validator<Object> required();
131
    public static Validator<Number> min(long value);
132
    public static Validator<Number> max(long value);
133
    public static Validator<String> email();
134
    public static Validator<String> pattern(String regex);
135
}
136

137
@interface Required {}
138
@interface Min { long value(); }
139
@interface Max { long value(); }
140
@interface Email {}
141
@interface Pattern { String value(); }
142
```
143

144
[Validation](./validation.md)
145

146
### Value Formatting and Conversion
147

148
Type-safe value parsing and formatting system with extensible formatter registration. Handles conversion between strings and typed objects with locale support.
149

150
```java { .api }
151
public class Formatters {
152
    public static <T> T parse(String text, Class<T> clazz);
153
    public static <T> String print(T t);
154
    public static <T> void register(Class<T> clazz, SimpleFormatter<T> formatter);
155
}
156

157
public abstract class SimpleFormatter<T> {
158
    public abstract T parse(String text, Locale locale);
159
    public abstract String print(T t, Locale locale);
160
}
161
```
162

163
[Formatting](./formatting.md)
164

165
### Dependency Injection
166

167
Guice-based dependency injection with builder patterns for application and injector configuration. Provides fluent APIs for module binding and configuration.
168

169
```java { .api }
170
public final class GuiceApplicationBuilder extends GuiceBuilder<GuiceApplicationBuilder, play.api.inject.guice.GuiceApplicationBuilder> {
171
    public GuiceApplicationBuilder();
172
    public GuiceApplicationBuilder configure(String key, Object value);
173
    public GuiceApplicationBuilder load(GuiceableModule... modules);
174
    public GuiceApplicationBuilder load(com.google.inject.Module... modules);
175
    public Application build();
176
}
177

178
public final class GuiceInjectorBuilder extends GuiceBuilder<GuiceInjectorBuilder, play.api.inject.guice.GuiceInjectorBuilder> {
179
    public GuiceInjectorBuilder();
180
    public Injector build();
181
}
182
```
183

184
[Dependency Injection](./dependency-injection.md)
185

186
### Utility Libraries
187

188
Comprehensive utility collection including cryptographic functions, time parsing, XML/YAML processing, classpath scanning, and streaming support.
189

190
```java { .api }
191
public class Crypto {
192
    public String sign(String message);
193
    public String generateToken();
194
    public String encryptAES(String value);
195
    public String decryptAES(String value);
196
}
197

198
public class Time {
199
    public static int parseDuration(String duration);
200
    public static Date parseCRONExpression(String cron);
201
}
202

203
public class Yaml {
204
    public static Object load(String resourceName);
205
}
206
```
207

208
[Utilities](./utilities.md)
209

210
### Streaming and Real-time Communication
211

212
Server-Sent Events and Comet streaming implementations for real-time web applications. Provides chunked response handling with connection lifecycle management.
213

214
```java { .api }
215
public abstract class EventSource {
216
    public static EventSource whenConnected(F.Callback<EventSource> callback);
217
    public void send(Event event);
218
    public void close();
219
    public abstract void onConnected();
220
}
221

222
public abstract class Comet {
223
    public static Comet whenConnected(String jsMethod, Callback<Comet> callback);
224
    public void sendMessage(String message);
225
    public void sendMessage(JsonNode message);
226
}
227
```
228

229
[Streaming](./streaming.md)
230

231
### Programmatic Routing
232

233
DSL for building type-safe routes programmatically with support for up to 3 parameters. Enables dynamic route creation and HTTP method handling.
234

235
```java { .api }
236
public class RoutingDsl {
237
    public PathPatternMatcher GET(String pathPattern);
238
    public PathPatternMatcher POST(String pathPattern);
239
    public PathPatternMatcher PUT(String pathPattern);
240
    public PathPatternMatcher DELETE(String pathPattern);
241
    public play.api.routing.Router build();
242
}
243
```
244

245
[Routing DSL](./routing.md)
246

247
## Types
248

249
```java { .api }
250
public class ValidationError {
251
    public ValidationError(String key, String message);
252
    public String key();
253
    public String message();
254
    public List<Object> arguments();
255
}
256

257
public class Form.Field {
258
    public String name();
259
    public String value();
260
    public List<ValidationError> errors();
261
}
262

263
public abstract class Constraints.Validator<T> {
264
    public abstract boolean isValid(T object);
265
    public abstract Tuple<String, Object[]> getErrorMessageKey();
266
}
267

268
// Play Framework functional types
269
public class F {
270
    public interface Callback<A> { void invoke(A a); }
271
    public interface Callback0 { void invoke(); }
272
    public interface Function0<A> { A apply(); }
273
    public interface Function<A,B> { B apply(A a); }
274
    public interface Function2<A,B,C> { C apply(A a, B b); }
275
    public interface Function3<A,B,C,D> { D apply(A a, B b, C c); }
276
    public interface Promise<A> {
277
        A get();
278
        <B> Promise<B> map(Function<A, B> function);
279
        <B> Promise<B> flatMap(Function<A, Promise<B>> function);
280
    }
281
}
282

283
public class Tuple<A, B> {
284
    public A _1();
285
    public B _2();
286
    public static <A, B> Tuple<A, B> create(A a, B b);
287
}
288
```