======Embedding xmlsh as a Servlet ====== Xmlsh comes with a generic Servlet class which can be used, extended, or you can write your own. This is based on J2EE Servlet Containers but is only tested with Tomcat 6. The Servlet is registered using the standard WAR file structure which you must create youself. When the servlet is bound to a URI, the file portion of the URI is mapped to a server side directory and executes xmlsh scripts from within that directory. For example, given this example web.xml file %%(xml) xmlsh tomcat application XmlshServlet org.xmlsh.servlet.XmlshServlet root /var/xmlsh 1 XmlshServlet *.xsh %% Request to http://host/xmlsh/script.xsh then the corresponding script in /var/xmlsh/script.xsh is executed. If a GET request is performed then the input to the script is null. If a POST command is performed then the input to the script is the body of the POST command. The output of the script becomes the response body. The content-type of the response body is set to the content-type property of the shell after invocation of the script. Starting with version 1.0.3 of xmlsh any POST or QUERY parameters are passed as an XML variable "HTTP_PARAMETERS" The format of the variable is an XML document of the form %%(xml) value 1 value 2 %% Starting with version 1.0.3 of xmlsh all HTTP headers are passed as an XML variable "HTTP_HEADERS" The format of the variable is an XML document of the form %%(xml)
localhost:8280
keep-alive
Mozilla/5.0 (Windows; U; Windows NT 6.1; en-US) AppleWebKit/532.5 (KHTML, like Gecko) Chrome/4.1.249.1036 Safari/532.5
max-age=0
Basic eG1sc2g6eG1sc2g=
application/xml,application/xhtml+xml,text/html;q=0.9,text/plain;q=0.8,image/png,*/*;q=0.5
gzip,deflate,sdch
en-US,en;q=0.8
ISO-8859-1,utf-8;q=0.7,*;q=0.3
%% For example the following script for "index.xsh" in the "xmlsh" servlet %% xecho $HTTP_PARAMETERS %% Given the following URL %% http://host:port/xmlsh?foo=bar&spam=value1&spam=value2 %% Results in %%(xml) bar value1 value2 %% You can configure a default index page "index.xsh" by adding this servlet mapping %%(xml) XmlshServlet / %% This maps the root directory to the xmlsh servlet, which then looks for "index.xsh" as the default welcome file. For servlets hosted in Tomcat you can use tomcat's authentication like any other servlet. For example, adding the following to the web.xml will request BASIC authentication. %%(xml) xmlsh users xmlsh Entire Application /* xmlsh BASIC XMLSH Realm %% You must edit the tomcat-users.xml file to add a user for the specified realm. ====Session Variables==== Starting with release 1.0.3 J2EE Session variables are supported via the [[CommandHttpsession httpsession]] command. ====Examples==== Example The following script invokes an xslt command on the input and outputs the result to the output, setting the content type to "text/html" %% set -content-type text/html xslt -f /test/spl.xsl %% ====Set up the WAR==== To create a working xmlsh servlet, a standard WAR structure needs to be created. Above is a sample web.xml, although the servlet can be configured in an existing WAR application, it need not be its own application. The servlet class is ""org.xmlsh.servlet.XmlshServlet"" There is a required servlet parameter *root* which specifies the directory where xmlsh scripts are located. All libraries (jars) required by xmlsh need to be available in the classpath for the servlet. Recommended that these get put into the WEB-INF/lib directory. ====Session Variables==== J2EE Session variables can be accessed and set within the invoked xmlsh script by using the [[CommandHttpsession httpsession]] command. ----