src/site/resources/1.0/html/JAX-RS Getting Started.html - wink-website - Git at Google

 <!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&#33;"</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&lt;<span class="code-object">Class</span>&lt;?&gt;&gt; getClasses() {
         Set&lt;<span class="code-object">Class</span>&lt;?&gt;&gt; classes = <span class="code-keyword">new</span> HashSet&lt;<span class="code-object">Class</span>&lt;?&gt;&gt;();
         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">
 &lt;?xml version=<span class="code-quote">"1.0"</span> encoding=<span class="code-quote">"UTF-8"</span>?&gt;
 &lt;!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> &gt;
 </span>
 &lt;web-app&gt;
     &lt;display-name&gt;Hello world Web Application&lt;/display-name&gt;
     &lt;servlet&gt;
         &lt;servlet-name&gt;HelloWorldApp&lt;/servlet-name&gt;
         &lt;servlet-class&gt;org.apache.wink.server.internal.servlet.RestServlet&lt;/servlet-class&gt;
         &lt;init-param&gt;
             &lt;param-name&gt;javax.ws.rs.Application&lt;/param-name&gt;
             &lt;param-value&gt;org.apache.wink.example.helloworld.HelloWorldApplication&lt;/param-value&gt;
         &lt;/init-param&gt;
         &lt;load-on-startup&gt;1&lt;/load-on-startup&gt;
     &lt;/servlet&gt;
     &lt;servlet-mapping&gt;
         &lt;servlet-name&gt;HelloWorldApp&lt;/servlet-name&gt;
         &lt;url-pattern&gt;/<span class="code-keyword">rest</span>/*&lt;/url-pattern&gt;
     &lt;/servlet-mapping&gt;
 &lt;/web-app&gt;
 </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-&lt;version #&gt;.jar
 WEB-INF/lib/wink-server-&lt;version #&gt;.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://&lt;hostname&gt;/&lt;web application context root&gt;/&lt;servlet url mapping path&gt;/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://&lt;hostname&gt;/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>
	<!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>