Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse files

Merge pull request #181 from patriot1burke/master

docbook
  • Loading branch information...
commit d64a6f47e34f4b8ce8917f3e4c86e17aae3d414a 2 parents 410ec0d + 6dfa3f7
Bill Burke patriot1burke authored
Showing with 1,546 additions and 2,406 deletions.
  1. +119 −138 jaxrs/docbook/pom.xml
  2. 0  jaxrs/docbook/reference/en/{ → en-US}/master.xml
  3. 0  jaxrs/docbook/reference/en/{ → en-US}/modules/AJAX_Client.xml
  4. 0  jaxrs/docbook/reference/en/{ → en-US}/modules/Async_job_service.xml
  5. +69 −71 jaxrs/docbook/reference/en/{ → en-US}/modules/Asynchronous_HTTP.xml
  6. 0  jaxrs/docbook/reference/en/{ → en-US}/modules/Atom.xml
  7. 0  jaxrs/docbook/reference/en/{ → en-US}/modules/Authentication.xml
  8. 0  jaxrs/docbook/reference/en/{ → en-US}/modules/Books.xml
  9. 0  jaxrs/docbook/reference/en/{ → en-US}/modules/CDI.xml
  10. +165 −185 jaxrs/docbook/reference/en/{ → en-US}/modules/Cache_NoCache_CacheControl.xml
  11. 0  jaxrs/docbook/reference/en/{ → en-US}/modules/Configuring_Individual_JAX-RS_Resource_Beans.xml
  12. 0  jaxrs/docbook/reference/en/{ → en-US}/modules/Content_Marshalling_Providers.xml
  13. 0  jaxrs/docbook/reference/en/{ → en-US}/modules/ExceptionMappers.xml
  14. 0  jaxrs/docbook/reference/en/{ → en-US}/modules/Guice.xml
  15. 0  jaxrs/docbook/reference/en/{ → en-US}/modules/Installation_Configuration.xml
  16. +124 −0 jaxrs/docbook/reference/en/en-US/modules/Interceptors.xml
  17. 0  jaxrs/docbook/reference/en/{ → en-US}/modules/JAX-RS_Content_Negotiation.xml
  18. +73 −73 jaxrs/docbook/reference/en/{ → en-US}/modules/JAX-RS_Resource_Locators_and_Sub_Resources.xml
  19. +28 −28 jaxrs/docbook/reference/en/{ → en-US}/modules/JBoss.xml
  20. 0  jaxrs/docbook/reference/en/{ → en-US}/modules/Jaxb.xml
  21. 0  jaxrs/docbook/reference/en/{ → en-US}/modules/Json.xml
  22. 0  jaxrs/docbook/reference/en/{ → en-US}/modules/License.xml
  23. 0  jaxrs/docbook/reference/en/{ → en-US}/modules/Links.xml
  24. 0  jaxrs/docbook/reference/en/{ → en-US}/modules/Maven_and_RESTEasy.xml
  25. +232 −231 jaxrs/docbook/reference/en/{ → en-US}/modules/Migration_from_older_versions.xml
  26. 0  jaxrs/docbook/reference/en/{ → en-US}/modules/Multipart.xml
  27. 0  jaxrs/docbook/reference/en/{ → en-US}/modules/Overview.xml
  28. +367 −0 jaxrs/docbook/reference/en/en-US/modules/RESTEasy_Client_Framework.xml
  29. 0  jaxrs/docbook/reference/en/{ → en-US}/modules/RESTEasy_EJB_Integration.xml
  30. 0  jaxrs/docbook/reference/en/{ → en-US}/modules/RESTEasy_Embedded_Container.xml
  31. 0  jaxrs/docbook/reference/en/{ → en-US}/modules/RESTEasy_Server-side_Mock_Framework.xml
  32. 0  jaxrs/docbook/reference/en/{ → en-US}/modules/RESTEasy_Spring_Integration.xml
  33. 0  jaxrs/docbook/reference/en/{ → en-US}/modules/Responses_using_javax.ws.rs.core.Response.xml
  34. 0  jaxrs/docbook/reference/en/{ → en-US}/modules/Seam.xml
  35. 0  jaxrs/docbook/reference/en/{ → en-US}/modules/Securing_JAX-RS_and_RESTeasy.xml
  36. +10 −0 jaxrs/docbook/reference/en/en-US/modules/StringConverter.xml
  37. 0  jaxrs/docbook/reference/en/{ → en-US}/modules/Using_Path.xml
  38. 0  jaxrs/docbook/reference/en/{ → en-US}/modules/Validation.xml
  39. 0  jaxrs/docbook/reference/en/{ → en-US}/modules/Yaml.xml
  40. 0  jaxrs/docbook/reference/en/{ → en-US}/modules/_Context.xml
  41. +11 −11 jaxrs/docbook/reference/en/{ → en-US}/modules/_CookieParam.xml
  42. +3 −3 jaxrs/docbook/reference/en/{ → en-US}/modules/_DefaultValue.xml
  43. +30 −30 jaxrs/docbook/reference/en/{ → en-US}/modules/_Encoded_and_encoding.xml
  44. 0  jaxrs/docbook/reference/en/{ → en-US}/modules/_Form.xml
  45. +25 −25 jaxrs/docbook/reference/en/{ → en-US}/modules/_FormParam.xml
  46. +10 −10 jaxrs/docbook/reference/en/{ → en-US}/modules/_HeaderParam.xml
  47. 0  jaxrs/docbook/reference/en/{ → en-US}/modules/_MatrixParam.xml
  48. 0  jaxrs/docbook/reference/en/{ → en-US}/modules/_PathParam.xml
  49. +8 −8 jaxrs/docbook/reference/en/{ → en-US}/modules/_QueryParam.xml
  50. 0  jaxrs/docbook/reference/en/{ → en-US}/modules/gzip.xml
  51. 0  jaxrs/docbook/reference/en/{ → en-US}/modules/signature.xml
  52. +252 −235 jaxrs/docbook/reference/en/{ → en-US}/modules/smime.xml
  53. +0 −366 jaxrs/docbook/reference/en/modules/Interceptors.xml
  54. +0 −761 jaxrs/docbook/reference/en/modules/RESTEasy_Client_Framework.xml
  55. +0 −214 jaxrs/docbook/reference/en/modules/StringConverter.xml
  56. +1 −1  jaxrs/resteasy-client/src/main/java/org/jboss/resteasy/client/jaxrs/ResteasyClient.java
  57. +4 −4 ...lient/src/main/java/org/jboss/resteasy/client/jaxrs/{internal → }/engines/ApacheHttpClient4Engine.java
  58. +2 −2 jaxrs/security/skeleton-key-idm/example/skeleton-key-server/src/main/webapp/WEB-INF/web.xml
  59. +1 −1  ...key-idm/skeleton-key-as7/src/main/java/org/jboss/resteasy/skeleton/key/as7/SkeletonKeyStoneLoginModule.java
  60. +11 −8 ...-key-idm/skeleton-key-core/src/main/java/org/jboss/resteasy/skeleton/key/server/SkeletonKeyApplication.java
  61. +1 −1  ...keleton-key-idm/skeleton-key-core/src/test/java/org/jboss/resteasy/test/skeleton/key/UsersResourceTest.java
