incubator-wink-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From ngalla...@apache.org
Subject svn commit: r787550 [2/3] - in /incubator/wink/contrib/ibm-jaxrs/resources: ./ META-INF/ META-INF/services/ dist/ docs/ docs/site/ docs/site/en/ docs/site/en/appdeveloperguide/ docs/site/en/appdeveloperguide/webcontainers/ docs/site/en/samples/ docs/si...
Date Tue, 23 Jun 2009 05:30:07 GMT
Propchange: incubator/wink/contrib/ibm-jaxrs/resources/docs/site/en/appdeveloperguide/webcontainers/was-console-prepareappinstall.png
------------------------------------------------------------------------------
    svn:mime-type = application/octet-stream

Added: incubator/wink/contrib/ibm-jaxrs/resources/docs/site/en/appdeveloperguide/webcontainers/was-console-preparebindings.png
URL: http://svn.apache.org/viewvc/incubator/wink/contrib/ibm-jaxrs/resources/docs/site/en/appdeveloperguide/webcontainers/was-console-preparebindings.png?rev=787550&view=auto
==============================================================================
Binary file - no diff available.

Propchange: incubator/wink/contrib/ibm-jaxrs/resources/docs/site/en/appdeveloperguide/webcontainers/was-console-preparebindings.png
------------------------------------------------------------------------------
    svn:mime-type = application/octet-stream

Added: incubator/wink/contrib/ibm-jaxrs/resources/docs/site/en/appdeveloperguide/webcontainers/was-console-startapp.png
URL: http://svn.apache.org/viewvc/incubator/wink/contrib/ibm-jaxrs/resources/docs/site/en/appdeveloperguide/webcontainers/was-console-startapp.png?rev=787550&view=auto
==============================================================================
Binary file - no diff available.

Propchange: incubator/wink/contrib/ibm-jaxrs/resources/docs/site/en/appdeveloperguide/webcontainers/was-console-startapp.png
------------------------------------------------------------------------------
    svn:mime-type = application/octet-stream

Added: incubator/wink/contrib/ibm-jaxrs/resources/docs/site/en/book.css
URL: http://svn.apache.org/viewvc/incubator/wink/contrib/ibm-jaxrs/resources/docs/site/en/book.css?rev=787550&view=auto
==============================================================================
--- incubator/wink/contrib/ibm-jaxrs/resources/docs/site/en/book.css (added)
+++ incubator/wink/contrib/ibm-jaxrs/resources/docs/site/en/book.css Tue Jun 23 05:30:05 2009
@@ -0,0 +1,44 @@
+body {
+	font-family: sans-serif, serif;
+	color: #000000;
+	font-size: 10pt;
+	border: 0px;
+	background: #FFFFFF;
+	margin-bottom: 1em
+}
+
+pre {
+	margin-top: 0pt;
+	margin-bottom: 0pt;
+	margin-right: 0pt;
+	margin-left: 0pt;
+	padding-left: 15pt;
+	font-size: 10pt;
+	font-family: monospace;
+	background-color: lightgray;
+}
+
+/* JAX-RS Styles */
+.mainTable {
+    background-color: #FFFFFF;
+    border: 1px #000000 solid;
+    font-family: sans-serif;
+    font-size: 11pt;
+    padding-top: 0px;
+    padding-bottom: 4px;
+    padding-left: 4px;
+    padding-right: 4px;
+    vertical-align: top;
+}
+
+/* Header and footer styles */
+.header {
+	font-size: 0.9em;
+	color: #000000;
+}
+
+.footer {
+	font-size: 0.8em;
+	font-style: italic;
+	color: #000000;
+}
\ No newline at end of file

Added: incubator/wink/contrib/ibm-jaxrs/resources/docs/site/en/footer.html
URL: http://svn.apache.org/viewvc/incubator/wink/contrib/ibm-jaxrs/resources/docs/site/en/footer.html?rev=787550&view=auto
==============================================================================
--- incubator/wink/contrib/ibm-jaxrs/resources/docs/site/en/footer.html (added)
+++ incubator/wink/contrib/ibm-jaxrs/resources/docs/site/en/footer.html Tue Jun 23 05:30:05 2009
@@ -0,0 +1,31 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
+<meta name="copyright" content="IBM Corporation 2008">
+<meta name="DC.Rights.Owner" content="IBM Corporation 2008">
+<!-- All rights reserved. Licensed Materials Property of IBM -->
+<!-- US Government Users Restricted Rights -->
+<!-- Use, duplication or disclosure restricted by -->
+<!-- GSA ADP Schedule Contract with IBM Corp. -->
+<style>
+@import "book.css";
+</style>
+</head>
+
+<body>
+<span class="footer">
+<hr align="left">
+Java and all Java-based trademarks are trademarks of Sun Microsystems,
+Inc. in the United States, other countries, or both. Microsoft, Windows,
+Windows NT, and the Windows logo are trademarks of Microsoft Corporation
+in the United States, other countries, or both. IBM and WebSphere are
+trademarks of International Business Machines Corporation in the United
+States, other countries, or both. Firefox and Mozilla are trademarks of
+the Mozilla in the United States, other countries, or both. UNIX is a
+registered trademark of The Open Group. Linux is the registered
+trademark of Linus Torvalds in the U.S. and other countries. <br>
+</span>
+</body>
+</html>
+

Added: incubator/wink/contrib/ibm-jaxrs/resources/docs/site/en/header.html
URL: http://svn.apache.org/viewvc/incubator/wink/contrib/ibm-jaxrs/resources/docs/site/en/header.html?rev=787550&view=auto
==============================================================================
--- incubator/wink/contrib/ibm-jaxrs/resources/docs/site/en/header.html (added)
+++ incubator/wink/contrib/ibm-jaxrs/resources/docs/site/en/header.html Tue Jun 23 05:30:05 2009
@@ -0,0 +1,25 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
+<meta name="copyright" content="IBM Corporation 2008">
+<meta name="DC.Rights.Owner" content="IBM Corporation 2008">
+<!-- All rights reserved. Licensed Materials Property of IBM -->
+<!-- US Government Users Restricted Rights -->
+<!-- Use, duplication or disclosure restricted by -->
+<!-- GSA ADP Schedule Contract with IBM Corp. -->
+<style>
+@import "book.css";
+</style>
+</head>
+
+<body>
+<span class="header"><strong>IBM
+JAX-RS</strong><br>
+<span style="height: 1px; text-align: left; width: 100%;">
+<hr>
+</span> </span>
+</span>
+</body>
+</html>
+

Added: incubator/wink/contrib/ibm-jaxrs/resources/docs/site/en/index.html
URL: http://svn.apache.org/viewvc/incubator/wink/contrib/ibm-jaxrs/resources/docs/site/en/index.html?rev=787550&view=auto
==============================================================================
--- incubator/wink/contrib/ibm-jaxrs/resources/docs/site/en/index.html (added)
+++ incubator/wink/contrib/ibm-jaxrs/resources/docs/site/en/index.html Tue Jun 23 05:30:05 2009
@@ -0,0 +1,124 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
+<meta name="copyright" content="IBM Corporation 2008">
+<meta name="DC.Rights.Owner" content="IBM Corporation 2008">
+<!-- All rights reserved. Licensed Materials Property of IBM -->
+<!-- US Government Users Restricted Rights -->
+<!-- Use, duplication or disclosure restricted by -->
+<!-- GSA ADP Schedule Contract with IBM Corp. -->
+<link rel="stylesheet" href="book.css" type="text/css">
+<link rel="stylesheet" href="../siteonly/site.css" type="text/css">
+<title>IBM JAX-RS</title>
+</head>
+<body>
+
+<!-- Header information -->
+<iframe src="header.html" scrolling="no" frameborder="0"
+	style="width: 100%; height: 75px;"> <a href="header.html">If
+you are using a lower-level browser, then click here to go directly to
+included content.</a> </iframe>
+
+<h1>IBM JAX-RS</h1>
+<div>
+<p>Welcome to IBM JAX-RS! IBM JAX-RS provides an implementation of
+the JAX-RS (JSR311) specification. In addition, this distribution
+includes documentation and samples to enable you to develop RESTful
+applications. To learn about each feature, click the link below that
+corresponds to the feature.</p>
+
+
+<table class="mainTable">
+	<tr class="mainTable">
+		<td class="mainTable" width="50%">
+		<h2><a href="whatisjaxrs.html">What is JAX-RS?</a></h2>
+		An overview of JAX-RS and REST services in Java.
+
+
+		<p>
+		<h2><a href="quickstart.html">Quick Start</a></h2>
+		Need to get up and running quickly? Here's a guide that will show you
+		how.
+		<blockquote>Look Ma! No hands! <a href="testyourapp.html">Test
+		your JAX-RS application without a web server.</a></blockquote>
+		</p>
+
+		<p>
+		<h2><a href="#">API Reference</a></h2>
+		The APIs defined by JAX-RS (JSR-311).
+
+		<p>
+		<h2><a href="#">See What is Happening</a></h2>
+		Keep up with the latest IBM JAX-RS developments here.
+		</p>
+
+		<p>
+		<h2><a href="#">Leveraging IBM JAX-RS</a></h2>
+		Have a project that needs JAX-RS support? Here are some details on how
+		to go about including the IBM JAX-RS runtime in your product.
+		</p>
+
+		<p>
+		<h2><a href="additional-reading.html">Additional Reading</a></h2>
+		Links to more background on REST and some of the surrounding
+		technologies.</td>
+		<td>
+
+		<p>
+		<h2>Guides</h2>
+		Here are a set of links that help answer common questions about JAX-RS
+		and developing REST services.
+		</p>
+
+		<p>
+		<h3>Developing JAX-RS Applications</h3>
+		<a href="appdeveloperguide/devenv.html">Compiling JAX-RS resources</a><br>
+		<a href="appdeveloperguide/deploying.html">Preparing an
+		application for web container deployment</a><br>
+		<a href="appdeveloperguide/webcontainers/install-websphere.html">Installing
+		a JAX-RS application on WebSphere</a>
+		</p>
+
+		<p>
+		<h3>JAX-RS/REST General</h3>
+		<a href="#">Defining the URI for a resource</a><br>
+		<a href="#">Defining what media types a resource can handle</a><br>
+		<a href="samples/contentnegotiation/index.html">Determine what
+		type of data format to send back</a>
+		</p>
+
+		<p>
+		<h3>Accessing Parameters</h3>
+		<a href="#">Embedding parameters in URIs</a><br>
+		<a href="#">Using HTTP query string parameters</a><br>
+		<a href="#">Using HTTP header parameters</a><br>
+		</p>
+
+		<p>
+		<h3>Reading and Returning Data</h3>
+		<a href="samples/xml/index.html">Representing a resource as XML</a><br>
+		<a href="appdeveloperguide/using-jaxb.html">Generating XML from
+		Java beans with JAXB</a><br>
+		<a href="samples/xml/index.html#using-stream">Generating XML with
+		streams</a><br>
+		<a href="samples/xml/index.html#using-dom">Generating XML with DOM</a><br>
+		</p>
+
+		<p>
+		<h3>Handling Errors</h3>
+		<a href="samples/guestbook/index.html">Returning an error message
+		to the client</a><br>
+		<a href="samples/guestbook/index.html">Including custom content in
+		an error message</a> <br>
+		<br>
+		</td>
+	</tr>
+</table>
+
+<!-- Footer information --> <iframe src="footer.html" scrolling="no"
+	frameborder="0" style="width: 100%;"> <a href="footer.html">If
+you are using a lower-level browser, then click here to go directly to
+included content.</a> </iframe>
+</body>
+</html>

