SoftArtisans WordWriter for the Java™ Platform

Impressed With Ease of Use

by Faisal Khan

View Article on StarDeveloper.com:
http://www.stardeveloper.com/articles/display.html?article=2003092401&page=1

One of the many uses of Microsoft Word is to create document templates for stuff like envelopes, letters, faxes, forms, web pages, email messages, memos, calendars, resumes, invoices, reports etc. You then generate Word documents from these templates by opening these templates in Microsoft Word and filling in the required fields manually. The new Word document thus generated can be saved and worked with as desired.

Although possible, this method is cumbersome and expensive due to following reasons:

• Requires a person to do this manually.
• Requires separate Microsoft Word installations/licenses where ever you want this to happen.
• Is very slow as opening, filling in records and saving documents back is a time taking process.

But what if you would want to do this programmatically from your .NET/Java™ program without needing Microsoft Word installed on your server? Well you have got the solution in the form of SoftArtisans WordWriter. This is the product that I am going to review today.

WordWriter is a library written for both .NET and Java™ which creates, modifies and delivers Microsoft Word documents over the web from document templates and a data source.

Key features of this product are:

• Doesn't require Microsoft Word to be installed on the server.
• Supports virtually all Word features and, since the Word doc is used as a template, an additional design tool is not required.
• High performance.
• Available in .NET and Java™ editions.

How does it work?

You will first have to create one or more Microsoft Word templates and then insert special Merge Fields within these templates. Save these templates and close Microsoft Word. You will then upload these templates to your server where your Java™ application server is running. Your Java™ application on the server will then open these templates and will make use of Java™ API provided by WordWriter to set the values of Merge Fields within the templates with the values that you provide. Once done, you can then stream the newly generated Word document back to the client browser and/or save it on the server hard disk.

I have selected Java™ edition of WordWriter for review. Following topics will be covered:

• Obtaining WordWriter
• Installation
• Configuration
• Running Web Samples
• Using WordWriter in a J2EE™ environment
• Viewing Documentation
• Final Comments

Obtaining WordWriter

To download the evaluation edition of WordWriter for Java™, go to the SoftArtisans Download Section and select "OfficeWriterSE for Java™" from the available options. "OfficeWriterSE for Java™" contains evaluation editions of ExcelWriter and WordWriter.

Installation

The name of the file that I downloaded from SoftArtisans Web site was "OfficeWriterSE-1.0J.zip". I unzipped it in a temporary folder. After unzipping, I found 2 files:

1. OfficeWriterSE-Setup-1.0.jar
2. OfficeWriterSE-Setup-1.0-Win32.exe

Both of them are setup files for WordWriter/ExcelWriter installation. Since I was using Windows 2000, I double-clicked OfficeWriterSE-Setup-1.0-Win32.exe to initiate the installation. If you are using an operating system other than Microsoft Windows, you would want to run the Java™ setup program by using a command like:

java -jar OfficeWriterSE-Setup-1.0.jar

Installation started by displaying a rather familiar Windows interface after which I accepted the license agreement.

Next it asked for a license key, since I was evaluating this product, I had no license key and left the field empty and simply clicked 'Next'. If you buy (or already have) WordWriter (OfficeWriterSE) then you can enter your license key here. Next it asked for the location where WordWriter should be installed. I accepted the default.

It then asked me to choose the type of setup and I chose "Custom". Next it allowed to me to select exactly the features that I wanted to install. Since I (for now) only wanted WordWriter to be installed, I checked only WordWriter features. It then displayed a summary of installation options chosen and I clicked 'Next' to start the actual installation of WordWriter.

Configuration

WordWriter comes with configuration instructions for IBM WebSphere, BEA WebLogic and Apache Tomcat application servers. Since I was using Resin, the configuration step consisted of copying 4 files from WordWriter installation folder to a couple of Resin's folders.

Steps to Configure Resin

To view the source and be able to run samples that come with WordWriter I had to install two .WAR (Web Archive) files on my Resin server running on my local system. Here is what I did:

Step 1: I copied WordWriter-v1.0.1.jar and WordWriter-v1-License.jar from WordWriter's installation folder which on my system is D:\Program Files\SoftArtisans\OfficeWriterSE-v1.0\WordWriterSE-v1.0. I pasted them in Resin's /lib folder which on my system is F:\Resin-2.1.6\lib.

This allows all web applications running on Resin to access WordWriter API.

Step 2: I then copied WordWriter-v1.0.1-Docs.war and WordWriter-v1.0.1-Samples.war WAR files from WordWriter's installation folder which on my system is D:\Program Files\SoftArtisans\OfficeWriterSE-v1.0\WordWriterSE-v1.0. I then pasted both of them in Resin's /webapps folder which on my system is F:\Resin-2.1.6\webapps.

This is all that I had to do to configure and install WordWriter Web applications on Resin web server.

Running Web Samples

All that I had to do to run the samples and view the documentation web applications that I deployed on Resin was to start the Resin web server by running following command at command prompt:

F:\Resin-2.1.6\bin>httpd.exe (Hit Enter)

If you have installed Resin as a Windows service then you can start Resin by executing following command at the command prompt:

net start resin

As soon as Resin started, it detected the 2 .WAR files and deployed them silently.

Running Samples

To access the samples web application, I used a URL like http://localhost/WordWriter-v1.0.1-Samples/ and boom there was the WordWriter samples application right in front of me.

IE Window - WordWriter Java™ Samples

There are a total of 14 samples that come with WordWriter which are divided into 3 categories. I first clicked the "[View Template]" link besides the first sample from the first category. It streamed the Word Template back to me.

You can clearly see 2 of the 3 Merge Fields present in this template. It is the value of any of these fields that can be set by WordWriter as we'll see later.

