Skip to content

Commit

Permalink
Merge pull request #242 from patriot1burke/master
Browse files Browse the repository at this point in the history 
docs
  • Loading branch information
@patriot1burke
patriot1burke committed Jan 24, 2013
2 parents 119ae2d + ce59338 commit 6590d5a
Show file tree
Hide file tree
Showing 9 changed files with 321 additions and 56 deletions.
273 changes: 227 additions & 46 deletions jaxrs/docbook/reference/en/en-US/modules/Installation_Configuration.xml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -10,10 +10,236 @@

</para>

<sect1 id="upgrading-as7">
<title>Upgrading Resteasy Within JBoss AS 7</title>
<para>
Resteasy is bundled with JBoss AS 7. You will likely have the need to upgrade Resteasy in AS7. The Resteasy
distribution comes with a zip file called resteasy-jboss-modules-3.0-beta-2.zip. Unzip this file while
with the modules/ directory of the JBoss AS7 distribution. This will overwrite some of the existing files there.
</para>
</sect1>
<sect1>
<title>Configuring in JBoss AS 7</title>
<para>
RESTEasy is bundled with JBoss AS 7 and completely integrated as per the requirements of Java EE 6.
First you must at least provide an empty web.xml file. You can of course deploy any custom servlet, filter
or security constraint you want to within your web.xml, but the least amount of work is to create an empty
web.xml file. Also, resteasy context-params are available if you want to tweak turn on/off any specific
resteasy feature.
</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>
<para>
Since we're not using a jax-rs servlet mapping, we must define an Application class that is annotated with
the @ApplicationPath annotation. If you return any empty set for by classes and singletons, your WAR will
be scanned for JAX-RS annotation resource and provider classes.
</para>
<programlisting>
import javax.ws.rs.ApplicationPath;
import javax.ws.rs.core.Application;

@ApplicationPath("/root-path")
public class MyApplication extends Application
{
}
</programlisting>
<para>
The Resteasy distribution has ported the "Restful Java" O'Reilly workbook examples to AS7. You can
find these under the directory examples/oreilly-workbook-as7.
</para>
</sect1>
<section>
<title>Resteasy Modules in AS7</title>
<para>
Resteasy and JAX-RS are automically loaded into your deployment's classpath, if and only if you are deploying
a JAX-RS Application. If you only want to use the client library, you will have to create a dependency
for it within your deployment. Also, only some resteasy features are automatically loaded. To bring
in these libraries, you'll have to create a jboss-deployment-structure.xml file within your WEB-INF
directory of your WAR file. Here's an example:
</para>
<programlisting>
<![CDATA[
<jboss-deployment-structure>
<deployment>
<dependencies>
<module name="org.jboss.resteasy.resteasy-yaml-provider" services="import"/>
</dependencies>
</deployment>
</jboss-deployment-structure>]]>

</programlisting>
<para>The <literal>services</literal> attribute must be set to import for modules that have default providers
that must be registered. The following
table specifies which modules are loaded by default when JAX-RS services are deployed and which aren't.
</para>
<para>
<table>
<tgroup cols="3" rowsep="1" colsep="1">
<thead>
<row>
<entry>
Module Name
</entry>
<entry>
Loaded by Default
</entry>
<entry>
Description
</entry>

