First asciidoc cut of gs-rest-service

README.asc

@@ -0,0 +1,168 @@
+:project_id: gs-rest-service
+:spring_version: 3.2.4.RELEASE
+:spring_boot_version: 0.5.0.M4
+This guide walks you through the process of creating a "hello world" link:/understanding/REST[RESTful web service] with Spring.
+
+== What you'll build
+
+You'll build a service that will accept HTTP GET requests at:
+
+    http://localhost:8080/greeting
+
+and respond with a link:/understanding/JSON[JSON] representation of a greeting:
+
+// Currently replacing json->javascript and groovy/gradle->java
+[source,javascript]
+----
+{"id":1,"content":"Hello, World!"}
+----
+
+You can customize the greeting with an optional `name` parameter in the query string:
+
+    http://localhost:8080/greeting?name=User
+
+The `name` parameter value overrides the default value of "World" and is reflected in the response:
+
+// Currently replacing json->javascript and groovy/gradle->java
+[source,javascript]
+----
+{"id":1,"content":"Hello, User!"}
+----
+
+
+== What you'll need
+
+ - About 15 minutes
+include::macros/prereq_editor_jdk_buildtools.asc[]
+
+
+include::macros/how_to_complete_this_guide.asc[]
+
+
+[[scratch]]
+== Set up the project
+
+include::macros/build_system_intro.asc[]
+
+include::macros/create_directory_structure_hello.asc[]
+
+
+include::macros/create_both_builds.asc[]
+
+include::macros/bootstrap_starter_pom_disclaimer.asc[]
+
+
+[[initial]]
+== Create a resource representation class
+
+Now that you've set up the project and build system, you can create your web service.
+
+Begin the process by thinking about service interactions.
+
+The service will handle `GET` requests for `/greeting`, optionally with a `name` parameter in the query string. The `GET` request should return a `200 OK` response with JSON in the body that represents a greeting. It should look something like this:
+
+// Currently replacing json->javascript and groovy/gradle->java
+[source,javascript]
+----
+{
+    "id": 1,
+    "content": "Hello, World!"
+}
+----
+
+The `id` field is a unique identifier for the greeting, and `content` is the textual representation of the greeting.
+
+To model the greeting representation, you create a resource representation class. Provide a plain old java object with fields, constructors, and accessors for the `id` and `content` data:
+
+[source,java]
+----
+include::complete/src/main/java/hello/Greeting.java[]
+----
+
+NOTE: As you see in steps below, Spring uses the http://wiki.fasterxml.com/JacksonHome[Jackson JSON] library to automatically marshal instances of type `Greeting` into JSON.
+
+Next you create the resource controller that will serve these greetings.
+
+
+== Create a resource controller
+
+In Spring's approach to building RESTful web services, HTTP requests are handled by a controller. These components are easily identified by the link:http://docs.spring.io/spring/docs/current/javadoc-api/org/springframework/stereotype/Controller.html[`@Controller`] annotation, and the `GreetingController` below handles `GET` requests for `/greeting` by returning a new instance of the `Greeting` class:
+
+[source,java]
+----
+include::complete/src/main/java/hello/GreetingController.java[]
+----
+
+This controller is concise and simple, but there's plenty going on under the hood. Let's break it down step by step.
+
+The `@RequestMapping` annotation ensures that HTTP requests to `/greeting` are mapped to the `greeting()` method.
+
+NOTE: The above example does not specify `GET` vs. `PUT`, `POST`, and so forth, because `@RequestMapping` maps all HTTP operations by default. Use `@RequestMapping(method=GET)` to narrow this mapping.
+
+`@RequestParam` binds the value of the query string parameter `name` into the `name` parameter of the `greeting()` method. This query string parameter is not `required`; if it is absent in the request, the `defaultValue` of "World" is used.
+
+The implementation of the method body creates and returns a new `Greeting` object with `id` and `content` attributes based on the next value from the `counter`, and formats the given `name` by using the greeting `template`.
+
+A key difference between a traditional MVC controller and the RESTful web service controller above is the way that the HTTP response body is created. Rather than relying on a link:/understanding/view-templates[view technology] to perform server-side rendering of the greeting data to HTML, this RESTful web service controller simply populates and returns a `Greeting` object. The object data will be written directly to the HTTP response as JSON.
+
+To accomplish this, the link:http://docs.spring.io/spring/docs/current/javadoc-api/org/springframework/web/bind/annotation/ResponseBody.html[`@ResponseBody`] annotation on the `greeting()` method tells Spring MVC that it does not need to render the greeting object through a server-side view layer, but that instead that the greeting object returned _is_ the response body, and should be written out directly.
+
+The `Greeting` object must be converted to JSON. Thanks to Spring's HTTP message converter support, you don't need to do this conversion manually. Because http://wiki.fasterxml.com/JacksonHome[Jackson 2] is on the classpath, Spring's link:http://docs.spring.io/spring/docs/current/javadoc-api/org/springframework/http/converter/json/MappingJackson2HttpMessageConverter.html[`MappingJackson2HttpMessageConverter`] is automatically chosen to convert the `Greeting` instance to JSON.
+
+
+== Make the application executable
+
+Although it is possible to package this service as a traditional link:/understanding/WAR[WAR] file for deployment to an external application server, the simpler approach demonstrated below creates a standalone application. You package everything in a single, executable JAR file, driven by a good old Java `main()` method. Along the way, you use Spring's support for embedding the link:/understanding/Tomcat[Tomcat] servlet container as the HTTP runtime, instead of deploying to an external instance.
+
+
+[source,java]
+----
+include::complete/src/main/java/hello/Application.java[]
+----
+
+The `main()` method defers to the link:http://docs.spring.io/spring-boot/docs/{spring_boot_version}/api/org/springframework/boot/SpringApplication.html[`SpringApplication`] helper class, providing `Application.class` as an argument to its `run()` method. This tells Spring to read the annotation metadata from `Application` and to manage it as a component in the link:/understanding/application-context[Spring application context].
+
+The `@ComponentScan` annotation tells Spring to search recursively through the `hello` package and its children for classes marked directly or indirectly with Spring's link:http://docs.spring.io/spring/docs/current/javadoc-api/org/springframework/stereotype/Component.html[`@Component`] annotation. This directive ensures that Spring finds and registers the `GreetingController`, because it is marked with `@Controller`, which in turn is a kind of `@Component` annotation.
+
+The link:http://docs.spring.io/spring-boot/docs/{spring_boot_version}/api/org/springframework/boot/autoconfigure/EnableAutoConfiguration.html[`@EnableAutoConfiguration`] annotation switches on reasonable default behaviors based on the content of your classpath. For example, because the application depends on the embeddable version of Tomcat (tomcat-embed-core.jar), a Tomcat server is set up and configured with reasonable defaults on your behalf. And because the application also depends on Spring MVC (spring-webmvc.jar), a Spring MVC link:http://docs.spring.io/spring/docs/current/javadoc-api/org/springframework/web/servlet/DispatcherServlet.html[`DispatcherServlet`] is configured and registered for you — no `web.xml` necessary! Auto-configuration is a powerful, flexible mechanism. See the http://docs.spring.io/spring-boot/docs/{spring_boot_version}/api/org/springframework/boot/autoconfigure/EnableAutoConfiguration.html[API documentation] for further details.
+
+include::macros/build_an_executable_jar_subhead.asc[]
+
+include::macros/build_an_executable_jar_with_both.asc[]
+
+:module: service
+include::macros/run_the_application_with_both.asc[]
+
+Logging output is displayed. The service should be up and running within a few seconds.
+
+
+== Test the service
+
+Now that the service is up, visit http://localhost:8080/greeting, where you see:
+
+// Currently replacing json->javascript and groovy/gradle->java
+[source,javascript]
+----
+{"id":1,"content":"Hello, World!"}
+----
+
+Provide a `name` query string parameter with http://localhost:8080/greeting?name=User. Notice how the value of the `content` attribute changes from "Hello, World!" to "Hello User!":
+
+// Currently replacing json->javascript and groovy/gradle->java
+[source,javascript]
+----
+{"id":2,"content":"Hello, User!"}
+----
+
+This change demonstrates that the `@RequestParam` arrangement in `GreetingController` is working as expected. The `name` parameter has been given a default value of "World", but can always be explicitly overridden through the query string.
+
+Notice also how the `id` attribute has changed from `1` to `2`. This proves that you are working against the same `GreetingController` instance across multiple requests, and that its `counter` field is being incremented on each call as expected.
+
+
+== Summary
+
+Congratulations! You've just developed a RESTful web service with Spring. 
+
+
+
+