The “Word To XML” servlet

The “Word To XML” servlet is a Java™ Servlet (server-side standard component) which has the same functions as the w2x-app desktop application.

Because it’s a server-side component and not a desktop application, please do not attempt to deploy the “Word To XML” servlet if you are an end-user of “Word To XML”. Please ask your IT personnel to do that for you.

Contents of the servlet software distribution

The “Word To XML” servlet comes in a software distribution of its own: w2x_servet-1_11_0.zip. This distribution contains a ready-to-deploy binary w2x.war, as well as the full Java™ source code of the servlet.

w2x.war

Ready-to-deploy Web application ARchive (WAR) containing the servlet.

src/

src/build.xml

The Java™ source code of the servlet. Run ant in src/ in order to use src/build.xml to rebuild w2x.war.

w2x/

Directory containing unpacked w2x.war. Needed to rebuild w2x.war.

lib/

Contains Java™ libraries needed to rebuild w2x.war.

Installing the servlet

File w2x.war may be easily installed in any servlet container implementing at least the Servlet 2.3 standard. Example of such servlet containers: Apache Tomcat, Jetty, Caucho Resin.

Though copying file w2x.war to the webapps/ folder of the servlet container and then restarting the servlet container is generally sufficient to deploy the “Word To XML” servlet, please refer to the documentation your servlet container to learn about the best deployment procedure.

On Windows, the .dll files contained in w2x_servlet_deployment_dir\WEB-INF\lib\ must be copied to a directory referenced by the PATH environment variable of the computer running the servlet.

Configuring the servlet

The “Word To XML” servlet is configured by specifying a number of init-param parameters. These parameters are found in WEB-INF/web.xml, where folder WEB-INF/ is contained in w2x.war.

All these init-param parameters are documented in web.xml. Example, parameter workDir:

Using the servlet to convert DOCX files

Let’s suppose your servlet container runs on host localhost and uses 8080 as its port. In order to use the “Word To XML” servlet, please point your Web browser to http://localhost:8080/w2x/. This will cause the browser to display a page containing a simple DOCX convert form.

Figure 2 The Convert DOCX form (servlet container running on host 192.168.1.202 and using port 8080)

In order to convert a DOCX file to another format:

Click “Choose File” to select the DOCX file to be converted.

Select the desired output format using the “Output format” combobox.

Click Convert to download a .zip (or .epub) archive containing the result of the conversion. Generating this .zip (or .epub) file may take several seconds to several minutes depending on the size of the DOCX input file.

Non interactive requests

It’s also possible to use the conversion services of the “Word To XML” servlet by sending URL /w2x/convert an HTTP POST request having a multipart/form-data encoding.

cURL2 example:

Other example:

The conversion request has three emulated form fields:

docx

Emulated <input type=”file”> field. Required. Contains the DOCX input file.

conv

Emulated <input type=”text”> field. Required. Contains the name of one of the conversionN.name init-param defined in WEB-INF/web.xml.

The stock WEB-INF/web.xml defines the following conversions to styled HTML:

xhtml_css (single page styled HTML), frameset (multi-page styled HTML, split on Heading 1), frameset2 (multi-page styled HTML, split on Heading 1, 2), frameset3 (multi-page styled HTML, split on Heading 1, 2, 3), webhelp (split on Heading 1), webhelp2 (split on Heading 1, 2), webhelp3 (split on Heading 1, 2, 3), epub (split on Heading 1), epub2 (split on Heading 1, 2), epub3 (split on Heading 1, 2, 3)

and also the following conversions to “semantic” XML:

docbook, docbook5, topic, map, bookmap, xhtml_strict, xhtml_loose, xhtml1_1, xhtml5.

params

Emulated <input type=”text”> field. Optional. Contains some w2x command-line options, generally -p parameters. These options are appended to the options of the conversion specified in the conv emulated form field.

The response to a successful conversion request is a .zip (or .epub) archive containing the result of the conversion.