</row>
</thead>
<tbody>
<row>
<entry>
org.jboss.resteasy.resteasy-jaxrs
</entry>
<entry>
yes
</entry>
<entry>
Core resteasy libraries for server and client. You will need to include this in your deployment
if you are only using JAX-RS client
</entry>
</row>
<row>
<entry>
org.jboss.resteasy.resteasy-cdi
</entry>
<entry>
yes
</entry>
<entry>
Resteasy CDI integration
</entry>
</row>
<row>
<entry>
org.jboss.resteasy.resteasy-jaxb-provider
</entry>
<entry>
yes
</entry>
<entry>
XML JAXB integration.
</entry>
</row>
<row>
<entry>
org.jboss.resteasy.resteasy-atom-provider
</entry>
<entry>
yes
</entry>
<entry>
Resteasy's atom library.
</entry>
</row>
<row>
<entry>
org.jboss.resteasy.resteasy-jackson-provider
</entry>
<entry>
yes
</entry>
<entry>
Integration with the JSON parser and object mapper, Jackson.
</entry>
</row>
<row>
<entry>
org.jboss.resteasy.resteasy-jsapi
</entry>
<entry>
yes
</entry>
<entry>
Resteasy's Javascript API.
</entry>
</row>
<row>
<entry>
org.jboss.resteasy.resteasy-multipart-provider
</entry>
<entry>
yes
</entry>
<entry>
Features for dealing with multipart formats.
</entry>
</row>
<row>
<entry>
org.jboss.resteasy.resteasy-crypto
</entry>
<entry>
no
</entry>
<entry>
S/MIME, DKIM, and support for other security formats.
</entry>
</row>
<row>
<entry>
org.jboss.resteasy.jose-jwt
</entry>
<entry>
no
</entry>
<entry>
JOSE-JWT library. JSON Web Token.
</entry>
</row>
<row>
<entry>
org.jboss.resteasy.resteasy-jettison-provider
</entry>
<entry>
no
</entry>
<entry>
Alternative JAXB-like parser for JSON.
</entry>
</row>
<row>
<entry>
org.jboss.resteasy.resteasy-yaml-provider
</entry>
<entry>
no
</entry>
<entry>
YAML marshalling.
</entry>
</row>
<row>
<entry>
org.jboss.resteasy.skeleton-key
</entry>
<entry>
no
</entry>
<entry>
OAuth2 support for AS7.
</entry>
</row>
</tbody>
</tgroup>
</table>
</para>
</section>
<sect1>
<title>Standalone Resteasy</title>
<para>
If you are using resteasy outside of JBoss AS 6, you will need to do a few manual steps to install and
If you are using resteasy outside of JBoss AS 7, you will need to do a few manual steps to install and
configure resteasy.
RESTeasy is deployed as a WAR archive and thus depends on a Servlet container. We strongly suggest that you
use Maven to build your WAR files as RESTEasy is split into
Expand Down Expand Up @@ -427,52 +653,7 @@
</web-app>]]>
</programlisting>
</sect1>
<sect1 id="upgrading-as7">
<title>Upgrading Resteasy Within JBoss AS 7</title>
<para>
Resteasy is bundled with JBoss AS 7. You will likely have the need to upgrade Resteasy in AS7. The Resteasy
distribution comes with a zip file called resteasy-jboss-modules-3.0-beta-2.zip. Unzip this file while
with the modules/ directory of the JBoss AS7 distribution. This will overwrite some of the existing files there.
</para>
</sect1>
<sect1>
<title>Configuring in JBoss AS 7</title>
<para>
RESTEasy is bundled with JBoss AS 7 and completely integrated as per the requirements of Java EE 6.
First you must at least provide an empty web.xml file. You can of course deploy any custom servlet, filter
or security constraint you want to within your web.xml, but the least amount of work is to create an empty
web.xml file. Also, resteasy context-params are available if you want to tweak turn on/off any specific
resteasy feature.
</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>
<para>
Since we're not using a jax-rs servlet mapping, we must define an Application class that is annotated with
the @ApplicationPath annotation. If you return any empty set for by classes and singletons, your WAR will
be scanned for JAX-RS annotation resource and provider classes.
</para>
<programlisting>
import javax.ws.rs.ApplicationPath;
import javax.ws.rs.core.Application;

@ApplicationPath("/root-path")
public class MyApplication extends Application
{
}
</programlisting>
<para>
The Resteasy distribution has ported the "Restful Java" O'Reilly workbook examples to AS7. You can
find these under the directory examples/oreilly-workbook-as7.
</para>
</sect1>
<sect1 id="RESTEasyLogging">
<title>RESTEasyLogging</title>

