JRuby-Rack 技术文档

1. 安装指南

安装 Warbler

使用 Warbler 是最简单的将 JRuby-Rack 与 Java 服务器一起使用的方法。Warbler 依赖于最新版本的 JRuby-Rack，并确保在构建 WAR 文件时将其包含在内。

手动安装

如果使用其他方式手动构建 WAR 文件，可以安装 jruby-rack gem。它提供了一个方法来定位 jar 文件：

require 'jruby-rack'
FileUtils.cp JRubyJars.jruby_rack_jar_path, '.'

否则，需要下载最新的 jar 发行版，将其放入 WEB-INF/lib 目录中，并在应用程序的 web.xml 中配置 RackFilter（见以下示例）。

使用基于 JRuby-Rack 的服务器

也可以使用基于 JRuby-Rack 的服务器，例如 Trinidad，它具有默认设置，无需配置部署描述符。

2. 项目使用说明

Rails 项目配置

以下是 Rails 项目 web.xml 配置的示例。请注意环境和运行时参数。对于 多线程（即 threadsafe!）Rails，如果使用单个运行时，将 min/max 都设置为 1。否则，根据需要定义运行时池的大小。

<context-param>
  <param-name>rails.env</param-name>
  <param-value>production</param-value>
</context-param>
<context-param>
  <param-name>jruby.min.runtimes</param-name>
  <param-value>1</param-value>
</context-param>
<context-param>
  <param-name>jruby.max.runtimes</param-name>
  <param-value>1</param-value>
</context-param>

<filter>
  <filter-name>RackFilter</filter-name>
  <filter-class>org.jruby.rack.RackFilter</filter-class>
  <!-- 可选的过滤器配置初始化参数 -->
  <init-param>
    <param-name>resetUnhandledResponse</param-name>
    <param-value>true</param-value>
  </init-param>
  <init-param>
    <param-name>addsHtmlToPathInfo</param-name>
    <param-value>true</param-value>
  </init-param>
  <init-param>
    <param-name>verifiesHtmlResource</param-name>
    <param-value>false</param-value>
  </init-param>
</filter>
<filter-mapping>
  <filter-name>RackFilter</filter-name>
  <url-pattern>/*</url-pattern>
</filter-mapping>

<listener>
  <listener-class>org.jruby.rack.rails.RailsServletContextListener</listener-class>
</listener>

其他 Rack 应用程序配置

使用非 Rails Rack 应用程序的主要区别是 JRuby-Rack 在 WEB-INF/config.ru 或 WEB-INF/*/config.ru 中查找名为 config.ru 的 "rackup" 文件。以下是一个 web.xml 配置示例：

<filter>
  <filter-name>RackFilter</filter-name>
  <filter-class>org.jruby.rack.RackFilter</filter-class>
  <!-- 可选的过滤器配置初始化参数（见上文） -->
</filter>
<filter-mapping>
  <filter-name>RackFilter</filter-name>
  <url-pattern>/*</url-pattern>
</filter-mapping>

<listener>
  <listener-class>org.jruby.rack.RackServletContextListener</listener-class>
</listener>

如果您的应用程序中没有 config.ru 文件或不想在 Web 应用程序中包含它，可以直接在 web.xml 中嵌入它（以下示例使用 Sinatra）：

<context-param>
  <param-name>rackup</param-name>
  <param-value>
    require 'rubygems'
    gem 'sinatra', '~> 1.3'
    require './lib/app'
    set :run, false
    set :environment, :production
    run Sinatra::Application
  </param-value>
</context-param>

确保对 XML 转义角括号！

3. 项目 API 使用文档

JRuby-Rack 的主要操作模式是作为过滤器。这允许静态内容请求通过并由应用程序服务器服务。动态请求仅发生在没有相应文件的 URL 上，与许多 Ruby/Rack 应用程序的期望相似。推荐的默认过滤器是 org.jruby.rack.RackFilter，该过滤器支持以下可选初始化参数：

• responseNotHandledStatuses：哪些状态（当过滤器链返回时）应被视为未处理的响应（默认值："403,404,405"），应作为 Rack 应用程序分发。
• resetUnhandledResponse：未处理的响应是否重置（接受值 "true"、"false" 和 "buffer" 仅重置缓冲区），默认为 "true"。
• addsHtmlToPathInfo：控制是否在检查请求是否为静态页面时将 .html 后缀添加到 URI。
• verifiesHtmlResource：与上一个参数一起使用，确保请求的静态资源存在，然后再添加 .html 请求 URI 后缀。

应用程序还可以配置为通过 servlet 而不是过滤器进行分发，servlet 类名为 org.jruby.rack.RackServlet。

4. 项目安装方式

请按照以下步骤安装 JRuby-Rack：

1. 使用 Warbler 进行一键安装。
2. 手动安装 jruby-rack gem 并将 jar 文件复制到项目的 WEB-INF/lib 目录中。
3. 使用基于 JRuby-Rack 的服务器，如 Trinidad，无需配置部署描述符。

请遵循上述指南以确保正确安装和使用 JRuby-Rack。