RESTEasy 系列 Chapter 3 Installation/Configuration 安装/配置

 

RESTEasy安装和配置的不同方式取决于你正在运行的环境。 如果你正运行在JBoss AS 6-M4 (milestone 4)或更高版本，resteasy已经完全集成和绑定，所以你只要做少量的工作。如果你正运行在一个不同的分布环境下，你需要做一些手工的安装和配置。

 

3.1.独立的Resteasy

 

如果你在JBoss AS 6外使用resteasy, 你需要手动做一些步聚来安装和配置resteasy. RESTeasy 部署的是一个WAR 文件所以依赖于一个Servlet容器。我们强烈建议你使用Maven来构建你的WAR文件，RESTEasy被拆分成多个不同的模块。你可以看一个Maven项目的例子，这个例子在examples/ 目录。

 

另外, 当你下载RESTeasy 并解压缩它的时候，你会看到一个lib/目录，它个包含了RESTeasy 所需要的库。拷贝它们到你的/WEB-INF/lib目录。将带JAX-RS注解的class源文件和提供者打到一个或多个jar包内放到/WEB-INF/lib，或者把你的原始class文件放在/WEB-INF/classes。

 

RESTeasy作为一个Servlet 实现部署在WAR文件中。 如果你打开一个下载的RESTeasy示例项目的WEB-INF/web.xml ，你会看到：

 

<web-app>
    <display-name>Archetype Created Web Application</display-name>
    <servlet>
        <servlet-name>Resteasy</servlet-name>
        <servlet-class>org.jboss.resteasy.plugins.server.servlet.HttpServletDispatcher</servlet-class>
        <init-param>
            <param-name>javax.ws.rs.Application</param-name>
            <param-value>com.restfully.shop.services.ShoppingApplication</param-value>
        </init-param>
    </servlet>
    <servlet-mapping>
        <servlet-name>Resteasy</servlet-name>
        <url-pattern>/*</url-pattern>
    </servlet-mapping>
</web-app>

 这个Resteasy的servlet负责初始化RESTeasy的一些基本组件。

 

 

3.2. 配置开关

Resteasy 接收配置选项来自于 <context-param> 元素。 

 

表3.1

配置参数名称	默认值	描述
resteasy.servlet.mapping.prefix	no default	如果Resteasy 的 servlet-mapping 配置的url-pattern 不是 /*
resteasy.scan	false	自动扫描 WEB-INF/lib 目录下的jar文件和 WEB-INF/classes 目录下标识了 @Provider 和 JAX-RS 注解(@Path, @GET, @POST etc..) 的类资源文件，并且注册它们。
resteasy.scan.providers	false	扫描 @Provider 类文件并注册它们
resteasy.scan.resources	false	扫描 JAX-RS 类源文件
resteasy.providers	no default	你想要注册的一个以逗号分隔，标识@Provider的完整类名的列表
resteasy.use.builtin.providers	true	无论是否默认注册, 内置 @Provider 类。 (只在 1.0-beta-5 或更高版本可用)
resteasy.resources	no default	你想要注册的一个以逗号分隔，标识 JAX-RS 的完整的类名列表
resteasy.jndi.resources	no default	你想要注册的 JAX-RS 资源，一个以逗号分隔的引用对象的JNDI名称
javax.ws.rs.Application	no default	一个应用程序类的完整名称，用来引导一个规范的可移植方式
resteasy.media.type.mappings	no default	Replaces the need for an Accept header by mapping file name extensions (like .xml or .txt) to a media type. Used when the client is unable to use a Accept header to choose a representation (i.e. a browser). See JAX-RS Content Negotiation chapter for more details.
resteasy.language.mappings	no default	Replaces the need for an Accept-Language header by mapping file name extensions (like .en or .fr) to a language. Used when the client is unable to use a Accept-Language header to choose a language (i.e. a browser). See JAX-RS Content Negotiation chapter for more details
resteasy.document.expand.entity.references	true	Expand external entities in org.w3c.dom.Document files

 

 

如果你的RESTEasy 配置的servlet-mapping的url-pattern有一个不是/*的映射，RESTEasy 的 servlet mapping前缀<context param>变量必须设置。

在例子当中， 如果 url-pattern 是：

 

<servlet-mapping>
    <servlet-name>Resteasy</servlet-name>
    <url-pattern>/restful-services/*</url-pattern>
</servlet-mapping>

 那么Resteasy-servlet.mapping的前缀必须是：

 

<context-param>
    <param-name>resteasy.servlet.mapping.prefix</param-name>
    <param-value>/restful-services</param-value>
</context-param>

 

3.3. javax.ws.rs.core.Application

javax.ws.rs.core.Application 类是一个标准的 JAX-RS 类，你可以在你的部署中实现以提供信息。这是一个简单的类列出了所有 JAX-RS 根资源和供应者。

 

/**
* Defines the components of a JAX-RS application and supplies additional
* metadata. A JAX-RS application or implementation supplies a concrete
* subclass of this abstract class.
*/
public abstract class Application {
    private static final Set<Object> emptySet = Collections.emptySet();


