documentation for version 1.2.0

3.2 ROutputErrors (DEPRECATED)

In prior releases, ROutputErrors would send all warning and error messages to the browser. This has been deprecated and will be removed from the next rApache release. All warnings and errors are now always sent through the apache logging system.

3.3 SetHandler r-info

When configuring rApache for the first time, you may want to add the following directive to ensure that your system is working. It produces a report about R and Apache when you visit the url at /RApacheInfo. For production systems, you might want to leave it out.

# Prints out a nice report about R running within Apache
<Location /RApacheInfo>
SetHandler r-info
</Location>

3.4 REvalOnStartup

This directive takes one argument: a string containing R expressions to evaluate upon startup. Any number of these directives can appear throughout the config files, and they are evaluated in the global environment in the order they appear. Useful for setting options and loading libraries like so:

# Load required DBI and RMySQL packages

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

3.5 RSourceOnStartup

Sometimes you want to evaluate quite a bit of code on startup. Equivalent to calling source() in the global environment. Just like REvalOnStartup, these directives can appear anywhere in the config files and they are evaluated in the order that they appear.

# Configure system with startup file

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

3.6 R Handlers

It's important to read through the following section carefully as it will easily cause the most confusion. You have two Apache directives, two rApache directives, and two SetHandler options to learn.

3.6.1 Difference in Location and Directory

The Apache directives Location and Directory are used here to match up urls and files to R handlers. Certainly, Apache is very configurable and other directives exist to provide more fine-grained control over urls and files, but please refer to the Apache documentation for further info.

"Location" is used to define the behavior of url's that do not map to files on the filesytem. In rApache, they can be used to invoke an R handler. For instance, suppose we have set up rApache on the site example.com and added the following "Location" directive as in section 2.3:

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

Then, the url http://example.com/Risneat will invoke the handler r-info, but that url doesn't map to any file on the filesystem.

"Directory" is used to define the behavior of files on the filesystem. In rApache, they can be used to evaluate files containing R expressions through an R handler like so:

# Any file under /var/www/brew is passed through the function brew located in
# the package brew
<Directory /var/www/brew>
    SetHandler r-script
    RHandler brew::brew
</Directory>

Suppose example.com's Apache DocumentRoot was /var/www/, then the file /var/www/brew/foo.html maps to the url http://example.com/brew/foo.html and is run throuh the R package brew.

3.6.2 Difference in r-handler and r-script

r-handler, r-script, and r-info are valid arguments to Apache's SetHandler directive ("r-info" is already described in section 2.3). Calling SetHandler forces url's to be parsed through the named handler.

r-handler is used when you want to call an R function without arguments. You can also specify a particular file as well (see below). It is generally used within Location directives.

r-script is used when you want to call an R function with 2 arguments: the first is the full path to the file, and the second is an R environment. It is generally used within Directory directives.

Using either of these requires that the function or script return a suitable HTTP response code. For most cases this will be the value OK, which sends an HTTP response code of 200 to the browser. If the function or script would like to signal an error condition, then it should return an object with an S3 class of 'try-error' (read the R documentation for try and tryCatch for further info on the 'try-error' class).

3.6.3 RHandler

RHandler is used to specify an R function to handle incoming web requests. The function must exist either in an attached package or it must be found on the R search path. You can use the "::" to preface the function with the package name, just as in R. Examples:

# Specify foo as the function to run. Probably created 
# by REvalOnStartup or RSourceOnStartup

RHandler foo

# Run the function bar located in the package foo

RHandler foo::bar

3.6.4 RFileHandler

RFileHandler is used to specify a file and/or the function to handle incoming web requests. The "::" notation is used to specifiy the file and the function together. Absolute paths to files are expected. Examples:

# Hello world example. equivalent to calling source('/var/www/R/hello.R')
# on each request.

RFileHandler /var/www/R/hello.R

# Call the function foo within the file bar.R

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

Another note about RFileHandler. Each file specified is parsed only when its timestamp changes. This is useful for debugging, and once you are happy with the functionality, you may want to place it in a package use RSourceOnStartup and turn it into a function call instead for more efficiency.

3.6.5 REval and RFileEval

These two will take arbitrary R expressions and run them on each request. They are similar to RHandler and RFileHandler. For instance the above RHandler configuration example can be converted to use REval:

# Specify foo as the function to run. Probably created 
# by REvalOnStartup or RSourceOnStartup

RHandler "foo()"

# Run the function bar located in the package foo

RHandler "foo::bar()"

and similarly for RFileHandler:

# Call the function foo within the file bar.R

RFileHandler "/var/www/R/bar.R:foo()"

Note that a single colon is used to separate the filename from the expression to be evaluated. Note also that r-script is ignored in this case and r-handler is presumed.

3.6.6 Example Configurations

By far the easiest configuration will be the brew example. Each file under /var/www/brew is treated as a brew script:

# Any file under /var/www/brew is passed through the function brew located in
# the package brew.
<Directory /var/www/brew>
	SetHandler r-script
	RHandler brew::brew
</Directory>

Another option is to use sys.source:

