Request Generator
1. Introduction
Generators are a special category of processors that have no XML data inputs, only
outputs. They are generally used at the top of an XML pipeline to generate XML data
from a Java object or other non-XML source.
The Request generator streams XML from the current HTTP request. It can serialize
request attributes including headers, parameters, query strings, user and server
information.
Note
The Request generator can be used as the first component in a web application pipeline,
but it is recommended to use the
Page Flow
Controller and
XForms whenever possible. There are
cases where additional data from the request may be required, however, and where the
Request generator must be used.
2. Configuration
The Request generator takes a mandatory configuration to select which request
attribute to display. This configuration consists of a series of
include and exclude elements containing XPath expressions
selecting a number of element from the request tree. Those expressions can be as
complex as any regular XPath 1.0 expression that returns a single node or a
node-set. However, it is recommended to keep those expressions as simple as
possible. One known limitation is that it is not possible to test on the
value element of uploaded files, as well as the content of the request
body.
Sample Configuration:
<config> <include>/request/path-info</include>
<include>/request/headers</include>
<include>/request/parameters/parameter[starts-with(name, 'document-id')]
</include> <exclude>/request/parameters/parameter[name = 'document-id-dummy']
</exclude> </config>
The full attribute tree is:
<request> <container-type>servlet</container-type>
<content-length>-1</content-length>
<parameters> <parameter> <name>id</name>
<value>12</value>
</parameter> <parameter> <name>print</name>
<value>false</value>
</parameter> </parameters> <body/>
<protocol>HTTP/1.1</protocol>
<remote-addr>127.0.0.1</remote-addr>
<remote-host>localhost</remote-host>
<scheme>http</scheme>
<server-name>localhost</server-name>
<server-port>8080</server-port>
<is-secure>false</is-secure>
<auth-type>BASIC</auth-type>
<remote-user>jdoe</remote-user>
<context-path>/oxf</context-path>
<headers> <header> <name>host</name>
<value>localhost:8080</value>
</header> <header> <name>user-agent</name>
<value>Mozilla/5.0 (Windows; U; Windows NT 5.1; en-US; rv:1.1) Gecko/20020826
</value> </header> <header> <name>accept-language</name>
<value>en-us, en;q=0.50</value>
</header> <header> <name>accept-encoding</name>
<value>gzip, deflate, compress;q=0.9</value>
</header> <header> <name>accept-charset</name>
<value>ISO-8859-1, utf-8;q=0.66, *;q=0.66</value>
</header> <header> <name>keep-alive</name>
<value>300</value>
</header> <header> <name>connection</name>
<value>keep-alive</value>
</header> <header> <name>referer</name>
<value>http://localhost:8080/oxf/</value>
</header> <header> <name>cookie</name>
<value>JSESSIONID=DA6E64FC1E6DFF0499B5D6F46A32186A</value>
</header> </headers> <method>GET</method>
<path-info>/doc/home-welcome</path-info>
<request-path>/doc/home-welcome</request-path>
<path-translated>C:\orbeon\projects\OXF\build\oxf-war\doc\home-welcome
</path-translated> <query-string>id=12&print=false</query-string>
<requested-session-id>DA6E64FC1E6DFF0499B5D6F46A32186A</requested-session-id>
<request-uri>/oxf/doc/home-welcome</request-uri>
<servlet-path/>
</request>
Note
PresentationServer adds a request attribute: the request-path. This
attribute is defined as a concatenation of the servlet-path and the
path-info. This is useful because both original attributes are
frequently mixed up and often change depending on the application server or its
configuration.
Warning
This generator excludes all attributes by default. To obtain the whole attributes
tree (as shown in the example above), you must explicitly include
/request:
<p:processor name="oxf:request" xmlns:p="
http://www.orbeon.com/oxf/pipeline"
> <p:input name="config"> <config> <include>/request</include>
</config> </p:input> <p:output name="data" id="request"/>
</p:processor>
3. Request Body
When the request includes /request/body, the Request generator
retrieves the body of the request sent to the application server. The content of
the body is made available as the following data types:
- If the attribute stream-type on the config element
is set to xs:anyURI, an URI is returned as the value of the
/request/body element.
- If the attribute stream-type on the config element
is set to xs:base64Binary, the content of the request encoded as
Base64 is returned as the value of the /request/body element.
- Otherwise, the content of the /request/body is set as either
xs:anyURI if the request body is large (as set by the
max-upload-memory-size property, by default larger than 10 KB), or
xs:base64Binary if the request body is small.
Examples of configuration:
<config stream-type="xs:anyURI"> <include>/request/body</include>
</config>
<config stream-type="xs:base64Binary"> <include>/request/body</include>
</config>
The resulting data type is always set on the body element, for example:
<request> <body xsi:type="xs:anyURI">file:/C:/Tomcat/temp/upload_00000005.tmp</body>
</request>
Warning
Reading the request body is incompatible with reading HTML forms posted with the
multipart/form-data encoding, typically used when uploading files.
In such a case, you should read either only the request body, or only the
request parameters.
4. Uploaded Files
Uploaded files are stored into parameter elements, like any other
form parameter. The rules for the data type used are the same as for the request
body (see above), the data type depending on the stream-type
attribute and the size of the uploaded files:
<config stream-type="xs:anyURI"> <include>/request/parameters</include>
</config>
The parameter element for an uploaded file contains the following
elements in addition to the name and value elements
use for other parameters:
- filename: stores the file name sent by the user agent
- content-type: store the media type sent by the user agent
- content-length: stores the actual size in bytes of the uploaded data
A resulting uploaded file may look as follows:
<request> <parameters> <parameter> <name>upload-form-element-name</name>
<filename>photo.jpg</filename>
<content-type>image/jpeg</content-type>
<content-length>2345</content-length>
<value xsi:type="xs:anyURI">file:/C:/Tomcat/temp/upload_00000005.tmp</value>
</parameter> </parameters> </request>
Warning
The URL stored as the value of the upload or request body is temporary and only
valid for the duration of the current request. It is only accessible from the server
side, and will not be accessible from a client such as a web browser. It is not
guaranteed to be a
file: URL, only that it can be read with
PresentationServer's
URL generator.