    /**
    * Get a set of root resource and provider classes. The default lifecycle
    * for resource class instances is per-request. The default lifecycle for
    * providers is singleton.
    * <p/>
    * <p>Implementations should warn about and ignore classes that do not
    * conform to the requirements of root resource or provider classes.
    * Implementations should warn about and ignore classes for which
    * {@link #getSingletons()} returns an instance. Implementations MUST
    * NOT modify the returned set.</p>
    *
    * @return a set of root resource and provider classes. Returning null
    * is equivalent to returning an empty set.
    */
    public abstract Set<Class<?>> getClasses();


    /**
    * Get a set of root resource and provider instances. Fields and properties
    * of returned instances are injected with their declared dependencies
    * (see {@link Context}) by the runtime prior to use.
    * <p/>
    * <p>Implementations should warn about and ignore classes that do not
    * conform to the requirements of root resource or provider classes.
    * Implementations should flag an error if the returned set includes
    * more than one instance of the same class. Implementations MUST
    * NOT modify the returned set.</p>
    * <p/>
    * <p>The default implementation returns an empty set.</p>
    *
    * @return a set of root resource and provider instances. Returning null
    * is equivalent to returning an empty set.
    */
    public Set<Object> getSingletons() {
        return emptySet;
    }



}

 

在应用程序中使用你必须设置一个servlet init-param, javax.ws.rs.Application 是一个完全符合条件的类，它实现了应用。例如：

 

    <servlet>
        <servlet-name>Resteasy</servlet-name>
        <servlet-class>org.jboss.resteasy.plugins.server.servlet.HttpServletDispatcher</servlet-class>
        <init-param>
            <param-name>javax.ws.rs.Application</param-name>
            <param-value>com.restfully.shop.services.ShoppingApplication</param-value>
        </init-param>
    </servlet>

 

如果你有这些设置，你应该关闭自动扫描功能， 因为这可能导致类被重复注册。

 

3.4. RESTEasy 作为 ServletContextListener

