BunnyX
An XML Proxy Server that dynamically creates an XML based API from existing web applications

BunnyX Configuration.

The BunnyX proxy server comes with two XML configuration files. Both XML files MUST be in the current directory (which is usually the same directory that the BunnyX Jar is located). The first XML file bunnyx-config-rules.xml, is a rule-based configuration for use by Apache Digester. This should not be modified unless it is overwritten with a new bunnyx-config-rules.xml from a later version of BunnyX. The second XML file, bunnyx-config.xml is the configuration file that can be used to adjust how the BunnyX proxy behaves.

The root element of the configuration file is the configurations element. The XML file allows for multiple configurations to be defined. The current configuration is identified using the current attribute, with the name of the configuration as the value. For example, to indicate that the current configuration is the one named noproxy the following would be present in the configuration file.

<?xml version="1.0" encoding="iso-8859-1"?>
<configurations current="noproxy">
 <config name="noproxy"></config>
 <config name="proxy"></config>
</configurations>

Each config block is identified using a name attribute and stores the actual configuration information to use. The first configuration element that is used is the server element. This element identifies the port a particular server should bind to when BunnyX is starting. BunnyX has two internal servers available, an XML-RPC server, and a pass through proxy server. These two server types are identified as xmlrpc and bunnyx respectively. As an example, a configuration that instructs the XML-RPC server to use port 82 and instructs the BunnyX proxy server to use port 1272, can be seen below. The configuration uses the type and listenport tags to set the configuration values.

<?xml version="1.0" encoding="iso-8859-1"?>
<configurations current="noproxy">
 <config name="noproxy">
   <server>
     <type>xmlrpc</type>
     <listenport>82</listenport>
   </server>
   <server>
     <type>bunnyx</type>
     <listenport>1272</listenport>
   </server>
 </config>
 <config name="proxy"></config>
</configurations>

Note, the default values used if no configuration information is specified for a particular server may cause the proxy to not work. As an example, the XML-RPC server would not be able to bind to port 80 if there is a web server bound to that port already running on the system. Just as the server configuration tag sets values for accepting connections, the client tag does the same for making connections. Just as the server the client has a type (currently only apachehttp is supported) and a set of download options as specified in the downloadoptions configuration tag.

The proxy implements a download pool where requests are queued until they can be serviced. The maxpoolsize indicates the maximum number of concurrent threads that are to be used when downloading and processing content. A higher number would increase availability and may increase response time however, it also requires more CPU power. Another download option sets the maximum number of http attempts the client should make if the initial request fails. Currently this option is not used by the proxy. The third and last download option is the readbuffersize tag. This indicates how much memory the client should reserve for each thread reading requests from the network. The larger the read buffer, the faster data can be read from the network, however this also increases the memory utilization of the proxy while running. Larger read buffers usually only make sense if you have a fast connection to the destination server.

As an example, a sample configuration of the Apache HTTP client can be seen below with a maximum pool size of 20, 3 attempts for each failed http request and a read buffer size of 8Kb (or 8192 bytes).

<?xml version="1.0" encoding="iso-8859-1"?>
<configurations current="noproxy">
 <config name="noproxy">
   <server></server>
   <server></server>
   <client>
     <type>apachehttp</type>
     <downloadoptions>
       <maxpoolsize>20</maxpoolsize>
       <maxhttpattempts>3</maxhttpattempts>
       <readbuffersize>8192</readbuffersize>
     </downloadoptions>
   </client>
 </config>
 <config name="proxy"></config>
</configurations>

The next configuration element is the database configuration. The configuration parameters indicate the jdbc driver, url, username and password to use when accessing the database of stored content. The following configuration indicates that the database that is being used is the Hsqldb with the url specified to access the database, the username sa and no password.

<?xml version="1.0" encoding="iso-8859-1"?>
<configurations current="noproxy">
 <config name="noproxy">
   <server></server>
   <server></server>
   <client></client>
   <database>
     <driver>org.hsqldb.jdbcDriver</driver>
     <url>jdbc:hsqldb:bunnyx</url>
     <username>sa</username>
     <password/>
   </database>
 </config>
 <config name="proxy"></config>
</configurations>

The BunnyX proxy dynamically converts HTML into XML based on dynamically included headers. Non-HTML content is not processed as long as it doesn't match a content type in the configuration. BunnyX options are divided into header options and options for contenttypes as can be seen below.

<?xml version="1.0" encoding="iso-8859-1"?>
<configurations current="noproxy">
 <config name="noproxy">
   <server></server>
   <server></server>
   <client></client>
   <database></database>
   <bunnyxoptions>
     <contenttypes></contenttypes>
     <headers></headers>
   </bunnyxoptions>
 </config>
 <config name="proxy"></config>
