文档

3.2 ROutputErrors

这条指令的出现意味着 rApache 需要将 R 的出错信息转换为 HTML 代码输出到浏览器中显示，而非写入 Apache 的错误日志。请注意，此举改变了传递给浏览器的 HTTP 响应状态代码。当 Apache 配置文件中含有 ROutputErrors 这条指令时，出错后将返回 200 OK. 否则，出错后将返回 500 INTERNAL_SERVER_ERROR. 示例配置片段如下：

# 将下列语句加入配置文件以将错误信息转换为在浏览器中显示的 HTML.
# 否则, 所有警告和错误信息将被写入 Apache 的错误日志.

ROutputErrors

3.3 SetHandler r-info

第一次配置 rapache 时，不妨添加以下指令来确认整套系统已正常工作。当您访问 /RApacheInfo 时，将看到一份自动生成的关于 R 和 Apache 状态的报告。配置生产环境的主机时，此步骤可略去。

# 生成并输出一份关于 R 在 Apache 中运行状态的报告.
<Location /RApacheInfo>
SetHandler r-info
</Location>

3.4 REvalOnStartup

这条指令可接受一个字符串型参数：在启动时要执行的 R 语言表达式。在配置文件中可写任意多条此类指令，并根据出现的先后顺序在全局环境 (global environment) 执行。如下所示，适合设置选项或载入 R 包：

# 载入所需的 DBI 包和 RMySQL 包

REvalOnStartup "library(DBI); library(RMySQL)"

3.5 RSourceOnStartup

使用此指令即可在启动时执行较多的 R 代码。这等价于在全局环境中调用 source() 函数。与 REvalOnStartup 指令类似，此指令可以出现在配置文件的任何位置，且根据出现的顺序依次执行。

# 配置启动时要执行的代码所在的文件

RSourceOnStartup "/var/www/lib/R/startup.R"

3.6 R Handlers

由于此节所述内容非常容易引发混乱，所以认真阅读此节是十分必要的。您将学习两条 Apache 指令，两条 rApache 指令，以及两种 SetHandler 选项。

3.6.1 Location 和 Directory 的区别

在此使用 Apache 指令 Location 和 Directory 的目的是将 URL、文件路径匹配到 R 处理器 (handler) 上。的确，Apache 的可定制性极强，还存在其他可以更精细地控制 URL 和文件的指令。请参阅 Apache 官方文档 以了解更多信息。

"Location" 用于定义与文件系统中的文件无映射关系的 URL 行为。在 rApache 中，它可以用于调用一个 R 处理器 (handler). 举例来说，假设我们已在 example.com 安装了 rApache, 并且如 3.3 节添加了如下的 "Location" 指令：

<Location /Risneat>
    SetHandler r-info
</Location>

那么，此 URL http://example.com/Risneat 将调用处理器 r-info, 但此 URL 不与文件系统中的任何文件存在映射关系。

"Directory" 用于定义文件系统中与文件有关的行为。在 rApache 中，它可以通过类似于下述的 R 处理器 (handler) 来执行包含 R 语言表达式的文件：

# 位于 /var/www/brew 目录下的所有文件
# 都将被传递给 brew 包中的函数 brew() 进行处理
<Directory /var/www/brew>
    SetHandler r-script
    RHandler brew::brew
</Directory>

假设站点 example.com 的 Apache 根目录 (DocumentRoot) 为 /var/www/, 那么文件 /var/www/brew/foo.html 映射到的 URL 就为 http://example.com/brew/foo.html, 且将通过 brew 包执行。

3.6.2 r-handler 和 r-script 的区别

r-handler, r-script 和 r-info 均为 Apache 中 SetHandler 指令的可用参数 ("r-info" 在 3.3 节中已作阐释)。调用 SetHandler 将强制通过指定名称的处理器 (handler) 解析相应的 URL.

r-handler 可用于不加参数调用 R 函数。您也可以指定一个特定文件 (见下文)。此参数通常与指令 Location 配合使用。