# Any file under /var/www/R-files is passed through the function sys.source.
<Directory /var/www/R-files>
	SetHandler r-script
	RHandler sys.source
</Directory>

Hello World for the url at /test/helloworld:

# Runs the R expressions in helloworld.r for every request
# that matches /test/helloworld, including /test/helloworld/foobar

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

Deploying a Rook application:

# Run the Rook application named 'app'. On each request, the expression 
# 'Rook::Server$call(app)' is evaluated in an environment populated by
# rookapp.R. 'app' is expected to be found in that environment.
<Location /test/RookApp>
        SetHandler r-handler
        RFileEval /path/to/Rook/App/rookapp.R:Rook::Server$call(app)
</Location>

4. rApache Functions

The following functions can be used inside R handlers.

4.1 setHeader

Add HTTP Response Headers (RFC2616) to the response. All headers must be added before the first output from print() or cat().

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

4.2 setContentType

Allows handler to set the content type of the request. Must be called before output with print or cat().

setContentType(type='image/png')

4.3 setCookie

Add HTTP Cookies to the response headers. In the simplest case, calling setCookie('foo','bar') sets the cookie 'foo' to the value 'bar'. Calling setCookie('foo') will delete the cookie 'foo'. Any non-standard key value pairs can be appended by using ...

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

4.4 urlEncode and urlDecode

Percent encoding and decoding (url for short) of character vectors.

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

4.5 RApacheInfo

Print out a report (sample) about rApache. Should be the only call in your R handler. Equivalent to using "SetHandler r-info".

RApacheInfo()

4.6 sendBin

Sends binary data to the browser. This function is equivalent to R's writeBin() function, but the connection argument is ignored. See the documentation to writeBin() in your R distribution for more information.

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

4.7 receiveBin

Reads data from the HTTP request body, if any. Returns a length zero raw vector when there's no more data to read.

receiveBin(length=-1L)

4.8 RApacheOutputErrors (DEPRECATED)

This function has been deprecated and will be removed from the next rApache release. It invokes a warning if it is called.

5. rApache Variables

In previous releases of rApache, information from the web server was passed to R handlers in a single variable. This system design element was copied from other apache modules, but it has proven to be too cumbersome to support in software maintenance. Rather, because R has support for lexical scoping and in a far broader sense the ability to manipulate the language, a simpler approach was implemented.

rApache variables, named similar to PHP variables, are read-only list variables whose values are in most cases character vectors. They are injected into the environment of the R handler, and they are found by your R code via lexical scoping rules.

5.1 GET

The GET variable contains those values obtained from an HTTP GET method, i.e. the key-value pairs found after the "?" of an URL, or data passed from an HTTP form when the method attribute is "GET". For example, the following form:

<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

The POST variable contains those values obtained from an HTTP POST method, i.e. data passed from an HTTP form when the method attribute is "POST". Switching the method to "POST" in the example form from the previous section will produce the same values, yet in the POST variable:

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

5.3 COOKIES

The COOKIES variable contains those values obtained from the HTTP response header named "Cookie". It is a list variable whose values are character vectors. See the setCookie function and this link for more info.

5.4 FILES

The FILES variable contains information about uploaded files via HTTP forms when the enctype attribute is set to "multipart/form-data". The following form:

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

It is a list of lists, with the nested list giving you the "name" of the file and the "tmp_name", the location of the temporary file. For instance, to reference the uploaded file from the input tag named "FirstFile" you would use FILES$FirstFile$tmp_name. Here's a code snippet to copy the file to the '/usr/local/uploaded_files' directory:

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

NOTE: the temporary files are deleted after the R handler completes handling the request. Thus, it is imperative that you copy/move this file to your desired location before the R handler returns.

5.5 SERVER

As you can see from the below output, the SERVER variable contains a wealth of information about the incoming web request:

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

Here's a description of each list element:

5.6 Handler Return Values and HTTP Response Codes

The following table describes variables that exist as integer vectors of length 1 in the R handler environment and are proper return values for R handlers. They consist of Apache module return values and HTTP Status Codes(see Status Code Definitions from RFC2616 for more info). The most reasonable response value and the one that most handlers will return is the value DONE.

Another suitable value to return from a handler is an object with S3 class of 'try-error'.

6. rApache Cookbook

For a complete look at an rApache application, download the useR2007 application which uses Hmisc and brew for power and sample size calculations.

The following code exercises all rApache functionality by just echoing what was sent from the browser. Copy and paste the following code to a file and then set up apache with the following configuration. You should then be able to point your browser at http://example.com/rapachetest (replacing example.com with your own hostname).

# 
# Place this in your Apache config file.
#
<Location /rapachetest>
	SetHandler r-handler
	RFileHandler /var/www/R/test.R
</Location>

#
# Copy and save this code to /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. License

The rApache source code is licensed under the Apache License Version 2.0.

8. Citing rApache

To cite rApache, use the following:

A BibTeX entry for LaTeX users is

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

9. Thanks

Thanks to the following people for their contributions, giving advice, noticing when things were broken and such. If I've forgotten to mention you, please email me.

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