</configurations>

The contenttypes are a list of types using the type tag that match each of the processible HTML content types. If a content type isn't being processed, check the content type header value returned by the server and add it to the list of types. Below, there are three processible content types, HTML, XHTML and HTML with a particular character set encoding.

<?xml version="1.0" encoding="iso-8859-1"?>
<configurations current="noproxy">
 <config name="noproxy">
   <server></server>
   <server></server>
   <client></client>
   <database></database>
   <bunnyxoptions>
     <contenttypes>
       <type>text/html</type>
       <type>text/xhtml</type>
       <type>text/html; charset=ISO-8859-1</type>
     </contenttypes>
     <headers></headers>
   </bunnyxoptions>
 </config>
 <config name="proxy"></config>
</configurations>

The headers tag lets you customize which Headers BunnyX responds to for processing data dynamically. There are two basic header types, prepend and formatas. The prepend headers let clients request URLs to be prepended to all or some of the HTML tags that are present in the server response. The formatas header indicates to the proxy that this particular client desires a specific format and processing of the server response.

The base configuration tags indicate the text that is used when identifying the relevant headers. In the example below, as the base of the BunnyX specific headers is X-ynnuB and the base of the prepend section is -URLPrepend, a header sent by a client to indicate that they would like to prepend a URL to the response of the server would be X-ynnuB-URLPrepend. When prepending URLs, especially to form actions, more often than not, the destination of the form submission would be different. Due to this, the original sumbission method used by the HTML before prepending needs to be saved. This is recorded in a hidden form field variable, named with the value stored in the originalmethod configuration tag. Below, this value is xynnuboriginalmethod. There is an additional base-like tag named basefortag which is used when prepending specific tags in the server response. This allows clients to specifically prepend URLs for particular tags, for example only the link tags are to be routed through a script, but the images are to go directly to the server.

The formatas configuration tag also has a base which works as in the prepend section. The three XML formats, XHTML, XMLFLAT and XMLBLOCK have values which are used to determine which format a client is requesting. Below, the formats match the name, but this can be altered. Some clients however may expect the values specified below. An additional tag, the default tag allows default formatting to be done by the proxy when there is no custom BunnyX tag sent. This means that clients that cannot be easily altered (such as a web browser), may retrieve formatted results without modification. The default is not necessary, and if omitted will, by default, not do any formatting to the server response. The default format that is specified below is the XMLBLOCK format in the default tags.

<?xml version="1.0" encoding="iso-8859-1"?>
<configurations current="noproxy">
 <config name="noproxy">
   <server></server>
   <server></server>
   <client></client>
   <database></database>
   <bunnyxoptions>
     <contenttypes></contenttypes>
     <headers>
       <base>X-ynnuB</base>
       <prepend>
         <base>-URLPrepend</base>
         <originalmethod>xynnuboriginalmethod</originalmethod>
         <basefortag>-URLTagPrepend</basefortag>
       </prepend>
       <formatas>
         <base>-FormatAs</base>
         <xhtml>XHTML</xhtml>
         <xmlflat>XMLFLAT</xmlflat>
         <xmlblock>XMLBLOCK</xmlblock>
         <default>XMLBLOCK</default>
       </formatas>
     </headers>
   </bunnyxoptions>
 </config>
 <config name="proxy"></config>
</configurations>

Using another proxy with BunnyX

If the web application that your client is trying to accessed can only be retrieved using a proxy, the BunnyX proxy must be configured to use that proxy. Note as of writing this, there is no authenticated proxy support available in BunnyX. To enable the BunnyX proxy to use another particular proxy to make requests, the client configuration must be changed. To make using the proxy versus not using it easier, a second configuration named "proxy" will have the configured client information. The sample configuration below indicates that the proxy to be used for BunnyX to make requests is at the IP address 192.168.80.17 and these requests must be made through port 80. There is also an exception list configured using noproxyfor that indicates which hosts or IP addresses the specified proxy should not be used for to make requests. Currently this is not used by the proxy.

<?xml version="1.0" encoding="iso-8859-1"?>
<configurations current="noproxy">
 <config name="noproxy"></config>
 <config name="proxy">
   <server></server>
   <server></server>
   <client>
     <proxy>
       <host>192.168.80.17</host>
       <port>80</port>
       <noproxyfor>
         <excepthost>localhost</excepthost>
         <excepthost>127.0.0.1</excepthost>
       </noproxyfor>
     </proxy>
   </client>
   <database></database>
   <bunnyxoptions></bunnyxoptions>
 </config>
</configurations>

A sample of the BunnyX configuration rules and the BunnyX configuration are available for download.

Php Logo   SourceForge Logo