| <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> |
| <html> |
| <head> |
| <title>Apache Wink : JAX-RS Getting Started</title> |
| <link rel="stylesheet" href="styles/site.css" type="text/css" /> |
| <META http-equiv="Content-Type" content="text/html; charset=UTF-8"> |
| </head> |
| |
| <body> |
| <table class="pagecontent" border="0" cellpadding="0" cellspacing="0" width="100%" bgcolor="#ffffff"> |
| <tr> |
| <td valign="top" class="pagebody"> |
| <div class="pageheader"> |
| <span class="pagetitle"> |
| Apache Wink : JAX-RS Getting Started |
| </span> |
| </div> |
| <div class="pagesubheading"> |
| This page last changed on Oct 13, 2009 by <font color="#0050B2">bluk</font>. |
| </div> |
| |
| <h1><a name="JAX-RSGettingStarted-CreatingaSimple%22HelloWorld%22Application"></a>Creating a Simple "Hello World" Application</h1> |
| |
| <p>The following example project will produce a simple JAX-RS application that can respond to requests at <b>"/helloworld"</b> with a <b>"Hello world!"</b> plain text resource. While not entirely RESTful, this example project is to show how to create a simple application and how to package it for consumption in a web container.</p> |
| |
| |
| <p>The application is packaged in a WAR file (which is similar to a JAR/ZIP file, except with special files in certain locations and a defined layout). It can be deployed in any web container, for example: Jetty, Tomcat and Geronimo. Perform the following steps in order to create the "<b>helloworld</b>" example application.</p> |
| |
| |
| <h2><a name="JAX-RSGettingStarted-Step1CreatingtheRootResource"></a>Step 1 - Creating the Root Resource</h2> |
| |
| |
| <h3><a name="JAX-RSGettingStarted-"></a></h3> |
| |
| <p>First, create a resource that will be used for HTTP GET requests to "<b>/helloworld</b>".</p> |
| |
| <div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent"> |
| <pre class="code-java">
|
| <span class="code-keyword">package</span> org.apache.wink.example.helloworld;
|
|
|
| <span class="code-keyword">import</span> javax.ws.rs.GET;
|
| <span class="code-keyword">import</span> javax.ws.rs.Path;
|
|
|
| @Path(<span class="code-quote">"/helloworld"</span>)
|
| <span class="code-keyword">public</span> class HelloWorldResource {
|
|
|
| @GET
|
| <span class="code-keyword">public</span> <span class="code-object">String</span> getMessage() {
|
| <span class="code-keyword">return</span> <span class="code-quote">"Hello World!"</span>;
|
| }
|
| }
|
| </pre> |
| </div></div> |
| |
| <p>As shown above, the Java class is just a plain old Java object that has JAX-RS annotations.</p> |
| |
| <h2><a name="JAX-RSGettingStarted-Step2Creatingajavax.ws.rs.core.Applicationsubclass"></a>Step 2 - Creating a javax.ws.rs.core.Application sub-class</h2> |
| |
| |
| |
| <p>For non-JAX-RS aware web container environments (most environments are currently non JAX-RS aware), a j<b>avax.ws.rs.core.Application</b> sub-class needs to be created which returns sets of JAX-RS root resources and providers. In the following example, there is only one root resource that will need to be returned.</p> |
| |
| <div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent"> |
| <pre class="code-java">
|
| <span class="code-keyword">package</span> org.apache.wink.example.helloworld;
|
|
|
| <span class="code-keyword">import</span> java.util.HashSet;
|
| <span class="code-keyword">import</span> java.util.Set;
|
|
|
| <span class="code-keyword">import</span> javax.ws.rs.core.Application;
|
|
|
| <span class="code-keyword">public</span> class HelloWorldApplication <span class="code-keyword">extends</span> Application {
|
|
|
| @Override
|
| <span class="code-keyword">public</span> Set<<span class="code-object">Class</span><?>> getClasses() {
|
| Set<<span class="code-object">Class</span><?>> classes = <span class="code-keyword">new</span> HashSet<<span class="code-object">Class</span><?>>();
|
| classes.add(HelloWorldResource.class);
|
| <span class="code-keyword">return</span> classes;
|
| }
|
|
|
| }
|
| </pre> |
| </div></div> |
| |
| <h3><a name="JAX-RSGettingStarted-Compilingtheclasses"></a>Compiling the classes</h3> |
| |
| |
| <p>Using the Apache Wink distribution's JARs in the classpath, compile the two classes from the previous example.</p> |
| |
| <h2><a name="JAX-RSGettingStarted-Step3Creatingaweb.xmlfile"></a>Step 3 - Creating a web.xml file</h2> |
| |
| |
| |
| |
| <p>Now create a web.xml deployment descriptor. The deployment descriptor details information about the web application in the WAR. In this case, it says that the Apache Wink JAX-RS servlet should be initialized with a HelloWorldApplication instance.</p> |
| |
| <p>In addition, any requests that begin with /rest/ will be handled by the Apache Wink JAX-RS servlet. So, the request URL would be "/rest/helloworld" to reach the HelloWorld resource.</p> |
| |
| <div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent"> |
| <pre class="code-java">
|
| <?xml version=<span class="code-quote">"1.0"</span> encoding=<span class="code-quote">"UTF-8"</span>?>
|
| <!DOCTYPE web-app PUBLIC
|
| <span class="code-quote">"-<span class="code-comment">//Sun Microsystems, Inc.//DTD Web Application 2.3//EN"</span>
|
| </span> <span class="code-quote">"http:<span class="code-comment">//java.sun.com/dtd/web-app_2_3.dtd"</span> >
|
| </span>
|
| <web-app>
|
| <display-name>Hello world Web Application</display-name>
|
| <servlet>
|
| <servlet-name>HelloWorldApp</servlet-name>
|
| <servlet-class>org.apache.wink.server.internal.servlet.RestServlet</servlet-class>
|
| <init-param>
|
| <param-name>javax.ws.rs.Application</param-name>
|
| <param-value>org.apache.wink.example.helloworld.HelloWorldApplication</param-value>
|
| </init-param>
|
| <load-on-startup>1</load-on-startup>
|
| </servlet>
|
| <servlet-mapping>
|
| <servlet-name>HelloWorldApp</servlet-name>
|
| <url-pattern>/<span class="code-keyword">rest</span>/*</url-pattern>
|
| </servlet-mapping>
|
| </web-app>
|
| </pre> |
| </div></div> |
| |
| <h2><a name="JAX-RSGettingStarted-Step4PackagingthewebapplicationintoaWARfile"></a>Step 4 - Packaging the web application into a WAR file</h2> |
| |
| |
| |
| |
| <p>Layout the application as follows and create a WAR file from the base directory (the one before WEB-INF). Create a WAR by running "jar cvf helloworld-jaxrs.war *" from the base directory.</p> |
| |
| <p>Not every JAR in the lib directory is necessary for all environments. Read the documentation for more information about the requirements.</p> |
| |
| <div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent"> |
| <pre class="code-java">
|
| WEB-INF/classes/org/apache/wink/example/helloworld/HelloWorldApplication.class
|
| WEB-INF/classes/org/apache/wink/example/helloworld/HelloWorldResource.class
|
| WEB-INF/lib/activation-1.1.jar
|
| WEB-INF/lib/commons-lang-2.3.jar
|
| WEB-INF/lib/jaxb-api-2.1.jar
|
| WEB-INF/lib/jaxb-impl-2.1.4.jar
|
| WEB-INF/lib/json-20080701.jar
|
| WEB-INF/lib/jsr311-api-1.0.jar
|
| WEB-INF/lib/slf4j-api-1.5.8.jar
|
| WEB-INF/lib/slf4j-simple-1.5.8.jar
|
| WEB-INF/lib/stax-api-1.0-2.jar
|
| WEB-INF/lib/wink-common-<version #>.jar
|
| WEB-INF/lib/wink-server-<version #>.jar
|
| WEB-INF/web.xml
|
| </pre> |
| </div></div> |
| |
| <h2><a name="JAX-RSGettingStarted-Step5InstallingtheWARfileintoyourenvironment"></a>Step 5 - Installing the WAR file into your environment</h2> |
| |
| |
| |
| |
| <p>Most web container environments will take a WAR file and deploy it without any further configuration required. However, note the "<b>Context Root</b>" of the web application, or change it as required.</p> |
| |
| <p>The context paths combine as follows:<br/> |
| http://<hostname>/<web application context root>/<servlet url mapping path>/helloworld</p> |
| |
| <p>If the environment deployed the WAR file to a context root of "/helloworldapp", then the following URL would be required to reach the HelloWorldResource.</p> |
| |
| <p>http://<hostname>/helloworldapp/rest/helloworld</p> |
| |
| |
| </td> |
| </tr> |
| </table> |
| <table border="0" cellpadding="0" cellspacing="0" width="100%"> |
| <tr> |
| <td height="12" background="http://cwiki.apache.org/confluence/images/border/border_bottom.gif"><img src="images/border/spacer.gif" width="1" height="1" border="0"/></td> |
| </tr> |
| <tr> |
| <td align="center"><font color="grey">Document generated by Confluence on Nov 11, 2009 06:57</font></td> |
| </tr> |
| </table> |
| </body> |
| </html> |