|
|
@@ -21,55 +21,51 @@ First you'll need to set up a basic build script. You can use any build system y
|
|
21
|
21
|
|
|
22
|
22
|
Add the [Spring MVC](TODO) and [Jackson](http://jackson.codehaus.org) JSON libraries as dependencies:
|
|
23
|
23
|
|
|
24
|
|
-### Maven \[[copy complete `pom.xml` to clipboard](start/pom.xml)\]
|
|
|
24
|
+### Maven
|
|
25
|
25
|
|
|
26
|
|
-Add the following within the `<project>` section of your pom.xml file:
|
|
|
26
|
+Create a `pom.xml` file with the following contents:
|
|
27
|
27
|
|
|
28
|
28
|
`pom.xml`
|
|
29
|
29
|
```xml
|
|
30
|
|
-<dependencies>
|
|
31
|
|
- <dependency>
|
|
32
|
|
- <groupId>org.springframework</groupId>
|
|
33
|
|
- <artifactId>spring-webmvc</artifactId>
|
|
34
|
|
- <version>3.2.2.RELEASE</version>
|
|
35
|
|
- </dependency>
|
|
36
|
|
- <dependency>
|
|
37
|
|
- <groupId>com.fasterxml.jackson.core</groupId>
|
|
38
|
|
- <artifactId>jackson-core</artifactId>
|
|
39
|
|
- <version>2.1.4</version>
|
|
40
|
|
- </dependency>
|
|
41
|
|
- <dependency>
|
|
42
|
|
- <groupId>com.fasterxml.jackson.core</groupId>
|
|
43
|
|
- <artifactId>jackson-databind</artifactId>
|
|
44
|
|
- <version>2.1.4</version>
|
|
45
|
|
- </dependency>
|
|
46
|
|
- <dependency>
|
|
47
|
|
- <groupId>org.apache.tomcat</groupId>
|
|
48
|
|
- <artifactId>tomcat-catalina</artifactId>
|
|
49
|
|
- <version>7.0.39</version>
|
|
50
|
|
- </dependency>
|
|
51
|
|
- <dependency>
|
|
52
|
|
- <groupId>org.apache.tomcat</groupId>
|
|
53
|
|
- <artifactId>tomcat-embed-core</artifactId>
|
|
54
|
|
- <version>7.0.39</version>
|
|
55
|
|
- </dependency>
|
|
56
|
|
- <dependency>
|
|
57
|
|
- <groupId>org.apache.tomcat</groupId>
|
|
58
|
|
- <artifactId>tomcat-jasper</artifactId>
|
|
59
|
|
- <version>7.0.39</version>
|
|
60
|
|
- </dependency>
|
|
61
|
|
-</dependencies>
|
|
|
30
|
+<?xml version="1.0" encoding="UTF-8"?>
|
|
|
31
|
+<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
|
|
|
32
|
+ xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
|
|
|
33
|
+ <modelVersion>4.0.0</modelVersion>
|
|
|
34
|
+
|
|
|
35
|
+ <groupId>org.springframework</groupId>
|
|
|
36
|
+ <artifactId>gs-rest-service-complete</artifactId>
|
|
|
37
|
+ <version>0.0.1-SNAPSHOT</version>
|
|
|
38
|
+
|
|
|
39
|
+ <parent>
|
|
|
40
|
+ <groupId>org.springframework.bootstrap</groupId>
|
|
|
41
|
+ <artifactId>spring-bootstrap-starters</artifactId>
|
|
|
42
|
+ <version>0.0.1-SNAPSHOT</version>
|
|
|
43
|
+ </parent>
|
|
|
44
|
+
|
|
|
45
|
+ <dependencies>
|
|
|
46
|
+ <dependency>
|
|
|
47
|
+ <groupId>org.springframework.bootstrap</groupId>
|
|
|
48
|
+ <artifactId>spring-bootstrap-web-starter</artifactId>
|
|
|
49
|
+ </dependency>
|
|
|
50
|
+ <dependency>
|
|
|
51
|
+ <groupId>com.fasterxml.jackson.core</groupId>
|
|
|
52
|
+ <artifactId>jackson-databind</artifactId>
|
|
|
53
|
+ </dependency>
|
|
|
54
|
+ </dependencies>
|
|
|
55
|
+
|
|
|
56
|
+</project>
|
|
62
|
57
|
```
|
|
63
|
58
|
|
|
|
59
|
+Experienced Maven users who feel nervous about using an external parent project: don't panic, you can take it out later, it's just there to reduce the amount of code you have to write to get started.
|
|
|
60
|
+
|
|
64
|
61
|
### Gradle \[[copy complete `build.gradle` to clipboard](start/build.gradle)\]
|
|
65
|
62
|
|
|
66
|
63
|
Add the following within the `dependencies { }` section of your build.gradle file:
|
|
67
|
64
|
|
|
68
|
65
|
`build.gradle`
|
|
69
|
66
|
```groovy
|
|
70
|
|
-compile 'org.springframework:spring-webmvc:3.2.2.RELEASE'
|
|
71
|
|
-compile 'com.fasterxml.jackson.core:jackson-core:2.1.4'
|
|
72
|
|
-compile 'com.fasterxml.jackson.core:jackson-databind:2.1.4'
|
|
|
67
|
+compile "org.springframework.bootstrap:spring-bootstrap-web-starter:0.0.1-SNAPSHOT"
|
|
|
68
|
+compile "com.fasterxml.jackson.core:jackson-databind:2.2.0-"
|
|
73
|
69
|
```
|
|
74
|
70
|
|
|
75
|
71
|
|
|
|
@@ -96,45 +92,6 @@ public class HelloWorldConfiguration {
|
|
96
|
92
|
This class is concise, but there's plenty going on under the hood. [`@EnableWebMvc`](http://static.springsource.org/spring/docs/3.2.x/javadoc-api/org/springframework/web/servlet/config/annotation/EnableWebMvc.html) handles the registration of a number of components that enable Spring's support for annotation-based controllers—you'll build one of those in an upcoming step. And we've also annotated the configuration class with [`@ComponentScan`](http://static.springsource.org/spring/docs/3.2.x/javadoc-api/org/springframework/context/annotation/ComponentScan.html) which tells Spring to scan the `hello` package for those controllers (along with any other annotated component classes).
|
|
97
|
93
|
|
|
98
|
94
|
|
|
99
|
|
-Setting up the Spring DispatcherServlet
|
|
100
|
|
-------------------------------------------
|
|
101
|
|
-Spring's [`DispatcherServlet`](http://static.springsource.org/spring/docs/3.2.x/javadoc-api/org/springframework/web/servlet/DispatcherServlet.html) will do the work of accepting incoming HTTP requests and routing them to our controller. The simplest way to configure and register the `DispatcherServlet` is with a [`WebApplicationInitializer`](http://static.springsource.org/spring/docs/3.2.x/javadoc-api/org/springframework/web/WebApplicationInitializer.html) class as follows:
|
|
102
|
|
-
|
|
103
|
|
-`src/main/java/hello/HelloWorldWebAppInitializer.java`
|
|
104
|
|
-```java
|
|
105
|
|
-package hello;
|
|
106
|
|
-
|
|
107
|
|
-import org.springframework.web.servlet.support.AbstractAnnotationConfigDispatcherServletInitializer;
|
|
108
|
|
-
|
|
109
|
|
-public class HelloWorldWebAppInitializer extends AbstractAnnotationConfigDispatcherServletInitializer {
|
|
110
|
|
-
|
|
111
|
|
- @Override
|
|
112
|
|
- protected String[] getServletMappings() {
|
|
113
|
|
- return new String[] { "/" };
|
|
114
|
|
- }
|
|
115
|
|
-
|
|
116
|
|
- @Override
|
|
117
|
|
- protected Class<?>[] getRootConfigClasses() {
|
|
118
|
|
- return null;
|
|
119
|
|
- }
|
|
120
|
|
-
|
|
121
|
|
- @Override
|
|
122
|
|
- protected Class<?>[] getServletConfigClasses() {
|
|
123
|
|
- return new Class[] { HelloWorldConfiguration.class };
|
|
124
|
|
- }
|
|
125
|
|
-
|
|
126
|
|
-}
|
|
127
|
|
-```
|
|
128
|
|
-
|
|
129
|
|
-By extending [`AbstractAnnotationConfigDispatcherServletInitializer`](http://static.springsource.org/spring/docs/3.2.x/javadoc-api/org/springframework/web/servlet/support/AbstractAnnotationConfigDispatcherServletInitializer.html), our web application initializer will get a `DispatcherServlet` that is configured with [`@Configuration`](http://static.springsource.org/spring/docs/3.2.x/javadoc-api/org/springframework/context/annotation/Configuration.html)-annotated classes. All we must do is tell it where those configuration classes are and what path(s) to map `DispatcherServlet` to.
|
|
130
|
|
-
|
|
131
|
|
-With regard to the servlet path mappings, `getServletMappings()` returns a single-entry array of `String` specifying that `DispatcherServlet` should be mapped to "/".
|
|
132
|
|
-
|
|
133
|
|
-The `getRootConfigClasses()` and `getServletConfigClasses()` methods specify the configuration classes. The `Class` array returned from `getRootConfigClasses()` specifies the classes for the root context provided to [`ContextLoaderListener`](http://static.springsource.org/spring/docs/3.2.x/javadoc-api/org/springframework/web/context/ContextLoaderListener.html). Similarly, the `Class` array returned from `getServletConfigClasses()` specifies the classes for the servlet application context provided to `DispatcherServlet`.
|
|
134
|
|
-
|
|
135
|
|
-For our purposes there will only be a servlet application context, so `getRootConfigClasses()` returns `null`. `getServletConfigClasses()`, however, specifies `HelloWorldConfiguration` as the only configuration class.
|
|
136
|
|
-
|
|
137
|
|
-
|
|
138
|
95
|
Creating a Representation Class
|
|
139
|
96
|
-------------------------------
|
|
140
|
97
|
With the essential Spring MVC configuration out of the way, it's time to get to the nuts and bolts of our REST service by creating a resource representation class and an endpoint controller.
|
|
|
@@ -145,11 +102,11 @@ What we want is to handle GET requests for /hello-world, optionally with a name
|
|
145
|
102
|
|
|
146
|
103
|
```json
|
|
147
|
104
|
{
|
|
148
|
|
- "id": 1,
|
|
149
|
|
- "content": "Hello, stranger!"
|
|
|
105
|
+ "id": 1,
|
|
|
106
|
+ "content": "Hello, stranger!"
|
|
150
|
107
|
}
|
|
151
|
108
|
```
|
|
152
|
|
-
|
|
|
109
|
+
|
|
153
|
110
|
The `id` field is a unique identifier for the greeting, and `content` is the textual representation of the greeting.
|
|
154
|
111
|
|
|
155
|
112
|
To model the greeting representation, we’ll create a representation class:
|
|
|
@@ -160,21 +117,21 @@ package hello;
|
|
160
|
117
|
|
|
161
|
118
|
public class Greeting {
|
|
162
|
119
|
|
|
163
|
|
- private final long id;
|
|
164
|
|
- private final String content;
|
|
|
120
|
+ private final long id;
|
|
|
121
|
+ private final String content;
|
|
165
|
122
|
|
|
166
|
|
- public Greeting(long id, String content) {
|
|
167
|
|
- this.id = id;
|
|
168
|
|
- this.content = content;
|
|
169
|
|
- }
|
|
|
123
|
+ public Greeting(long id, String content) {
|
|
|
124
|
+ this.id = id;
|
|
|
125
|
+ this.content = content;
|
|
|
126
|
+ }
|
|
170
|
127
|
|
|
171
|
|
- public long getId() {
|
|
172
|
|
- return id;
|
|
173
|
|
- }
|
|
|
128
|
+ public long getId() {
|
|
|
129
|
+ return id;
|
|
|
130
|
+ }
|
|
174
|
131
|
|
|
175
|
|
- public String getContent() {
|
|
176
|
|
- return content;
|
|
177
|
|
- }
|
|
|
132
|
+ public String getContent() {
|
|
|
133
|
+ return content;
|
|
|
134
|
+ }
|
|
178
|
135
|
|
|
179
|
136
|
}
|
|
180
|
137
|
```
|
|
|
@@ -198,15 +155,15 @@ import org.springframework.web.bind.annotation.ResponseBody;
|
|
198
|
155
|
@Controller
|
|
199
|
156
|
@RequestMapping("/hello-world")
|
|
200
|
157
|
public class HelloWorldController {
|
|
201
|
|
-
|
|
202
|
|
- private static final String template = "Hello, %s!";
|
|
203
|
|
- private final AtomicLong counter = new AtomicLong();
|
|
204
|
|
-
|
|
205
|
|
- @RequestMapping(method=RequestMethod.GET)
|
|
206
|
|
- public @ResponseBody Greeting sayHello(@RequestParam(value="name", required=false, defaultValue="Stranger") String name) {
|
|
207
|
|
- return new Greeting(counter.incrementAndGet(), String.format(template, name));
|
|
208
|
|
- }
|
|
209
|
|
-
|
|
|
158
|
+
|
|
|
159
|
+ private static final String template = "Hello, %s!";
|
|
|
160
|
+ private final AtomicLong counter = new AtomicLong();
|
|
|
161
|
+
|
|
|
162
|
+ @RequestMapping(method=RequestMethod.GET)
|
|
|
163
|
+ public @ResponseBody Greeting sayHello(@RequestParam(value="name", required=false, defaultValue="Stranger") String name) {
|
|
|
164
|
+ return new Greeting(counter.incrementAndGet(), String.format(template, name));
|
|
|
165
|
+ }
|
|
|
166
|
+
|
|
210
|
167
|
}
|
|
211
|
168
|
```
|
|
212
|
169
|
|
|
|
@@ -217,87 +174,75 @@ The magic is in the [`@ResponseBody`](http://static.springsource.org/spring/docs
|
|
217
|
174
|
|
|
218
|
175
|
Creating an executable main class
|
|
219
|
176
|
---------------------------------
|
|
220
|
|
-To run the REST service, we'll create a main class that deploys the application to Tomcat.
|
|
221
|
177
|
|
|
222
|
|
-`src/main/java/hello/Main.java`
|
|
|
178
|
+We can launch the application from a custom main class, or we can do that directly from one of the configuration classes. The easiest way is to use the `SpringApplication` helper class:
|
|
|
179
|
+
|
|
|
180
|
+`src/main/java/hello/HelloWorldConfiguration.java`
|
|
|
181
|
+
|
|
223
|
182
|
```java
|
|
224
|
183
|
package hello;
|
|
225
|
184
|
|
|
226
|
|
-import java.util.HashSet;
|
|
227
|
|
-
|
|
228
|
|
-import org.apache.catalina.Context;
|
|
229
|
|
-import org.apache.catalina.core.AprLifecycleListener;
|
|
230
|
|
-import org.apache.catalina.core.StandardServer;
|
|
231
|
|
-import org.apache.catalina.startup.Tomcat;
|
|
232
|
|
-import org.springframework.web.SpringServletContainerInitializer;
|
|
233
|
|
-
|
|
234
|
|
-public class Main {
|
|
235
|
|
-
|
|
236
|
|
- public static void main(String[] args) throws Exception {
|
|
237
|
|
- Tomcat tomcat = new Tomcat();
|
|
238
|
|
- tomcat.setPort(8080);
|
|
239
|
|
- tomcat.setBaseDir(".");
|
|
240
|
|
- tomcat.getHost().setAppBase("/");
|
|
241
|
|
-
|
|
242
|
|
- // Add AprLifecycleListener
|
|
243
|
|
- StandardServer server = (StandardServer)tomcat.getServer();
|
|
244
|
|
- AprLifecycleListener listener = new AprLifecycleListener();
|
|
245
|
|
- server.addLifecycleListener(listener);
|
|
246
|
|
-
|
|
247
|
|
- Context context = tomcat.addWebapp("/", "/");
|
|
248
|
|
- HashSet<Class<?>> classes = new HashSet<Class<?>>();
|
|
249
|
|
- classes.add(HelloWorldWebAppInitializer.class);
|
|
250
|
|
- context.addServletContainerInitializer(new SpringServletContainerInitializer(), classes);
|
|
251
|
|
- tomcat.start();
|
|
252
|
|
- tomcat.getServer().await();
|
|
|
185
|
+import org.springframework.bootstrap.SpringApplication;
|
|
|
186
|
+import org.springframework.bootstrap.context.annotation.EnableAutoConfiguration;
|
|
|
187
|
+import org.springframework.context.annotation.ComponentScan;
|
|
|
188
|
+import org.springframework.context.annotation.Configuration;
|
|
|
189
|
+import org.springframework.web.servlet.config.annotation.EnableWebMvc;
|
|
|
190
|
+
|
|
|
191
|
+@Configuration
|
|
|
192
|
+@EnableAutoConfiguration
|
|
|
193
|
+@EnableWebMvc
|
|
|
194
|
+@ComponentScan
|
|
|
195
|
+public class HelloWorldConfiguration {
|
|
|
196
|
+ public static void main(String[] args) {
|
|
|
197
|
+ SpringApplication.run(HelloWorldConfiguration.class, args);
|
|
253
|
198
|
}
|
|
254
|
199
|
}
|
|
255
|
200
|
```
|
|
256
|
201
|
|
|
257
|
|
-As you can see, the `main()` method fires up an embedded Tomcat server and then loads the application, via the `HelloWorldWebAppInitializer`, into Tomcat.
|
|
|
202
|
+The `@EnableAutoConfiguration` annotation has also been added: it provides a load of defaults (like the embedded servlet container) depending on the contents of your classpath, and other things.
|
|
258
|
203
|
|
|
|
204
|
+Running the Service
|
|
|
205
|
+-------------------------------------
|
|
|
206
|
+
|
|
|
207
|
+Add the following to your `pom.xml`:
|
|
|
208
|
+
|
|
|
209
|
+`pom.xml`
|
|
|
210
|
+```xml
|
|
|
211
|
+<properties>
|
|
|
212
|
+ <start-class>hello.HelloWorldConfiguration</start-class>
|
|
|
213
|
+</properties>
|
|
|
214
|
+```
|
|
|
215
|
+
|
|
|
216
|
+You can now run the application with the Maven exec plugin:
|
|
|
217
|
+
|
|
|
218
|
+```
|
|
|
219
|
+$ mvn exec:java
|
|
|
220
|
+
|
|
|
221
|
+... service comes up ...
|
|
|
222
|
+```
|
|
|
223
|
+
|
|
|
224
|
+so in another terminal you can do this
|
|
|
225
|
+
|
|
|
226
|
+```
|
|
|
227
|
+$ curl localhost:8080/hello-world
|
|
|
228
|
+{"id":1,"content":"Hello, Stranger!"}
|
|
|
229
|
+```
|
|
259
|
230
|
|
|
260
|
231
|
Building an executable JAR
|
|
261
|
232
|
--------------------------
|
|
262
|
233
|
|
|
263
|
|
-Add the following to the <build><plugins> section of your pom.xml file:
|
|
|
234
|
+Add the following to your `pom.xml` file (keeping any existing properties or plugins intact):
|
|
264
|
235
|
|
|
265
|
236
|
`pom.xml`
|
|
266
|
237
|
```xml
|
|
267
|
|
-<plugin>
|
|
268
|
|
- <groupId>org.apache.maven.plugins</groupId>
|
|
269
|
|
- <artifactId>maven-shade-plugin</artifactId>
|
|
270
|
|
- <version>1.6</version>
|
|
271
|
|
- <configuration>
|
|
272
|
|
- <createDependencyReducedPom>true</createDependencyReducedPom>
|
|
273
|
|
- <filters>
|
|
274
|
|
- <filter>
|
|
275
|
|
- <artifact>*:*</artifact>
|
|
276
|
|
- <excludes>
|
|
277
|
|
- <exclude>META-INF/*.SF</exclude>
|
|
278
|
|
- <exclude>META-INF/*.DSA</exclude>
|
|
279
|
|
- <exclude>META-INF/*.RSA</exclude>
|
|
280
|
|
- </excludes>
|
|
281
|
|
- </filter>
|
|
282
|
|
- </filters>
|
|
283
|
|
- </configuration>
|
|
284
|
|
- <executions>
|
|
285
|
|
- <execution>
|
|
286
|
|
- <phase>package</phase>
|
|
287
|
|
- <goals>
|
|
288
|
|
- <goal>shade</goal>
|
|
289
|
|
- </goals>
|
|
290
|
|
- <configuration>
|
|
291
|
|
- <transformers>
|
|
292
|
|
- <transformer implementation="org.apache.maven.plugins.shade.resource.ServicesResourceTransformer"/>
|
|
293
|
|
- <transformer implementation="org.apache.maven.plugins.shade.resource.ManifestResourceTransformer">
|
|
294
|
|
- <mainClass>hello.Main</mainClass>
|
|
295
|
|
- </transformer>
|
|
296
|
|
- </transformers>
|
|
297
|
|
- </configuration>
|
|
298
|
|
- </execution>
|
|
299
|
|
- </executions>
|
|
300
|
|
-</plugin>
|
|
|
238
|
+<build>
|
|
|
239
|
+ <plugins>
|
|
|
240
|
+ <plugin>
|
|
|
241
|
+ <groupId>org.apache.maven.plugins</groupId>
|
|
|
242
|
+ <artifactId>maven-shade-plugin</artifactId>
|
|
|
243
|
+ </plugin>
|
|
|
244
|
+ </plugins>
|
|
|
245
|
+</build>
|
|
301
|
246
|
```
|
|
302
|
247
|
|
|
303
|
248
|
The following will produce a single executable JAR file containing all necessary dependency classes:
|
|
|
@@ -306,18 +251,7 @@ The following will produce a single executable JAR file containing all necessary
|
|
306
|
251
|
$ mvn package
|
|
307
|
252
|
```
|
|
308
|
253
|
|
|
309
|
|
-> _**TODO:** this produces a bunch of the following. Fix?_
|
|
310
|
|
-> ```
|
|
311
|
|
-> [WARNING] We have a duplicate javax/el/ExpressionFactory$4.class in /Users/cbeams/.m2/repository/org/apache/> tomcat/tomcat-el-api/7.0.39/tomcat-el-api-7.0.39.jar
|
|
312
|
|
->```
|
|
313
|
|
->> It seems to be a quirk with the shade plugin and seems harmless. There is some advice online for removing
|
|
314
|
|
->> or minimizing the warnings by adding exclusions to the dependencies. But given that it seems harmless, I'm
|
|
315
|
|
->> unsure if we should dwell on this.
|
|
316
|
|
-
|
|
317
|
|
-
|
|
318
|
|
-Running the Service
|
|
319
|
|
--------------------------------------
|
|
320
|
|
-Now that the REST service code has been built into an executable JAR file, you can run it like this:
|
|
|
254
|
+Now you can run it from the jar as well, and distribute that as an executable artifact:
|
|
321
|
255
|
|
|
322
|
256
|
```
|
|
323
|
257
|
$ java -jar target/gs-rest-service-0.0.1-SNAPSHOT.jar
|
|
|
@@ -325,12 +259,6 @@ $ java -jar target/gs-rest-service-0.0.1-SNAPSHOT.jar
|
|
325
|
259
|
... service comes up ...
|
|
326
|
260
|
```
|
|
327
|
261
|
|
|
328
|
|
-Once the service starts, you can test it by pointing your web browser at http://localhost:8080/hello-world. Or you can consume it from the command line using curl:
|
|
329
|
|
-
|
|
330
|
|
-```sh
|
|
331
|
|
-$ curl http://localhost:8080/hello-world
|
|
332
|
|
-```
|
|
333
|
|
-
|
|
334
|
262
|
Congratulations! You have just developed a simple REST service using Spring. This is a basic foundation for building a complete REST API in Spring.
|
|
335
|
263
|
|
|
336
|
264
|
|