257 jaxrs/docbook/pom.xml
View
@@ -1,138 +1,119 @@
-<project xmlns="http://maven.apache.org/POM/4.0.0"
- xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
- xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
-
- <modelVersion>4.0.0</modelVersion>
-
- <groupId>org.jboss.resteasy</groupId>
- <artifactId>resteasy-reference-guide-${translation}</artifactId>
- <version>3.0-alpha-1-SNAPSHOT</version>
- <packaging>jdocbook</packaging>
- <name>RESTEasy Reference Guide (${translation})</name>
- <description/>
- <repositories>
- <repository>
- <id>jboss</id>
- <url>http://repository.jboss.org/nexus/content/groups/public/</url>
- </repository>
- <!--
- <repository>
- <id>repo1.maven.org</id>
- <url>http://repo1.maven.org/maven2</url>
- </repository> -->
- </repositories>
- <pluginRepositories>
- <pluginRepository>
- <id>jboss</id>
- <url>http://repository.jboss.org/nexus/content/groups/public/</url>
- </pluginRepository>
- <!--
- <pluginRepository>
- <id>maven2-repository.dev.java.net</id>
- <url>http://download.java.net/maven/2</url>
- </pluginRepository>
- <pluginRepository>
- <id>plugin repo1.maven.org</id>
- <url>http://repo1.maven.org/maven2</url>
- </pluginRepository>
- <pluginRepository>
- <id>maven-repository.dev.java.net</id>
- <name>Java.net Maven 1 Repository (legacy)</name>
- <url>http://download.java.net/maven/1</url>
- <layout>legacy</layout>
- </pluginRepository>
- -->
- </pluginRepositories>
-
- <build>
- <plugins>
- <plugin>
- <groupId>org.jboss.maven.plugins</groupId>
- <artifactId>maven-jdocbook-plugin</artifactId>
- <version>2.1.2</version>
- <extensions>true</extensions>
- <dependencies>
- <dependency>
- <groupId>org.jboss</groupId>
- <artifactId>jbossorg-docbook-xslt</artifactId>
- <version>1.1.0</version>
- </dependency>
- <dependency>
- <groupId>org.jboss</groupId>
- <artifactId>jbossorg-jdocbook-style</artifactId>
- <version>1.0.0</version>
- <type>jdocbook-style</type>
- </dependency>
- </dependencies>
- <configuration>
- <!--minmemory>1024m</minmemory>
- <maxmemory>1024m</maxmemory -->
- <sourceDocumentName>master.xml</sourceDocumentName>
- <sourceDirectory>reference/en</sourceDirectory>
- <imageResource>
- <directory>reference/en</directory>
- <includes>
- <include>images/*</include>
- </includes>
- </imageResource>
- <!-- <cssResource>
- <directory>src/main/css</directory>
- </cssResource> -->
- <!--put back css -->
-
- <formats>
- <format>
- <formatName>html</formatName>
- <stylesheetResource>classpath:/xslt/org/jboss/xhtml.xsl</stylesheetResource>
- <finalName>index.html</finalName>
- </format>
- <format>
- <formatName>html_single</formatName>
- <stylesheetResource>classpath:/xslt/org/jboss/xhtml-single.xsl</stylesheetResource>
- <finalName>index.html</finalName>
- </format>
-
- <format>
- <formatName>pdf</formatName>
- <stylesheetResource>classpath:/xslt/org/jboss/pdf.xsl</stylesheetResource>
- <finalName>RESTEasy_Reference_Guide.pdf</finalName>
- <profilingTypeName>two_pass</profilingTypeName>
- </format>
-
-
- <!--<format>
- <formatName>eclipse</formatName>
- <stylesheetResource>classpath:/xslt/main-eclipse.xsl</stylesheetResource>
- <finalName>index.html</finalName>
- </format>-->
- </formats>
- <options>
- <xincludeSupported>true</xincludeSupported>
- <xmlTransformerType>saxon</xmlTransformerType>
- <!-- needed for uri-resolvers; can be ommitted if using 'current' uri scheme -->
- <!-- could also locate the docbook dependency and inspect its version... -->
- <!--docbookVersion>1.72.0</docbookVersion -->
- <docbookVersion>1.72.0</docbookVersion>
- <transformerParameters>
- <property>
- <name>javax.xml.parsers.DocumentBuilderFactory</name>
- <value>org.apache.xerces.jaxp.DocumentBuilderFactoryImpl</value>
- </property>
- <property>
- <name>javax.xml.parsers.SAXParserFactory</name>
- <value>org.apache.xerces.jaxp.SAXParserFactoryImpl</value>
- </property>
- <!--<javax.xml.parsers.DocumentBuilderFactory>org.apache.xerces.jaxp.DocumentBuilderFactoryImpl</javax.xml.parsers.DocumentBuilderFactory>
- <javax.xml.parsers.SAXParserFactory>org.apache.xerces.jaxp.SAXParserFactoryImpl</javax.xml.parsers.SAXParserFactory>
- <javax.xml.validation.SchemaFactory:http\://www.w3.org/2001/XMLSchema>org.apache.xerces.jaxp.validation.XMLSchemaFactory</javax.xml.validation.SchemaFactory:http\://www.w3.org/2001/XMLSchema>-->
- </transformerParameters>
- </options>
- </configuration>
- </plugin>
- </plugins>
- </build>
-
- <properties>
- <translation>en-US</translation>
- </properties>
-</project>
+<project xmlns="http://maven.apache.org/POM/4.0.0"
+ xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
+
+ <modelVersion>4.0.0</modelVersion>
+
+ <groupId>org.jboss.resteasy</groupId>
+ <artifactId>resteasy-reference-guide-${translation}</artifactId>
+ <version>3.0-alpha-1-SNAPSHOT</version>
+ <packaging>jdocbook</packaging>
+ <name>RESTEasy Reference Guide (${translation})</name>
+ <description/>
+ <repositories>
+ <repository>
+ <id>jboss</id>
+ <url>http://repository.jboss.org/nexus/content/groups/public/</url>
+ </repository>
+ <!--
+ <repository>
+ <id>repo1.maven.org</id>
+ <url>http://repo1.maven.org/maven2</url>
+ </repository> -->
+ </repositories>
+ <pluginRepositories>
+ <pluginRepository>
+ <id>jboss</id>
+ <url>http://repository.jboss.org/nexus/content/groups/public/</url>
+ </pluginRepository>
+ <!--
+ <pluginRepository>
+ <id>maven2-repository.dev.java.net</id>
+ <url>http://download.java.net/maven/2</url>
+ </pluginRepository>
+ <pluginRepository>
+ <id>plugin repo1.maven.org</id>
+ <url>http://repo1.maven.org/maven2</url>
+ </pluginRepository>
+ -->
+ </pluginRepositories>
+
+ <build>
+ <plugins>
+ <plugin>
+ <groupId>org.jboss.maven.plugins</groupId>
+ <artifactId>maven-jdocbook-plugin</artifactId>
+ <version>2.3.8</version>
+ <extensions>true</extensions>
+
+ <dependencies>
+ <dependency>
+ <groupId>org.jboss.pressgang</groupId>
+ <artifactId>pressgang-xslt-ns</artifactId>
+ <version>2.0.2</version>
+ </dependency>
+ <dependency>
+ <groupId>org.jboss.pressgang</groupId>
+ <artifactId>pressgang-jdocbook-style</artifactId>
+ <type>jdocbook-style</type>
+ <version>2.0.2</version>
+ </dependency>
+ </dependencies>
+
+ <configuration>
+ <sourceDocumentName>master.xml</sourceDocumentName>
+ <masterTranslation>en-US</masterTranslation>
+ <sourceDirectory>reference/en</sourceDirectory>
+ <imageResource>
+ <directory>reference/en</directory>
+ <includes>
+ <include>images/*</include>
+ </includes>
+ </imageResource>
+ <formats>
+ <format>
+ <formatName>html_single</formatName>
+ <stylesheetResource>classpath:/xslt/org/jboss/xhtml-single.xsl</stylesheetResource>
+ <finalName>index.html</finalName>
+ <!-- <profilingTypeName>two_pass</profilingTypeName> -->
+ </format>
+ <format>
+ <formatName>html</formatName>
+ <stylesheetResource>classpath:/xslt/org/jboss/xhtml.xsl</stylesheetResource>
+ <finalName>index.html</finalName>
+ <!-- <profilingTypeName>two_pass</profilingTypeName> -->
+ </format>
+ <format>
+ <formatName>pdf</formatName>
+ <stylesheetResource>classpath:/xslt/org/jboss/pdf.xsl</stylesheetResource>
+ <finalName>${project.artifactId}.pdf</finalName>
+ </format>
+ <!--<format>-->
+ <!--<formatName>eclipse</formatName>-->
+ <!--<stylesheetResource>classpath:/xslt/org/jboss/eclipse.xsl</stylesheetResource>-->
+ <!--<finalName>${project.artifactId}.html</finalName>-->
+ <!--</format>-->
+ </formats>
+ <injections>
+ <injection>
+ <name>project.version</name>
+ <value>${project.version}</value>
+ </injection>
+ </injections>
+ <options>
+ <xmlTransformerType>saxon</xmlTransformerType>
+ <xincludeSupported>true</xincludeSupported>
+ <useRelativeImageUris>true</useRelativeImageUris>
+ <!-- TODO Probably obsolete after the upgrade to maven-jdocbook-plugin 2.3.0 -->
+ <docbookVersion>1.72.0</docbookVersion>
+ <!-- <localeSeparator>-</localeSeparator> -->
+ </options>
+ </configuration>
+ </plugin>
+ </plugins>
+ </build>
+
+ <properties>
+ <translation>en-US</translation>
+ </properties>
+</project>
0  jaxrs/docbook/reference/en/master.xml → jaxrs/docbook/reference/en/en-US/master.xml
View
File renamed without changes
0  jaxrs/docbook/reference/en/modules/AJAX_Client.xml → ...ocbook/reference/en/en-US/modules/AJAX_Client.xml
View
File renamed without changes
0  ...ocbook/reference/en/modules/Async_job_service.xml → .../reference/en/en-US/modules/Async_job_service.xml
View
File renamed without changes
140 ...ocbook/reference/en/modules/Asynchronous_HTTP.xml → .../reference/en/en-US/modules/Asynchronous_HTTP.xml
View
@@ -1,72 +1,70 @@
-<chapter id="Asynchronous_HTTP_Request_Processing">
- <title>Asynchronous HTTP Request Processing</title>
- <para>
- Asynchronous HTTP Request Processing is a relatively new technique that allows you to process a single HTTP
- request using non-blocking I/O and, if desired in separate threads. Some refer to it as COMET capabilities.
- The primary use case for Asynchronous HTTP is
- in the case where the client is polling the server for a delayed response. The usual example is an AJAX chat
- client where you want to push/pull from both the client and the server. These scenarios have the client blocking
- a long time on the server’s socket waiting for a new message. What happens in synchronous HTTP where the server is
- blocking on incoming and outgoing I/O is that you end up having a thread consumed per client connection.
- This eats up memory and valuable thread resources. Not such a big deal in 90% of applications (in fact using
- asynchronous processing may actually hurt your performance in most common scenarios), but when you start
- getting a lot of concurrent clients that are blocking like this, there’s a lot of wasted resources and your
- server does not scale that well.
- </para>
- <para>
- The JAX-RS 2.0 specification has added asynchronous HTTP support via three classes. The @Suspend annotation,
- AsynchronousResponse interface, and the ExecutionContext interface.
- </para>
- <para>
- Injection an AsynchronousResponse as a parameter to your jax-rs methods or obtaining it by calling one of the
- ExecutionContext.suspend() methods tells Resteasy that the HTTP request/response should be detached from the currently
- executing thread and that the current thread should not try to automatically process the response.
- </para>
- <para>
- The AsynchronousResponse is the callback object.
- The act of calling one of the resume() methods will cause a response to be sent back to the client and will also terminate the
- HTTP request. Here is an example of asynchronous processing:
- </para>
-
-
- <programlisting>
-import javax.ws.rs.Suspend;
-import javax.ws.rs.core.AsynchronousResponse;
-
-@Path("/")
-public class SimpleResource
-{
-
- @GET
- @Path("basic")
- @Produces("text/plain")
- @Suspend(timeOut=10000)
- public void getBasic(final AsynchronousResponse response) throws Exception
- {
- Thread t = new Thread()
- {
- @Override
- public void run()
- {
- try
- {
- Response jaxrs = Response.ok("basic").type(MediaType.TEXT_PLAIN).build();
- response.resume(jaxrs);
- }
- catch (Exception e)
- {
- e.printStackTrace();
- }
- }
- };
- t.start();
- }
-}
- </programlisting>
- <para>
- AsynchronousResponse also has other methods to cancel the execution. See javadoc for more details.
- </para>
- <para>
- NOTE: The old Resteasy proprietary API for async http has been deprecated and may be removed as soon as Resteasy 3.1.
- </para>
+<chapter id="Asynchronous_HTTP_Request_Processing">
+ <title>Asynchronous HTTP Request Processing</title>
+ <para>
+ Asynchronous HTTP Request Processing is a relatively new technique that allows you to process a single HTTP
+ request using non-blocking I/O and, if desired in separate threads. Some refer to it as COMET capabilities.
+ The primary use case for Asynchronous HTTP is
+ in the case where the client is polling the server for a delayed response. The usual example is an AJAX chat
+ client where you want to push/pull from both the client and the server. These scenarios have the client blocking
+ a long time on the server’s socket waiting for a new message. What happens in synchronous HTTP where the server is
+ blocking on incoming and outgoing I/O is that you end up having a thread consumed per client connection.
+ This eats up memory and valuable thread resources. Not such a big deal in 90% of applications (in fact using
+ asynchronous processing may actually hurt your performance in most common scenarios), but when you start
+ getting a lot of concurrent clients that are blocking like this, there’s a lot of wasted resources and your
+ server does not scale that well.
+ </para>
+ <para>
+ The JAX-RS 2.0 specification has added asynchronous HTTP support via two classes. The @Suspended annotation,
+ and AsyncResponse interface.
+ </para>
+ <para>
+ Injecting an AsynchronousResponse as a parameter to your jax-rs methods tells Resteasy that the HTTP request/response should be detached from the currently
+ executing thread and that the current thread should not try to automatically process the response.
+ </para>
+ <para>
+ The AsyncResponse is the callback object.
+ The act of calling one of the resume() methods will cause a response to be sent back to the client and will also terminate the
+ HTTP request. Here is an example of asynchronous processing:
+ </para>
+
+
+ <programlisting>
+import javax.ws.rs.Suspend;
+import javax.ws.rs.core.AsynchronousResponse;
+
+@Path("/")
+public class SimpleResource
+{
+
+ @GET
+ @Path("basic")
+ @Produces("text/plain")
+ public void getBasic(@Suspended final AsyncResponse response) throws Exception
+ {
+ Thread t = new Thread()
+ {
+ @Override
+ public void run()
+ {
+ try
+ {
+ Response jaxrs = Response.ok("basic").type(MediaType.TEXT_PLAIN).build();
+ response.resume(jaxrs);
+ }
+ catch (Exception e)
+ {
+ e.printStackTrace();
+ }
+ }
+ };
+ t.start();
+ }
+}
+ </programlisting>
+ <para>
+ AsyncResponse also has other methods to cancel the execution. See javadoc for more details.
+ </para>
+ <para>
+ NOTE: The old Resteasy proprietary API for async http has been deprecated and may be removed as soon as Resteasy 3.1.
+ </para>
</chapter>
0  jaxrs/docbook/reference/en/modules/Atom.xml → jaxrs/docbook/reference/en/en-US/modules/Atom.xml
View
File renamed without changes
0  ...s/docbook/reference/en/modules/Authentication.xml → ...ook/reference/en/en-US/modules/Authentication.xml
View
File renamed without changes
0  jaxrs/docbook/reference/en/modules/Books.xml → jaxrs/docbook/reference/en/en-US/modules/Books.xml
View
File renamed without changes
0  jaxrs/docbook/reference/en/modules/CDI.xml → jaxrs/docbook/reference/en/en-US/modules/CDI.xml
View
File renamed without changes
350 ...ference/en/modules/Cache_NoCache_CacheControl.xml → ...e/en/en-US/modules/Cache_NoCache_CacheControl.xml
View
@@ -1,185 +1,165 @@
-<chapter id="Cache_NoCache_CacheControl">
- <title>Resteasy Caching Features</title>
- <para>
- Resteasy provides numerous annotations and facilities to support HTTP caching semantics. Annotations to make setting Cache-Control
- headers easier and both server-side and client-side in-memory caches are available.
- </para>
- <sect1 id="Cache_Annotation">
- <title>@Cache and @NoCache Annotations</title>
- <para>
- Resteasy provides an extension to JAX-RS that allows you to automatically set Cache-Control headers on a successful
- GET request. It can only be used on @GET annotated methods. A successful @GET request is any request
- that returns 200 OK response.
- </para>
- <programlisting>
-package org.jboss.resteasy.annotations.cache;
-
-public @interface Cache
-{
- int maxAge() default -1;
- int sMaxAge() default -1;
- boolean noStore() default false;
- boolean noTransform() default false;
- boolean mustRevalidate() default false;
- boolean proxyRevalidate() default false;
- boolean isPrivate() default false;
-}
-
-public @interface NoCache
-{
- String[] fields() default {};
-}
-
- </programlisting>
- <para>
- While @Cache builds a complex Cache-Control header, @NoCache is a simplified notation to say that you don't
- want anything cached i.e. Cache-Control: nocache.
- </para>
- <para>
- These annotations can be put on the resource class or interface and specifies a default cache value for each
- @GET resource method. Or they can be put individually on each @GET resource method.
- </para>
- </sect1>
- <sect1 id="client_cache">
- <title>Client "Browser" Cache</title>
- <para>
- Resteasy has the ability to set up a client-side, browser-like, cache. You can use it with the Client Proxy Framework, or with raw
- ClientRequests. This cache looks for Cache-Control headers sent back with a server response. If the Cache-Control headers specify
- that the client is allowed to cache the response, Resteasy caches it within local memory. The cache obeys max-age requirements
- and will also automatically do HTTP 1.1 cache revalidation if either or both the Last-Modified and/or ETag headers are sent back with the
- original response. See the HTTP 1.1 specification for details on how Cache-Control or cache revalidation works.
- </para>
- <para>It is very simple to enable caching. Here's an example of using the client cache with the Client Proxy Framework</para>
-<programlisting>
-@Path("/orders")
-public interface OrderServiceClient {
-
- @Path("{id}")
- @GET
- @Produces("application/xml")
- public Order getOrder(@PathParam("id") String id);
-}
-</programlisting>
- <para>To create a proxy for this interface and enable caching for that proxy requires only a few simple steps:</para>
-<programlisting>
-import org.jboss.resteasy.client.ProxyFactory;
-import org.jboss.resteasy.client.cache.CacheFactory;
-import org.jboss.resteasy.client.cache.LightweightBrowserCache;
-
-public static void main(String[] args) throws Exception
-{
- RegisterBuiltin.register(ResteasyProviderFactory.getInstance());
- OrderServiceClient proxy = ProxyFactory.create(OrderServiceClient.class, generateBaseUrl());
-
- // This line enables caching
- LightweightBrowserCache cache = CacheFactory.makeCacheable(proxy);
-}
-</programlisting>
- <para>If you are using the ClientRequest class to make invocations rather than the proxy framework, it is just as easy</para>
-<programlisting>
-import org.jboss.resteasy.client.ProxyFactory;
-import org.jboss.resteasy.client.cache.CacheFactory;
-import org.jboss.resteasy.client.cache.LightweightBrowserCache;
-
-public static void main(String[] args) throws Exception
-{
- RegisterBuiltin.register(ResteasyProviderFactory.getInstance());
-
- // This line enables caching
- LightweightBrowserCache cache = new LightweightBrowserCache();
-
- ClientRequest request = new ClientRequest("http://example.com/orders/333");
- CacheFactory.makeCacheable(request, cache);
-}
-</programlisting>
- <para>The LightweightBrowserCache, by default, has a maximum 2 megabytes of caching space. You can change this programmatically by callings
- its setMaxBytes() method. If the cache gets full, the cache completely wipes itself of all cached data. This may seem
- a bit draconian, but the cache was written to avoid unnecessary synchronizations in a concurrent environment where the cache is
- shared between multiple threads. If you desire a more complex caching solution or if you want to plug in a thirdparty cache
- please contact our resteasy-developers list and discuss it with the community.
- </para>
- </sect1>
- <sect1 id="server_cache">
- <title>Local Server-Side Response Cache</title>
- <para>Resteasy has a server-side, local, in-memory cache that can sit in front of your JAX-RS services.
- It automatically caches marshalled responses from HTTP GET JAX-RS invocations if, and only if your
- JAX-RS resource method sets a Cache-Control header. When a GET comes in, the Resteasy Server Cache checks
- to see if the URI is stored in the cache. If it does, it returns the already marshalled response without
- invoking your JAX-RS method. Each cache entry has a max age to whatever is specified in the Cache-Control
- header of the initial request. The cache also will automatically generate an ETag using an MD5 hash on the
- response body. This allows the client to do HTTP 1.1 cache revalidation with the IF-NONE-MATCH header.
- The cache is also smart enough to perform revalidation if there is no initial cache hit, but the jax-rs
- method still returns a body that has the same ETag.
- </para>
- <para>
- Starting in Resteasy 2.3, the cache is also automatically invalidated for a particular URI that has
- PUT, POST, or DELETE invoked on it. You can also obtain a reference to the cache by injecting a
- org.jboss.resteasy.plugins.cache.ServerCache
- via the @Context annotation
- </para>
-<programlisting>
-
- @Context
- ServerCache cache;
-
- @GET
- public String get(@Context ServerCache cache) {...}
-
-</programlisting>
- <para>To set up the server-side cache, there are a few simple steps you have to perform. If you are using Maven you must depend on the resteasy-cache-core artifact:</para>
-<programlisting>
-<![CDATA[
-<dependency>
- <groupId>org.jboss.resteasy</groupId>
- <artifactId>resteasy-cache-core</artifactId>
- <version>3.0-alpha-1-SNAPSHOT</version>
-</dependency>
-]]>
-</programlisting>
- <para>The next thing you have to do is to add a ServletContextListener, org.jboss.resteasy.plugins.cache.server.ServletServerCache.
- This must be specified after the ResteasyBootstrap listener in your web.xml file.</para>
-<programlisting>
-<![CDATA[
-<web-app>
- <listener>
- <listener-class>
- org.jboss.resteasy.plugins.server.servlet.ResteasyBootstrap
- </listener-class>
- </listener>
-
- <context-param>
- <param-name>resteasy.server.cache.maxsize</param-name>
- <param-value>1000</param-value>
- </context-param>
-
- <context-param>
- <param-name>resteasy.server.cache.eviction.wakeup.interval</param-name>
- <param-value>5000</param-value>
- </context-param>
-
- <listener>
- <listener-class>
- org.jboss.resteasy.plugins.cache.server.ServletServerCache
- </listener-class>
- </listener>
-
- <servlet>
- <servlet-name>Resteasy</servlet-name>
- <servlet-class>
- org.jboss.resteasy.plugins.server.servlet.HttpServletDispatcher
- </servlet-class>
- </servlet>
-
- <servlet-mapping>
- <servlet-name>Resteasy</servlet-name>
- <url-pattern>/rest-services/*</url-pattern>
- </servlet-mapping>
-
-</web-app>
-]]>
-</programlisting>
- <para>The cache implementation is based on the JBoss Cache project: http://jboss.org/jbosscache. There are two context-param configuration variables
- that you can set. resteasy.server.cache.maxsize sets the number of elements that can be cached. The resteasy.server.cache.eviction.wakeup.interval sets the rate at which the background eviction thread runs to purge the cache of stale entries.
- </para>
- </sect1>
-</chapter>
+<chapter id="Cache_NoCache_CacheControl">
+ <title>Resteasy Caching Features</title>
+ <para>
+ Resteasy provides numerous annotations and facilities to support HTTP caching semantics. Annotations to make setting Cache-Control
+ headers easier and both server-side and client-side in-memory caches are available.
+ </para>
+ <sect1 id="Cache_Annotation">
+ <title>@Cache and @NoCache Annotations</title>
+ <para>
+ Resteasy provides an extension to JAX-RS that allows you to automatically set Cache-Control headers on a successful
+ GET request. It can only be used on @GET annotated methods. A successful @GET request is any request
+ that returns 200 OK response.
+ </para>
+ <programlisting>
+package org.jboss.resteasy.annotations.cache;
+
+public @interface Cache
+{
+ int maxAge() default -1;
+ int sMaxAge() default -1;
+ boolean noStore() default false;
+ boolean noTransform() default false;
+ boolean mustRevalidate() default false;
+ boolean proxyRevalidate() default false;
+ boolean isPrivate() default false;
+}
+
+public @interface NoCache
+{
+ String[] fields() default {};
+}
+
+ </programlisting>
+ <para>
+ While @Cache builds a complex Cache-Control header, @NoCache is a simplified notation to say that you don't
+ want anything cached i.e. Cache-Control: nocache.
+ </para>
+ <para>
+ These annotations can be put on the resource class or interface and specifies a default cache value for each
+ @GET resource method. Or they can be put individually on each @GET resource method.
+ </para>
+ </sect1>
+ <sect1 id="client_cache">
+ <title>Client "Browser" Cache</title>
+ <para>
+ Resteasy has the ability to set up a client-side, browser-like, cache. You can use it with the Client Proxy Framework, or with raw
+ ClientRequests. This cache looks for Cache-Control headers sent back with a server response. If the Cache-Control headers specify
+ that the client is allowed to cache the response, Resteasy caches it within local memory. The cache obeys max-age requirements
+ and will also automatically do HTTP 1.1 cache revalidation if either or both the Last-Modified and/or ETag headers are sent back with the
+ original response. See the HTTP 1.1 specification for details on how Cache-Control or cache revalidation works.
+ </para>
+ <para>It is very simple to enable caching. Here's an example of using the client cache with the Client Proxy Framework</para>
+<programlisting>
+@Path("/orders")
+public interface OrderServiceClient {
+
+ @Path("{id}")
+ @GET
+ @Produces("application/xml")
+ public Order getOrder(@PathParam("id") String id);
+}
+</programlisting>
+ <para>To create a proxy for this interface and enable caching for that proxy requires only a few simple steps:</para>
+<programlisting>
+import org.jboss.resteasy.client.ProxyFactory;
+import org.jboss.resteasy.client.cache.CacheFactory;
+import org.jboss.resteasy.client.cache.LightweightBrowserCache;
+
+public static void main(String[] args) throws Exception
+{
+ RegisterBuiltin.register(ResteasyProviderFactory.getInstance());
+ OrderServiceClient proxy = ProxyFactory.create(OrderServiceClient.class, generateBaseUrl());
+
+ // This line enables caching
+ LightweightBrowserCache cache = CacheFactory.makeCacheable(proxy);
+}
+</programlisting>
+ <para>If you are using the ClientRequest class to make invocations rather than the proxy framework, it is just as easy</para>
+<programlisting>
+import org.jboss.resteasy.client.ProxyFactory;
+import org.jboss.resteasy.client.cache.CacheFactory;
+import org.jboss.resteasy.client.cache.LightweightBrowserCache;
+
+public static void main(String[] args) throws Exception
+{
+ RegisterBuiltin.register(ResteasyProviderFactory.getInstance());
+
+ // This line enables caching
+ LightweightBrowserCache cache = new LightweightBrowserCache();
+
+ ClientRequest request = new ClientRequest("http://example.com/orders/333");
+ CacheFactory.makeCacheable(request, cache);
+}
+</programlisting>
+ <para>The LightweightBrowserCache, by default, has a maximum 2 megabytes of caching space. You can change this programmatically by callings
+ its setMaxBytes() method. If the cache gets full, the cache completely wipes itself of all cached data. This may seem
+ a bit draconian, but the cache was written to avoid unnecessary synchronizations in a concurrent environment where the cache is
+ shared between multiple threads. If you desire a more complex caching solution or if you want to plug in a thirdparty cache
+ please contact our resteasy-developers list and discuss it with the community.
+ </para>
+ </sect1>
+ <sect1 id="server_cache">
+ <title>Local Server-Side Response Cache</title>
+ <para>Resteasy has a server-side cache that can sit in front of your JAX-RS services.
+ It automatically caches marshalled responses from HTTP GET JAX-RS invocations if, and only if your
+ JAX-RS resource method sets a Cache-Control header. When a GET comes in, the Resteasy Server Cache checks
+ to see if the URI is stored in the cache. If it does, it returns the already marshalled response without
+ invoking your JAX-RS method. Each cache entry has a max age to whatever is specified in the Cache-Control
+ header of the initial request. The cache also will automatically generate an ETag using an MD5 hash on the
+ response body. This allows the client to do HTTP 1.1 cache revalidation with the IF-NONE-MATCH header.
+ The cache is also smart enough to perform revalidation if there is no initial cache hit, but the jax-rs
+ method still returns a body that has the same ETag.
+ </para>
+ <para>
+ The cache is also automatically invalidated for a particular URI that has
+ PUT, POST, or DELETE invoked on it. You can also obtain a reference to the cache by injecting a
+ org.jboss.resteasy.plugins.cache.ServerCache
+ via the @Context annotation
+ </para>
+<programlisting>
+
+ @Context
+ ServerCache cache;
+
+ @GET
+ public String get(@Context ServerCache cache) {...}
+
+</programlisting>
+ <para>To set up the server-side cache you must register an instance of org.jboss.resteasy.plugins.cache.server.ServerCacheFeature
+ via your Application getSingletons() or getClasses() methods. The underlying cache is Infinispan. By default,
+ Resteasy will create an Infinispan cache for you. Alternatively, you can create and pass in an instance
+ of your cache to the ServerCacheFeature constructor. You can also configure Infinispan by specifying
+ various context-param variables in your web.xml. First, if you are using Maven you must depend on the resteasy-cache-core artifact:</para>
+<programlisting>
+<![CDATA[
+<dependency>
+ <groupId>org.jboss.resteasy</groupId>
+ <artifactId>resteasy-cache-core</artifactId>
+ <version>3.0-alpha-1-SNAPSHOT</version>
+</dependency>
+]]>
+</programlisting>
+ <para>The next thing you should probably do is set up the Infinispan configuration in your web.xml.</para>
+<programlisting>
+<![CDATA[
+<web-app>
+ <context-param>
+ <param-name>server.request.cache.infinispan.config.file</param-name>
+ <param-value>infinispan.xml</param-value>
+ </context-param>
+
+ <context-param>
+ <param-name>server.request.cache.infinispan.cache.name</param-name>
+ <param-value>MyCache</param-value>
+ </context-param>
+
+</web-app>
+]]>
+</programlisting>
+ <para>
+ server.request.cache.infinispan.config.file can either be a classpath or a file path. server.request.cache.infinispan.cache.name
+ is the name of the cache you want to reference that is declared in the config file.
+ </para>
+ </sect1>
+</chapter>
0  .../Configuring_Individual_JAX-RS_Resource_Beans.xml → .../Configuring_Individual_JAX-RS_Resource_Beans.xml
View
File renamed without changes
0  ...ence/en/modules/Content_Marshalling_Providers.xml → ...n/en-US/modules/Content_Marshalling_Providers.xml
View
File renamed without changes
0  ...docbook/reference/en/modules/ExceptionMappers.xml → ...k/reference/en/en-US/modules/ExceptionMappers.xml
View
File renamed without changes
0  jaxrs/docbook/reference/en/modules/Guice.xml → jaxrs/docbook/reference/en/en-US/modules/Guice.xml
View
File renamed without changes
0  ...ference/en/modules/Installation_Configuration.xml → ...e/en/en-US/modules/Installation_Configuration.xml
View
File renamed without changes
124 jaxrs/docbook/reference/en/en-US/modules/Interceptors.xml
View
@@ -0,0 +1,124 @@
+<chapter id="Interceptors">
+ <title>Filters and Interceptors</title>
+ <para>JAX-RS 2.0 has two different concepts for interceptions: Filters and Interceptors. Filters are mainly used to
+ modify or process incoming and outgoing request headers or response headers. They execute before and after
+ request and response processing.</para>
+ <sect1>
+ <title>Server Side Filters</title>
+ <para>
+ On the server-side you have two different types of filters. ContainerRequestFilters
+ run before your JAX-RS resource method is invoked. ContainerResponseFilters run after your JAX-RS resource method
+ is invoked. As an added caveat, ContainerRequestFilters come in two flavors: pre-match and post-matching. Pre-matching
+ ContainerRequestFilters are designated with the @PreMatching annotation and will execute before the JAX-RS resource
+ method is matched with the incoming HTTP request. Pre-matching filters often are used to modify request attributes
+ to change how it matches to a specific resource method (i.e. strip .xml and add an Accept header). ContainerRequestFilters can abort the request by calling ContainerRequestContext.abortWith(Response). A filter
+ might want to abort if it implements a custom authentication protocol.
+ </para>
+ <para>
+ After the resource class method is executed, JAX-RS will run all ContainerResponseFilters. These filters
+ allow you to modify the outgoing response before it is marshalling and sent to the client.
+ So given all that, here's some pseudo
+ code to give some understanding of how things work.
+ </para>
+ <programlisting>
+ // execute pre match filters
+ for (ContainerRequestFilter filter : preMatchFilters) {
+ filter.filter(requestContext);
+ if (isAborted(requestContext)) {
+ sendAbortionToClient(requestContext);
+ return;
+ }
+ }
+ // match the HTTP request to a resource class and method
+ JaxrsMethod method = matchMethod(requestContext);
+
+ // Execute post match filters
+ for (ContainerRequestFilter filter : postMatchFilters) {
+ filter.filter(requestContext);
+ if (isAborted(requestContext)) {
+ sendAbortionToClient(requestContext);
+ return;
+ }
+ }
+
+ // execute resource class method
+ method.execute(request);
+
+ // execute response filters
+ for (ContainerResponseFilter filter : responseFilters) {
+ filter.filter(requestContext, responseContext);
+ }
+ </programlisting>
+ </sect1>
+ <sect1>
+ <title>Client Side Filters</title>
+ <para>
+ On the client side you also have two types of filters: ClientRequestFilter and ClientResponseFilter.
+ ClientRequestFilters run before your HTTP request is sent over the wire to the server. ClientResponseFilters
+ run after a response is received from the server, but before the response body is unmarshalled. ClientRequestFilters
+ are also allowed to abort the execute of the request and provide a canned response without going over the
+ wire to the server. ClientResponseFilters can modfiy the Response object before it is handed back to
+ application code. Here's some pseudo code to illustrate things.
+ </para>
+ <programlisting>
+ // execute request filters
+ for (ClientRequestFilter filter : requestFilters) {
+ filter.filter(requestContext);
+ if (isAborted(requestContext)) {
+ return requestContext.getAbortedResponseObject();
+ }
+ }
+
+ // send request over the wire
+ response = sendRequest(request);
+
+ // execute response filters
+ for (ClientResponseFilter filter : responseFilters) {
+ filter.filter(requestContext, responseContext);
+ }
+ </programlisting>
+ </sect1>
+ <sect1>
+ <title>Reader and Writer Interceptors</title>
+ <para>
+ While filters modify request or response headers, interceptors deal with message bodies. Interceptors are executed
+ in the same call stack as their corresponding reader or writer. ReaderInterceptors
+ wrap around the execution of MessageBodyReaders. WriterInterceptors wrap around the execution of MessageBodyWriters.
+ They can be used to implement a specific content-encoding. They can be used to generate digital signatures or
+ to post or pre-process a Java object model before or after it is marshalled.
+ </para>
+ </sect1>
+ <sect1>
+ <title>Per Resource Method Filters and Interceptors</title>
+ <para>
+ Sometimes you want a filter or interceptor to only run for a specific resource method. You can do this in two different
+ ways: register an implementation of DynamicFeature or use the @NameBinding annotation. The DynamicFeature
+ interface is executed at deployment time for each resource method. You just use the Configurable interface
+ to register the filters and interceptors you want for the specific resource method. @NameBinding works a lot
+ like CDI interceptors. You annotate a custom annotation with @NameBinding and then apply that custom annotation
+ to your filter and resource method
+ </para>
+ <programlisting>
+ @NameBinding
+ public @interface DoIt {}
+
+ @DoIt
+ public class MyFilter implements ContainerRequestFilter {...}
+
+ @Path("/root")
+ public class MyResource {
+
+ @GET
+ @DoIt
+ public String get() {...}
+ }
+ </programlisting>
+ </sect1>
+ <sect1>
+ <title>Ordering</title>
+ <para>
+ Ordering is accomplished by using the @BindingPriority annotation on your filter or interceptor class.
+ </para>
+ </sect1>
+
+</chapter>
0  ...ference/en/modules/JAX-RS_Content_Negotiation.xml → ...e/en/en-US/modules/JAX-RS_Content_Negotiation.xml
View
File renamed without changes
146 ...es/JAX-RS_Resource_Locators_and_Sub_Resources.xml → ...es/JAX-RS_Resource_Locators_and_Sub_Resources.xml
View
@@ -7,28 +7,28 @@ Resource classes are able to partially process a request and provide another &qu
</para>
<para>
-<programlisting>
-@Path("/")
-public class ShoppingStore {
-
- @Path("/customers/{id}")
- public Customer getCustomer(@PathParam("id") int id) {
- Customer cust = ...; // Find a customer object
- return cust;
- }
-}
-
-
-public class Customer {
-
- @GET
- public String get() {...}
-
- @Path("/address")
- public String getAddress() {...}
-
-}
-
+<programlisting>
+@Path("/")
+public class ShoppingStore {
+
+ @Path("/customers/{id}")
+ public Customer getCustomer(@PathParam("id") int id) {
+ Customer cust = ...; // Find a customer object
+ return cust;
+ }
+}
+
+
+public class Customer {
+
+ @GET
+ public String get() {...}
+
+ @Path("/address")
+ public String getAddress() {...}
+
+}
+
</programlisting>
</para>
<para>
@@ -68,28 +68,28 @@ Another interesting feature of Sub-resource locators is that the locator method
</para>
<para>
-<programlisting>
-@Path("/")
-public class ShoppingStore {
-
- @Path("/customers/{id}")
- public java.lang.Object getCustomer(@PathParam("id") int id) {
- Customer cust = ...; // Find a customer object
- return cust;
- }
-}
-
-
-public class Customer {
-
- @GET
- public String get() {...}
-
- @Path("/address")
- public String getAddress() {...}
-
-}
-
+<programlisting>
+@Path("/")
+public class ShoppingStore {
+
+ @Path("/customers/{id}")
+ public java.lang.Object getCustomer(@PathParam("id") int id) {
+ Customer cust = ...; // Find a customer object
+ return cust;
+ }
+}
+
+
+public class Customer {
+
+ @GET
+ public String get() {...}
+
+ @Path("/address")
+ public String getAddress() {...}
+
+}
+
</programlisting>
</para>
<para>
@@ -98,35 +98,35 @@ In the above example, getCustomer() returns a java.lang.Object. Per request, at
</para>
<para>
-<programlisting>
-@Path("/")
-public class ShoppingStore {
-
- @Path("/customers/{id}")
- public java.lang.Object getCustomer(@PathParam("id") int id) {
- Customer cust = entityManager.find(Customer.class, id);
- return cust;
- }
-}
-
-
-public class Customer {
-
- @GET
- public String get() {...}
-
- @Path("/address")
- public String getAddress() {...}
-
-}
-
-public class CorporateCustomer extendsCustomer {
-
- @Path("/businessAddress")
- public String getAddress() {...}
-
-}
-
+<programlisting>
+@Path("/")
+public class ShoppingStore {
+
+ @Path("/customers/{id}")
+ public java.lang.Object getCustomer(@PathParam("id") int id) {
+ Customer cust = entityManager.find(Customer.class, id);
+ return cust;
+ }
+}
+
+
+public class Customer {
+
+ @GET
+ public String get() {...}
+
+ @Path("/address")
+ public String getAddress() {...}
+
+}
+
+public class CorporateCustomer extendsCustomer {
+
+ @Path("/businessAddress")
+ public String getAddress() {...}
+
+}
+
</programlisting>
</para>
<para>
56 jaxrs/docbook/reference/en/modules/JBoss.xml → jaxrs/docbook/reference/en/en-US/modules/JBoss.xml
View
@@ -1,28 +1,28 @@
-<chapter id="JBoss5">
- <title>JBoss AS 5.x Integration</title>
- <para>Resteasy has no special integration with JBoss Application Server so it must be configured and
- installed
- like any other container. There are some issues though. You must make sure that there is not a copy
- of servlet-api-xxx.jar in your WEB-INF/lib directory as this may cause problems. Also, if you are running
- with JDK 6, make sure to filter out the JAXB jars as they come with JDK 6.
- </para>
-</chapter>
-<chapter id="JBoss AS 6">
-<title>JBoss AS 6 Integration</title>
-<para>
- RESTEasy is preconfigured and completely integrated with JBoss 6-M4 and higher. You can use it with EJB
- and CDI and you can rely completely on JBoss for scanning for your JAX-RS services and deploying them. All
- you have to provide is your JAX-RS service classes packaged within a WAR either as POJOs, CDI beans,
- or EJBs and provide an empty web.xml file as follows:
-</para>
-<para>
- <programlisting>
- <![CDATA[
-<web-app version="3.0" 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_3_0.xsd">
-</web-app>
-]]>
- </programlisting>
-</para>
-</chapter>
+<chapter id="JBoss5">
+ <title>JBoss AS 5.x Integration</title>
+ <para>Resteasy has no special integration with JBoss Application Server so it must be configured and
+ installed
+ like any other container. There are some issues though. You must make sure that there is not a copy
+ of servlet-api-xxx.jar in your WEB-INF/lib directory as this may cause problems. Also, if you are running
+ with JDK 6, make sure to filter out the JAXB jars as they come with JDK 6.
+ </para>
+</chapter>
+<chapter id="JBoss AS 6">
+<title>JBoss AS 6/7 Integration</title>
+<para>
+ RESTEasy is preconfigured and completely integrated with JBoss 6-M4 and higher. You can use it with EJB
+ and CDI and you can rely completely on JBoss for scanning for your JAX-RS services and deploying them. All
+ you have to provide is your JAX-RS service classes packaged within a WAR either as POJOs, CDI beans,
+ or EJBs and provide an empty web.xml file as follows:
+</para>
+<para>
+ <programlisting>
+ <![CDATA[
+<web-app version="3.0" 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_3_0.xsd">
+</web-app>
+]]>
+ </programlisting>
+</para>
+</chapter>
0  jaxrs/docbook/reference/en/modules/Jaxb.xml → jaxrs/docbook/reference/en/en-US/modules/Jaxb.xml
View
File renamed without changes
0  jaxrs/docbook/reference/en/modules/Json.xml → jaxrs/docbook/reference/en/en-US/modules/Json.xml
View
File renamed without changes
0  jaxrs/docbook/reference/en/modules/License.xml → jaxrs/docbook/reference/en/en-US/modules/License.xml
View
File renamed without changes
0  jaxrs/docbook/reference/en/modules/Links.xml → jaxrs/docbook/reference/en/en-US/modules/Links.xml
View
File renamed without changes
0  ...cbook/reference/en/modules/Maven_and_RESTEasy.xml → ...reference/en/en-US/modules/Maven_and_RESTEasy.xml
View
File renamed without changes
463 ...ence/en/modules/Migration_from_older_versions.xml → ...n/en-US/modules/Migration_from_older_versions.xml
View
@@ -1,231 +1,232 @@
-<chapter id="doc">
- <title>Documentation Support</title>
- <para>There's a great javadoc engine that allows you to generate javadocs for JAX-RS and JAXB called<ulink
- url="http://www.lunatech-labs.com/open-source/jax-doclets">JAX-Doclet</ulink>. Follow the link for more
- details.
- </para>
-</chapter>
-
-<chapter id="Migration_from_older_versions">
-<title>Migration from older versions</title>
-<sect1>
- <title>Migrating from 2.x to 3.0</title>
- <itemizedlist>
- <listitem>
- resteasy-crypto: SignedInput and SignedOutput must have a multipart/signed content type set either through
- the request or response object, or by annotation @Consumes/@Produces
- </listitem>
- <listitem>
- Server-side cache setup has been changed. Please see documentation for more details.
- </listitem>
- <listitem>
- The security filters for @RolesAllowed, etc. now return 403, Forbidden instead of 401.
- </listitem>
- <listitem>
- Most add() methods have been removed or made protected in ResteasyProviderFactory. Use registerProvider() and registerProviderInstance() methods.
- </listitem>
- <listitem>
- Resteasy's odl proprietary interceptor, client, and async http APIs have been deprecated and may be removed (probably Resteasy 3.1).
- JAX-RS 2.0 has standardized these features.
- </listitem>
- <listitem>
- The new JAX-RS 2.0 client-side filters will not be bound and run when you are using Resteasy's old client api.
- </listitem>
- <listitem>
- On server-side, all old Resteasy interceptors can run in parallel with the new JAX-RS 2.0 filter and interceptor
- interfaces.
- </listitem>
- <listitem>
- Some SPIs have changed. This should not effect applications unless you are doing something you aren't supposed
- to do.
- </listitem>
- <listitem>
- The async tomcat and async jboss web modules have been removed. If you are not running under Servlet 3.0,
- async HTTP server-side, will be faked and run synchronously in same request thread.
- </listitem>
- </itemizedlist>
-</sect1>
-<sect1>
- <title>Migrating from 2.3.2 to 2.3.3</title>
- <itemizedlist>
- <listitem>
- MultipartInput has a new close() method. If you have a read body that is MultipartInput or one of
- its subinterfaces, then you must call this method to clean up any temporary files created. Otherwise,
- these possible temporary files are deleted on GC or JDK shutdown. Other multipart providers clean up
- automatically.
- </listitem>
- </itemizedlist>
-</sect1>
-<sect1>
- <title>Migrating from 2.3.0 to 2.3.1</title>
- <itemizedlist>
- <listitem>
- sjsxp has been removed as a dependency for the Resteasy JAXB provider
- </listitem>
- </itemizedlist>
-</sect1>
-<sect1>
- <title>Migrating from 2.2.x to 2.3</title>
- <itemizedlist>
- <listitem>
- The Apache Abdera integration has been removed as a project. If you want the integration back, please
- ping our dev lists or open a JIRA.
- </listitem>
- <listitem>
- Apache Http Client 4.x is now the default underlying client HTTP mechanism. If there are problems, you
- can change the default mechanism by calling ClientRequest.setDefaultExecutorClass.
- </listitem>
- <listitem>
- ClientRequest no longer supports a shared default executor. The
- <code>createPerRequestInstance</code> parameter has been removed from
- <methodname>ClientRequest.setDefaultExecutorClass()</methodname>.
- </listitem>
- <listitem>
- resteasy-doseta module no longer exists. It is now renamed to the resteasy-crypto module and also includes other things beyond doseta.
- </listitem>
- <listitem>
- Doseta work has be refactored a bit and may have broken backward compatibility.
- </listitem>
- <listitem>
- Jackson has been upgraded from 1.6.3 to 1.8.5. Let me know if there are any issues.
- </listitem>
- <listitem>
- Form parameter processing behavior was modified because of RESTEASY-574. If you are having problems with form paramater processing on Tomcat after
- this fix, please log a JIRA or contact the resteasy-developers email list.
- </listitem>
- <listitem>
- Some subtle changes were made to ExceptionMapper handling so that you can write ExceptionMappers for any exception thrown internally or within
- your application. See JIRA Issue RESTEASY-595 for more details. This may have an effect on existing applications that have an ExceptionMapper
- for RuntimeException in that you will start to see Resteasy internal exceptions being caught by this kind of ExceptionMapper.
- </listitem>
- <listitem>
- The resteasy-cache (Server-side cache) will now invalidate the cache when a PUT, POST, or DELETE is done on a particular URI.
- </listitem>
- </itemizedlist>
-</sect1>
-<sect1 id="22_221">
- <title>Migrating from 2.2.0 to 2.2.1</title>
- <itemizedlist>
- <listitem>
- Had to upgrade JAXB libs from 2.1.x to 2.2.4 as there was a concurrency bug in JAXB impl.
- </listitem>
- </itemizedlist>
-</sect1>
-<sect1 id="21_22">
- <title>Migrating from 2.1.x to 2.2</title>
- <itemizedlist>
- <listitem>
- ClientRequest.getHeaders() always returns a copy. It also converts the values within
- ClientRequest.getHeadersAsObjects() to string. If you
- add values to the map returned by getHeaders() nothing happen. Instead add values to the
- getHeadersAsObjects() map. This allows non-string header objects
- to propagate through the MessageBodyWriter interceptor and ClientExecutor interceptor chains.
- </listitem>
- </itemizedlist>
-</sect1>
-<sect1 id="20_21">
- <title>Migrating from 2.0.x to 2.1</title>
- <itemizedlist>
- <listitem>
- Slf4j is no longer the default logging mechanism for resteasy. Resteasy also no longer ships with SLF4J
- libraries. Please read the logging
- section in the Installation and Configuration chapter for more details.
- </listitem>
- <listitem>
- The constructor used to instantiate resource and provider classes is now picked based on the requirements of
- the JAX-RS specification.
- Specifically, the public constructor with the most arguments is picked. This behavior varies from previous
- versions where a no-arg
- constructor is preferred.
- </listitem>
- </itemizedlist>
-</sect1>
-<sect1 id="Migrating_to_Resteasy_12_20">
- <title>Migrating from 1.2.x to 2.0</title>
-
- <para>
-
- <itemizedlist>
- <listitem>
- TJWS has been forked to fix some bugs. The new groupId is org.jboss.resteasy, the artifactId is
- tjws. It will match the resteasy distribution version
- </listitem>
- <listitem>
- Please check out the JBoss 6 integration. It makes things a lot easier if you are deploying in that
- environment
- </listitem>
- <listitem>
- There is a new Filter implementation that is the preferred deployment mechanism. Servlet-based
- deployments are still supported, but it is suggested you use to using a FilterDispatcher. See
- documentation for more details.
- </listitem>
- <listitem>
- As per required by the spec List or array injection of empty values will return an empty collection
- or array, not null. I.e.
- (@QueryParam("name") List&lt;String&gt; param) param will be an empty List. Resteasy 1.2.x and
- earlier would return null.
- </listitem>
- <listitem>
- We have forked TJWS, the servlet container used for embedded testing into the group
- org.jboss.resteasy, with the artifact id of tjws. You will need
- to remove these dependencies from your maven builds if you are using any part of the resteasy
- embeddable server. TJWS has a number of startup/shutdown
- race conditions we had to fix in order to make unit testing viable.
- </listitem>
- <listitem>
- Spring integration compiled against Spring 3.0.3. It may or may not still work with 2.5.6 and lower
- </listitem>
- </itemizedlist>
- </para>
-</sect1>
-<sect1 id="migrating_1.2_1.2.1">
- <title>Migrating from 1.2.GA to 1.2.1.GA</title>
- <para>
- Methods @Deprecated within 1.2.GA have been removed. This is in the Client Framework and has to do with all
- references to Apache HTTP Client. You must now create an ClientExecutor if you want to manage your Apache
- HTTP Client
- sessions.
- </para>
-</sect1>
-<sect1 id="Migrating_to_Resteasy_1_1_1_2">
- <title>Migrating from 1.1 to 1.2</title>
-
- <para>
-
- <itemizedlist>
- <listitem>
- The resteasy-maven-import artifact has been renamed to resteasy-bom
- </listitem>
- <listitem>
- Jettison and Fastinfoset have been broken out of the resteasy-jaxb-provider maven module. You will
- now need to include resteasy-jettison-provider or resteasy-fastinfoset-provider if you use either
- of these libraries.
- </listitem>
- <listitem>
- The constructors for ClientRequest that have a HttpClient parameter (Apache Http Client 3.1 API) are
- now deprecated. They will be removed in the final release of 1.2. You must create a Apache hTTP
- Client Executor and pass it in as a parameter if you want to re-use existing Apache HttpClient
- sessions or do any special configuration. The same is true for the ProxyFactoyr methods.
- </listitem>
- <!--
- <listitem>
- Apache HttpClient 4.0 is now the default client used for our ClientRequest and ProxyFactory APIs. Version 3.1 of this library is still support. Just allocate an executor for that instead. Or you can set the default one used by modifying the static field ClientRequest.defaultExecutorClass.
- </listitem>
- -->
- <listitem>
- Apache HttpClient 4.0 support is available if you want to use it. I've had some trouble with it so
- it is not the default implementation yet for the client framework.
- </listitem>
- <listitem>
- It is no longer required to call RegisterBuiltin.register() to initialize the set of providers. Too
- many users forgot to do this (include myself!). You can turn this off by calling the static method
- ResteasyProviderFactory.setRegisterBuiltinByDefault(false)
- </listitem>
- <listitem>
- The Embedded Container's API has changed to use org.jboss.resteasy.spi.ResteasyDeployment. Please
- see embedded documentation for more details.
- </listitem>
- </itemizedlist>
- </para>
-</sect1>
-</chapter>
+<chapter id="doc">
+ <title>Documentation Support</title>
+ <para>There's a great javadoc engine that allows you to generate javadocs for JAX-RS and JAXB called<ulink
+ url="http://www.lunatech-labs.com/open-source/jax-doclets">JAX-Doclet</ulink>. Follow the link for more
+ details.
+ </para>
+</chapter>
+
+<chapter id="Migration_from_older_versions">
+<title>Migration from older versions</title>
+<sect1>
+ <title>Migrating from 2.x to 3.0</title>
+ <itemizedlist>
+ <listitem>
+ Resteasy manual client API, interceptors, StringConverters, StringParamterConverters, and Async HTTP APIs have all been
+ deprecated and will be removed possibly in a later release. There is now a JAX-RS 2.0 equivalent for each
+ of these things.
+ </listitem>
+ <listitem>
+ resteasy-crypto: SignedInput and SignedOutput must have a multipart/signed content type set either through
+ the request or response object, or by annotation @Consumes/@Produces
+ </listitem>
+ <listitem>
+ Server-side cache setup has been changed. Please see documentation for more details.
+ </listitem>
+ <listitem>
+ The security filters for @RolesAllowed, etc. now return 403, Forbidden instead of 401.
+ </listitem>
+ <listitem>
+ Most add() methods have been removed or made protected in ResteasyProviderFactory. Use registerProvider() and registerProviderInstance() methods.
+ </listitem>
+ <listitem>
+ The new JAX-RS 2.0 client-side filters will not be bound and run when you are using Resteasy's old client api.
+ </listitem>
+ <listitem>
+ On server-side, all old Resteasy interceptors can run in parallel with the new JAX-RS 2.0 filter and interceptor
+ interfaces.
+ </listitem>
+ <listitem>
+ Some SPIs have changed. This should not effect applications unless you are doing something you aren't supposed
+ to do.
+ </listitem>
+ <listitem>
+ The async tomcat and async jboss web modules have been removed. If you are not running under Servlet 3.0,
+ async HTTP server-side, will be faked and run synchronously in same request thread.
+ </listitem>
+ </itemizedlist>
+</sect1>
+<sect1>
+ <title>Migrating from 2.3.2 to 2.3.3</title>
+ <itemizedlist>
+ <listitem>
+ MultipartInput has a new close() method. If you have a read body that is MultipartInput or one of
+ its subinterfaces, then you must call this method to clean up any temporary files created. Otherwise,
+ these possible temporary files are deleted on GC or JDK shutdown. Other multipart providers clean up
+ automatically.
+ </listitem>
+ </itemizedlist>
+</sect1>
+<sect1>
+ <title>Migrating from 2.3.0 to 2.3.1</title>
+ <itemizedlist>
+ <listitem>
+ sjsxp has been removed as a dependency for the Resteasy JAXB provider
+ </listitem>
+ </itemizedlist>
+</sect1>
+<sect1>
+ <title>Migrating from 2.2.x to 2.3</title>
+ <itemizedlist>
+ <listitem>
+ The Apache Abdera integration has been removed as a project. If you want the integration back, please
+ ping our dev lists or open a JIRA.
+ </listitem>
+ <listitem>
+ Apache Http Client 4.x is now the default underlying client HTTP mechanism. If there are problems, you
+ can change the default mechanism by calling ClientRequest.setDefaultExecutorClass.
+ </listitem>
+ <listitem>
+ ClientRequest no longer supports a shared default executor. The
+ <code>createPerRequestInstance</code> parameter has been removed from
+ <methodname>ClientRequest.setDefaultExecutorClass()</methodname>.
+ </listitem>
+ <listitem>
+ resteasy-doseta module no longer exists. It is now renamed to the resteasy-crypto module and also includes other things beyond doseta.
+ </listitem>
+ <listitem>
+ Doseta work has be refactored a bit and may have broken backward compatibility.
+ </listitem>
+ <listitem>
+ Jackson has been upgraded from 1.6.3 to 1.8.5. Let me know if there are any issues.
+ </listitem>
+ <listitem>
+ Form parameter processing behavior was modified because of RESTEASY-574. If you are having problems with form paramater processing on Tomcat after
+ this fix, please log a JIRA or contact the resteasy-developers email list.
+ </listitem>
+ <listitem>
+ Some subtle changes were made to ExceptionMapper handling so that you can write ExceptionMappers for any exception thrown internally or within
+ your application. See JIRA Issue RESTEASY-595 for more details. This may have an effect on existing applications that have an ExceptionMapper
+ for RuntimeException in that you will start to see Resteasy internal exceptions being caught by this kind of ExceptionMapper.
+ </listitem>
+ <listitem>
+ The resteasy-cache (Server-side cache) will now invalidate the cache when a PUT, POST, or DELETE is done on a particular URI.
+ </listitem>
+ </itemizedlist>
+</sect1>
+<sect1 id="22_221">
+ <title>Migrating from 2.2.0 to 2.2.1</title>
+ <itemizedlist>
+ <listitem>
+ Had to upgrade JAXB libs from 2.1.x to 2.2.4 as there was a concurrency bug in JAXB impl.
+ </listitem>
+ </itemizedlist>
+</sect1>
+<sect1 id="21_22">
+ <title>Migrating from 2.1.x to 2.2</title>
+ <itemizedlist>
+ <listitem>
+ ClientRequest.getHeaders() always returns a copy. It also converts the values within
+ ClientRequest.getHeadersAsObjects() to string. If you
+ add values to the map returned by getHeaders() nothing happen. Instead add values to the
+ getHeadersAsObjects() map. This allows non-string header objects
+ to propagate through the MessageBodyWriter interceptor and ClientExecutor interceptor chains.
+ </listitem>
+ </itemizedlist>
+</sect1>
+<sect1 id="20_21">
+ <title>Migrating from 2.0.x to 2.1</title>
+ <itemizedlist>
+ <listitem>
+ Slf4j is no longer the default logging mechanism for resteasy. Resteasy also no longer ships with SLF4J
+ libraries. Please read the logging
+ section in the Installation and Configuration chapter for more details.
+ </listitem>
+ <listitem>
+ The constructor used to instantiate resource and provider classes is now picked based on the requirements of
+ the JAX-RS specification.
+ Specifically, the public constructor with the most arguments is picked. This behavior varies from previous
+ versions where a no-arg
+ constructor is preferred.
+ </listitem>
+ </itemizedlist>
+</sect1>
+<sect1 id="Migrating_to_Resteasy_12_20">
+ <title>Migrating from 1.2.x to 2.0</title>
+
+ <para>
+
+ <itemizedlist>
+ <listitem>
+ TJWS has been forked to fix some bugs. The new groupId is org.jboss.resteasy, the artifactId is
+ tjws. It will match the resteasy distribution version
+ </listitem>
+ <listitem>
+ Please check out the JBoss 6 integration. It makes things a lot easier if you are deploying in that
+ environment
+ </listitem>
+ <listitem>
+ There is a new Filter implementation that is the preferred deployment mechanism. Servlet-based
+ deployments are still supported, but it is suggested you use to using a FilterDispatcher. See
+ documentation for more details.
+ </listitem>
+ <listitem>
+ As per required by the spec List or array injection of empty values will return an empty collection
+ or array, not null. I.e.
+ (@QueryParam("name") List&lt;String&gt; param) param will be an empty List. Resteasy 1.2.x and
+ earlier would return null.
+ </listitem>
+ <listitem>
+ We have forked TJWS, the servlet container used for embedded testing into the group
+ org.jboss.resteasy, with the artifact id of tjws. You will need
+ to remove these dependencies from your maven builds if you are using any part of the resteasy
+ embeddable server. TJWS has a number of startup/shutdown
+ race conditions we had to fix in order to make unit testing viable.
+ </listitem>
+ <listitem>
+ Spring integration compiled against Spring 3.0.3. It may or may not still work with 2.5.6 and lower
+ </listitem>
+ </itemizedlist>
+ </para>
+</sect1>
+<sect1 id="migrating_1.2_1.2.1">
+ <title>Migrating from 1.2.GA to 1.2.1.GA</title>
+ <para>
+ Methods @Deprecated within 1.2.GA have been removed. This is in the Client Framework and has to do with all
+ references to Apache HTTP Client. You must now create an ClientExecutor if you want to manage your Apache
+ HTTP Client
+ sessions.
+ </para>
+</sect1>
+<sect1 id="Migrating_to_Resteasy_1_1_1_2">
+ <title>Migrating from 1.1 to 1.2</title>
+
+ <para>
+
+ <itemizedlist>
+ <listitem>
+ The resteasy-maven-import artifact has been renamed to resteasy-bom
+ </listitem>
+ <listitem>
+ Jettison and Fastinfoset have been broken out of the resteasy-jaxb-provider maven module. You will
+ now need to include resteasy-jettison-provider or resteasy-fastinfoset-provider if you use either
+ of these libraries.
+ </listitem>
+ <listitem>
+ The constructors for ClientRequest that have a HttpClient parameter (Apache Http Client 3.1 API) are
+ now deprecated. They will be removed in the final release of 1.2. You must create a Apache hTTP
+ Client Executor and pass it in as a parameter if you want to re-use existing Apache HttpClient
+ sessions or do any special configuration. The same is true for the ProxyFactoyr methods.
+ </listitem>
+ <!--
+ <listitem>
+ Apache HttpClient 4.0 is now the default client used for our ClientRequest and ProxyFactory APIs. Version 3.1 of this library is still support. Just allocate an executor for that instead. Or you can set the default one used by modifying the static field ClientRequest.defaultExecutorClass.
+ </listitem>
+ -->
+ <listitem>
+ Apache HttpClient 4.0 support is available if you want to use it. I've had some trouble with it so
+ it is not the default implementation yet for the client framework.
+ </listitem>
+ <listitem>
+ It is no longer required to call RegisterBuiltin.register() to initialize the set of providers. Too
+ many users forgot to do this (include myself!). You can turn this off by calling the static method
+ ResteasyProviderFactory.setRegisterBuiltinByDefault(false)
+ </listitem>
+ <listitem>
+ The Embedded Container's API has changed to use org.jboss.resteasy.spi.ResteasyDeployment. Please
+ see embedded documentation for more details.
+ </listitem>
+ </itemizedlist>
+ </para>
+</sect1>
+</chapter>
0  jaxrs/docbook/reference/en/modules/Multipart.xml → .../docbook/reference/en/en-US/modules/Multipart.xml
View
File renamed without changes
0  jaxrs/docbook/reference/en/modules/Overview.xml → ...s/docbook/reference/en/en-US/modules/Overview.xml
View
File renamed without changes
367 jaxrs/docbook/reference/en/en-US/modules/RESTEasy_Client_Framework.xml
View
@@ -0,0 +1,367 @@
+<chapter id="RESTEasy_Client_Framework">
+ <title>Resteasy Client API</title>
+
+ <sect1>
+ <title>JAX-RS 2.0 Client API</title>
+ <para>JAX-RS 2.0 introduces a new client API so that you can make http requests to your remote RESTful web services.
+ It is a 'fluent' request building API with really 3 main classes: Client, WebTarget, and Response. The Client
+ interface is a builder of WebTarget instances. WebTarget represents a distinct URL or URL template from which
+ you can build more sub-resource WebTargets or invoke requests on.</para>
+ <para>
+ There are really two ways to create a Client. Standard way, or you can instantiate Resteasy's core class
+ directly. The advantage of the latter is that you can work with Resteasy extension interfaces.
+ </para>
+ <programlisting>
+ Client client = ClientFactory.newClient();
+ WebTarget target = client.target("http://foo.com/resource");
+ Response response = target.request().get();
+ String value = response.readEntity(String.class);
+ response.close(); // You should close connections!
+
+ ResteasyClient client = new ResteasyClient();
+ ResteasyWebTarget target = client.target("http://foo.com/resource");
+ </programlisting>
+ <para>
+ Resteasy will load automatically load a set of default providers. (Basically all classes listed in all
+ META-INF/services/javax.ws.rs.ext.Providers files). Additionally, you can manually register other providers,
+ filters, and interceptors through the Configuration object provided by the method call Client.configuration().
+ Configuration also lets you set various configuration properties that may be needed.
+ </para>
+ <para>
+ Each WebTarget has its own Configuration instance which inherits the components and properties registered with
+ its parent. This allows you to set specific configuration options per target resource. For example, username
+ and password.
+ </para>
+ </sect1>
+ <para>
+
+ </para>
+
+ <sect1>
+ <title>Resteasy Proxy Framework</title>
+ <para>
+
+ The Resteasy Proxy Framework is the mirror opposite of the JAX-RS server-side specification. Instead of using
+ JAX-RS annotations to map an incoming request to your RESTFul Web Service method, the client framework builds an
+ HTTP request that it uses to invoke on a remote RESTful Web Service. This remote service does not have to be a
+ JAX-RS service and can be any web resource that accepts HTTP requests.
+ </para>
+ <para>
+
+ Resteasy has a client proxy framework that allows you to use JAX-RS annotations to invoke on a remote HTTP
+ resource.
+ The way it works is that you write a Java interface and use JAX-RS annotations on methods and the interface. For
+ example:
+ </para>
+ <para>
+
+<programlisting>
+public interface SimpleClient
+{
+ @GET
+ @Path("basic")
+ @Produces("text/plain")
+ String getBasic();
+
+ @PUT
+ @Path("basic")
+ @Consumes("text/plain")
+ void putBasic(String body);
+
+ @GET
+ @Path("queryParam")
+ @Produces("text/plain")
+ String getQueryParam(@QueryParam("param")String param);
+
+ @GET
+ @Path("matrixParam")
+ @Produces("text/plain")
+ String getMatrixParam(@MatrixParam("param")String param);
+
+ @GET
+ @Path("uriParam/{param}")
+ @Produces("text/plain")
+ int getUriParam(@PathParam("param")int param);
+}</programlisting>
+ </para>
+ <para>
+
+ Resteasy has a simple API based on Apache HttpClient. You generate a proxy then you can invoke methods on the
+ proxy. The invoked method gets translated to an HTTP request based on how you annotated the method and posted to
+ the server. Here's how you would set this up:
+ </para>
+ <para>
+
+ <programlisting>
+ Client client = ClientFactory.newClient();
+ WebTarget target = client.target("http://example.com/base/uri");
+ ResteasyWebTarget rtarget = (ResteasyWebTarget)target;
+
+ SimpleClient simple = rtarget.proxy(SimpleClient.class);
+ client.putBasic("hello world");
+ </programlisting>
+ Alternatively you can use the Resteasy client extension interfaces directly:
+ <programlisting>
+ ResteasyClient client = new ResteasyClient();
+ ResteasyWebTarget target = client.target("http://example.com/base/uri");
+
+ SimpleClient simple = target.proxy(SimpleClient.class);
+ client.putBasic("hello world");
+ </programlisting>
+
+ </para>
+ <para>
+
+ @CookieParam works the mirror opposite of its server-side counterpart and creates a cookie header to send to the
+ server. You do not need to use @CookieParam if you allocate your own javax.ws.rs.core.Cookie object and pass it
+ as
+ a parameter to a client proxy method. The client framework understands that you are passing a cookie to the
+ server
+ so no extra metadata is needed.
+ </para>
+ <para>
+ The framework also supports the JAX-RS locator pattern, but on the client side. So, if you have a method annotated only with @Path, that proxy method
+ will return a new proxy of the interface returned by that method.
+ </para>
+ <sect1 id="Custom_client-side_responses">
+ <title>Abstract Responses</title>
+
+ <para>
+
+ Sometimes you are interested not only in the response body of a client request, but also either the response
+ code and/or response headers. The Client-Proxy framework has two ways to get at this information
+ </para>
+ <para>
+
+
+ </para>
+ <para>
+
+ You may return a javax.ws.rs.core.Response.Status enumeration from your method calls:
+ </para>
+ <para>
+
+ <programlisting>
+@Path("/")
+public interface MyProxy {
+ @POST
+ Response.Status updateSite(MyPojo pojo);
+}
+ </programlisting>
+ </para>
+ <para>
+
+ Internally, after invoking on the server, the client proxy internals will convert the HTTP response code into
+ a
+ Response.Status enum.
+ </para>
+ <para>
+
+
+ </para>
+ <para>
+
+ If you are interested in everything, you can get it with the javax.ws.rs.core.Response class:
+ </para>
+ <para>
+
+ <programlisting>
+@Path("/")
+public interface LibraryService {
+
+ @GET
+ @Produces("application/xml")
+ Response getAllBooks();
+}</programlisting>
+ </para>
+ </sect1>
+ <sect1 id="Sharing_interfaces">
+ <title>Sharing an interface between client and server</title>
+ <para>
+ It is generally possible to share an interface between the client and server. In this scenario, you just
+ have your JAX-RS services implement an annotated interface
+ and then reuse that same interface to create client proxies to invoke on the client-side.
+ </para>
+
+ </sect1>
+ </sect1>
+
+
+
+
+
+ <sect1 id="transport_layer">
+ <title>Apache HTTP Client 4.x and other backends</title>
+
+ <para>
+ Network communication between the client and server is handled in Resteasy,
+ by default, by HttpClient (4.x) from the Apache HttpComponents project. In general,
+ the interface between the Resteasy Client Framework and the network is
+ found in an implementation of
+ <classname>org.jboss.resteasy.client.jaxrs.ClientHttpEngine</classname>, and
+ <classname>org.jboss.resteasy.client.jaxrs.engines.ApacheHttpClient4Engine</classname>,
+ which uses HttpClient (4.x), is the default implementation. Resteasy
+ also ships with the following client engines, all found in the
+ <code>org.jboss.resteasy.client.jaxrs.engines</code> package:
+ </para>
+
+ <itemizedlist>
+ <listitem>
+ URLConnectionClientExecutor: uses <classname>java.net.HttpURLConnection</classname>;
+ </listitem>
+ <listitem>InMemoryClientExecutor: dispatches requests to a server in the same JVM.</listitem>
+ </itemizedlist>
+ <para>
+ and a client executor may be passed to a specific <classname>ClientRequest</classname>:
+ </para>
+
+ <programlisting>
+ResteasyClient client = (ResteasyClient)ClientFactory.newClient();
+ClientHttpEngine engine = new ApacheHttpClient4Engine();
+client.httpEngine(engine);
+ </programlisting>
+
+ <para>
+ Resteasy and HttpClient make reasonable default decisions so that it is possible to use the client
+ framework without ever referencing HttpClient, but for some applications it may be necessary to drill
+ down into the HttpClient details. <classname>ApacheHttpClient4Engine</classname> can
+ be supplied with an instance of <classname>org.apache.http.client.HttpClient</classname> and
+ an instance of <classname>org.apache.http.protocol.HttpContext</classname>, which can carry
+ additional configuration details into the HttpClient layer. For example, authentication
+ may be configured as follows:
+ </para>
+
+ <programlisting>
+// Configure HttpClient to authenticate preemptively
+// by prepopulating the authentication data cache.
+
+// 1. Create AuthCache instance
+AuthCache authCache = new BasicAuthCache();
+
+// 2. Generate BASIC scheme object and add it to the local auth cache
+BasicScheme basicAuth = new BasicScheme();
+authCache.put("com.bluemonkeydiamond.sippycups", basicAuth);
+
+// 3. Add AuthCache to the execution context
+BasicHttpContext localContext = new BasicHttpContext();
+localContext.setAttribute(ClientContext.AUTH_CACHE, authCache);
+
+// 4. Create client executor and proxy
+httpClient = new DefaultHttpClient();
+ApacheHttpClient4Engine engine = new ApacheHttpClient4Engine(httpClient, localContext);
+ResteasyClient client = (ResteasyClient)ClientFactory.newClient();
+client.httpEngine(engine);
+ </programlisting>
+
+ <para>
+ One default decision made by HttpClient and adopted by Resteasy is the use of
+ <classname>org.apache.http.impl.conn.SingleClientConnManager</classname>,
+ which manages a single socket at any given time and which
+ supports the use case in which one or more invocations are made serially
+ from a single thread. For multithreaded applications,
+ <classname>SingleClientConnManager</classname> may be replaced by
+ <classname>org.apache.http.impl.conn.tsccm.ThreadSafeClientConnManager</classname>:
+ </para>
+
+ <programlisting>
+ClientConnectionManager cm = new ThreadSafeClientConnManager();
+HttpClient httpClient = new DefaultHttpClient(cm);
+ApacheHttpClient4Engine engine = new ApacheHttpClient4Engine(httpClient);
+ </programlisting>
+
+ <para>
+ For more information about HttpClient (4.x), see the documentation
+ at <ulink url="http://hc.apache.org/httpcomponents-client-ga/tutorial/html/">
+ http://hc.apache.org/httpcomponents-client-ga/tutorial/html/</ulink>.
+ </para>
+
+ <para>
+ <emphasis role="bold">Note.</emphasis> It is important to understand
+ the difference between "releasing" a connection and "closing" a
+ connection. <emphasis role="bold">Releasing</emphasis> a connection
+ makes it available for reuse. <emphasis role="bold">Closing</emphasis>
+ a connection frees its resources and makes it unusable.
+ </para>
+ <para>
+ <classname>SingleClientConnManager</classname> manages
+ a single socket, which it allocates to at most a single invocation
+ at any given time. Before that socket can be reused, it has to be
+ released from its current use, which can occur in one of two ways. If
+ an execution of a request or a call on
+ a proxy returns a class other than <classname>Response</classname>,
+ then Resteasy will take care of releasing the connection. For example,
+ in the fragments
+ </para>
+
+ <programlisting>
+WebTarget target = client.target("http://localhost:8081/customer/123");
+String answer = target.request().get(String.class);
+ </programlisting>
+
+ <para>
+ or
+ </para>
+
+ <programlisting>
+ResteasyWebTarget target = client.target("http://localhost:8081/customer/123");
+RegistryStats stats = target.proxy(RegistryStats.class);
+RegistryData data = stats.get();
+ </programlisting>
+
+ <para>
+ Resteasy will release the connection under the covers. The only counterexample is the case
+ in which the response is an instance of <classname>InputStream</classname>, which must
+ be closed explicitly.
+ </para>
+
+ <para>
+ On the other hand, if the result of an invocation is an instance of
+ <classname>Response</classname>, then Response.close() method must be used to released the connection.
+ </para>
+
+ <programlisting>
+WebTarget target = client.target("http://localhost:8081/customer/123");
+Response response = target.request().get();
+System.out.println(response.getStatus());
+response.close();
+ </programlisting>
+
+ <para>
+ You should probably execute this in a try/finally block. Again, releasing a connection only makes it available
+ for another use. <emphasis role="bold">It does not normally close the socket.</emphasis>
+ </para>
+
+ <para>
+ On the other hand,
+ <methodname>ApacheHttpClient4Engine.finalize()</methodname> will close any open
+ sockets, but only if it created the <classname>HttpClient</classname> it has been
+ using. If an <classname>HttpClient</classname> has been passed into the
+ <classname>ApacheHttpClient4Executor</classname>, then the user is responsible
+ for closing the connections:
+ </para>
+
+ <programlisting>
+HttpClient httpClient = new DefaultHttpClient();
+ApacheHttpClient4Engine executor = new ApacheHttpClient4Engine(httpClient);
+...
+httpClient.getConnectionManager().shutdown();
+ </programlisting>
+
+ <para>
+ Note that if <classname>ApacheHttpClient4Engine</classname> has created its own
+ instance of <classname>HttpClient</classname>, it is not necessary to wait
+ for <methodname>finalize()</methodname> to close open sockets. The
+ <classname>ClientHttpEngine</classname> interface has a <methodname>close()</methodname>
+ method for this purpose.
+ </para>
+
+ <para>
+ Finally, if your javax.ws.rs.client.Client class has created the engine automatically for you, you should
+ call Client.close() and this will clean up any socket connections.
+ </para>
+
+ </sect1>
+
+
+</chapter>
+
0  ...reference/en/modules/RESTEasy_EJB_Integration.xml → ...nce/en/en-US/modules/RESTEasy_EJB_Integration.xml
View
File renamed without changes
0  ...erence/en/modules/RESTEasy_Embedded_Container.xml → .../en/en-US/modules/RESTEasy_Embedded_Container.xml
View
File renamed without changes
0  ...n/modules/RESTEasy_Server-side_Mock_Framework.xml → ...S/modules/RESTEasy_Server-side_Mock_Framework.xml
View
File renamed without changes
0  ...erence/en/modules/RESTEasy_Spring_Integration.xml → .../en/en-US/modules/RESTEasy_Spring_Integration.xml
View
File renamed without changes
0  ...les/Responses_using_javax.ws.rs.core.Response.xml → ...les/Responses_using_javax.ws.rs.core.Response.xml
View
File renamed without changes
0  jaxrs/docbook/reference/en/modules/Seam.xml → jaxrs/docbook/reference/en/en-US/modules/Seam.xml
View
File renamed without changes
0  ...rence/en/modules/Securing_JAX-RS_and_RESTeasy.xml → ...en/en-US/modules/Securing_JAX-RS_and_RESTeasy.xml
View
File renamed without changes
10 jaxrs/docbook/reference/en/en-US/modules/StringConverter.xml
View
@@ -0,0 +1,10 @@
+<chapter id="StringConverter">
+ <title>String marshalling for String based @*Param</title>
+ <para>@PathParam, @QueryParam, @MatrixParam, @FormParam, and @HeaderParam are represented as strings in a raw
+ HTTP request. The specification says that these types of injected parameters can be converted to objects
+ if these objects have a valueOf(String) static method or a constructor that takes one String parameter.
+ What if you have a class where valueOf() or this string constructor doesn't exist or is inappropriate for
+ an HTTP request? JAX-RS 2.0 has the javax.ws.rs.ext.ParamConverterProvider to help in this situation.
+ See javadoc for more details.
+ </para>
+</chapter>
0  jaxrs/docbook/reference/en/modules/Using_Path.xml → ...docbook/reference/en/en-US/modules/Using_Path.xml
View
File renamed without changes
0  jaxrs/docbook/reference/en/modules/Validation.xml → ...docbook/reference/en/en-US/modules/Validation.xml
View
File renamed without changes
0  jaxrs/docbook/reference/en/modules/Yaml.xml → jaxrs/docbook/reference/en/en-US/modules/Yaml.xml
View
File renamed without changes
0  jaxrs/docbook/reference/en/modules/_Context.xml → ...s/docbook/reference/en/en-US/modules/_Context.xml
View
File renamed without changes
22 jaxrs/docbook/reference/en/modules/_CookieParam.xml → ...cbook/reference/en/en-US/modules/_CookieParam.xml
View
@@ -11,17 +11,17 @@ GET /books?num=5
</para>
<para>
-<programlisting>
-
-
-
- @GET
- public String getBooks(@CookieParam("sessionid") int id) {
- ...
- }
-
- @GET
- publi cString getBooks(@CookieParam("sessionid") javax.ws.rs.core.Cookie id) {...}
+<programlisting>
+
+
+
+ @GET
+ public String getBooks(@CookieParam("sessionid") int id) {
+ ...
+ }
+
+ @GET
+ publi cString getBooks(@CookieParam("sessionid") javax.ws.rs.core.Cookie id) {...}
</programlisting>
</para>
<para>
6 jaxrs/docbook/reference/en/modules/_DefaultValue.xml → ...book/reference/en/en-US/modules/_DefaultValue.xml
View
@@ -7,9 +7,9 @@
</para>
<para>
-<programlisting>
- @GET
- public String getBooks(@QueryParam("num") @DefaultValue("10") int num) {...}
+<programlisting>
+ @GET
+ public String getBooks(@QueryParam("num") @DefaultValue("10") int num) {...}
</programlisting>
</para>
<para>
60 ...ok/reference/en/modules/_Encoded_and_encoding.xml → ...erence/en/en-US/modules/_Encoded_and_encoding.xml
View
@@ -15,13 +15,13 @@ The @javax.ws.rs.Encoded annotation can be used on a class, method, or param. B
</para>
<para>
-<programlisting>
-@Path("/")
-public class MyResource {
-
- @Path("/{param}")
- @GET
- public String get(@PathParam("param") @Encoded String param) {...}
+<programlisting>
+@Path("/")
+public class MyResource {
+
+ @Path("/{param}")
+ @GET
+ public String get(@PathParam("param") @Encoded String param) {...}
</programlisting>
</para>
<para>
@@ -34,17 +34,17 @@ You may also use the @Encoded annotation on the entire method and any combinatio
</para>
<para>
-<programlisting>
-@Path("/")
-public class MyResource {
-
- @Path("/{param}")
- @GET
- @Encoded
- public String get(@QueryParam("foo") String foo, @PathParam("param") String param) {}
-}
-
-
+<programlisting>
+@Path("/")
+public class MyResource {
+
+ @Path("/{param}")
+ @GET
+ @Encoded
+ public String get(@QueryParam("foo") String foo, @PathParam("param") String param) {}
+}
+
+
</programlisting>
</para>
<para>
@@ -54,14 +54,14 @@ In the above example, the values of the &quot;foo&quot; query param and &quot;pa
<para>
You can also set the default to be encoded for the entire class.
-<programlisting>
-@Path("/")
-@Encoded
-public class ClassEncoded {
-
- @GET
- public String get(@QueryParam("foo") String foo) {}
-}
+<programlisting>
+@Path("/")
+@Encoded
+public class ClassEncoded {
+
+ @GET
+ public String get(@QueryParam("foo") String foo) {}
+}
</programlisting>
</para>
<para>
@@ -74,8 +74,8 @@ The @Path annotation has an attribute called encode. Controls whether the liter
</para>
<para>
-<programlisting>
-@Path(value="hello%20world", encode=false)
+<programlisting>
+@Path(value="hello%20world", encode=false)
</programlisting>
</para>
<para>
@@ -88,8 +88,8 @@ Much like @Path.encode(), this controls whether the specified query param name s
</para>
<para>
-<programlisting>
-@QueryParam(value="hello%20world", encode=false)
+<programlisting>
+@QueryParam(value="hello%20world", encode=false)
</programlisting>
</para>
<para>
0  jaxrs/docbook/reference/en/modules/_Form.xml → jaxrs/docbook/reference/en/en-US/modules/_Form.xml
View
File renamed without changes
50 jaxrs/docbook/reference/en/modules/_FormParam.xml → ...docbook/reference/en/en-US/modules/_FormParam.xml
View
@@ -7,14 +7,14 @@ When the input request body is of the type &quot;application/x-www-form-urlencod
</para>
<para>
-<programlisting>
-&lt;form method="POST" action="/resources/service"&gt;
-First name:
-&lt;input type="text" name="firstname"&gt;
-&lt;br&gt;
-Last name:
-&lt;input type="text" name="lastname"&gt;
-&lt;/form&gt;
+<programlisting>
+&lt;form method="POST" action="/resources/service"&gt;
+First name:
+&lt;input type="text" name="firstname"&gt;
+&lt;br&gt;
+Last name:
+&lt;input type="text" name="lastname"&gt;
+&lt;/form&gt;
</programlisting>
</para>
<para>
@@ -23,14 +23,14 @@ If you post through that form, this is what the service might look like:
</para>
<para>
-<programlisting>
-@Path("/")
-public class NameRegistry {
-
- @Path("/resources/service")
- @POST
- public void addName(@FormParam("firstname") String first, @FormParam("lastname") String last) {...}
-
+<programlisting>
+@Path("/")
+public class NameRegistry {
+
+ @Path("/resources/service")
+ @POST
+ public void addName(@FormParam("firstname") String first, @FormParam("lastname") String last) {...}
+
</programlisting>
</para>
<para>
@@ -39,15 +39,15 @@ You cannot combine @FormParam with the default &quot;application/x-www-form-urle
</para>
<para>
-<programlisting>
-@Path("/")
-public class NameRegistry {
-
- @Path("/resources/service")
- @POST
- @Consumes("application/x-www-form-urlencoded")
- public void addName(@FormParam("firstname") String first, MultivaluedMap&lt;String, String&gt; form) {...}
-
+<programlisting>
+@Path("/")
+public class NameRegistry {
+
+ @Path("/resources/service")
+ @POST
+ @Consumes("application/x-www-form-urlencoded")
+ public void addName(@FormParam("firstname") String first, MultivaluedMap&lt;String, String&gt; form) {...}
+
</programlisting>
</para>
<para>
20 jaxrs/docbook/reference/en/modules/_HeaderParam.xml → ...cbook/reference/en/en-US/modules/_HeaderParam.xml
View
@@ -11,12 +11,12 @@ GET /books?num=5
</para>
<para>
-<programlisting>
-
- @GET
- public String getBooks(@HeaderParam("From") String from) {
- ...
- }
+<programlisting>
+
+ @GET
+ public String getBooks(@HeaderParam("From") String from) {
+ ...
+ }
</programlisting>
</para>
<para>
@@ -25,10 +25,10 @@ Like PathParam, your parameter type can be an String, primitive, or class that h
</para>
<para>
-<programlisting>
-
- @PUT
- public void put(@HeaderParam("Content-Type") MediaType contentType, ...)
+<programlisting>
+
+ @PUT
+ public void put(@HeaderParam("Content-Type") MediaType contentType, ...)
</programlisting>
</para>
<para>
0  jaxrs/docbook/reference/en/modules/_MatrixParam.xml → ...cbook/reference/en/en-US/modules/_MatrixParam.xml
View
File renamed without changes
0  jaxrs/docbook/reference/en/modules/_PathParam.xml → ...docbook/reference/en/en-US/modules/_PathParam.xml
View
File renamed without changes
16 jaxrs/docbook/reference/en/modules/_QueryParam.xml → ...ocbook/reference/en/en-US/modules/_QueryParam.xml
View
@@ -11,14 +11,14 @@ GET /books?num=5
</para>
<para>
-<programlisting>
-
-
-
- @GET
- public String getBooks(@QueryParam("num") int num) {
- ...
- }
+<programlisting>
+
+
+
+ @GET
+ public String getBooks(@QueryParam("num") int num) {
+ ...
+ }
</programlisting>
</para>
<para>
0  jaxrs/docbook/reference/en/modules/gzip.xml → jaxrs/docbook/reference/en/en-US/modules/gzip.xml
View
File renamed without changes
0  jaxrs/docbook/reference/en/modules/signature.xml → .../docbook/reference/en/en-US/modules/signature.xml
View
File renamed without changes
487 jaxrs/docbook/reference/en/modules/smime.xml → jaxrs/docbook/reference/en/en-US/modules/smime.xml
View
@@ -1,235 +1,252 @@
-<chapter>
- <title>Body Encryption and Signing via SMIME</title>
-
- <para>S/MIME (Secure/Multipurpose Internet Mail Extensions) is a standard
- for public key encryption and signing of MIME data. MIME data being a set of
- headers and a message body. Its most often seen in the email world when
- somebody wants to encrypt and/or sign an email message they are sending
- across the internet. It can also be used for HTTP requests as well which is
- what the RESTEasy integration with S/MIME is all about. RESTEasy allows you
- to easily encrypt and/or sign an email message using the S/MIME standard.
- While the API is described here, you may also want to check out the example
- projects that come with the RESTEasy distribution. It shows both Java and
- Python clients exchanging S/MIME formatted messages with a JAX-RS
- service.</para>
-
- <section>
- <title>Maven settings</title>
-
- <para>You must include the resteasy-crypto project to use the smime framework.</para>
-
- <para><programlisting> &lt;dependency&gt;
- &lt;groupId&gt;org.jboss.resteasy&lt;/groupId&gt;
- &lt;artifactId&gt;resteasy-crypto&lt;/artifactId&gt;
- &lt;version&gt;3.0-alpha-1-SNAPSHOT&lt;/version&gt;
- &lt;/dependency&gt;
-
-</programlisting></para>
- </section>
-
- <section>
- <title>Message Body Encryption</title>
-
- <para>While HTTPS is used to encrypt the entire HTTP message, S/MIME
- encryption is used solely for the message body of the HTTP request or
- response. This is very useful if you have a representation that may be
- forwarded by multiple parties (for example, HornetQ's REST Messaging
- integration!) and you want to protect the message from prying eyes as it
- travels across the network. RESTEasy has two different interfaces for
- encrypting message bodies. One for output, one for input. If your client
- or server wants to send an HTTP request or response with an encrypted
- body, it uses the
- <literal>org.jboss.resteasy.security.smime.EnvelopedOutput</literal> type.
- Encrypting a body also requires an X509 certificate which can be generated
- by the Java keytool command-line interface, or the openssl tool that comes
- installed on many OS's. Here's an example of using the
- <literal>EnvelopedOutput</literal> interface:</para>
-
- <programlisting>// server side
-
-@Path("encrypted")
-@GET
-public EnvelopedOutput getEncrypted()
-{
- Customer cust = new Customer();
- cust.setName("Bill");
-
- X509Certificate certificate = ...;
- EnvelopedOutput output = new EnvelopedOutput(cust, MediaType.APPLICATION_XML_TYPE);
- output.setCertificate(certificate);
- return output;
-}
-
-
-// client side
-X509Certificate cert = ...;
-Customer cust = new Customer();
-cust.setName("Bill");
-EnvelopedOutput output = new EnvelopedOutput(cust, "application/xml");
-output.setCertificate(cert);
-ClientResponse res = request.body("application/pkcs7-mime", output).post();
-
-</programlisting>
-
- <para>An EnvelopedOutput instance is created passing in the entity you
- want to marshal and the media type you want to marshal it into. So in this
- example, we're taking a Customer class and marshalling it into XML before
- we encrypt it. RESTEasy will then encrypt the EnvelopedOutput using the
- BouncyCastle framework's SMIME integration. The output is a Base64
- encoding and would look something like this:</para>
-
- <programlisting>Content-Type: application/pkcs7-mime; smime-type=enveloped-data; name="smime.p7m"
-Content-Transfer-Encoding: base64
-Content-Disposition: attachment; filename="smime.p7m"
-
-MIAGCSqGSIb3DQEHA6CAMIACAQAxgewwgekCAQAwUjBFMQswCQYDVQQGEwJBVTETMBEGA1UECBMK
-U29tZS1TdGF0ZTEhMB8GA1UEChMYSW50ZXJuZXQgV2lkZ2l0cyBQdHkgTHRkAgkA7oW81OriflAw
-DQYJKoZIhvcNAQEBBQAEgYCfnqPK/O34DFl2p2zm+xZQ6R+94BqZHdtEWQN2evrcgtAng+f2ltIL
-xr/PiK+8bE8wDO5GuCg+k92uYp2rLKlZ5BxCGb8tRM4kYC9sHbH2dPaqzUBhMxjgWdMCX6Q7E130
-u9MdGcP74Ogwj8fNl3lD4sx/0k02/QwgaukeY7uNHzCABgkqhkiG9w0BBwEwFAYIKoZIhvcNAwcE
-CDRozFLsPnSgoIAEQHmqjSKAWlQbuGQL9w4nKw4l+44WgTjKf7mGWZvYY8tOCcdmhDxRSM1Ly682
-Imt+LTZf0LXzuFGTsCGOUo742N8AAAAAAAAAAAAA
-</programlisting>
-
- <para>Decrypting an S/MIME encrypted message requires using the
- org.jboss.resteasy.security.smime.EnvelopedInput interface. You also need
- both the private key and X509Certificate used to encrypt the message.
- Here's an example:</para>
-
- <programlisting>// server side
-
-@Path("encrypted")
-@POST
-public void postEncrypted(EnvelopedInput&lt;Customer&gt; input)
-{
- PrivateKey privateKey = ...;
- X509Certificate certificate = ...;
- Customer cust = input.getEntity(privateKey, certificate);
-}
-
-// client side
-
-ClientRequest request = new ClientRequest("http://localhost:9095/smime/encrypted");
-EnvelopedInput input = request.getTarget(EnvelopedInput.class);
-Customer cust = (Customer)input.getEntity(Customer.class, privateKey, cert);
-
-</programlisting>
-
- <para>Both examples simply call the getEntity() method passing in the
- PrivateKey and X509Certificate instances requires to decrypt the message.
- On the server side, a generic is used with EnvelopedInput to specify the
- type to marshal to. On the server side this information is passed as a
- parameter to getEntity(). The message is in MIME format: a Content-Type
- header and body, so the EnvelopedInput class now has everything it needs
- to know to both decrypt and unmarshall the entity. </para>
- </section>
-
- <section>
- <title>Message Body Signing</title>
-
- <para>S/MIME also allows you to digitally sign a message. It is a bit
- different than the Doseta Digital Signing Framework. Doseta is an HTTP
- header that contains the signature. S/MIME uses the multipart/signed data
- format which is a multipart message that contains the entity and the
- digital signature. So Doseta is a header, S/MIME is its own media type.
- Generally I would prefer Doseta as S/MIME signatures require the client to
- know how to parse a multipart message and Doseta doesn't. Its up to you
- what you want to use.</para>
-
- <para>Resteasy has two different interfaces for creating a
- multipart/signed message. One for input, one for output. If your client or
- server wants to send an HTTP request or response with an multipart/signed
- body, it uses the
- <literal>org.jboss.resteasy.security.smime.SignedOutput</literal> type.
- This type requires both the PrivateKey and X509Certificate to create the
- signature. Here's an example of signing an entity and sending a
- multipart/signed entity.</para>
-
- <programlisting>// server-side
-
- @Path("signed")
- @GET
- public SignedOutput getSigned()
- {
- Customer cust = new Customer();
- cust.setName("Bill");
-
- SignedOutput output = new SignedOutput(cust, MediaType.APPLICATION_XML_TYPE);
- output.setPrivateKey(privateKey);
- output.setCertificate(certificate);
- return output;
- }
-
-
-// client side
-
- ClientRequest request = new ClientRequest("http://localhost:9095/smime/signed");
- Customer cust = new Customer();
- cust.setName("Bill");
- SignedOutput output = new SignedOutput(cust, "application/xml");
- output.setPrivateKey(privateKey);
- output.setCertificate(cert);
- ClientResponse res = request.body("multipart/signed", output).post();
-
-</programlisting>
-
- <para>An SignedOutput instance is created passing in the entity you want
- to marshal and the media type you want to marshal it into. So in this
- example, we're taking a Customer class and marshalling it into XML before
- we sign it. RESTEasy will then sign the SignedOutput using the
- BouncyCastle framework's SMIME integration. The output iwould look
- something like this:</para>
-
- <programlisting>Content-Type: multipart/signed; protocol="application/pkcs7-signature"; micalg=sha1; boundary="----=_Part_0_1083228271.1313024422098"
-
-------=_Part_0_1083228271.1313024422098
-Content-Type: application/xml
-Content-Transfer-Encoding: 7bit
-
-&lt;customer name="bill"/&gt;
-------=_Part_0_1083228271.1313024422098
-Content-Type: application/pkcs7-signature; name=smime.p7s; smime-type=signed-data
-Content-Transfer-Encoding: base64
-Content-Disposition: attachment; filename="smime.p7s"
-Content-Description: S/MIME Cryptographic Signature
-
-MIAGCSqGSIb3DQEHAqCAMIACAQExCzAJBgUrDgMCGgUAMIAGCSqGSIb3DQEHAQAAMYIBVzCCAVMC
-AQEwUjBFMQswCQYDVQQGEwJBVTETMBEGA1UECBMKU29tZS1TdGF0ZTEhMB8GA1UEChMYSW50ZXJu
-ZXQgV2lkZ2l0cyBQdHkgTHRkAgkA7oW81OriflAwCQYFKw4DAhoFAKBdMBgGCSqGSIb3DQEJAzEL
-BgkqhkiG9w0BBwEwHAYJKoZIhvcNAQkFMQ8XDTExMDgxMTAxMDAyMlowIwYJKoZIhvcNAQkEMRYE
-FH32BfR1l1vzDshtQvJrgvpGvjADMA0GCSqGSIb3DQEBAQUABIGAL3KVi3ul9cPRUMYcGgQmWtsZ
-0bLbAldO+okrt8mQ87SrUv2LGkIJbEhGHsOlsgSU80/YumP+Q4lYsVanVfoI8GgQH3Iztp+Rce2c
-y42f86ZypE7ueynI4HTPNHfr78EpyKGzWuZHW4yMo70LpXhk5RqfM9a/n4TEa9QuTU76atAAAAAA
-AAA=
-------=_Part_0_1083228271.1313024422098--
-</programlisting>
-
- <para>To unmarshal and verify a signed message requires using the
- <literal>org.jboss.resteasy.security.smime.SignedInput</literal>
- interface. You only need the X509Certificate to verify the message. Here's
- an example of unmarshalling and verifying a multipart/signed
- entity.</para>
-
- <programlisting>// server side
-
- @Path("signed")
- @POST
- public void postSigned(SignedInput&lt;Customer&gt; input) throws Exception
- {
- Customer cust = input.getEntity();
- if (!input.verify(certificate))
- {
- throw new WebApplicationException(500);
- }
- }
-
-// client side
-
- ClientRequest request = new ClientRequest("http://localhost:9095/smime/signed");
- SignedInput input = request.getTarget(SignedInput.class);