r-script 使用两个参数调用 R 函数：第一个参数为文件的完整路径，第二个参数用于指定 R 中的环境 (environment)。此参数通常与 Directory 指令配合使用。

使用上述任意一个 SetHandler 指令的参数都要求调用的函数或脚本返回一个合适的 HTTP 响应代码。当此代码的值为 OK 的情况下 (大多数), 将传递给浏览器一个 HTTP 响应代码 200. 若您的函数或脚本想在出错时给出提示，则须返回一个 S3 类 (class) 中的 'try-error' 对象 (关于 'try-error' 类，请参阅 R 语言文档中关于 try 和 tryCatch 的部分)。

3.6.3 RHandler

RHandler 用以指定一个具体的 R 函数来处理提交的 Web 请求。此 R 函数必须存在于已加载包或 R 的搜索路径中。如同在 R 中一样，您可以在函数名前使用 "::" 以指定其所属包的名称。示例：

# 指定 foo() 为要执行的函数.
# 可能由 REvalOnStartup 或 RSourceOnStartup 创建

RHandler foo

# 执行位于 foo 包中的 bar() 函数

RHandler foo::bar

3.6.4 RFileHandler

RFileHandler 用以指定一个文件和 (或) 函数来处理收到的 Web 请求。使用记号 "::" 来同时指定文件和文件中的函数 (需使用文件的绝对路径)。示例：

# 一个 Hello world 程序. 等价于对每个请求调用 source('/var/www/R/hello.R')

RFileHandler /var/www/R/hello.R

# 调用 bar.R 中的 foo() 函数

RFileHandler /var/www/R/bar.R::foo

关于 RFileHandler 另外一个注解是，当且仅当其指定的文件的时间戳改变时，文件才会被重新解析。这一特性对调试有相当帮助，一旦代码成熟，您可以将其做成包并使用 RSourceOnStartup 指令来读取，然后作为函数调用，这样做效率更高。

3.6.5 配置示例

目前最简单的配置实例是 brew 包的例子。在 /var/www/brew 目录下的每个文件均被视为一个 brew 脚本：

# 位于 /var/www/brew 目录下的所有文件都将通过 brew 包中的 brew() 函数处理
<Directory /var/www/brew>
	SetHandler r-script
	RHandler brew::brew
</Directory>

另一个选择是使用 sys.source:

# 在 /var/www/R-files 目录下的所有文件都将通过函数 sys.source() 执行.
<Directory /var/www/R-files>
	SetHandler r-script
	RHandler sys.source
</Directory>

一个 Hello World 程序，URL 为 /test/helloworld:

# 为所有匹配 /test/helloworld 目录的请求, 包括针对
# /test/helloworld/foobar 目录的请求执行 helloworld.r 中的 R 表达式

<Location /test/helloworld>
        SetHandler r-handler
        RFileHandler /path/to/R/scripts/helloworld.r
</Location>

4. rApache 函数

以下函数可用于 R 处理器 (handler) 中。

4.1 setHeader

为响应添加 HTTP 响应头 (response header) (RFC2616). 所有的 headers 必须在第一次 print() 或 cat() 的输出前被添加。

setHeader(header='X-Powered-By',value='rApache')

4.2 setContentType

允许处理器 (handler) 设置请求的 内容类型 (content type). 必须在使用 print() 或 cat() 函数做输出前调用.

setContentType(type='image/png')

4.3 setCookie

为响应头添加 HTTP Cookies. 最简单的情形, 调用 setCookie(r,'foo','bar') 将赋值 'bar' 给名为 'foo' 的 cookie. 调用 setCookie(r,'foo') 将删除名为 'foo' 的 cookie. 可使用 ... 来附加任何非标准的键值对.

setCookie(name='sessionID',value=paste(rnorm(1)))

4.4 urlEncode 和 urlDecode

对字符型向量进行百分比式编解码.

urlEncode(str='hello world@example.com')
urlDecode(str='hello+world%40example.com')

4.5 RApacheInfo