Added: incubator/wink/contrib/ibm-jaxrs/resources/docs/site/en/leveraging-ibmjaxrs.html
URL: http://svn.apache.org/viewvc/incubator/wink/contrib/ibm-jaxrs/resources/docs/site/en/leveraging-ibmjaxrs.html?rev=787550&view=auto
==============================================================================
--- incubator/wink/contrib/ibm-jaxrs/resources/docs/site/en/leveraging-ibmjaxrs.html (added)
+++ incubator/wink/contrib/ibm-jaxrs/resources/docs/site/en/leveraging-ibmjaxrs.html Tue Jun 23 05:30:05 2009
@@ -0,0 +1,71 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
+<meta name="copyright" content="IBM Corporation 2008">
+<meta name="DC.Rights.Owner" content="IBM Corporation 2008">
+<!-- All rights reserved. Licensed Materials Property of IBM -->
+<!-- US Government Users Restricted Rights -->
+<!-- Use, duplication or disclosure restricted by -->
+<!-- GSA ADP Schedule Contract with IBM Corp. -->
+<link rel="stylesheet" href="book.css" type="text/css">
+<link rel="stylesheet" href="../siteonly/site.css" type="text/css">
+<title>IBM JAX-RS</title>
+</head>
+<body>
+
+<!-- Header information -->
+<iframe src="header.html" scrolling="no" frameborder="0"
+	style="width: 100%; height: 75px;"> <a href="header.html">If
+you are using a lower-level browser, then click here to go directly to
+included content.</a> </iframe>
+
+
+
+<h4>How do I get a copy of IBM JAX-RS?</h4>
+
+<p>You should visit our Project's <a
+	href="https://cs.opensource.ibm.com/frs/?group_id=3532">Files</a>
+section for distributed versions of the IBM JAX-RS project.</p>
+
+<h4>How do I use the project?</h4>
+
+<p>Visit our <a href="../../appdeveloperguide/index.html">application
+developer's guide</a> to get started.</p>
+
+<h4>I found a bug. How do I get it fixed?</h4>
+
+<p>Please <a
+	href="https://cs.opensource.ibm.com/account/login.php?return_to=%2Ftracker%2F%3Fatid%3D10978%26group_id%3D3532%26func%3Dbrowse">sign</a>
+into the community source site and then <a
+	href="https://cs.opensource.ibm.com/tracker/?func=add&group_id=3532&atid=10978">submit</a>
+a bug to the project tracker. You can also submit feature requests. If
+you can share a code sample, describe your runtime environment, and/or
+explain what you wanted to achieve, that would be very helpful.</p>
+
+<h4>What's next?</h4>
+
+<p>You can check out the rest of the project web site, read the
+documentation, and open <a
+	href="https://cs.opensource.ibm.com/tracker/?atid=10981&group_id=3532&func=browse">feature
+requests</a> or <a
+	href="https://cs.opensource.ibm.com/tracker/?func=add&group_id=3532&atid=10978">bug
+reports</a>.</p>
+
+<p>If you have a question on how you would like to use this project,
+a use case, or any other feedback, please post to the <a
+	href="https://cs.opensource.ibm.com/forum/?group_id=3532">forums</a>.
+We appreciate hearing from you!</p>
+
+<h4>Considerations</h4>
+<p>Portions of this project, both documentation and source code,
+have been taken from the Apache CXF project.</p>
+
+<!-- Footer information -->
+<iframe src="footer.html" scrolling="no" frameborder="0"
+	style="width: 100%;"> <a href="footer.html">If you are
+using a lower-level browser, then click here to go directly to included
+content.</a> </iframe>
+
+</body>
+</html>
\ No newline at end of file