RESTEasy 可以使用 ServletContextListener 代替 Servlet 执行初始化。如果你正在编写自定义的监听器需要在启动时和RESTEasy进行交互，你可能会需要它。这方面的一个例子是RESTEasy和Spring的集成需要一个Spring的ServletContextListener。org.jboss.resteasy.plugins.server.servlet.ResteasyBootstrap类是一个ServletContextListener，它配置一个ResteasyProviderFactory和Registry的实例。你可以获取一个 ResteasyProviderFactory 和 Registry 的实例来自于 ServletContext attributes org.jboss.resteasy.spi.ResteasyProviderFactory 和 org.jboss.resteasy.spi.Registry。有了这些实例你可以通过 RESTEasy 注册接口进行交互编程。

 

    <web-app>
        <listener>
            <listener-class>org.jboss.resteasy.plugins.server.servlet.ResteasyBootstrap</listener-class>
        </listener>
        <!-- ** INSERT YOUR LISTENERS HERE!!!! -->
        <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>/resteasy/*</url-pattern>
        </servlet-mapping>
    </web-app>

 

3.5. RESTEasy 作为 servlet Filter

Resteasy作为一个servlet运行的缺点是你不能拥有静态资源像.html和.jpeg文件在你的JAX-RS服务相同的目录。Resteasy允许你作为一个Filter来代替运行。如果JAX-RS资源请求的URL没有找到，Resteasy将委托回到基础的servlet容器解析URL。

 

    <web-app>
        <filter>
            <filter-name>Resteasy</filter-name>
            <filter-class>org.jboss.resteasy.plugins.server.servlet.FilterDispatcher</filter-class>
            <init-param>
                <param-name>javax.ws.rs.Application</param-name>
                <param-value>com.restfully.shop.services.ShoppingApplication</param-value>
            </init-param>
        </filter>
        <filter-mapping>
            <filter-name>Resteasy</filter-name>
            <url-pattern>/*</url-pattern>
        </filter-mapping>
    </web-app>

 

3.6. 补丁 JBoss AS 7

Resteasy 和 JBoss AS 7是捆绑的。你可能会需要升级 Resteasy 的 AS7。该Resteasy的分发带有一个zip文件，全名为resteasy-jboss-modules-2.3.5.Final.zip。在JBoss AS 7的顶级目录（一个模块/目录），解压该文件，你应该在最新的和最伟大的Resteasy后面打上该补丁。

 

3.7. 配置 JBoss AS 7

 

Resteasy 和 JBoss AS 7是捆绑并且完全集成的需要Java EE 6。首先你必须至少提供一个空的web.xml文件。当然你可以部署任意你想要的自定义servlet，filter或security constraint 在 web.xml。但是工作的最少需求是创建一个空的web.xml文件。此外，resteasy的context-params 是可用的，如果你想要调整开启/关闭任何特定的resteasy特性。

 

    <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>

 

因为我们没有使用 jax-rs servlet 映射，我们必须定义一个带有@ApplicationPath注解的应用类。如果你返回任何空集的类和单例对象，你的WAR将扫描JAX-RS注解资源和供应类。

 

import javax.ws.rs.ApplicationPath;
import javax.ws.rs.core.Application;

@ApplicationPath("/root-path")
public class MyApplication extends Application {
}

 

 "Restful Java" O'Reilly workbook AS7例子已经有Resteasy的分发。你能在目录examples/oreilly-workbook-as7 下找到它们。

 

3.8. RESTEasy 日志

RESTEasy 支持日志，通过 java.util.logging, Log4j, 或 Slf4j。如何挑选一个具体的框架来委托由下面的算法来表示：

 

• 如果 log4j 在应用的 classpath中, 使用log4j 
• 如果 slf4j 在应用的classpath中, 使用slf4j
• java.util.logging 是默认的，如果 log4j 和 slf4j 没有在 classpath 中
• 如果servlet 上下文 参数 resteasy.logger.type 设置了 JUL, LOG4J 或 SLF4J 默认的行为将被覆盖 

日志记录类别是一个进行中的工作，但最初的设置应该更容易解决问题，目前，框架定义了以下日志分类：

 

表3.2

分类	功能
org.jboss.resteasy.core	记录所有RESTEasy核心活动的实现
org.jboss.resteasy.plugins.providers	记录所有RESTEasy实体提供活动
org.jboss.resteasy.plugins.server	记录所有RESTEasy服务器上活动实现
org.jboss.resteasy.specimpl	记录所有JAX-RS实现类的活动
org.jboss.resteasy.mock	记录所有RESTEasy模拟框架活动