输出一份关于 rapache 的报告 (示例). 须为 R 处理器 (handler) 中的唯一调用。等价于使用 "SetHandler r-info".

RApacheInfo()

4.6 sendBin

向浏览器发送二进制数据. 此函数等价于 R 中的 writeBin() 函数, 但在这里参数 connection 已被忽略. 参阅 R 文档中关于 writeBin() 函数的部分.

sendBin(object=readBin(t,'raw',n=file.info(t)$size))

4.7 RApacheOutputErrors

决定 rApache 将错误信息输出到浏览器还是输出到 apache 错误日志. 优先级高于作用于整个模块的 apache 配置指令 ROutputErrors. 此函数也可控制发送给请求者的 HTTP 响应代码, 参数 status=TRUE 时为 200, 参数 status=FALSE 时为 500.

# 将警告和错误转换为 HTML 注释
RApacheOutputErrors(status=TRUE,prefix='&lt!--\n',suffix='--&gt\n')

5. rApache 变量

在早期版本的 rApache 中，来自 Web 服务器的信息是作为一个单独的变量传递给 R 处理器 (handler) 的。这种体系设计仿效了其他第三方 apache 模块的普遍做法，但事实证明，这种设计给维护模块的开发者带来了诸多不便。由于 R 支持词法作用域 (lexical scoping) 机制，并拥有在更广意义上灵活操纵语言的能力，所以我们改而实现了另一种更为简明的设计。

和 PHP 变量的名字相似，rApache 变量存在于一个只读列表中，大多数情况下其值为字符型向量。它们已被注入到 R 处理器 (handler) 所在环境中，您编写的 R 代码将根据词法作用域规则来寻找它们。

5.1 GET

变量 GET 包含了以 HTTP GET 方式获取的值 (values). 即 URL 中，问号后接的键值对，或当 HTML 表单的 method 属性为 "GET" 时所传递的数据。举例来说，如下表单：

<form method="GET" action="http://example.com/brew/get.html">
	<input type="text" name="p1" value="0.95">
	<input type="text" name="p2" value="0.7">
<input type="submit" name="Submit">
</form>

> str(GET)
List of 3
 $ p1    : chr "0.95"
 $ p2    : chr "0.7"
 $ Submit: chr "Submit Query"

5.2 POST

变量 POST 包含了通过 HTTP POST 方式发送的值。即，当 HTML 表单的 method 属性为 "POST" 时所传递的数据。将上一小节示例中的 method 修改为 "POST" 将生成同样的值。只是此处存入的是 POST 变量：

> str(POST)
List of 3
 $ p1    : chr "0.95"
 $ p2    : chr "0.7"
 $ Submit: chr "Submit Query"

5.3 COOKIES

变量 COOKIES 包含了从名为 "Cookie" 的 HTTP 响应头取得的值。它是一个值为字符型向量的列表型变量。参考 setCookie 函数和此链接以了解更多。

5.4 FILES

变量 FILES 包含了当 HTML 表单的 enctype 属性被设置为 "multipart/form-data" 时，通过表单所上传文件的信息。如下表单：

<form enctype="multipart/form-data" method="POST" action="URL">
	<input type="file" name="FirstFile">
	<input type="file" name="SecondFile">
<input type="submit" name="Upload">

> str(FILES)
List of 2
 $ FirstFile :List of 2
  ..$ name    : chr "useR2007poster.pdf"
  ..$ tmp_name: chr "/tmp/apreqc9GlXE"
 $ SecondFile:List of 2
  ..$ name    : chr "rapache-1.0.0-useR2007.tar.gz"
  ..$ tmp_name: chr "/tmp/apreqoQ2hhX"

它是一个由列表组成的列表型变量，以嵌套结构给出了文件的名称 ("name")、缓存文件的文件名 ("tmp_name") 以及缓存文件的所在位置。例如，要引用 input 标签名为 "FirstFile" 的已上传文件，写法即为 FILES$FirstFile$tmp_name. 以下是一段将文件复制到 '/usr/local/uploaded_files' 目录的代码：