Added: incubator/wink/contrib/ibm-jaxrs/resources/docs/site/en/quickstart.html
URL: http://svn.apache.org/viewvc/incubator/wink/contrib/ibm-jaxrs/resources/docs/site/en/quickstart.html?rev=787550&view=auto
==============================================================================
--- incubator/wink/contrib/ibm-jaxrs/resources/docs/site/en/quickstart.html (added)
+++ incubator/wink/contrib/ibm-jaxrs/resources/docs/site/en/quickstart.html Tue Jun 23 05:30:05 2009
@@ -0,0 +1,248 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
+<meta name="copyright" content="IBM Corporation 2008">
+<meta name="DC.Rights.Owner" content="IBM Corporation 2008">
+<!-- All rights reserved. Licensed Materials Property of IBM -->
+<!-- US Government Users Restricted Rights -->
+<!-- Use, duplication or disclosure restricted by -->
+<!-- GSA ADP Schedule Contract with IBM Corp. -->
+<link rel="stylesheet" href="book.css" type="text/css">
+<link rel="stylesheet" href="../siteonly/site.css" type="text/css">
+<title>IBM JAX-RS QuickStart</title>
+</head>
+<body>
+
+<!-- Header information -->
+<iframe src="header.html" scrolling="no" frameborder="0"
+	style="width: 100%; height: 75px;"> <a href="header.html">If
+you are using a lower-level browser, then click here to go directly to
+included content.</a> </iframe>
+
+<h1>JAX-RS QuickStart Guide</h1>
+
+<p>This quickstart guide will walk you through development of a very basic "Hello, World!" JAX-RS sample application in <a href="http://www.eclipse.org/">Eclipse IDE</a> (version 3.4.2, as of this writing), deployable on nearly any web container framework.</p>
+
+<ol>
+<li>Create a new java project.  Let's call it "jaxrs_helloworld"</li>
+<li>Configure your project to have the JAX-RS API and implementation library jars on its buildpath
+	<br />
+	<ul>
+		<li>Right-click project -&gt; Properties -&gt; Java Build Path -&gt; Libraries -&gt; Add External JARs -&gt; browse to find ibmjaxrs-SNAPSHOT.jar AND jsr311-api-0.11.jar -&gt; OK</li>
+	</ul>
+</li>
+<li>Develop your server-side JAX-RS application:
+	<ol>
+		<li>Create a new class that processes incoming requests
+		<blockquote>
+        As a best practice, you may wish to name your resource with "Resource" at the end of your class name.<br />
+        <br />
+        Resource classes can support the four HTTP commands:  POST, GET, DELETE, and PUT.  Our HelloWorldResource class will only support GET.
+        </blockquote>
+        <ul>
+        	<li>Right-click project -> New -> Java Class -> </li>
+			<li>Package: org.myorg.jaxrs.sample</li>
+			<li>Class:  HelloWorldResource</li>
+		</ul>
+		</li>
+		<li>Create a method that takes no parameters, and returns the string "Hello, World!"  The method name is arbitrary:
+
+<table border="0" width="100%">
+	<tbody>
+		<tr>
+			<td class="code-outline">
+			<div><pre><code>public String helloWorld() {
+	return "Hello, World!";
+}</code></pre></div>
+			</td>
+		</tr>
+	</tbody>
+</table>
+		<br />	
+		The JAX-RS runtime needs to know where to expose this resource.  Add the @Path annotation to the method:
+<table border="0" width="100%">
+	<tbody>
+		<tr>
+			<td class="code-outline">
+			<div><pre><code><strong style="color:green;">@Path("helloworld")</strong>
+public String helloWorld() {
+	return "Hello, World!";
+}</code></pre></div>
+			</td>
+		</tr>
+	</tbody>
+</table>
+		<br />
+Now JAX-RS needs to know which methods perform what actions.  Our only method, helloWorld(), simply returns a String.  So logically, it fits with the GET command.  Add the @GET annotation to the helloWorld() method:
+<table border="0" width="100%">
+	<tbody>
+		<tr>
+			<td class="code-outline">
+			<div><pre><code><strong style="color:green;">@GET</strong>
+@Path("helloworld")
+public String helloWorld() {
+	return "Hello, World!";
+}</code></pre></div>
+			</td>
+		</tr>
+	</tbody>
+</table>
+		<br />
+Now our resource class is configured to handle HTTP inbound GET requests at:
+<table border="0" width="100%">
+	<tbody>
+		<tr>
+			<td class="code-outline">
+			<div><pre><code>http://&lt;host&gt;:&lt;port&gt;/&lt;context_root&gt;/helloworld</code></pre></div>
+			</td>
+		</tr>
+	</tbody>
+</table>
+		<br />
+		Note:  &lt;context_root&gt; is defined by the the servlet container on which you deploy your application and may be an empty value, making your URL http://&lt;host&gt;:&lt;port&gt;/helloworld
+		<br />
+		<br />
+		Since all web browsers send GET requests when a URL is entered in as the location, we will be able to query our application very simply from a browser.
+		<br />
+		<br />
+However, we need to register the HelloWorldResource class as a resource with the JAX-RS runtime.  We do this by creating a HelloWorldApplication class that declares resources to the JAX-RS runtime:
+		</li>
+
+<li>Create a new application class:
+	<blockquote>
+	As a best practice, you may wish to name your resource with "Application" at the end of your class name.
+	</blockquote>
+	<ul>
+        	<li>Right-click project -&gt; New -&gt; Java Class -&gt;</li>
+			<li>Package: org.myorg.jaxrs.sample</li>
+			<li>Class: HelloWorldApplication</li>
+			<li>Superclass:  javax.ws.rs.core.Application;</li>
+	</ul>
+	<br />
+
+	In the HelloWorldApplication, write a method to override the javax.ws.rs.core.Application.getClasses method.  This is how you declare to the JAX-RS runtime which classes should be exposed as resources.  In our application, we only have one resource class, so your getClasses method would look like this:
+
+<table border="0" width="100%">
+	<tbody>
+		<tr>
+			<td class="code-outline">
+			<div><pre><code>@Override
+public Set&lt;Class&lt;?&gt;&gt; getClasses() {
+	Set&lt;Class&lt;?&gt;&gt; classes = new HashSet&lt;Class&lt;?&gt;&gt;();
+	classes.add(HelloWorldResource.class);
+	return classes;
+}</code></pre></div>
+			</td>
+		</tr>
+	</tbody>
+</table>
+		<br />
+At this point, we have a complete JAX-RS application with a single resource to handle an HTTP GET request!
+		<br />
+		<br />
+		(The next few steps assume you are not using Eclipse or other IDE tools to build a WAR file.)
+		<br />
+		<br />
+		</li>
+		<li>
+		There's one last thing to do.  We have to tell the application server's servlet container what servlet implementation to use, and we have to pass our application class name as a parameter to the JAX-RS servlet implementation.  This is all done with the very familiar web.xml deployment descriptor:
+		<br />
+		<br />
+		Create the necessary web.xml deployment descriptor:
+		<ul>
+			<li>Create a WEB-INF directory as a peer to your project src directory</li>
+			<li>Create a web.xml file inside.  At a minimum, you will need a a servlet-name, servlet-class, init-param, and servlet-mapping.  For our HelloWorldApplication, it would look like this:
+
+<table border="0" width="100%">
+	<tbody>
+		<tr>
+			<td class="code-outline">
+			<div><pre><code>&lt;?xml version="1.0" encoding="UTF-8"?&gt;
+	&lt;!--
+		This program may be used, executed, copied, modified and distributed
+		without royalty for the purpose of developing, using, marketing, or
+		distributing.
+	--&gt;
+&lt;web-app id="WebApp_ID" version="2.5"
+	xmlns="http://java.sun.com/xml/ns/javaee" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+	xsi:schemaLocation="http://java.sun.com/xml/ns/javaee http://java.sun.com/xml/ns/javaee/web-app_2_5.xsd"&gt;
+	&lt;servlet&gt;
+		&lt;servlet-name&gt;HelloWorld&lt;/servlet-name&gt;
+		&lt;servlet-class&gt;com.ibm.ws.jaxrs.web.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.myorg.jaxrs.sample.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;HelloWorld&lt;/servlet-name&gt;
+		&lt;url-pattern&gt;/*&lt;/url-pattern&gt;
+	&lt;/servlet-mapping&gt;
+&lt;/web-app&gt;</code></pre></div>
+			</td>
+		</tr>
+	</tbody>
+</table>
+
+	</li>
+	<li>Export your project as a WAR to be deployed on a web server with a servlet container.  Recall that the structure of a WAR is:
+<table border="0" width="100%">
+	<tbody>
+		<tr>
+			<td class="code-outline">
+			<div><pre><code>WEB-INF/classes/&lt;path_to_compiled_classes&gt;
+WEB-INF/lib/&lt;library_jars_for_your_app&gt;
+WEB-INF/web.xml</code></pre></div>
+			</td>
+		</tr>
+	</tbody>
+</table>
+		<br />
+		Specifically, our HelloWorld application WAR file would be (note that the listed JAR files in the lib folder are required by the JAX-RS runtime, and thus are required to be in your WAR file):
+<table border="0" width="100%">
+	<tbody>
+		<tr>
+			<td class="code-outline">
+			<div><pre><code>META-INF/MANIFEST.MF
+WEB-INF/classes/com/ibm/jaxrs/sample/helloworld/HelloWorldResource.class
+WEB-INF/classes/com/ibm/jaxrs/sample/helloworld/HelloWorldApplication.class
+WEB-INF/web.xml
+WEB-INF/lib/ibmjaxrs-SNAPSHOT.jar
+WEB-INF/lib/jsr311-api-0.11.jar
+WEB-INF/lib/abdera-0.4.0-incubating.jar
+WEB-INF/lib/abdera-core-0.4.0-incubating.jar
+</code></pre></div>
+			</td>
+		</tr>
+	</tbody>
+</table>
+		</li>
+		</ul>
+	</li>
+	</ol>
+</li>
+
+
+<li><font size="4">That's it!  Hello, World!</font></li>
+
+</ol>
+
+<h2>Next Steps</h2>
+
+<ul>
+<li>You may want to implement methods to handle @POST, @PUT, @DELETE.  Implementing these methods follows the same conventions as the method that handles @GET, except of course they could take parameters as input.  Please see <a href="index.html">additional documentation and samples</a>.</li>
+<li>Note also that this "Hello, World!" sample transmits simple String data across the wire, and the JAX-RS runtime can handle String ("text/plain", in HTTP terms) natively.  If you wish to transmit data in a specific format, such as JSON, XML, or your own proprietary format, you will need to provide the annotations to declare such, and optionally provide your own custom MessageBodyReader and MessageBodyWriter.</li>
+<li><a href="testyourapp.html">Test your app without a web server.</a></li>
+<li>That's not all you can do!  Poke around <a href="index.html">the documentation</a> and see for yourself!
+</ul>
+
+<!-- Footer information -->
+<iframe src="footer.html" scrolling="no" frameborder="0"
+	style="width: 100%;"> <a href="footer.html">If you are
+using a lower-level browser, then click here to go directly to included
+content.</a> </iframe>
+
+</body>
+</html>
\ No newline at end of file

Added: incubator/wink/contrib/ibm-jaxrs/resources/docs/site/en/samples-index.html
URL: http://svn.apache.org/viewvc/incubator/wink/contrib/ibm-jaxrs/resources/docs/site/en/samples-index.html?rev=787550&view=auto
==============================================================================
--- incubator/wink/contrib/ibm-jaxrs/resources/docs/site/en/samples-index.html (added)
+++ incubator/wink/contrib/ibm-jaxrs/resources/docs/site/en/samples-index.html Tue Jun 23 05:30:05 2009
@@ -0,0 +1,42 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
+<meta name="copyright" content="IBM Corporation 2008" />
+<meta name="DC.Rights.Owner" content="IBM Corporation 2008" />
+<!-- All rights reserved. Licensed Materials Property of IBM -->
+<!-- US Government Users Restricted Rights -->
+<!-- Use, duplication or disclosure restricted by -->
+<!-- GSA ADP Schedule Contract with IBM Corp. -->
+<link rel="stylesheet" href="book.css" type="text/css">
+<title>IBM JAX-RS: Samples Guide</title>
+</head>
+
+<body>
+<!-- Header information -->
+<iframe src="header.html" scrolling="no" frameborder="0"
+	style="width: 100%; height: 75px;"><a href="header.html">Hmm,
+you are using a very old browser. Click here to go directly to included
+content.</a></iframe>
+
+<h2 align="center">Samples Guide</h2>
+<div>
+<ul>
+	<li><a href="samples/addressbook/index.html">Address Book
+	Sample</a></li>
+	<li><a href="samples/contentnegotiation/index.html">Content
+	Negotiation Scoreboard Sample</a></li>
+	<li><a href="samples/guestbook/index.html">Guestbook Sample</a> -
+	Exceptions and other Errors</li>
+	<li><a href="samples/providers/index.html">Provider Sample</a> -
+	Creating MessageBodyReaders/Writers</li>
+	<li><a href="samples/xml/index.html">XML Phonebook Service</a> -
+	XML via Generic Entity Types</li>
+</ul>
+</div>
+
+<iframe src="footer.html" scrolling="no" frameborder="0"
+	style="width: 100%;"><a href="footer.html">Hmm, you are
+using a very old browser. Click here to go directly to included content.</a></iframe>
+</body>
+</html>
\ No newline at end of file

Added: incubator/wink/contrib/ibm-jaxrs/resources/docs/site/en/samples/addressbook/images/client.png
URL: http://svn.apache.org/viewvc/incubator/wink/contrib/ibm-jaxrs/resources/docs/site/en/samples/addressbook/images/client.png?rev=787550&view=auto
==============================================================================
Binary file - no diff available.

Propchange: incubator/wink/contrib/ibm-jaxrs/resources/docs/site/en/samples/addressbook/images/client.png
------------------------------------------------------------------------------
    svn:mime-type = application/octet-stream

Added: incubator/wink/contrib/ibm-jaxrs/resources/docs/site/en/samples/addressbook/index.html
URL: http://svn.apache.org/viewvc/incubator/wink/contrib/ibm-jaxrs/resources/docs/site/en/samples/addressbook/index.html?rev=787550&view=auto
==============================================================================
--- incubator/wink/contrib/ibm-jaxrs/resources/docs/site/en/samples/addressbook/index.html (added)
+++ incubator/wink/contrib/ibm-jaxrs/resources/docs/site/en/samples/addressbook/index.html Tue Jun 23 05:30:05 2009
@@ -0,0 +1,433 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
+<meta name="copyright" content="IBM Corporation 2008" />
+<meta name="DC.Rights.Owner" content="IBM Corporation 2008" />
+<!-- All rights reserved. Licensed Materials Property of IBM -->
+<!-- US Government Users Restricted Rights -->
+<!-- Use, duplication or disclosure restricted by -->
+<!-- GSA ADP Schedule Contract with IBM Corp. -->
+<link rel="stylesheet" href="../../book.css" type="text/css">
+<link rel="stylesheet" href="../../../siteonly/site.css" type="text/css">
+<title>IBM JAX-RS: Address Book Sample</title>
+</head>
+
+<body>
+<!-- Header information -->
+<iframe src="../../header.html" scrolling="no" frameborder="0"
+	style="width: 100%; height: 75px;"><a href="../../header.html">Hmm,
+you are using a very old browser. Click here to go directly to included
+content.</a></iframe>
+
+<h2 align="center">Address Book Sample Application Guide</h2>
+<h4 align="center">Version 1.0.0</h4>
+
+<h2 class="topictitle1">Overview</h2>
+
+<div>
+<p>The Address Book sample is an example of a RESTful service that
+stores/retrieves/removes/updates address book entries. Additionally, a
+client interface, written with DOJO, is provided to manipulate and view
+the address book.</p>
+
+</div>
+
+<div class="section">
+<h3 class="sectiontitle">AddressBook Resource</h3>
+<p>The path to the AddressBook resource is declared by the @Path
+annotation.</p>
+<table border="0" width="100%">
+	<tbody>
+		<tr>
+			<td class="code-outline">
+			<div><pre><code>package com.ibm.rest.sample;
+
+import java.util.Iterator;
+import java.util.List;
+
+import javax.ws.rs.Consumes;
+import javax.ws.rs.DELETE;
+import javax.ws.rs.FormParam;
+import javax.ws.rs.GET;
+import javax.ws.rs.POST;
+import javax.ws.rs.PUT;
+import javax.ws.rs.Path;
+import javax.ws.rs.PathParam;
+import javax.ws.rs.Produces;
+import javax.ws.rs.QueryParam;
+
+@Path(value = "/addresses")
+public class AddressBook {</code></pre></div>
+			</td>
+		</tr>
+	</tbody>
+</table>
+
+<p>The AddressBook has seven methods of interest:</p>
+<ol>
+	<li>
+	<p>This method maps to incoming GET requests whose request path is
+	of the form '/addresses'</p>
+	<table border="0" width="100%">
+		<tbody>
+			<tr>
+				<td class="code-outline">
+				<div><pre><code>@GET
+@Produces(value = { "text/xml", "application/json" })
+public AddressList getAddresses()</code></pre></div>
+				</td>
+			</tr>
+		</tbody>
+	</table>
+	</li>
+	<li>
+	<p>This method maps to incoming POST requests whose request path is
+	of the form '/addresses' and the Content-Type is
+	"application/x-www-form-urlencoded". The information to create a new
+	address instance is contained in the posted form.</p>
+	<table border="0" width="100%">
+		<tbody>
+			<tr>
+				<td class="code-outline">
+				<div><pre><code>@POST
+@Consumes(value = "application/x-www-form-urlencoded")
+public void createAddress(
+@FormParam(value = "entryName") String entryName, 
+@FormParam(value = "zipCode") String zipCode, 
+@FormParam(value = "streetAddress") String streetAddress, 
+@FormParam(value = "city") String city, 
+@FormParam(value = "state") String state, 
+@FormParam(value = "country") String country)</code></pre></div>
+				</td>
+			</tr>
+		</tbody>
+	</table>
+	</li>
+	<li>
+	<p>This method maps to incoming POST requests whose request path is
+	of the form '/addresses' and the Content-Type is "text/xml". The
+	information to create a new address instance is contained in the posted
+	xml.</p>
+	<table border="0" width="100%">
+		<tbody>
+			<tr>
+				<td class="code-outline">
+				<div><pre><code>@POST
+@Consumes(value="text/xml")
+public void addAddress(Address address)</code></pre></div>
+				</td>
+			</tr>
+		</tbody>
+	</table>
+	</li>
+	<li>
+	<p>This method maps to incoming DELETE requests. The request path
+	will be of the form '/addresses/{address_entry_name}'</p>
+	<table border="0" width="100%">
+		<tbody>
+			<tr>
+				<td class="code-outline">
+				<div><pre><code>@DELETE
+@Consumes(value = { "text/xml", "application/x-www-form-urlencoded" })
+@Path(("/{entryName}"))
+public void removeAddress(@PathParam(value = "entryName") String entryName)</code></pre></div>
+				</td>
+			</tr>
+		</tbody>
+	</table>
+	</li>
+	<li>
+	<p>This method maps to incoming PUT requests whose request path is
+	of the form '/addresses'. The information to update an address instance
+	is contained in the query string.</p>
+	<table border="0" width="100%">
+		<tbody>
+			<tr>
+				<td class="code-outline">
+				<div><pre><code>@PUT
+@Consumes(value = { "text/xml", "application/x-www-form-urlencoded" })
+public void updateAddress(
+    @QueryParam(value = "entryName") String entryName, 
+    @QueryParam(value = "zipCode") String zipCode, 
+    @QueryParam(value = "streetAddress") String streetAddress, 
+    @QueryParam(value = "city") String city, 
+    @QueryParam(value = "state") String state, 
+    @QueryParam(value = "country") String country)</code></pre></div>
+				</td>
+			</tr>
+		</tbody>
+	</table>
+	</li>
+	<li>
+	<p>This method maps to incoming GET requests to search for an
+	address instance. The request path will be of the form
+	'/addresses/search/{search_string}'</p>
+	<table border="0" width="100%">
+		<tbody>
+			<tr>
+				<td class="code-outline">
+				<div><pre><code>@GET
+@Path(value="/search/{searchstring}")
+@Consumes(value = { "text/xml", "application/x-www-form-urlencoded" })
+@Produces(value = { "text/xml", "application/json"})
+public AddressList search(@PathParam(value="searchstring") String searchString)</code></pre></div>
+				</td>
+			</tr>
+		</tbody>
+	</table>
+	</li>
+	<li>
+	<p>This method maps to incoming requests, other than DELETE
+	requests, whose request path is of the form
+	'/addresses/{address_entry_name}'.</p>
+	<table border="0" width="100%">
+		<tbody>
+			<tr>
+				<td class="code-outline">
+				<div><pre><code>@Path("/{entryName}")
+public Address getAddress(@PathParam(value = "entryName")</code></pre></div>
+				</td>
+			</tr>
+		</tbody>
+	</table>
+	<p>This method will delegate requests to the Address subresource.
+	The Address subresource has a single method to serve GET requests:</p>
+
+	<table border="0" width="100%">
+		<tbody>
+			<tr>
+				<td class="code-outline">
+				<div><pre><code>@GET
+@Consumes(value = { "text/xml", "application/x-www-form-urlencoded" })
+@Produces(value = { "text/xml", "application/json" })
+public Address get()</code></pre></div>
+				</td>
+			</tr>
+		</tbody>
+	</table>
+</ol>
+</div>
+
+<p>Here's a brief summary of the resource:</p>
+
+<div class="tableborder">
+<table cellspacing="0" cellpadding="4" frame="border" border="1"
+	rules="all">
+	<caption>Table 1. URI Overview</caption>
+	<thead>
+		<tr>
+			<th>HTTP Method</th>
+			<th>URI</th>
+			<th>Input Type(s)</th>
+			<th>Output Type(s)</th>
+			<th>Note(s)</th>
+		</tr>
+	</thead>
+	<tbody>
+		<tr>
+			<td>GET</td>
+			<td>/addresses</td>
+			<td>*/*</td>
+			<td>text/xml, application/json</td>
+			<td>Get all addresses</td>
+		</tr>
+		<tr>
+			<td>POST</td>
+			<td>/addresses</td>
+			<td>application/x-www-form-urlencoded</td>
+			<td>n/a</td>
+			<td>Add a new address</td>
+		</tr>
+		<tr>
+			<td>POST</td>
+			<td>/addresses</td>
+			<td>text/xml</td>
+			<td>n/a</td>
+			<td>Add a new address</td>
+		</tr>
+		<tr>
+			<td>DELETE</td>
+			<td>/addresses/{entryName}</td>
+			<td>text/xml, application/x-www-form-urlencoded</td>
+			<td>n/a</td>
+			<td>Remove the specified address</td>
+		</tr>
+		<tr>
+			<td>PUT</td>
+			<td>/addresses</td>
+			<td>text/xml, application/x-www-form-urlencoded</td>
+			<td>n/a</td>
+			<td>Update an existing address</td>
+		</tr>
+		<tr>
+			<td>GET</td>
+			<td>/addresses/search/{searchString}</td>
+			<td>text/xml, application/x-www-form-urlencoded</td>
+			<td>text/xml, application/json</td>
+			<td>Get addresses whose entry matches 'searchString'</td>
+		</tr>
+		<tr>
+			<td>GET</td>
+			<td>/addresses/{entryName}</td>
+			<td>text/xml, application/x-www-form-urlencoded</td>
+			<td>text/xml, application/json</td>
+			<td>Delegate to GET on Address class, retrieve specified address</td>
+		</tr>
+	</tbody>
+</table>
+
+</div>
+
+
+<div class="section">
+<h3 class="sectiontitle">Address Book Client</h3>
+
+<p>The address book client presents a web interface that allows you
+to manipulate the Address Book Resource:</p>
+<img src="images/client.png" border="1" /></div>
+
+
+<div class="section">
+<h3 class="sectiontitle">Installing/Running</h3>
+
+<ol>
+	<li>Install the 'addressBook_server.war' in a web container and
+	assign a context root of '/rest' to the WAR.</li>
+	<li>Install the 'addressBook_client.war' in a web container and
+	assign a context root of your choosing.</li>
+	<li>Navigate to
+	http://{yourhost}:{yourport}/{client_context_root}/addressBook.html.</li>
+	<li>Use the client interface to add, remove, update, or search for
+	entries in the Address Book</li>
+</ol>
+</div>
+
+
+<div class="section">
+<h3 class="sectiontitle">Alternative cURL based commands for
+accessing the server</h3>
+
+<ul>
+	<li>
+	<p>Get the list of current addresses using HTTP GET</p>
+
+	<table border="0" width="100%">
+		<tbody>
+			<tr>
+				<td class="code-outline">
+				<div class="displaycode"><pre><code>curl http://{yourhost}:{yourport}/rest/addresses</code></pre></div>
+				</td>
+			</tr>
+		</tbody>
+	</table>
+	</li>
+	<li>
+	<p>Add a new address using HTTP POST (with form data)</p>
+	<table border="0" width="100%">
+		<tbody>
+			<tr>
+				<td class="code-outline">
+				<div><pre><code>curl -X POST --data-urlencode 'entryName=fooBar' \
+    --data-urlencode 'streetAddress=1 Rogers St' \
+    --data-urlencode 'city=Cambridge' \
+    --data-urlencode 'state=MA' \
+    --data-urlencode 'zipCode=02142-1203' \
+    --data-urlencode 'country=USA' \
+    http://{yourhost}:{yourport}/rest/addresses</code></pre></div>
+				</td>
+			</tr>
+		</tbody>
+	</table>
+	</li>
+	<li>
+	<p>Add a new address using HTTP POST (with xml)</p>
+
+
+	<table border="0" width="100%">
+		<tbody>
+			<tr>
+				<td class="code-outline">
+				<div><pre><code>curl -X POST -H "Content-Type: text/xml" \
+    -d "&lt;address&gt;&lt;city&gt;Cambridge&lt;/city&gt;&lt;country&gt;USA&lt;/country&gt;&lt;entryName&gt;fooBar2&lt;/entryName&gt;&lt;state&gt;MA&lt;/state&gt;&lt;/address&gt;" \
+    http://localhost:8080/AddressBook/addresses</code></pre></div>
+				</td>
+			</tr>
+		</tbody>
+	</table>
+	</li>
+	<li>
+	<p>Get a specific address using HTTP GET</p>
+	<table border="0" width="100%">
+		<tbody>
+			<tr>
+				<td class="code-outline">
+				<div><pre><code>curl http://{yourhost}:{yourport}/rest/addresses/fooBar</code></pre></div>
+				</td>
+			</tr>
+		</tbody>
+	</table>
+
+	</li>
+	<li>
+	<p>Update the street address using HTTP PUT</p>
+
+	<table border="0" width="100%">
+		<tbody>
+			<tr>
+				<td class="code-outline">
+				<div><pre><code>curl -X PUT --data-urlencode 'entryName=fooBar' \
+    --data-urlencode 'streetAddress=One Rogers St' \
+    http://{yourhost}:{yourport}/rest/addresses</code></pre></div>
+				</td>
+			</tr>
+		</tbody>
+	</table>
+
+	</li>
+	<li>
+	<p>Search for an address that starts with "foo"</p>
+	<table border="0" width="100%">
+		<tbody>
+			<tr>
+				<td class="code-outline">
+				<div><pre><code>curl -X GET http://{yourhost}:{yourport}/rest/addresses/search/foo</code></pre></div>
+				</td>
+			</tr>
+		</tbody>
+	</table>
+	</li>
+	<li>
+	<p>Search for address for "fooBar" and get back JSON</p>
+	<table border="0" width="100%">
+		<tbody>
+			<tr>
+				<td class="code-outline">
+				<div><pre><code>curl -X GET -i -H "Accept: application/json" http://{yourhost}:{yourport}/rest/addresses/search/fooBar</code></pre></div>
+				</td>
+			</tr>
+		</tbody>
+	</table>
+	</li>
+	<li>
+	<p>Delete address for "fooBar"</p>
+
+	<table border="0" width="100%">
+		<tbody>
+			<tr>
+				<td class="code-outline">
+				<div><pre><code>curl -X DELETE http://{yourhost}:{yourport}/rest/addresses/fooBar</code></pre></div>
+				</td>
+			</tr>
+		</tbody>
+	</table>
+	</li>
+</ul>
+</div>
+
+
+<iframe src="../../footer.html" scrolling="no" frameborder="0"
+	style="width: 100%;"><a href="../../footer.html">Hmm, you are
+using a very old browser. Click here to go directly to included content.</a></iframe>
+</body>
+</html>
\ No newline at end of file

