The REST Examples
There are three examples included in the tutorial that demonstrate how to create and use resources. They are:
hello: a simple “Hello, world” example that responds to HTTP GET requests
calculator: a basic calculator example that demonstrates how to extract and process URI parameters
rsvp: a more complicated example that allows you to create, retrieve, update, and delete attendees to an event
Configuring Your Environment
To run the examples, you must have:
installed the Sun Web Developer Pack
configured the Sun Web Developer Pack with Application Server 9.1
optionally installed NetBeans IDE 5.5.1 and the Sun Web Developer Pack modules
The hello Application
The hello application is a “Hello, world” application that demonstrates the basics of developing a resource. There is a single class, Hello that contains one method, sayHello that responds to HTTP GET requests with a greeting that is sent back as plain text.
The following code is the contents of the Hello class:
@UriTemplate("/hello") public class Hello { public Hello() {} @HttpMethod("GET") @ProduceMime("text/plain") public String sayHello() { return new String("Hello there."); } }
When you build the hello application, the rbpt task processes the annotations decorating the Hello class and produces helper classes and artifacts that are then packaged into the hello.war archive. The following helper classes and artifacts are generated:
com.sun.tutorials.swdp.rest.restbeans.RESTBeansResources: A helper servlet that processes incoming requests and finds the appropriate resource and method to process the request
com.sun.ws.rest.wadl.resource.application.wadl: The Web Application Description Language (WADL) file for this resource
com.sun.ws.rest.wadl.resource.WadlResource.class: a helper class for accessing the WADL file
The web.xml deployment descriptor for hello.war contains the settings for configuring your resource with the REST API runtime:
<servlet> <servlet-name>REST Application</servlet-name> <servlet-class>com.sun.ws.rest.impl.container.servlet.ServletAdaptor</servlet-class> <init-param> <param-name>resourcebean</param-name> <param-value>com.sun.tutorials.swdp.rest.restbeans.RESTBeansResources</param-value> </init-param> </servlet> <servlet-mapping> <servlet-name>REST Application</servlet-name> <url-pattern>/restbean/*</url-pattern> </servlet-mapping>
The com.sun.ws.rest.impl.container.servlet.ServletAdaptor servlet is part of the REST API runtime, and works with the generated RESTBeansResources class to get the resources provided by your application. The <servlet-mapping> elements specify which URLs your application responds to relative to the context root of your WAR. Both the context root and the specified URL pattern prefix the URI Template specified in the @UriTemplate annotation in the resource class file. In the case of the hello example application, the @UriTemplate is set to /hello, and the context root specified in sun-web.xml is /helloso our resource will respond to requests of the form:
http://<server>:<server port>/hello/restbean/hello
Building and Running the hello Application
in NetBeans IDE 5.5.1
- Select File→Open Project in NetBeans IDE 5.5.1.
- Navigate to <swdp.tutorial.home>/examples/rest, select hello, and click OK.
- Right click on the hello application in the
Projects pane and select Run Project.
This will generate the helper classes and artifacts for your resource, compile the classes, package the files into a WAR file, deploy the WAR to your Application Server 9.1 instance, and open a web browser to the following URL:
http://server:server port/hello/restbean/hello
Note - You will see some warning messages in your Output pane. These warnings can safely be ignored.
You will see the following output in your web browser:
Hello there.
Building and Running the hello Application
with Ant
- Open a terminal prompt and navigate to swdp.tutorial.home/examples/rest/hello.
- Enter ant and press Enter.
This will build and package the hello.war web application.
Note - You will see some warning messages in the output from the rest-generate task. These warnings can safely be ignored.
- Enter ant deploy and press Enter.
This will deploy hello.war to Application Server 9.1.
- In a web browser navigate to:
http://server:server port/hello/restbean/hello
You will see the following output in your web browser:
Hello there.
The calculator Application
The calculator example application is a calculator that adds two numbers together. The numbers are specified in the request URI. There is a single class, Calculator that contains one method, add that responds to HTTP GET requests. The add method has two parameters specified as URI variables, num1 and num2. These numbers are added together and the sum is returned to the client.
The following code is the contents of Calculator.java:
@UriTemplate("/number1={num1}&number2={num2}") @ProduceMime("text/plain") public class Calculator { @HttpMethod("GET") public String add( @UriParam("num1") int number1, @UriParam("num2") int number2) { int sum = number1 + number2; return new String(Integer.toString(sum)); } }
The @UriTemplate annotation defines a URI template with two URI variables, num1 and num2. These variables are then specified as parameters to the add method by decoration the parameter location with a @UriParam annotation. The parameters are cast to the Java programming language primitive type int and stored as the method variables number1 and number2, respectively. These numbers are added together and returned as a StringRepresentation.
Building and Running the calculator Application
in NetBeans IDE 5.5.1
- Select File→Open Project in NetBeans IDE 5.5.1.
- Navigate to swdp.tutorial.home/examples/rest, select calculator, and click OK.
- Right click on the calculator application in
the Projects pane and select Run Project.
This will generate the helper classes and artifacts for your resource, compile the classes, package the files into a WAR file, deploy the WAR to your Application Server 9.1 instance, and open a web browser to the following URL:
http://server:server port/calculator/restbean/number1=3&number2=4
Note - You will see some warning messages in your Output pane. These warnings can safely be ignored.
You will see the following output in your web browser:
7