destination <- file.path('/usr/local/uploaded_files',FILES$FirstFile$name)
file.copy(FILES$FirstFile$tmp_name,destination,overwrite=TRUE)

注意：当 R 处理器 (handler) 处理请求完成后，缓存文件将被自动删除。因此，请切记在 R 处理器 return 之前将缓存文件复制或移动到您想要的位置。

5.5 SERVER

如下列输出所示，SERVER 变量包含了关于传入 Web 请求的丰富信息：

> str(SERVER)
List of 30
 $ headers_in        :List of 9
  ..$ Host           : chr "localhost:8181"
  ..$ User-Agent     : chr "Mozilla/5.0 (X11; U; Linux i686; en-US; ..."
  ..$ Accept         : chr "text/xml,application/xml,application/x..."
  ..$ Accept-Language: chr "en-us,en;q=0.5"
  ..$ Accept-Encoding: chr "gzip,deflate"
  ..$ Accept-Charset : chr "ISO-8859-1,utf-8;q=0.7,*;q=0.7"
  ..$ Keep-Alive     : chr "300"
  ..$ Connection     : chr "keep-alive"
  ..$ Cache-Control  : chr "max-age=0"
 $ proto_num         : int 1001
 $ protocol          : chr "HTTP/1.1"
 $ unparsed_uri      : chr "/brew/server.html/beetles/?foo=bar"
 $ uri               : chr "/brew/server.html/beetles/"
 $ filename          : chr "/home/hornerj/rapache/branches/rapache-1-0-br..."
 $ canonical_filename: chr "/home/hornerj/rapache/branches/rapache-1-0-br..."
 $ path_info         : chr "/beetles/"
 $ args              : chr "foo=bar"
 $ content_type      : chr "text/html"
 $ handler           : chr "r-script"
 $ content_encoding  : NULL
 $ range             : NULL
 $ hostname          : chr "localhost"
 $ user              : NULL
 $ header_only       : logi FALSE
 $ no_cache          : logi FALSE
 $ no_local_copy     : logi FALSE
 $ assbackwards      : logi FALSE
 $ status            : int 200
 $ method_number     : int 0
 $ eos_sent          : logi FALSE
 $ the_request       : chr "GET /brew/server.html/beetles/?foo=bar HTTP/1.1"
 $ method            : chr "GET"
 $ status_line       : NULL
 $ bytes_sent        : num 0
 $ clength           : num 0
 $ remaining         : num 0
 $ read_length       : num 0
 $ request_time      :'POSIXct', format: chr "2007-08-15 11:11:49"
 $ mtime             :'POSIXct', format: chr "1969-12-31 18:00:00"

以下是列表中元素的具体说明：

5.6 处理器返回值和 HTTP 响应代码

下表描述了在 R 处理器 (handler) 环境中以长度为 1 的整数型向量形式存在的变量，以及它们对于 R 处理器 (handler) 正确的返回值。其中包括了 Apache 模块的返回值和 HTTP 状态代码 (参看 RFC2616 中的状态代码定义)。最正常的，同时也是绝大多数处理器 (handler) 将返回的值为 DONE.

另一个可能的处理器 (handler) 返回值是一个 S3 中 'try-error' 类的对象.

6. rApache 实战

要查看一个完整的 rApache 应用，请下载 useR2007 会议上的示例程序。 此程序使用了 Hmisc 和 brew 包来进行势和样本量的计算。

下列代码通过对浏览器发送的数据给出回显，实践了 rApache 的全部功能。请复制以下代码并粘贴到一个文件中，然后使用下述选项设置 rApache, 最后使用浏览器访问 http://example.com/rapachetest (请用您自己的主机名替换 example.com).

# 
# 以下请放入您的 Apache 配置文件.
#
<Location /rapachetest>
	SetHandler r-handler
	RFileHandler /var/www/R/test.R
</Location>