Added: incubator/wink/contrib/ibm-jaxrs/resources/docs/site/en/samples/contentnegotiation/index.html
URL: http://svn.apache.org/viewvc/incubator/wink/contrib/ibm-jaxrs/resources/docs/site/en/samples/contentnegotiation/index.html?rev=787550&view=auto
==============================================================================
--- incubator/wink/contrib/ibm-jaxrs/resources/docs/site/en/samples/contentnegotiation/index.html (added)
+++ incubator/wink/contrib/ibm-jaxrs/resources/docs/site/en/samples/contentnegotiation/index.html Tue Jun 23 05:30:05 2009
@@ -0,0 +1,518 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
+<meta name="copyright" content="IBM Corporation 2008" />
+<meta name="DC.Rights.Owner" content="IBM Corporation 2008" />
+<!-- All rights reserved. Licensed Materials Property of IBM -->
+<!-- US Government Users Restricted Rights -->
+<!-- Use, duplication or disclosure restricted by -->
+<!-- GSA ADP Schedule Contract with IBM Corp. -->
+
+<link rel="stylesheet" href="../../book.css" type="text/css">
+<link rel="stylesheet" href="../../../siteonly/site.css" type="text/css">
+<title>IBM JAX-RS: Content Negotiation Sample</title>
+</head>
+
+<body>
+<!-- Header information -->
+<iframe src="../../header.html" scrolling="no" frameborder="0"
+	style="width: 100%; height: 75px;"><a href="../../header.html">Hmm,
+you are using a very old browser. Click here to go directly to included
+content.</a></iframe>
+
+<h2 align="center">Content Negotiation Sample Application Guide</h2>
+<h4 align="center">Version 1.0.0</h4>
+
+<h2 class="topictitle1">Overview</h2>
+
+<div>
+<p>What if your application needs to return both XML and JSON
+representations of a resource? What are some ways to implement that in
+JAX-RS while supporting clients? How can HTTP itself help the client
+negotiate what the response will be like from the server?</p>
+
+<p>Content negotiation is a core concept within the HTTP protocol. A
+user fetches data from a URL and content is returned back. In some
+cases, the response's representation such as the data format (a.k.a.
+content media type) is static and pre-determined. For instance, if the
+user HTTP GETs a resource like "index.html", more than likely, the user
+will always be getting a HTML page (the resource's representation with a
+text/html media type). In more advanced cases, the response's
+representation is negotiated between the client and the server by
+various <a href="http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html">HTTP
+Accept* headers</a>. The content type, language, character set, and encoding
+can be negotiated between the client and the server.</p>
+</div>
+
+
+<div class="section">
+<h3 class="sectiontitle">Hardcoded Data Formats in URLs and
+Parameters</h3>
+
+<p>Some RESTful services today use hard coded URL schemes to ensure
+that clients can request content in the format they want. For instance,
+some put the format information in the URL path so
+"example.com/collection/resource<b>.json</b>" and
+"example.com/collection/resource<b>.xml</b>" would only return content
+in JSON and XML respectively. Some other services make clients specify
+the response content type in a parameter like
+"example.com/collection/resource<b>?format=xml</b>". Depending on how
+advanced your client applications are, this may be all you need.
+However, this could lead to long URLs as clients need to add in
+information like encoding, language, character sets, etc. (i.e. some URL
+like
+"example.com/collection/resource?format=xml&amp;lang=en&amp;encoding=gzip&amp;charset=UTF-8").
+The client application developer would also have to know all of the
+possible parameters.</p>
+
+</div>
+
+
+<div class="section">
+<h3 class="sectiontitle">Content Negotiation with HTTP Headers</h3>
+
+<p>Instead of hardcoding URLs with content representation
+information, you could create uniform URLs and put the content
+negotiation information in the HTTP request headers. So in essence, on
+the HTTP request, a client can use a single URL (i.e.
+"example.com/collection/resource") but add an Accept: HTTP header and
+specify that the client prefers application/json and then text/xml (or
+vice versa). Using HTTP's built-in content negotiation methods reduces
+the possible URLs and uses standard HTTP headers which are uniform
+across services (if services choose to acknowledge them).</p>
+
+<p>In clients, complexity can be reduced. For instance, if
+collections only have to list one URL for each resource (as opposed to
+one URL for each resource in each data format), then there are potential
+savings in bandwidth and processing time. A client would find a single
+URL for a resource, add in a few standard HTTP headers, and then issue
+the request. There would be no need for additional path or query
+parameters.</p>
+
+<p>There are potential hazards to using HTTP headers for content
+negotiation. While most proxies and caches respect HTTP headers, a few
+implementations may not do what is expected. Clients must also be able
+to set HTTP headers. The vast majority of clients can set HTTP headers
+(including JavaScript libraries). Finally, client application developers
+must understand what HTTP headers they can set for the request.</p>
+
+<p>The rest of this document explains how to implement content
+negotiation in the JAX-RS server-side service.</p>
+
+</div>
+
+<h2 class="topictitle1">The Sample</h2>
+
+<div class="section">
+<h3 class="sectiontitle">Data Formats</h3>
+
+<p>This sample will support <a href="http://json.org/">JSON</a>,
+XML, and plain text. The data is a simple score between two teams.
+Examples of each format are given:</p>
+
+<h4>JSON</h4>
+<table border="0" width="100%">
+	<tbody>
+		<tr>
+			<td class="code-outline">
+			<div><pre><code>{
+"homeTeam" : "Blue Team",
+"homeScore" : 1,
+"visitorTeam" : "Red Team",
+"visitorScore" : 2
+}</code></pre></div>
+			</td>
+		</tr>
+	</tbody>
+</table>
+
+<h4>XML</h4>
+<table border="0" width="100%">
+	<tbody>
+		<tr>
+			<td class="code-outline">
+			<div><pre><code>&lt;score&gt;
+&lt;homeTeam&gt;Blue Team&lt;/homeTeam&gt;
+&lt;homeScore&gt;1&lt;/homeScore&gt;
+&lt;visitorTeam&gt;Red Team&lt;/visitorTeam&gt;
+&lt;visitorScore&gt;2&lt;/visitorScore&gt;
+&lt;/score&gt;</code></pre></div>
+			</td>
+		</tr>
+	</tbody>
+</table>
+
+
+<h4>Text Plain</h4>
+<table border="0" width="100%">
+	<tbody>
+		<tr>
+			<td class="code-outline">
+			<div><pre><code>Home Team: Blue Team ; Home Score: 1 ; Visitor Team: Red Team ; Visitor Score: 2</code></pre></div>
+			</td>
+		</tr>
+	</tbody>
+</table>
+
+</div>
+
+
+<div class="section">
+<h3 class="sectiontitle">Hardcoded URLs with Multiple Methods</h3>
+
+<p>A simple way to support multiple content types is via the
+hardcoded URLs mentioned earlier and the following code snippet
+illustrates one way to do that.</p>
+
+<p>Visiting http://&lt;your host&lt;/&lt;context
+root&gt;/multiplemethods/score/1234.json would return a JSON
+representation of the resource. Visiting http://&lt;your
+host&lt;/&lt;context root&gt;/multiplemethods/score/1234.xml would
+return a XML representation of the resource. Finally, visiting
+http://&lt;your host&lt;/&lt;context
+root&gt;/multiplemethods/score/1234.text would return a text
+representation of the resource.</p>
+
+<table border="0" width="100%">
+	<tbody>
+		<tr>
+			<td class="code-outline">
+			<div><pre><code>@GET
+@Path("multiplemethods/score/{gamenum}.json")
+@Produces("application/json")
+public Response processRequestWithJSON(@PathParam("gamenum") String gameNum) {
+	Score s = Scoreboard.getScoreForGame(gameNum);
+	JSONObject jsonObj = new JSONObject();
+	jsonObj.put("homeTeam", s.getHomeTeam());
+	jsonObj.put("homeScore", s.getHomeScore());
+	jsonObj.put("visitorTeam", s.getVisitorTeam());
+	jsonObj.put("visitorScore", s.getVisitorScore());
+	return Response.ok(jsonObj).build();
+}
+
+@GET
+@Path("multiplemethods/score/{gamenum}.xml")
+@Produces("text/xml")
+public Response processRequestWithXML(@PathParam("gamenum") String gameNum) {
+	Score s = Scoreboard.getScoreForGame(gameNum);
+	/* Score is a JAXB annotated class so can return directly */
+	return Response.ok(s).build();
+}
+
+@GET
+@Path("multiplemethods/score/{gamenum}.text")
+@Produces("text/plain")
+public Response processRequestWithText(@PathParam("gamenum") String gameNum) {
+	Score s = Scoreboard.getScoreForGame(gameNum);
+	String entity = "Home Team: " + s.getHomeTeam() + " ; Home Score: " + s.getHomeScore() + " ; Visitor Team: " + s.getVisitorTeam() + " ; Visitor Score: " + s.getVisitorScore();
+	return Response.ok(entity).build();
+}</code></pre></div>
+			</td>
+		</tr>
+	</tbody>
+</table>
+</div>
+
+
+<div class="section">
+<h3 class="sectiontitle">Hardcoded URLs with a Single Method</h3>
+
+<p>Now let's try to use one method to process all of the requests.
+The only functional difference in the snippet is that "multiplemethods"
+above in the URL paths is replaced with "singlemethod" in the code
+snippet below.</p>
+
+<table border="0" width="100%">
+	<tbody>
+		<tr>
+			<td class="code-outline">
+			<div><pre><code>@GET
+@Path("singlemethod/score/{gamenum}.{type}")
+public Response processRequest(@PathParam("gamenum") String gameNum, @PathParam("type") String type) {
+	Score s = Scoreboard.getScoreForGame(gameNum);
+	if ("json".equals(type)) {
+        JSONObject jsonObj = new JSONObject();
+       	jsonObj.put("homeTeam", s.getHomeTeam());
+		jsonObj.put("homeScore", s.getHomeScore());
+		jsonObj.put("visitorTeam", s.getVisitorTeam());
+		jsonObj.put("visitorScore", s.getVisitorScore());
+		return Response.ok(jsonObj).type(MediaType.APPLICATION_JSON).build();
+	} else if ("xml".equals(type)) {
+		/* Score is a JAXB annotated class so can return directly */
+		return Response.ok(s).type("text/xml").build();
+	} else if ("text".equals(type)) {
+		String entity = "Home Team: " + s.getHomeTeam() + " ; Home Score: " + s.getHomeScore()
+			+ " ; Visitor Team: " + s.getVisitorTeam() + " ; Visitor Score: "
+			+ s.getVisitorScore();
+		return Response.ok(entity).type(MediaType.TEXT_PLAIN_TYPE).build();
+	} else {
+		/* return a HTTP status code */
+		return Response.status(406).build();
+	}
+}</code></pre></div>
+			</td>
+		</tr>
+	</tbody>
+</table>
+</div>
+
+
+<div class="section">
+<h3 class="sectiontitle">HTTP Accept Header</h3>
+
+<p>Instead of adding the ".{type}" to the URL in the above code
+snippets, let's use the HTTP Accept header for content negotiation. The
+HTTP Accept request header allows the client to specify what media type
+(aka data format) the response should be in. For instance, if the client
+adds <b>Accept: application/json</b> to the HTTP request, then the
+client is telling the server that it would only like to receive the
+response in JSON format. If the client instead had <b>Accept:
+text/xml</b>, then the client would only accept XML as the response.</p>
+
+<p>The Accept header could specify multiple media types to indicate
+that the client is willing to receive content in any of the media types
+specified. For example, <b>Accept: application/json, text/xml</b> would
+indicate that both JSON and XML are acceptable representations. Note
+that you get only one actual representation back, so the response entity
+would only be in JSON <b>or</b> XML; the client would not receive the
+same content in multiple formats.</p>
+
+<p>Clients can also add a quality factor parameter to the media
+type. This allows clients to specify that they would accept any single
+format from a list of multiple data types but in a particular preference
+order. For example, <b>Accept: application/json; q=0.4,
+text/xml;q=0.9</b> indicates that XML is preferred but JSON is acceptable as
+well if XML is not available.</p>
+
+<p>See the <a
+	href="http://www.w3.org/Protocols/rfc2616/rfc2616.html">HTTP
+specification</a> for the full details on the Accept header.</p>
+</div>
+
+
+<div class="section">
+<h3 class="sectiontitle">@Context javax.ws.rs.core.HttpHeaders
+interface</h3>
+
+<p>The Accept header is fairly powerful in that it allows clients to
+not only let the server know multiple response media types are
+acceptable but a preferred ordering. However, this could lead to a lot
+of code that just tries to process the request Accept header. JAX-RS
+implementations must provide a <b>javax.ws.rs.core.HttpHeaders</b>
+injectable object which allows developers to retrieve a pre-sorted list
+of acceptable responses.</p>
+
+<p>javax.ws.rs.core.HttpHeaders objects are injected by the JAX-RS
+runtime. Annotate the HttpHeaders type with @javax.ws.rs.core.Context as
+shown in the following code snippet.</p>
+
+<table border="0" width="100%">
+	<tbody>
+		<tr>
+			<td class="code-outline">
+			<div><pre><code>@GET
+@Path("httpheader/score/{gamenum}")
+@Produces(value={"application/json", "application/xml", "text/xml", "text/plain"})
+public Response processRequestWithHTTPHeaders(@PathParam("gamenum") String gameNum, @Context HttpHeaders headers) {
+	Score s = Scoreboard.getScoreForGame(gameNum);
+	
+	List&lt;MediaType&gt; acceptableMediaTypes = headers.getAcceptableMediaTypes();
+	for (MediaType responseMediaType : acceptableMediaTypes) {
+		if(MediaType.APPLICATION_JSON_TYPE.isCompatible(responseMediaType)) {
+			JSONObject jsonObj = new JSONObject();
+			jsonObj.put("homeTeam", s.getHomeTeam());
+			jsonObj.put("homeScore", s.getHomeScore());
+			jsonObj.put("visitorTeam", s.getVisitorTeam());
+			jsonObj.put("visitorScore", s.getVisitorScore());
+			return Response.ok(jsonObj).type("application/json").build();
+		} else if (MediaType.TEXT_XML_TYPE.isCompatible(responseMediaType)
+			|| MediaType.APPLICATION_XML_TYPE.isCompatible(responseMediaType)) {
+			/* Score is a JAXB annotated class so can return directly */
+			return Response.ok(s).type(responseMediaType).build();
+		} else if (MediaType.TEXT_PLAIN_TYPE.isCompatible(responseMediaType)) {
+			String entity = "Home Team: " + s.getHomeTeam() + " ; Home Score: " + s.getHomeScore() + " ; Visitor Team: " + s.getVisitorTeam() + " ; Visitor Score: " + s.getVisitorScore();
+			return Response.ok(entity).type("text/plain").build();
+		}
+	}
+	
+	/* return a HTTP status code */
+	return Response.status(406).build();
+}</code></pre></div>
+			</td>
+		</tr>
+	</tbody>
+</table>
+
+<p>Developers can also get any other request HTTP header from the
+HttpHeaders object.</p>
+</div>
+
+
+<div class="section">
+<h3 class="sectiontitle">@Context javax.ws.rs.core.Request
+interface</h3>
+
+<p>An alternative to using the HttpHeaders is to use the injectable
+<b>javax.ws.rs.core.Request</b> interface. JAX-RS provides <b>javax.ws.rs.core.Request#selectVariant(java.util.List<Variant>
+variants)</b> for determining what media type, language, and encoding to use
+in the response.</p>
+
+<p>javax.ws.rs.core.Request objects are injected by the JAX-RS
+runtime just like the HttpHeaders.</p>
+
+<p>The following snippet builds a list of possible response
+variations and then uses the injected Request object to select the best
+representation.</p>
+
+<table border="0" width="100%">
+	<tbody>
+		<tr>
+			<td class="code-outline">
+			<div><pre><code>@GET
+@Path("acceptheader/score/{gamenum}")
+@Produces(value = {"application/json", "application/xml", "text/xml", "text/plain" })
+public Response processRequest(@PathParam("gamenum") String gameNum, @Context Request requestObj) {
+	Score s = Scoreboard.getScoreForGame(gameNum);
+	
+	/* build a list of possible response representation variants */
+	/* in this case, only the media types are uesd */
+	List&lt;Variant&gt; possibleVariants = Variant.mediaTypes(MediaType.APPLICATION_JSON_TYPE, MediaType.TEXT_XML_TYPE, MediaType.TEXT_PLAIN_TYPE).add().build();
+	
+	/* select the best matching variant based on the request HTTP headers */
+	Variant responseVariant = requestObj.selectVariant(possibleVariants);
+
+	/* get the media type that the JAX-RS runtime believes is the best possible variant */
+	MediaType responseMediaType = responseVariant.getMediaType();
+	Locale responseLocale = responseVariant.getLanguage();
+	
+	/* ...there would be some code to get a Locale specific translation... */
+	String homeTeamTranslated = s.getHomeTeam(responseLocale);
+	String visitorTeamTranslated = s.getVisitorTeam(responseLocale);
+	
+	if(MediaType.APPLICATION_JSON_TYPE.isCompatible(responseMediaType)) {
+		JSONObject jsonObj = new JSONObject();
+		jsonObj.put("homeTeam", homeTeamTranslated);
+		jsonObj.put("homeScore", s.getHomeScore());
+		jsonObj.put("visitorTeam", visitorTeamTranslated);
+		jsonObj.put("visitorScore", s.getVisitorScore());
+		return Response.ok(jsonObj).build();
+	} else if (MediaType.TEXT_XML_TYPE.isCompatible(responseMediaType)
+		|| MediaType.APPLICATION_XML_TYPE.isCompatible(responseMediaType)) {
+		/* Score is a JAXB annotated class so can be return directly */
+		return Response.ok(s).type(responseMediaType).build();
+	} else if (MediaType.TEXT_PLAIN_TYPE.isCompatible(responseMediaType)) {
+		String entity = "Home Team: " + homeTeamTranslated + " ; Home Score: " + s.getHomeScore() + " ; Visitor Team: " + visitorTeamTranslated + " ; Visitor Score: " + s.getVisitorScore();
+		return Response.ok(entity).build();
+	}
+	
+	/*
+     * the Request object should return the best response type among the 3
+	 * given so the following code should never execute
+	 */
+	return Response.serverError().build();
+}</code></pre></div>
+			</td>
+		</tr>
+	</tbody>
+</table>
+
+<p>The list of possible variants can also include language and
+encoding permutations. Use the
+javax.ws.rs.core.Variant.VariantListBuilder to build up the possible
+list.</p>
+
+<p>It should be noted that each JAX-RS runtime may produce different
+results depending on how the method is implemented (i.e. some may value
+the Accept-Language header more than the Accept header or vice versa).</p>
+</div>
+
+
+<div class="section">
+<h3 class="sectiontitle">Apache HTTP Client Using Accept Headers</h3>
+
+<p><a href="http://hc.apache.org/">Apache HTTP client</a> can easily
+add request headers. This sample is with Apache HTTP Client 3.1.</p>
+
+<table border="0" width="100%">
+	<tbody>
+		<tr>
+			<td class="code-outline">
+			<div><pre><code>HttpClient client = new HttpClient();
+
+GetMethod getMethod = new GetMethod("http://example.com/path/to/resource");
+
+/* set the Accept request header preferring xml over json */
+getMethod.setRequestHeader("Accept", "application/json; q=0.5, text/xml;q=0.8");
+        
+client.executeMethod(getMethod);
+        
+/* print the content */
+System.out.println(getMethod.getResponseBodyAsString());</code></pre></div>
+			</td>
+		</tr>
+	</tbody>
+</table>
+</div>
+
+
+
+<div class="section">
+<h3 class="sectiontitle">Dojo AJAX HTTP Request Using Accept
+Headers</h3>
+
+<p><a href="http://wwww.dojotoolkit.org/">Dojo</a> JavaScript
+library AJAX requests can also incorporate HTTP headers by setting a
+headers property. Dojo does use the handleAs property so you may have to
+directly access the XmlHttpRequest object and check the Response
+Content-Type header to determine what format was actually returned.</p>
+
+<table border="0" width="100%">
+	<tbody>
+		<tr>
+			<td class="code-outline">
+			<div><pre><code>
+var requestHeaders = {
+	"Accept" : "text/xml;q=0.8, application/json;q=0.2"
+};
+			
+dojo.xhrGet( {
+	url: "http://example.com/path/to/resource",
+	handleAs: "text",
+	headers: requestHeaders, 
+	load: function(data, ioArgs) {
+		/* process response */
+	},
+	error: function(data, ioArgs) {
+		/* got error */
+	}
+});</code></pre></div>
+			</td>
+		</tr>
+	</tbody>
+</table>
+
+
+</div>
+
+
+
+<div class="section">
+<h3 class="sectiontitle">Conclusion</h3>
+
+<p>Content negotiation can be done by invoking different URLs, using
+parameters in the URL, or using HTTP headers. Each have their advantages
+and disadvantages.</p>
+
+</div>
+
+
+
+
+</div>
+
+<iframe src="../../footer.html" scrolling="no" frameborder="0"
+	style="width: 100%;"><a href="../../footer.html">Hmm, you are
+using a very old browser. Click here to go directly to included content.</a></iframe>
+</body>
+</html>

