blob: 9277f6f1a911134914913ad2903ef7aa60df68d3 [file] [log] [blame]
<!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>