#
# 复制下列代码到 /var/www/R/test.R 并保存
#
hrefify <- function(title) gsub('[\\.()]','_',title,perl=TRUE)
scrub <- function(str){ 
	if (is.null(str)) return('NULL')
	if (length(str) == 0) return('length 0 string')
	cat("\n<!-- before as.character: (",str,")-->\n",sep='')
	str <- as.character(str)
	cat("\n<!-- after as.character: (",str,")-->\n",sep='')
	str <- gsub('&','&amp;',str); str <- gsub('@','_at_',str); 
	str <- gsub('<','&lt;',str); str <- gsub('>','&gt;',str); 
	if (length(str) == 0 || is.null(str) || str == '')
		str <- '&nbsp;' 
	str
}
cl<-'e'
zebary <- function(i){ 
	cl <<- ifelse(cl=='e','o','e')
	cat('<tr class="',cl,'"><td>',scrub(i),'</td></tr>\n',sep='')
}
zeblist <- function(i,l){ 
	cl <<- ifelse(cl=='e','o','e')
	 cat('<tr class="',cl,'"><td class="l">',names(l)[i],'</td><td>')
	if(is.list(l[[i]]))
		zebra(names(l)[i],l[[i]])
	else {
		if (length(l[[i]]) > 1)
			zebary(l[[i]])
		else
			cat(scrub(l[[i]]))
	}
		
	cat('</td></tr>\n',sep='')
}
zebra <- function(title,l){ 
	cat('<h2><a name="',hrefify(title),'"> </a>',title,'</h2>\n<table><tbody>',sep='')
	ifelse(is.list(l),lapply(1:length(l),zeblist,l), lapply(l,zebary))
	cat('</tbody></table>\n<br/><hr/>') 
}

# Output starts here
setContentType("text/html")

if(is.null(GET)){
	called <- 1
} else {
	called <- as.integer(GET$called) + 1
}

setCookie('called',called,expires=Sys.time()+100)

cat('<HTML><head><style type="text/css">\n') 
cat('table { border: 1px solid #8897be; border-spacing: 0px; font-size: 10pt; }')
cat('td { border-bottom:1px solid #d9d9d9; border-left:1px solid #d9d9d9; border-spacing: 0px; padding: 3px 8px; }')
cat('td.l { font-weight: bold; width: 10%; }\n')
cat('tr.e { background-color: #eeeeee; border-spacing: 0px; }\n')
cat('tr.o { background-color: #ffffff; border-spacing: 0px; }\n')
cat('</style></head><BODY><H1>Canonical Test for rApache</H1>\n')
cat('<form enctype=multipart/form-data method=POST action="?called=',called,'">\n',sep='')
cat('Enter a string: <input type=text name=name value=""><br>\n',sep='')
cat('Enter another string: <input type=text name=name value=""><br>\n',sep='')
cat('Upload a file: <input type=file name=fileUpload><br>\n')
cat('Upload another file: <input type=file name=anotherFile><br>\n')
cat('<input type=submit name=Submit>')

cat("<hr>\n")
zebra('CGI GET Data',GET)
zebra('CGI POST Data',POST)
zebra('Cookies',COOKIES)
if (!is.null(FILES)){
	cat('<h2>Files Uploaded in POST Data</h2>\n')
	for (n in names(FILES)){
		zebra(paste("Form Variable",n),FILES[[n]])
	}
}
zebra("SERVER Variables",SERVER)
cat("</BODY></HTML>\n")

DONE

7. 许可协议

rApache 的源代码使用 Apache License Version 2.0 进行授权。

8. 引用 rApache

要引用 rApache，使用：

可供 LaTeX 用户使用的 BibTeX 条目为

@Manual{,
	title = {rApache: Web application development with R and Apache.},
	author = {Jeffrey Horner},
	year = {2011},
	url = {http://www.rapache.net/},
}

9. 致谢

感谢以下同仁的贡献、建议和对问题的反馈。如果我忘记提到您，请发邮件与我联系。

	Gregoire Thomas
	Jan de Leeuw
	Keven E. Thorpe
	Jeremy Stephens
	Aleksander Wawer
	David Konerding
	Robert Kofler
	Jeroen Ooms
	Michael Driscoll