Expand Down
23 changes: 23 additions & 0 deletions jaxrs/docbook/reference/en/en-US/modules/OAuth2.xml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -171,6 +171,8 @@ oauthclient2=oauth,user
"realm-key-alias" : "mydomain",
"realm-keystore-password" : "password",
"realm-private-key-password" : "password",
"access-code-lifetime" : "300",
"token-lifetime" : "3600",
"truststore" : "${jboss.server.config.dir}/client-truststore.ts",
"truststore-password" : "password",
"resources" : [
Expand Down Expand Up @@ -257,6 +259,27 @@ oauthclient2=oauth,user
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>access-code-lifetime</term>
<listitem>
<para>
The access code is obtained via a browser redirect after you log into the central server.
This access code is then transmitted in a separate request to the auth server to obtain
an access token. This variable is the lifetime of this access code. In how many seconds
will it expire. You want to keep this value short. The default is 300 seconds.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>token-lifetime</term>
<listitem>
<para>
This is how long in seconds the access token is viable after it was first created. The
default is one hour. Depending on your security requirements you may want to extend
or shorten this default.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>truststore</term>
<listitem>
Expand Down
5 changes: 4 additions & 1 deletion jaxrs/jboss-modules/build.xml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -74,6 +74,10 @@
<maven-resource group="org.jboss.resteasy" artifact="resteasy-cdi"/>
</module-def>

<module-def name="org.jboss.resteasy.resteasy-crypto">
<maven-resource group="org.jboss.resteasy" artifact="resteasy-crypto" jandex="true"/>
</module-def>

<module-def name="org.jboss.resteasy.resteasy-jackson-provider">
<maven-resource group="org.jboss.resteasy" artifact="resteasy-jackson-provider" jandex="true"/>
</module-def>
Expand All @@ -90,7 +94,6 @@
<maven-resource group="org.jboss.resteasy" artifact="async-http-servlet-3.0"/>
<maven-resource group="org.jboss.resteasy" artifact="resteasy-jaxrs"/>
<maven-resource group="org.jboss.resteasy" artifact="resteasy-client"/>
<maven-resource group="org.jboss.resteasy" artifact="resteasy-crypto" jandex="true"/>
</module-def>

<module-def name="org.jboss.resteasy.jose-jwt">
Expand Down
1 change: 1 addition & 0 deletions jaxrs/jboss-modules/src/main/resources/modules/org/jboss/resteasy/jose-jwt/main/module.xml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -37,6 +37,7 @@
<module name="javax.enterprise.api"/>
<module name="javax.servlet.api"/>
<module name="javax.ws.rs.api"/>
<module name="org.jboss.resteasy.resteasy-crypto" services="import"/>
<module name="org.jboss.resteasy.resteasy-jaxrs"/>
<module name="org.jboss.resteasy.resteasy-jackson-provider"/>
</dependencies>
Expand Down
39 changes: 39 additions & 0 deletions ...oss-modules/src/main/resources/modules/org/jboss/resteasy/resteasy-crypto/main/module.xml
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,39 @@
<?xml version="1.0" encoding="UTF-8"?>

<!--
~ JBoss, Home of Professional Open Source.
~ Copyright 2010, Red Hat, Inc., and individual contributors
~ as indicated by the @author tags. See the copyright.txt file in the
~ distribution for a full listing of individual contributors.
~
~ This is free software; you can redistribute it and/or modify it
~ under the terms of the GNU Lesser General Public License as
~ published by the Free Software Foundation; either version 2.1 of
~ the License, or (at your option) any later version.
~
~ This software is distributed in the hope that it will be useful,
~ but WITHOUT ANY WARRANTY; without even the implied warranty of
~ MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
~ Lesser General Public License for more details.
~
~ You should have received a copy of the GNU Lesser General Public
~ License along with this software; if not, write to the Free
~ Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
~ 02110-1301 USA, or see the FSF site: http://www.fsf.org.
-->

<module xmlns="urn:jboss:module:1.1" name="org.jboss.resteasy.resteasy-crypto">
<resources>
<!-- Insert resources here -->
</resources>

<dependencies>
<module name="javax.mail.api"/>
<module name="org.apache.james.mime4j"/>
<module name="javax.api"/>
<module name="javax.servlet.api"/>
<module name="javax.ws.rs.api"/>
<module name="org.jboss.resteasy.resteasy-jaxrs"/>
<module name="org.bouncycastle" export="true"/>
</dependencies>
</module>
Loading

0 comments on commit 6590d5a

Please sign in to comment.