Noodle Documentation
Introduction
Noodle is a set of 100% Pure Java classes for transparently making
arbitrary changes to an HTTP request and response. You can use Noodle
to create a servlet that, on every HTTP request, runs Java 'filters'
that you define on the request, sends the new request off to another
web server, and streams the resulting response through another set of
filters. The execution path looks something like this:
The above diagram is read left to right and then right to left; it
translates as the following:
The HTTP client is, e.g., a web browser. It makes a
connection to the Noodle servlet through an HTTP server, just as it
would make a connection to any other servlet. Its HTTP request is the
client request. When the Noodle servlet is executed, it sets up
some internal data and executes predefined proxy request
filters. These filters have a chance to modify the
HttpServletRequest headers as well as the content of the request (such
as the POST data).
Once the proxy request filters have been executed, Noodle makes an
HTTP connection to the HTTP server and sends the Proxy
request. The HTTP server treats this as it would any other HTTP
request, and returns a response (the Proxy response) consisting
of a set of HTTP headers and any body data. Noodle reads the data from
the proxy response in chunks, and filters it using proxy response filters,
which can add to, modify, or remove any of the headers or content sent
to the client through the client response.
The beauty of the Noodle system is that it is easy to implement any
sort of proxy request and proxy response filters. These filters can do
anything you want to munge both the header and body data as it's
passed back and forth, such as executing regular expressions on body
data using a Java regular
expressions package.
Noodle is considered a "transparent" HTTP proxy because neither the
HTTP client nor the HTTP server can know about the presence of Noodle.
With the creative use of Apache's mod_rewrite it is possible to place
Noodle in front of nearly any type of CGI to change the CGI's UI
without without modifications to the CGI or any need to re-write links
within the CGI. An example of using Noodle in this way would be to add
your own look and feel to Bugzilla without
needing to modify Bugzilla's source code yourself. Implementing this
functionality is left as an exercise to the reader.
Please subscribe to the Noodle mailing list if you have
questions or comments.
Licensing Information
Noodle is available under the Tigris.org license, which is similar
to the BSD license. You can do pretty much whatever you want with this
code, but please make sure to read the conditions stated in the
license.
Noodle also contains a bit of utility source code from both the Apache JServ project as well
as the Turbine project
(it is not necessary to download either of these; the required code
comes directly with Noodle). In order to create the internal HTTP
connection, Noodle uses the HTTPClient code
(included in the /lib directory). This replaces the poorly designed
and buggy java.net.URLConnection class. We credit and
thank the authors of all of those projects for the use of their source
code.
Noodle was originally created by Jon S. Stevens, and suffered a
major rewrite at the hands of Leonard Richardson, and again
an additional rewrite of some of the functionality by Ed Korthof.
Building
To build Noodle all you need to do is "cd build;
build-noodle.{sh,bat} war". That will compile the source code and
create a "noodle-war" WAR directory that you can move to your
tomcat/webapps/ directory and rename to "noodle".
You should use the .bat extension if you are on Win32 or the .sh
extension if you are on Unix. You must have the JAVA_HOME environment
variable set appropriately as well as the JSDK (Java Servlet
Development Kit) 2.0 and higher in your classpath. All other packages
currently required for building Noodle are included with Noodle.
The URL given in the introduction can be used to execute Noodle
itself and run the NoodleTest servlet. Please look at the source code
and the tech to see what is happening. It is all well documented and
easy to read.
To read how to drive Noodle from a servlet, how regular URLs turn
into Noodle URLs, and how to write Noodle filters, please see the Noodle Technical Manual.