Added: incubator/wink/contrib/ibm-jaxrs/resources/docs/site/en/samples/guestbook/index.html
URL: http://svn.apache.org/viewvc/incubator/wink/contrib/ibm-jaxrs/resources/docs/site/en/samples/guestbook/index.html?rev=787550&view=auto
==============================================================================
--- incubator/wink/contrib/ibm-jaxrs/resources/docs/site/en/samples/guestbook/index.html (added)
+++ incubator/wink/contrib/ibm-jaxrs/resources/docs/site/en/samples/guestbook/index.html Tue Jun 23 05:30:05 2009
@@ -0,0 +1,337 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
+<meta name="copyright" content="IBM Corporation 2008" />
+<meta name="DC.Rights.Owner" content="IBM Corporation 2008" />
+<!-- All rights reserved. Licensed Materials Property of IBM -->
+<!-- US Government Users Restricted Rights -->
+<!-- Use, duplication or disclosure restricted by -->
+<!-- GSA ADP Schedule Contract with IBM Corp. -->
+
+<link rel="stylesheet" href="../../book.css" type="text/css">
+<link rel="stylesheet" href="../../../siteonly/site.css" type="text/css">
+<title>IBM JAX-RS: Guestbook Sample</title>
+</head>
+
+<body>
+<!-- Header information -->
+<iframe src="../../header.html" scrolling="no" frameborder="0"
+	style="width: 100%; height: 75px;"><a href="../../header.html">Hmm,
+you are using a very old browser. Click here to go directly to included
+content.</a></iframe>
+
+<h2 align="center">Guestbook Sample Application Guide</h2>
+<h4 align="center">Version 1.0.0</h4>
+
+<h2 class="topictitle1">Overview</h2>
+
+<div>
+<p>The Guestbook sample demonstrates some scenarios for the handling
+of bad conditions, exceptions, and errors.</p>
+
+<p>The sample is based on early Internet guestbooks where visitors
+leave new comments, update or delete old comments, or retrieve a list of
+comments. The comments are stored in an in-memory data store.</p>
+
+<p>This sample is only for illustrative purposes and is not intended
+to be a starting point for a real guestbook.</p>
+</div>
+
+<div class="section">
+<h3 class="sectiontitle">URI Overview</h3>
+
+<div>
+<div class="tableborder">
+<table cellspacing="0" cellpadding="4" frame="border" border="1"
+	rules="all">
+	<caption>Table 1. URI Overview</caption>
+	<thead>
+		<tr>
+			<th>HTTP Method</th>
+			<th>URI</th>
+			<th>Input Type(s)</th>
+			<th>Output Type(s)</th>
+			<th>Note(s)</th>
+		</tr>
+	</thead>
+	<tbody>
+		<tr>
+			<td>GET</td>
+			<td>/guestbook/{id}</td>
+			<td>n/a</td>
+			<td>text/xml</td>
+			<td>Sets HTTP status code</td>
+		</tr>
+		<tr>
+			<td>POST</td>
+			<td>/guestbook</td>
+			<td>text/xml</td>
+			<td>text/xml</td>
+			<td>Throws javax.ws.rs.WebApplicationException</td>
+		</tr>
+		<tr>
+			<td>DELETE</td>
+			<td>/guestbook/{id}</td>
+			<td>n/a</td>
+			<td>n/a</td>
+			<td>Throws RuntimeException</td>
+		</tr>
+		<tr>
+			<td>PUT</td>
+			<td>/guestbook/{id}</td>
+			<td>text/xml</td>
+			<td>text/xml</td>
+			<td>Throws checked exception</td>
+		</tr>
+	</tbody>
+</table>
+</div>
+</div>
+</div>
+
+<div class="section">
+<h3 class="sectiontitle">HTTP Status Codes</h3>
+
+<p>Most RESTful web services use standard <a
+	href="http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html">HTTP
+status codes</a> to some degree. You can set the status code in a <b>javax.ws.rs.core.Response</b>
+by calling its <b>status</b> method.</p>
+
+<p>A simple HTTP GET method for retrieving a new message is
+displayed below. In the code example below, an infamous HTTP 404 status
+code is set if the comment with a given message ID does not exist. A
+normal HTTP 200 OK status and response entity are set if the message is
+found using one of Response's convienence methods.</p>
+
+<table border="0" width="100%">
+	<tbody>
+		<tr>
+			<td class="code-outline">
+			<div><pre><code>@GET
+@Path("{id}")
+@Produces("text/xml")
+public Response readComment(@PathParam("id") String commentId) {
+    Comment msg = GuestbookDatabase.getGuestbook().getComment(Integer.valueOf(commentId));
+    if (msg == null) {
+        return Response.status(404).build();
+    }
+
+    return Response.ok(msg).build();
+}</code></pre></div>
+			</td>
+		</tr>
+	</tbody>
+</table>
+</div>
+
+<div class="section">
+<h3 class="sectiontitle">javax.ws.rs.WebApplicationException</h3>
+<p>Before talking about regular Java exceptions and errors, JAX-RS
+introduces the <b>javax.ws.rs.WebApplicationException</b>. It provides
+an easy way to throw an exception with a status code or a whole <b>javax.ws.rs.core.Response</b>.
+The status code or Response can be used by the runtime to construct a
+more usable end-user response. WebApplicationException is useful when
+you want to give a custom response but do not want to add a new checked
+exception to your method signature.</p>
+
+<p>A HTTP POST method for creating a new message is given below.</p>
+
+<p>A HTTP 400 status code is set if the POST requester did not send
+a comment to store via a WebApplicationException.</p>
+
+<p>If an ID, message, or an author are not set in the comment
+request data, then a custom HTTP 400 status Response with an entity is
+constructed. The Response is then passed to a WebApplicationException
+which itself is thrown. By default, the JAX-RS runtime will use the
+Response to return the client response.</p>
+
+<table border="0" width="100%">
+	<tbody>
+		<tr>
+			<td class="code-outline">
+			<div><pre><code>@POST
+@Produces("text/xml")
+@Consumes("text/xml")
+public Response createComment(Comment aComment, @Context UriInfo uriInfo) {
+    /*  
+     * If no comment data was sent, then return a bad request.
+     */
+    if (aComment == null) {
+        throw new WebApplicationException(Response.Status.BAD_REQUEST);
+    }
+
+    if (aComment.getId() == null || aComment.getMessage() == null
+        || aComment.getAuthor() == null) {
+        CommentError commentError = new CommentError();
+        commentError.setErrorMessage("Please include a comment ID, a message, and your name.");
+        Response resp = Response.status(Response.Status.BAD_REQUEST).entity(commentError)
+            .build();
+        throw new WebApplicationException(resp);
+    }
+
+    GuestbookDatabase.getGuestbook().storeComment(aComment);
+    try {
+        return Response.created(new URI(uriInfo.getAbsolutePath() + "/" + aComment.getId()))
+            .entity(aComment).build();
+    } catch (URISyntaxException e) {
+        e.printStackTrace();
+        throw new WebApplicationException(e);
+    }
+}</code></pre></div>
+			</td>
+		</tr>
+	</tbody>
+</table>
+</div>
+
+<div class="section">
+<h3 class="sectiontitle">Runtime Exceptions, Errors, Checked
+Exceptions, and other Throwables</h3>
+
+<p>In a real application, you cannot wrap every exception in a
+WebApplicationException. In JAX-RS, runtime exceptions and errors
+propagate to the container. Checked exceptions and other throwables are
+wrapped in a container specific exception, and then the container
+exception is thrown. By allowing the exceptions to be thrown to the
+container, then the container's regular exception handling is used (e.g.
+servlet error pages).</p>
+
+<p>Here is a HTTP DELETE resource method that shows a possible
+runtime exception:</p>
+
+<table border="0" width="100%">
+	<tbody>
+		<tr>
+			<td class="code-outline">
+			<div><pre><code>@DELETE
+@Path("{id}")
+@Produces("text/xml")
+public Response deleteComment(@PathParam("id") String commentId) {
+    GuestbookDatabase.getGuestbook().deleteComment(Integer.valueOf(commentId));
+    return Response.noContent().build();
+}</code></pre></div>
+			</td>
+		</tr>
+	</tbody>
+</table>
+
+<p>In the above snippet, if the path parameter "commentId" is not an
+integer, then a NumberFormatException is thrown from Integer.valueOf().
+The runtime exception would be thrown to the container.</p>
+
+<p>Here is a HTTP PUT method that shows a possible checked
+exception:</p>
+
+<table border="0" width="100%">
+	<tbody>
+		<tr>
+			<td class="code-outline">
+			<div><pre><code>@PUT
+@Path("{id}")
+@Produces("text/xml")
+@Consumes("text/xml")
+public Response updateComment(Comment aComment, @PathParam("id") String commentId)
+    throws GuestbookException {
+    if (aComment.getId() == null || !Integer.valueOf(commentId).equals(aComment.getId())) {
+        throw new GuestbookException("Unexpected ID.");
+    }
+
+    Comment existingComment = GuestbookDatabase.getGuestbook().getComment(
+        Integer.valueOf(commentId));
+    if (existingComment == null) {
+        throw new GuestbookException("Cannot find existing comment to update.");
+    }
+    GuestbookDatabase.getGuestbook().storeComment(aComment);
+    return Response.ok(aComment).build();
+}</code></pre></div>
+			</td>
+		</tr>
+	</tbody>
+</table>
+
+
+<p>GuestbookException is an application defined checked Java
+exception. There are many conditions where it is thrown. If the checked
+exception is thrown, then it is wrapped in a container-specific
+exception (such as a ServletException) and then re-thrown to the
+container.</p>
+
+</div>
+
+
+<div class="section">
+<h3 class="sectiontitle">ExceptionMapper</h3>
+
+<p>Allowing exceptions to be thrown to the container may be all you
+need but sometimes you may want to give a custom response. In the above
+HTTP PUT method, the request data could not include the Comment. The <b>aComment.getId()</b>
+call would result in a NullPointerException if "aComment" is null.</p>
+
+<p>An javax.ws.rs.ext.ExceptionMapper&lt;T&gt; allows the JAX-RS
+runtime to catch any java.lang.Throwable and map it to a JAX-RS
+Response. You could do additional tasks as well such as logging the
+exception in the ExceptionMapper.</p>
+
+<p>Here is an example of an ExceptionMapper for
+NullPointerException:</p>
+
+<table border="0" width="100%">
+	<tbody>
+		<tr>
+			<td class="code-outline">
+			<div><pre><code>package com.ibm.rest.sample.guestbook;
+
+import javax.ws.rs.core.Response;
+import javax.ws.rs.ext.ExceptionMapper;
+import javax.ws.rs.ext.Provider;
+
+@Provider
+public class NullPointerExceptionMapper implements ExceptionMapper&lt;NullPointerException&gt; {
+
+    public Response toResponse(NullPointerException arg0) {
+        CommentError commentError = new CommentError();
+        commentError.setErrorMessage("Someone forgot a null check.");
+        return Response.serverError().entity(commentError).build();
+    }
+
+}</code></pre></div>
+			</td>
+		</tr>
+	</tbody>
+</table>
+
+<p>Whenever a NullPointerException is thrown, the JAX-RS runtime
+will use the above ExceptionMapper to create a Response. The Response
+would then be used in normal processing.</p>
+
+<p>To create an ExceptionMapper:</p>
+
+<ol>
+	<li>Implement the ExceptionMapper&lt;T&gt; interface where T is
+	the type of exception to map.</li>
+	<li>Add the @javax.ws.rs.ext.Provider annotation on the provider
+	class.</li>
+	<li>Add the provider class to the set of classes returned in your
+	javax.ws.rs.core.Application's getClasses() or getSingletons() method.</li>
+</ol>
+
+<p>ExceptionMappers are chosen based on the generic type T. The
+closest matching ExceptionMapper type to the thrown exception type is
+used.</p>
+
+<p>For instance, suppose there were separate
+ExceptionMapper&lt;RuntimeException&gt; and an
+ExceptionMapper&lt;NullPointerException&gt; providers. If a
+NullPointerException or any of its subclasses was thrown in the
+application, the ExceptionMapper&lt;NullPointerException&gt; would be
+used. If any other RuntimeException is thrown, the
+ExceptionMapper&lt;RuntimeException&gt; would be used.</p>
+
+</div>
+
+<iframe src="../../footer.html" scrolling="no" frameborder="0"
+	style="width: 100%;"><a href="../../footer.html">Hmm, you are
+using a very old browser. Click here to go directly to included content.</a></iframe>
+</body>
+</html>

