[jboss-cvs] JBossAS SVN: r91859 - projects/docs/enterprise/5.0/RESTEasy/en-US.
jboss-cvs-commits at lists.jboss.org
jboss-cvs-commits at lists.jboss.org
Thu Jul 30 22:20:42 EDT 2009
Author: laubai
Date: 2009-07-30 22:20:42 -0400 (Thu, 30 Jul 2009)
New Revision: 91859
Modified:
projects/docs/enterprise/5.0/RESTEasy/en-US/Atom.xml
projects/docs/enterprise/5.0/RESTEasy/en-US/Content_Marshalling_Providers.xml
projects/docs/enterprise/5.0/RESTEasy/en-US/Migration_from_older_versions.xml
projects/docs/enterprise/5.0/RESTEasy/en-US/RESTEasy_Reference_Guide.xml
Log:
Revised files.
Modified: projects/docs/enterprise/5.0/RESTEasy/en-US/Atom.xml
===================================================================
--- projects/docs/enterprise/5.0/RESTEasy/en-US/Atom.xml 2009-07-31 01:41:53 UTC (rev 91858)
+++ projects/docs/enterprise/5.0/RESTEasy/en-US/Atom.xml 2009-07-31 02:20:42 UTC (rev 91859)
@@ -56,11 +56,9 @@
<section id="jaxb_atom">
<title>Using JAXB with the Atom Provider</title>
<para>
- The <classname>org.jboss.resteasy.plugins.providers.atom.Content</classname> class allows you to unmarshal and marshal JAXB
- annotated objects that are the body of the content. Here's an example of sending an Entry with
- a Customer object attached as the body of the entry's content.
+ The <classname>org.jboss.resteasy.plugins.providers.atom.Content</classname> class lets you marshal and unmarshal JAXB-annotated objects that form the body of an entry's content. The following code is an example of sending an <literal>Entry</literal> with a <literal>Customer</literal> object attached as the body of the entry's content.
</para>
- <programlisting><![CDATA[
+ <programlisting><![CDATA[
@XmlRootElement(namespace = "http://jboss.org/Customer")
@XmlAccessorType(XmlAccessType.FIELD)
public class Customer
@@ -99,19 +97,14 @@
return entry;
}
}
-]]></programlisting>
+]]></programlisting>
<para>
- The Content.setJAXBObject() method is used to tell the content object you are sending back
- a Java JAXB object and want it marshalled appropriately. If you are using a different base
- format other than XML, i.e. "application/atom+json", this attached JAXB object will be marshalled
- into that same format.
+ The <literal>Content.setJAXBObject()</literal> method tells the content object that you are returning a Java JAXB object to be marshalled. If you use a base format other than XML (for example, <literal>application/atom+json</literal>), the attached JAXB object will be marshalled into that format.
</para>
<para>
- If you have an atom document as your input, you can also extract JAXB objects from Content using the
- Content.getJAXBObject(Class clazz) method. Here is an example of an input atom document and extracting
- a Customer object from the content.
+ If your input is an Atom document, you can also extract JAXB objects from <literal>Content</literal> by using <code>Content.getJAXBObject(Class clazz)</code>. The code that follows is an example of extracting a <literal>Customer</literal> object from the <literal>Content</literal>:
</para>
- <programlisting><![CDATA[
+ <programlisting><![CDATA[
@Path("atom")
public static class AtomServer
{
@@ -124,39 +117,35 @@
Customer cust = content.getJAXBObject(Customer.class);
}
}
-]]></programlisting>
+]]></programlisting>
</section>
<section id="Abdera">
<title>Atom support through Apache Abdera</title>
<para>
- Resteasy provides support for Apache Abdera, an implementation of the Atom protocol and data format.
- http://incubator.apache.org/abdera/
+ RESTEasy supports Apache Abdera, an implementation of the Atom protocol and data format. You can find Abdera at the <ulink url="http://incubator.apache.org/abdera/">Apache web site</ulink>.
</para>
<para>
- Abdera is a full-fledged Atom server. Resteasy only supports integration with JAX-RS for Atom data format
- marshalling and unmarshalling to and from the Feed and Entry interface types in Abdera. Here's a simple example:
+ Abdera is a fully-fledged Atom server, but RESTEasy only supports integration with JAX-RS for marshalling and unmarshalling the Atom data format to and from the <classname>Feed</classname> and <classname>Entry</classname> interface types in Abdera.
</para>
<section id="Abdera and Maven">
<title>Abdera and Maven</title>
- <para>The Abdera provider is not included with the Resteasy distribution. To include the Abdera provider
- in your WAR poms, include the following. Please change the version to be the version of resteasy you
- are working with. Also, Resteasy may be coded to pick up an older version of Abdera than what you want. You're
- on your own with fixing this one, sorry.
+ <para>The Abdera provider is not included with the RESTEasy distribution. To include the Abdera provider in your WAR archive's <filename>pom</filename> files, add the following. Remember to change the version in the code to the version of RESTEasy that you are working with.</para>
+ <warning><para>RESTEasy may not pick up the latest version of Abdera.</para></warning>
</para>
- <programlisting><![CDATA[
- <repository>
- <id>jboss</id>
- <url>http://repository.jboss.org/maven2</url>
- </repository>
+ <programlisting><![CDATA[
+ <repository>
+ <id>jboss</id>
+ <url>http://repository.jboss.org/maven2</url>
+ </repository>
...
- <dependency>
- <groupId>org.jboss.resteasy</groupId>
- <artifactId>abdera-atom-provider</artifactId>
- <version>...version...</version>
- </dependency>
-]]></programlisting>
+ <dependency>
+ <groupId>org.jboss.resteasy</groupId>
+ <artifactId>abdera-atom-provider</artifactId>
+ <version>...version...</version>
+ </dependency>
+]]></programlisting>
</section>
<section id="using_abdera">
<title>Using the Abdera Provider</title>
@@ -190,7 +179,7 @@
import java.util.Date;
/**
- * @author <a href="mailto:bill at burkecentral.com">Bill Burke</a>
+ * @author <a href="mailto:bill at burkecentral.com">Bill Burke</a>
* @version $Revision: 1 $
*/
public class AbderaTest extends BaseResourceTest
Modified: projects/docs/enterprise/5.0/RESTEasy/en-US/Content_Marshalling_Providers.xml
===================================================================
--- projects/docs/enterprise/5.0/RESTEasy/en-US/Content_Marshalling_Providers.xml 2009-07-31 01:41:53 UTC (rev 91858)
+++ projects/docs/enterprise/5.0/RESTEasy/en-US/Content_Marshalling_Providers.xml 2009-07-31 02:20:42 UTC (rev 91859)
@@ -3,16 +3,13 @@
]>
<chapter id="Content_Marshalling_Providers">
<title>Content Marshalling/Providers</title>
- <sect1 id="Default_Providers_and_default_JAX-RS_Content_Marshalling">
+ <section id="Default_Providers_and_default_JAX-RS_Content_Marshalling">
<title>Default Providers and default JAX-RS Content Marshalling</title>
<para>
-
- Resteasy can automatically marshal and unmarshal a few different message bodies.
+ RESTEasy can automatically marshal and unmarshal several different message body types.
</para>
- <para>
-
- <table frame="topbot">
+ <table frame="topbot"><title>Message Body Types</title>
<tgroup cols="2" rowsep="1" colsep="1">
<thead>
<row>
@@ -54,7 +51,7 @@
text/plain
</entry>
<entry>
- primtives, java.lang.String, or any type that has a String constructor, or static
+ primitives, java.lang.String, or any type that has a String constructor, or static
valueOf(String) method for input, toString() for output
</entry>
</row>
@@ -93,55 +90,29 @@
</tbody>
</tgroup>
</table>
-
- </para>
- <para>
-
- </para>
- <para>
-
- </para>
- <para>
-
-
- </para>
- </sect1>
- <sect1 id="Content_Marshalling_with__Provider_classes">
+
+ </section>
+ <section id="Content_Marshalling_with__Provider_classes">
<title>Content Marshalling with @Provider classes</title>
<para>
-
- The JAX-RS specification allows you to plug in your own request/response body reader and writers. To do this,
- you annotate a class
- with @Provider and specify the @Produces types for a writer and @Consumes types for a reader. You must
- also implement
- a MessageBodyReader/Writer interface respectively. Here is an example.
+ The JAX-RS specification lets you plug in your own readers and writers for request or reponse bodies. To do so, annotate a class with <literal>@Provider</literal> and specify the <literal>@Produces</literal> types for a reader. You must also implement a <literal>MessageBodyReader</literal> and a <literal>MessageBodyWriter</literal> interface. <!--#modify Example! What example! Removing description of invisible example as well.-->
</para>
- <para>
+ <!--<para>
The Resteasy ServletContextLoader will automatically scan your WEB-INF/lib and classes directories for classes
annotated with @Provider or you can manually configure them in web.xml. See Installation/Configuration
- </para>
- <para>
-
-
- </para>
- </sect1>
- <sect1 id="MessageBodyWorkers">
+ </para>-->
+ </section>
+ <section id="MessageBodyWorkers">
<title>Providers Utility Class</title>
<para>
-
- javax.ws.rs.ext.Providers is a simple injectable interface that allows you to look up MessageBodyReaders,
- Writers, ContextResolvers, and ExceptionMappers. It is very useful, for instance, for implementing
- multipart providers. Content types that embed
- other random content types.
+ <literal>javax.ws.rs.ext.Providers</literal> is a simple injectable interface that lets you locate <literal>MessageBodyReader</literal>s, <literal>MessageBodyWriter</literal>s, <literal>ContextResolver</literal>s and <literal>ExceptionMapper</literal>s. It also lets you implement multi-part providers (content types that embed other content types).
</para>
- <para>
-
<programlisting>
-<![CDATA[
+<![CDATA[
public interface Providers
{
@@ -153,7 +124,7 @@
* {@code type} is assignable to the generic type of the reader, and
* eliminating those that do not match.
* The list of matching readers is then ordered with those with the best
- * matching values of {@link javax.ws.rs.Consumes} (x/y > x/* > */*)
+ * matching values of {@link javax.ws.rs.Consumes} (x/y > x/* > */*)
* sorted first. Finally, the
* {@link MessageBodyReader#isReadable}
* method is called on each reader in order using the supplied criteria and
@@ -164,16 +135,16 @@
* @param genericType the type of object to be produced. E.g. if the
* message body is to be converted into a method parameter, this will be
* the formal type of the method parameter as returned by
- * <code>Class.getGenericParameterTypes</code>.
+ * <code>Class.getGenericParameterTypes</code>.
* @param annotations an array of the annotations on the declaration of the
* artifact that will be initialized with the produced instance. E.g. if the
* message body is to be converted into a method parameter, this will be
* the annotations on that parameter returned by
- * <code>Class.getParameterAnnotations</code>.
+ * <code>Class.getParameterAnnotations</code>.
* @return a MessageBodyReader that matches the supplied criteria or null
* if none is found.
*/
- <T> MessageBodyReader<T> getMessageBodyReader(Class<T> type,
+ <T> MessageBodyReader<T> getMessageBodyReader(Class<T> type,
Type genericType, Annotation annotations[], MediaType mediaType);
/**
@@ -184,7 +155,7 @@
* {@code type} is assignable to the generic type of the reader, and
* eliminating those that do not match.
* The list of matching writers is then ordered with those with the best
- * matching values of {@link javax.ws.rs.Produces} (x/y > x/* > */*)
+ * matching values of {@link javax.ws.rs.Produces} (x/y > x/* > */*)
* sorted first. Finally, the
* {@link MessageBodyWriter#isWriteable}
* method is called on each writer in order using the supplied criteria and
@@ -195,16 +166,16 @@
* @param genericType the type of object to be written. E.g. if the
* message body is to be produced from a field, this will be
* the declared type of the field as returned by
- * <code>Field.getGenericType</code>.
+ * <code>Field.getGenericType</code>.
* @param annotations an array of the annotations on the declaration of the
* artifact that will be written. E.g. if the
* message body is to be produced from a field, this will be
* the annotations on that field returned by
- * <code>Field.getDeclaredAnnotations</code>.
+ * <code>Field.getDeclaredAnnotations</code>.
* @return a MessageBodyReader that matches the supplied criteria or null
* if none is found.
*/
- <T> MessageBodyWriter<T> getMessageBodyWriter(Class<T> type,
+ <T> MessageBodyWriter<T> getMessageBodyWriter(Class<T> type,
Type genericType, Annotation annotations[], MediaType mediaType);
/**
@@ -216,7 +187,7 @@
* @return an {@link ExceptionMapper} for the supplied type or null if none
* is found.
*/
- <T extends Throwable> ExceptionMapper<T> getExceptionMapper(Class<T> type);
+ <T extends Throwable> ExceptionMapper<T> getExceptionMapper(Class<T> type);
/**
* Get a context resolver for a particular type of context and media type.
@@ -227,7 +198,7 @@
* eliminating those that do not match. If only one resolver matches the
* criteria then it is returned. If more than one resolver matches then the
* list of matching resolvers is ordered with those with the best
- * matching values of {@link javax.ws.rs.Produces} (x/y > x/* > */*)
+ * matching values of {@link javax.ws.rs.Produces} (x/y > x/* > */*)
* sorted first. A proxy is returned that delegates calls to
* {@link ContextResolver#getContext(java.lang.Class)} to each matching context
* resolver in order and returns the first non-null value it obtains or null
@@ -238,23 +209,17 @@
* @return a matching context resolver instance or null if no matching
* context providers are found.
*/
- <T> ContextResolver<T> getContextResolver(Class<T> contextType,
+ <T> ContextResolver<T> getContextResolver(Class<T> contextType,
MediaType mediaType);
}
-]]>
+]]>
</programlisting>
- </para>
+
<para>
-
+ You can inject an instance of <literal>Providers</literal> into <literal>MessageBodyReader</literal> or <literal>MessageBodyWriter</literal> like so:
</para>
- <para>
-
- A Providers instance is injectable into MessageBodyReader or Writers:
- </para>
- <para>
-
- <programlisting>
+ <programlisting>
@Provider
@Consumes("multipart/fixed")
public class MultipartProvider implements MessageBodyReader {
@@ -265,10 +230,6 @@
}
</programlisting>
- </para>
- <para>
-
- </para>
- </sect1>
+ </section>
</chapter>
Modified: projects/docs/enterprise/5.0/RESTEasy/en-US/Migration_from_older_versions.xml
===================================================================
--- projects/docs/enterprise/5.0/RESTEasy/en-US/Migration_from_older_versions.xml 2009-07-31 01:41:53 UTC (rev 91858)
+++ projects/docs/enterprise/5.0/RESTEasy/en-US/Migration_from_older_versions.xml 2009-07-31 02:20:42 UTC (rev 91859)
@@ -5,47 +5,43 @@
<title>Migration from older versions</title>
<section id="Migrating_to_Resteasy_Beta_6">
<title>Migrating from 1.0.x and 1.1-RC1</title>
-
- <itemizedlist>
-
+ <para>You can expect the following changes when you migrate to the latest version of RESTEasy:</para>
+ <itemizedlist>
<listitem>
- <para>You now turn on Resteasy role-based security i.e. @RolesAllowed, by using the new resteasy.role.based.security context-param.</para>
+ <para>
+ You can now turn on RESTEasy's role-based security (<literal>@RolesAllowed</literal>) by using the new <literal>resteasy.role.based.security context-param</literal>.</para>
</listitem>
<listitem>
- <para>@Wrapped is now on by default for lists and arrays and sets of JAXB objects. You can also change the namepace and element names using this annotation.</para>
+ <para><literal>@Wrapped</literal> is now enabled by default for Lists, Arrays, and Sets of JAXB objects. You can also change the namespace and element names with this annotation.</para>
</listitem>
<listitem>
- <para>@Wrapped no longer is enclosed in a resteasy namespace prefix nor uses the http://jboss.org/resteasy namespace. Its just the default namespace.</para>
+ <para><literal>@Wrapped</literal> is not enclosed in a RESTEasy namespace prefix, and now uses the default namespace instead of the <literal>http://jboss.org/resteasy</literal> namespace.</para>
</listitem>
<listitem>
- <para>@Wrapped JSON is now enclosed in a simple JSON array</para>
+ <para><literal>@Wrapped JSON</literal> is now enclosed in a simple JSON Array.</para>
</listitem>
<listitem>
- <para>If you have the resteasy-jackson-provider-xxx.jar in your classpath, the Jackson JSON provider
- will be triggered. This will screw up code that is dependent on the Jettison JAXB/JSon provider.
- If you had been using the Jettison JAXB/Json providers, you must either remove
- Jackson from your WEB-INF/lib or classpath, or use the @NoJackson annotation on your JAXB classes.</para>
+ <para>Placing the <filename>resteasy-jackson-provider-xxx.jar</filename> in your classpath triggers the Jackson JSON provider. This can cause code errors if you had previously been using the Jettison JAXB/JSON providers. To fix this, you must either remove Jackson from your <filename>WEB-INF/lib</filename> or the classpath, or use the <literal>@NoJackson</literal> annotation on your JAXB classes.</para>
</listitem>
<listitem>
- <para>The tjws and servlet-api artifacts are now scoped "provided" in the resteasy-jar dependencies. You may
- have to include and scope them as "provided" or "test" within your poms if you are getting class not found errors.</para>
+ <para>
+ The <literal>tjws</literal> and <literal>servlet-api</literal> artifacts are now scoped as <emphasis>provided</emphasis> in the <literal>resteasy-jar</literal> dependencies. If you have trouble with <emphasis>Class not found</emphasis> errors, you may need to scope them as <literal>provided</literal> or <literal>test</literal> in your <filename>pom</literal> files.</para>
<programlisting>
-<![CDATA[
- <dependency>
- <groupId>javax.servlet</groupId>
- <artifactId>servlet-api</artifactId>
- <scope>provided</scope>
- </dependency>
- <dependency>
- <groupId>tjws</groupId>
- <artifactId>webserver</artifactId>
- <scope>provided</scope>
- </dependency>
-]]>
+<![CDATA[
+ <dependency>
+ <groupId>javax.servlet</groupId>
+ <artifactId>servlet-api</artifactId>
+ <scope>provided</scope>
+ </dependency>
+ <dependency>
+ <groupId>tjws</groupId>
+ <artifactId>webserver</artifactId>
+ <scope>provided</scope>
+ </dependency>
+]]>
</programlisting>
</listitem>
</itemizedlist>
-
</section>
</chapter>
Modified: projects/docs/enterprise/5.0/RESTEasy/en-US/RESTEasy_Reference_Guide.xml
===================================================================
--- projects/docs/enterprise/5.0/RESTEasy/en-US/RESTEasy_Reference_Guide.xml 2009-07-31 01:41:53 UTC (rev 91858)
+++ projects/docs/enterprise/5.0/RESTEasy/en-US/RESTEasy_Reference_Guide.xml 2009-07-31 02:20:42 UTC (rev 91859)
@@ -53,9 +53,9 @@
<xi:include href="_Context.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
<xi:include href="JAX-RS_Resource_Locators_and_Sub_Resources.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
<xi:include href="JAX-RS_Content_Negotiation.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
- <!--<xi:include href="Content_Marshalling_Providers.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />-->
+ <xi:include href="Content_Marshalling_Providers.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
<xi:include href="Jaxb.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
-<!--<xi:include href="Atom.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />-->
+<xi:include href="Atom.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
<xi:include href="Json.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
<xi:include href="Multipart.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
<xi:include href="Yaml.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
@@ -78,7 +78,7 @@
<xi:include href="RESTEasy_Client_Framework.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
<xi:include href="Maven_and_RESTEasy.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
<xi:include href="JBoss.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
-<!-- <xi:include href="Migration_from_older_versions.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />-->
+ <xi:include href="Migration_from_older_versions.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
<xi:include href="Revision_History.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
</book>
More information about the jboss-cvs-commits
mailing list