Microsoft Word - Viewing Word Template

Next I ran the first sample from the first category by clicking the "[Run Sample]" besides it. It successfully created a new Word document and streamed it back to my browser.

Instead of saving, I hit the 'Open' button and Microsoft Word again automatically opened the document for me.

Microsoft Word - Viewing WordWriter Generated Word Document

As you can also see, the Merge Fields successfully got replaced by values specified by the Java™ code in the first sample.

I then moved on to run all the samples one by one provided by WordWriter and all the samples worked the first time as expected. Great!

Using WordWriter in a J2EE™ Environment

We'll first have a look at a code example to see exactly what kind of code we are expected to write to make use of WordWriter and then we'll see some possible uses and recommendations for using WordWriter in a J2EE™ environment.

Code Example

The code that is required to open a template, set some data source and create new Word document takes just few lines of code:

String names[] = {"FullName", "CityName"};
String values[] = {"Faisal Khan", "Lahore"};
WordTemplate wt = null;

wt = new WordTemplate();
wt.open(TEMPLATE_FILE_NAME);
wt.setDataSource(values, names);
wt.process();
wt.save(OUTPUT_FILE_NAME);

Explanation

In a nutshell what this code does is to create an array of Merge Field names that are to be found in the specified Word template, then it creates an array of values that are to be inserted in those Merge Fields . Next we create a WordTemplate object and open the template file. Next we set the data sources and call the WordTemplate.process() method which replaces the Merge Field instances in the template with the values specified in the values array. In the end we save the document locally and later open in Microsoft Word to confirm that values were successfully inserted.

Possible Uses and Recommendations for using WordWriter in a J2EE™ Environment

In a complete J2EE™ environment you'll have most of your business logic coded in the form of Enterprise JavaBeans™ which will be running in an application server. Those EJBs can be accessed by a number of different types of clients ranging from console-based clients to GUI clients, web clients (JSP/Servlets), EJBs, and other non-Java™ programs accessing your EJBs through CORBA IIOP protocol e.g. COM components on Windows server.

EJBs open the World for you, they allow your business logic to be accessed by different clients and participate in distributed transactions. Here is what you can do in the context of WordWriter:

• Create EJB Wrappers - then deploy these components in your application server. You then access these wrapper EJBs like you'd access any other EJB.
  
  
• Use Session EJBs for synchronous operations - e.g. when an employee in your company is writing a memo using the web interface provided by JSP pages running on your application server. When he/she submits the "Create Memo" button he/she expects a quick response from the application server. Your JSP page can access the Session EJB which uses WordWriter to create memo from a Word memo template (which contains your company logo among other things :)) and then streams it back to your JSP, which streams it back to the employee.
  
  
• Use Message-Driven EJBs for asynchronous operations - e.g. when an employee needs to generate and send an invoice to a client, he/she can use JSP pages to fill-in the appropriate fields for an invoice and then enqueue that data in a queue using JMS, and then he/she can move on to do other tasks. Your Message-Driven EJB will pick that invoice data and using WordWriter will create a new Word invoice document from your company's invoice template. It'll generate new invoice document and then enqueue it in some other JMS queue so that some other Message-Driven EJB can pick that invoice document and actually send it to your client e.g. by email, mail etc.
  
  
• Use transactions - You should be able to use your WordWriter EJB in single/multi-step local/distributed transaction where the task that is done by your WordWriter EJB is one of the many tasks that are supposed to be done e.g. like above example suggested, generating an invoice can be one of the steps required to complete a checkout transaction.
  
  
• Use multiple clients - You can offer web and GUI interfaces to your company's employees where they fill in form fields to generate Word documents that are either streamed back to them or are enqueued in a JMS queue to be later worked with. You can also create separate Java™ programs which can be scheduled to run at a specific time and whose task is to connect your remote EJBs and generate specified Word documents from different data sources.

Viewing Documentation

The documentation that comes with WordWriter is pretty comprehensive and if you are anything like me, you can read all of it in an hour.

The documentation is divided into 2 sections:

1. JavaDoc API
2. User's Guide

JavaDoc API

The JavaDoc API is the standard Java™ API documentation for WordWriter's only class; WordTemplate. Like I said before, the API is very simple, short and sweet. There are no huge numbers of proprietary classes, interfaces, factories etc to learn. You'll just have to see WordTemplate class and few of its methods.

User's Guide

This is where the actual fun lies. Here I was able to find all the information I needed about WordWriter. It is divided into following sections:

• Introduction
• Quick Start
• Features in Depth
• Programmer's Reference
• Samples
• Installation
• External Links

It was this documentation that I said I was able to read in an hour. It explains everything from what are Word templates to how to create new templates and insert Merge Fields in them. Then it explains the Java™ API that comes with WordWriter. Samples and installation are all covered in great detail.

What to expect in future versions of WordWriter?

Currently WordWriter is a v1.0 product whose strong point is the ability to generate Word documents from templates using only few lines of code. Following are some of the features that are expected in the next version:

• The ability to use multiple rows from the ResultSet. Currently you can only use the values from the first row of the ResultSet.
  
  Being able to add multiple rows from a data source will allow you to create multiple rows for a table inside your template.
  
  
• Along with .WAR web samples, there should be at least 5-6 .EAR EJB samples. Since mainly WordWriter is going to be made use of inside EJBs, it makes sense to have different types of EJB samples that one can deploy, test and work with, and which make use of different types of clients and display both synchronous and asynchronous use of WordWriter.

Final Comments

After downloading, installing, configuring, testing and running WordWriter samples, I must say that I was impressed by its simplicity and ease of use. If you need to create Word documents from Word templates programmatically then do give WordWriter a try, it will be well worth your time and effort.

About The Author

Faisal Khan is the main author and owner of Stardeveloper.com.