Added: incubator/wink/contrib/ibm-jaxrs/resources/docs/site/en/samples/providers/index.html
URL: http://svn.apache.org/viewvc/incubator/wink/contrib/ibm-jaxrs/resources/docs/site/en/samples/providers/index.html?rev=787550&view=auto
==============================================================================
--- incubator/wink/contrib/ibm-jaxrs/resources/docs/site/en/samples/providers/index.html (added)
+++ incubator/wink/contrib/ibm-jaxrs/resources/docs/site/en/samples/providers/index.html Tue Jun 23 05:30:05 2009
@@ -0,0 +1,416 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
+<meta name="copyright" content="IBM Corporation 2008" />
+<meta name="DC.Rights.Owner" content="IBM Corporation 2008" />
+<!-- All rights reserved. Licensed Materials Property of IBM -->
+<!-- US Government Users Restricted Rights -->
+<!-- Use, duplication or disclosure restricted by -->
+<!-- GSA ADP Schedule Contract with IBM Corp. -->
+
+<link rel="stylesheet" href="../../book.css" type="text/css">
+<link rel="stylesheet" href="../../../siteonly/site.css" type="text/css">
+<title>IBM JAX-RS: Providers Sample</title>
+</head>
+
+<body>
+<!-- Header information -->
+<iframe src="../../header.html" scrolling="no" frameborder="0"
+	style="width: 100%; height: 75px;"><a href="../../header.html">Hmm,
+you are using a very old browser. Click here to go directly to included
+content.</a></iframe>
+
+<h2 align="center">Providers Sample Application Guide</h2>
+<h4 align="center">Version 1.0.0</h4>
+
+<h2 class="topictitle1">Overview</h2>
+
+<div>
+<p>The Providers Sample demonstrates how to create custom MessageBodyReaders
+and MessageBodyWriters to support additional media types not supported by default
+by the IBM JAX-RS runtime.</p>
+
+<p>Before looking at this sample specifically, we'll take a look at the API which
+allow the JAX-RS runtime to be extended to support various media types.</p>
+
+<p>We'll then examine the components of the Providers Sample to demonstrate how
+to extend the JAX-RS runtime in this manner.</p>
+</div>
+
+<div class="section">
+<h3 class="sectiontitle">JAX-RS Entity Providers</h3>
+
+<p>In JAX-RS, entity providers provide mappings between represenations and their Java types.
+When a request is made to a resource implementation, entity providers are used to
+marshall/unmarshall the message body to and from the corresponding Java type.</p>
+
+<p>There are two type of providers, <b>MessageBodyReaders</b> and <b>MessageBodyWriters</b>.
+Both interfaces can be implemented to create custom providers for any media type.
+Extending the runtime in this manner is the focus of this sample.</p>
+
+<p>Implementations implement the MessgeBodyReader and/or MessageBodyWriter interfaces
+and are annotatd with the @Provider annotation.</p>
+</div>
+
+<div class="section">
+<h3 class="sectiontitle">javax.ws.rs.ext.MessageBodyReader&lt;T&gt;</h3>
+
+<p>MessageBodyReader implentations are used to unmarshall represenations to a Java type.
+The following methods define the interface:</p>
+
+<table border="0" width="100%">
+	<tbody>
+		<tr>
+			<td class="code-outline">
+			<div><pre><code>boolean isReadable(java.lang.Class<?> type, 
+		java.lang.reflect.Type genericType,
+		java.lang.annotation.Annotation[] annotations,
+		MediaType mediaType);
+			
+T readFrom(java.lang.Class<T> type,
+		java.lang.reflect.Type genericType,
+		java.lang.annotation.Annotation[] annotations,
+		MediaType mediaType,
+		MultivaluedMap<java.lang.String,java.lang.String> httpHeaders,
+		java.io.InputStream entityStream);
+			</code></pre></div>
+			</td>
+		</tr>
+	</tbody>
+</table>
+
+<p>The <b>isReadable</b> method determines if the reader is able to process the message body.</p>
+
+<p>The <b>readFrom</b> method does the work to convert the message body to the corresponding Java
+type T via the provided InputStream.</p>
+</div>
+
+<div class="section">
+<h3 class="sectiontitle">javax.ws.rs.ext.MessageBodyWriter&lt;T&gt;</h3>
+
+<p>MessageBodyWriter implementations are used to marshall Java Objects to a representation
+which is put on the response message body. The following methods define the interface:</p>
+
+<table border="0" width="100%">
+	<tbody>
+		<tr>
+			<td class="code-outline">
+			<div><pre><code>getSize(T t, java.lang.Class<?> type,
+		java.lang.reflect.Type genericType,
+		java.lang.annotation.Annotation[] annotations,
+		MediaType mediaType);
+			
+isWriteable(java.lang.Class<?> type,
+		java.lang.reflect.Type genericType,
+		java.lang.annotation.Annotation[] annotations,
+		MediaType mediaType);
+		
+writeTo(T t, java.lang.Class<?> type,
+		java.lang.reflect.Type genericType,
+		java.lang.annotation.Annotation[] annotations,
+		MediaType mediaType,
+		MultivaluedMap<java.lang.String,java.lang.Object> httpHeaders,
+		java.io.OutputStream entityStream);
+			</code></pre></div>
+			</td>
+		</tr>
+	</tbody>
+</table>
+
+<p>The <b>getSize</b> method determines the number of bytes to be written to the provided OutputStream in the writeTo method.</p>
+
+<p>The <b>isWriteable</b> method determines whether or not the writer is able to process the Java type
+and convert an instance to the corresponding representation.</p>
+
+<p>The <b>writeTo</b> method does the work to convert the Java Object of type T to
+the representation that is put on the response message body via the provided OutputStream.</p>
+</div>
+
+<div class="section">
+<h3 class="sectiontitle">MessageBodyReader/MessageBodyWriter Annotations</h3>
+
+<p>As mentioned earlier, entity provider implementations must be annotated with the <b>@Provider</b> annotation.
+Additionally the <b>@Consumes</b> and <b>@Produces</b> annotations can be used to explicitly declare a supported
+media type(s) and to more efficiently determine if a provider implementation should be used.</p>
+
+<p>MessageBodyReaders annotated with the <b>@Consumes</b> annotation will allow the runtime to quickly
+eliminate candidate providers based on the annotation value. For example, if the annotation
+value on ReaderA is "text/xml", @Consumes(value="text/xml"), and the Content-Type header 
+value of an incoming request is "text/plain," the runtime can immediately determine that
+ReaderA is not a candidate to unmarshall the message body on the request.</p>
+
+<p>Likewise, the <b>@Produces</b> annotation can be used to narrow the list of candidate MessageBodyWriters
+that can be used to marshall Java Objects for an outgoing response.</p>
+</div>
+
+<div class="section">
+<h3 class="sectiontitle">Declaring Custom Entity Providers to the Runtime</h3>
+<p>Before the runtime will process custom entity providers, they must be returned by an instance of <b>
+javax.ws.rs.core.Application</b>. The Application class returns resource and provider classes and instances
+for use within applications.</p>
+</div>
+
+<div class="section">
+<h3 class="sectiontitle">Provider Process Flow</h3>
+
+<p>Lastly, before we look at the Provider Sample implementations it helps to understand the process
+flow that takes place when a request is received and the repsonse is sent out, and where the
+entity providers are invoked in that process.</p>
+
+<ol>
+<li>A request is received from a client application.</li>
+<li>The JAX-RS runtime determines the resource class and method to invoke.</li>
+<li>A MessageBodyReader is selected based on the @Consumes annotation of the entity provider and resource method if present and the isReadable method.</li>
+<li>The readFrom method is invoked on the selected MessageBodyReader.</li>
+<li>The resource method is invoked.</li>
+<li>A MessageBodyWriter is selected based on the @Produces annotation of the entity provider and resource method if present and the isWritable method</li>
+<li>The writeTo method is invoked on the selected MessageBodyWriter.</li>
+<li>The response is sent out.</li>
+</ol>
+</div>
+
+
+<div class="section">
+<h3 class="sectiontitle">Providers Sample - integer/text, integer/int</h3>
+
+<p>In the Providers Sample, the runtime is being extended to support the
+<b>intger/text</b> and <b>integer/int</b> media types. These are not standard
+media types.</p>
+</div>
+
+<div class="section">
+<h3 class="sectiontitle">Providers Sample - IntegerResource.java</h3>
+
+<p>IntegerResource is a simple resource class that wraps an Integer Object.
+The root path for the resource class is /integer.</p>
+<table border="0" width="100%">
+	<tbody>
+		<tr>
+			<td class="code-outline">
+			<div><pre><code>@Path(value="/integer")
+public class IntegerResource {
+...
+...
+}</code></pre></div>
+			</td>
+		</tr>
+	</tbody>
+</table>
+
+<p>There are two primary resource methods to note. <b>getInteger</b> and <b>setInteger</b>
+are the GET and POST methods and produce/accept both the integer/text and integer/int media
+types.</p>
+<table border="0" width="100%">
+	<tbody>
+		<tr>
+			<td class="code-outline">
+			<div><pre><code>@POST
+@Consumes(value={"integer/int", "integer/text"})
+public void setInteger(Integer integer) {
+	IntegerResource.integer = integer;
+}
+
+@GET
+@Produces(value={"integer/int", "integer/text"})
+public Response getInteger() {
+	return Response.ok(IntegerResource.integer).build();
+}</code></pre></div>
+			</td>
+		</tr>
+	</tbody>
+</table>
+</div>
+
+<div class="section">
+<h3 class="sectiontitle">Providers Sample - IntegerTextProvider.java</h3>
+
+<p>IntegerTextProvider implements both the MessageBodyReader and MessageBodyWriter interfaces. It consumes
+and produces the integer/text media type. By implementing the reader and writer interfaces,
+the integer/text media type is now supported.</p>
+
+<table border="0" width="100%">
+	<tbody>
+		<tr>
+			<td class="code-outline">
+			<div><pre><code>@Provider
+@Consumes(value="integer/text")
+@Produces(value="integer/text")
+public class IntegerTextProvider implements MessageBodyReader&lt;Integer&gt;, MessageBodyWriter&lt;Integer&gt; {
+...
+...
+}</code></pre></div>
+			</td>
+		</tr>
+	</tbody>
+</table>
+
+<p>The isReadable method is implemented so that true is returned for the Integer type.</p>
+
+<table border="0" width="100%">
+	<tbody>
+		<tr>
+			<td class="code-outline">
+			<div><pre><code>public boolean isReadable(Class<?> type, Type genericType, Annotation[] annotations, MediaType mediaType) {
+	return type == Integer.class;
+}</code></pre></div>
+			</td>
+		</tr>
+	</tbody>
+</table>
+
+<p>When an @POST request is made to the IntegerResource.setInteger(Integer) method,
+the runtime must decide which MessageBodyReader will be used to unmarshall the Integer
+from the request body. Since IntegerTextProvider and IntegerIntProvider both implement
+the MessageBodyReader interface, and both have isReadable methods that return true
+for the Integer type, the Content-Type is used to determine that IntegerTextProvider
+should be used for the integer/text media type.</p>
+
+<p>The readFrom method is implemented to read the body and convert it to an Integer
+which is then passed to the setInteger method of the IntegerResource class.</p>
+
+<table border="0" width="100%">
+	<tbody>
+		<tr>
+			<td class="code-outline">
+			<div><pre><code>public Integer readFrom(Class<Integer> clazz, Type genericType, Annotation[] annotations, MediaType m, 
+		MultivaluedMap<String, String> headers, InputStream is) throws IOException {
+	System.out.println("Reading Integer as text.");
+	return Integer.parseInt(toString(is));
+}
+
+protected String toString(InputStream is) throws IOException {
+	int avail = is.available();
+
+	StringBuilder buf = new StringBuilder();
+	final byte[] buffer = new byte[avail];
+	int n = 0;
+	n = is.read(buffer);
+	while (-1 != n) {
+		buf.append(new String(buffer, 0, n, UTF8_CHARSET.name()));
+		n = is.read(buffer);
+	}
+	is.close();
+	return buf.toString();
+}</code></pre></div>
+			</td>
+		</tr>
+	</tbody>
+</table>
+
+<p>Like isReadable, isWritable is implemented so that true is returned for the Integer type.</p>
+
+<table border="0" width="100%">
+	<tbody>
+		<tr>
+			<td class="code-outline">
+			<div><pre><code>public boolean isWriteable(Class<?> type, Type genericType, Annotation[] annotations,
+            MediaType mediaType) {
+	return type == Integer.class;
+}</code></pre></div>
+			</td>
+		</tr>
+	</tbody>
+</table>
+
+<p>When an @GET request is made to the IntegerResource.getInteger() method,
+the runtime must decide which MessageBodyWriter will be used to marshall the Integer
+for the response. Since IntegerTextProvider and IntegerIntProvider both implement
+the MessageBodyWriter interface, and both have isWritable methods that return true
+for the Integer type, the Accpet header is used to determine that IntegerTextProvider
+should be used for the integer/text media type.</p>
+
+<p><b>NOTE:</b> If no Content-Type is specified on the request for a POST or no
+Accept is specified on the request for a GET, or if the media type is ambiguous
+(ex: */*), the runtime may choose any supporting implementation based on the
+isReadable and isWritable return values.</p>
+
+<p>The writeTo method is implemented to convert an Integer to a text String.</p>
+
+<table border="0" width="100%">
+	<tbody>
+		<tr>
+			<td class="code-outline">
+			<div><pre><code>public void writeTo(Integer obj, Class<?> clazz, Type genericType, Annotation[] annotations,  
+		MediaType m, MultivaluedMap&lt;String, Object&gt; headers, OutputStream os) throws IOException {
+	System.out.println("Writing Integer as text.");
+        
+	List&lt;Object&gt; list = new ArrayList&lt;Object&gt;();
+	list.add(m.toString());
+	headers.put("Content-Type", list);
+        
+	String s = obj.toString();
+	byte[] b = new byte[s.length()];
+	char[] c = s.toCharArray();
+	for(int i = 0; i < b.length; ++i)
+		b[i] = (byte)c[i];
+	os.write(b);
+	os.close();
+}</code></pre></div>
+			</td>
+		</tr>
+	</tbody>
+</table>
+</div>
+
+<div class="section">
+<h3 class="sectiontitle">Providers Sample - IntegerIntProvider.java</h3>
+
+<p>IntegerIntProvider is very similar to IntegerTextProvider except that it produces and consumes
+the integer/int media type. Rather than converting Strings to Integer and vice versa, the
+provider converts Integers to and from their binary representations. Implementing the
+reader and writer interfaces in this manner adds support for the integer/int media type.</p>
+
+<table border="0" width="100%">
+	<tbody>
+		<tr>
+			<td class="code-outline">
+			<div><pre><code>@Provider
+@Consumes(value="integer/int")
+@Produces(value="integer/int")
+public class IntegerIntProvider implements MessageBodyReader&lt;Integer&gt;, MessageBodyWriter&lt;Integer&gt; {
+...
+...
+}</code></pre></div>
+			</td>
+		</tr>
+	</tbody>
+</table>
+</div>
+
+<div class="section">
+<h3 class="sectiontitle">Providers Sample - ProvidersApplication.java</h3>
+<p>The ProvidersApplication class declares the sample resource and provider classes via the getClasses() and getSingletons() methods.
+In this case, the IntegerResource class is returned in getClasses() meaning it's scope is limited to single requests. The custom
+entity providers are returned via the getSingletons() method meaning a single instance is used to unmarshall/marshall data for all
+requests.</p>
+
+<table border="0" width="100%">
+	<tbody>
+		<tr>
+			<td class="code-outline">
+			<div><pre><code>@Override
+public Set&lt;Class&lt;?&gt;&gt; getClasses() {
+    Set&lt;Class&lt;?&gt;&gt; clazzes = new HashSet&lt;Class&lt;?&gt;&gt;();
+    clazzes.add(IntegerResource.class);
+    return clazzes;
+}
+
+@Override
+public Set&lt;Object&gt; getSingletons() {
+    Set&lt;Object&gt; singletons = new HashSet&lt;Object&gt;();
+    singletons.add(new IntegerIntProvider());
+    singletons.add(new IntegerTextProvider());
+    return singletons;
+}</code></pre></div>
+			</td>
+		</tr>
+	</tbody>
+</table>
+</div>
+
+<iframe src="../../footer.html" scrolling="no" frameborder="0"
+	style="width: 100%;"><a href="../../footer.html">Hmm, you are
+using a very old browser. Click here to go directly to included content.</a></iframe>
+</body>
+</html>



Mime
View raw message