com.softartisans.wordwriter
Class WordTemplate

java.lang.Object
  com.softartisans.wordwriter.WordTemplate

public class WordTemplate

extends java.lang.Object

An implemenation of WordWriter template functionality. Opens a WordWriter template file, populates it with data from a specified data source, and generates a new Word file. A WordWriter template is a file created in Microsoft Word that contains merge fields. A merge field displays a data source field name (for example, a database column name) where a data source value will be inserted. Merge fields are bound to a data source in code.

Field Summary

static int

ALL_ROWS

Constructor Summary

WordTemplate()
Creates a new WordTemplate object.

Method Summary

java.lang.String[]	getBookmarks() Returns all bookmarks in this template.
java.lang.String	getContentType()
int	getDocumentsCreatedToday()
java.lang.String[]	getFieldMarkers() Returns the names of all mergefields in this template.
java.lang.String[]	getFieldMarkers(java.lang.String aBookmark) Returns the names of all mergefields contained within a specified bookmark
java.lang.String	getLicenseKey()
java.lang.String	getVersion() Returns the exact version of the WordWriter product.
void	open(java.io.InputStream templateStream) Opens WordWriter template from an InputStream.
void	open(java.lang.String templateFileName) Opens WordWriter template from a file on disk.
void	process() Processes WordWriter template and populates MergeFields with data from the specified data source.
void	save(javax.servlet.http.HttpServletResponse response) Sends generated Word binary file to the client's browser.
void	save(javax.servlet.http.HttpServletResponse response, java.lang.String attachmentName, boolean openInBrowser) Sends generated Word binary file to the client's browser.
void	save(java.io.OutputStream outputStream) Sends generated Word binary file to OutputStream.
void	save(java.lang.String outputFileName) Saves generated Word binary file on disk.
void	setContentType(java.lang.String contentType) Sets custom content type response parameter string used for streaming the resulting Word document to browser
void	setDataSource(java.lang.Object[] dataRow, java.lang.String[] fieldNames) Sets the default data source for the document's body to an array of objects.
void	setDataSource(java.lang.Object[] dataRow, java.lang.String[] fieldNames, java.lang.String name) Sets a named data source for the document's body to an array of objects.
void	setDataSource(java.sql.ResultSet rs) Sets the default data source for the document's body to Resultset passed as a parameter.
void	setDataSource(java.sql.ResultSet rs, java.lang.String name) Sets a named data source for the document's body to Resultset passed as a parameter.
void	setLicenseKey(java.lang.String licenseKey) Instructs WordTemplate to use a particular license key for the duration of this instance, rather than obtaining one programatically from the License.jar file in the classpath.
void	setLocale(java.util.Locale locale) Sets the formatting for dates, numbers and currency to the specified locale.
void	setRepeatBlock(java.lang.Object[][] jaggedArray, java.lang.String[] columnNames, java.lang.String bookmark) Sets data source for the given repeat block to a jagged array of objects.
void	setRepeatBlock(java.lang.Object[][] jaggedArray, java.lang.String[] columnNames, java.lang.String bookmark, int maxRows, boolean transpose) Sets data source for the given repeat block to a jagged array of objects.
void	setRepeatBlock(java.lang.Object[] dataRow, java.lang.String[] fieldNames, java.lang.String bookmark) Sets data source for the given repeat block to an array of objects.
void	setRepeatBlock(java.sql.ResultSet rs, java.lang.String bookmark) Sets data source for the given repeat block (an arbitrary document fragment to be repeated with each row in a data source) to Resultset passed as a parameter.
void	setRepeatBlock(java.sql.ResultSet rs, java.lang.String bookmark, int maxRows) Sets data source for the given repeat block (an arbitrary document fragment to be repeated with each row in a data source) to Resultset passed as a parameter.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

ALL_ROWS

public static final int ALL_ROWS

See Also:

Constant Field Values

Constructor Detail

WordTemplate

public WordTemplate()

Creates a new WordTemplate object.

Method Detail

open

public void open(java.lang.String templateFileName)
          throws java.io.FileNotFoundException,
                 java.lang.NullPointerException,
                 java.lang.SecurityException,
                 java.lang.Exception

Opens WordWriter template from a file on disk.

Parameters:

templateFileName - file name for the WordWriter template to open

Throws:

java.lang.NullPointerException - if an argument is null of empty string

java.io.FileNotFoundException - if path is invalid or file access denied

java.lang.SecurityException - if a security manager exists and its checkRead method denies read access to the template file

java.lang.Exception - if file is not a valid WordWriter template, or another error

open

public void open(java.io.InputStream templateStream)
          throws java.lang.NullPointerException,
                 java.lang.Exception

Opens WordWriter template from an InputStream.

Parameters:

templateStream - java.io.InputStream with WordWriter template.

Throws:

java.lang.NullPointerException - if an argument is null

java.lang.Exception - if the stream does not contain a valid WordWriter template, or another error

setLocale

public void setLocale(java.util.Locale locale)

Sets the formatting for dates, numbers and currency to the specified locale. Locale must specify language and country, because otherwise it can not be used for string formatting.

Parameters:

locale - java.util.Locale, or null to set the Locale to system default

setDataSource

public void setDataSource(java.sql.ResultSet rs,
                          java.lang.String name)
                   throws java.sql.SQLException,
                          java.lang.Exception

Sets a named data source for the document's body to Resultset passed as a parameter. Resultset gets advanced to the next record before data is read

Parameters:

rs - Resultset to be used as a data source

name - The name of the data source. This is used for referencing the data source in a field using the WordWriter field syntax.

Returns:

1

Throws:

java.sql.SQLException - if SQL error occurs

java.lang.Exception

setDataSource

public void setDataSource(java.sql.ResultSet rs)
                   throws java.sql.SQLException,
                          java.lang.Exception

Sets the default data source for the document's body to Resultset passed as a parameter. Resultset gets advanced to the next record before data is read

Parameters:

rs - Resultset to be used as a data source

Returns:

1

Throws:

java.sql.SQLException - if SQL error occurs

java.lang.Exception

setDataSource

public void setDataSource(java.lang.Object[] dataRow,
                          java.lang.String[] fieldNames,
                          java.lang.String name)
                   throws java.lang.NullPointerException,
                          java.lang.Exception

Sets a named data source for the document's body to an array of objects. Objects in the array must not be arrays themselves. WordWriter binds MergeFields to data fields by name, so each object in the data array must have a corresponding field name in the array of field names. Objects in the object array can be null

Parameters:

dataRow - array of objects

fieldNames - Names of the objects in the array

name - The name of the data source. This is used for referencing the data source in a field using the WordWriter field syntax.

Throws:

java.lang.NullPointerException - if dataRow or fieldNames is null or empty

java.lang.Exception - if dataRow is different length than fieldNames

setDataSource

public void setDataSource(java.lang.Object[] dataRow,
                          java.lang.String[] fieldNames)
                   throws java.lang.NullPointerException,
                          java.lang.Exception

Sets the default data source for the document's body to an array of objects. Objects in the array must not be arrays themselves. WordWriter binds MergeFields to data fields by name, so each object in the data array must have a corresponding field name in the array of field names. Objects in the object array can be null

Parameters:

dataRow - array of objects

fieldNames - Names of the objects in the array

Throws:

java.lang.NullPointerException - if dataRow or fieldNames is null or empty

java.lang.Exception - if dataRow is different length than fieldNames

process

public void process()
             throws java.lang.Exception

Processes WordWriter template and populates MergeFields with data from the specified data source. Calls to open and setDataSource and/or, setRepeatBlock and optional setLocale must precede this call.

Throws:

java.lang.Exception - if template is not open, data source not set, or if other error occurs

save

public void save(java.io.OutputStream outputStream)
          throws java.lang.NullPointerException,
                 java.lang.Exception

Sends generated Word binary file to OutputStream.

Parameters:

outputStream - java.io.OutputStream

Throws:

java.lang.NullPointerException - if an argument is null

java.lang.Exception - if an error occurs (due to invalid WordWriter Template file or otherwise).

save

public void save(java.lang.String outputFileName)
          throws java.lang.NullPointerException,
                 java.io.FileNotFoundException,
                 java.lang.SecurityException,
                 java.lang.Exception

Saves generated Word binary file on disk. The calling process must have Write and Create access rights to the output directory

Parameters:

outputFileName - path for the output Word document file

Throws:

java.lang.NullPointerException - if an argument is null

java.io.FileNotFoundException - if the output file can not be created or opened for writing

java.lang.SecurityException - if a security manager exists and its checkWrite method denies write access to the output file

java.lang.Exception - if a fatal error occurs (due to invalid WordWriter template file or otherwise).

save

public void save(javax.servlet.http.HttpServletResponse response)
          throws java.lang.NullPointerException,
                 java.lang.Exception

Sends generated Word binary file to the client's browser. The resulting document will be open in the browser. Response's content disposition is set to inline, file name is set to a default file name. To override default file name use next signature.

Parameters:

response - javax.servlet.http.HttpServletResponse

Throws:

java.lang.NullPointerException - if an argument is null

java.lang.Exception - if an error occurs

save

public void save(javax.servlet.http.HttpServletResponse response,
                 java.lang.String attachmentName,
                 boolean openInBrowser)
          throws java.lang.NullPointerException,
                 java.lang.Exception

Sends generated Word binary file to the client's browser. Parameter openInBrowser specifies if resulting document will be open in browser, or in stand-alone instance of Word or Word viewer. Use this signature to explicitly specify the output file name and to control response content disposition.

Parameters:

response - javax.servlet.http.HttpServletResponse

attachmentName - generated file name (passed to content disposition), or null for default file name

openInBrowser - if true, sets content disposition to "inline". Resulting document will be opened in the client's browser. If false, sets content disposition to "attachment". Resulting documemnt will be opened in a stand-alone instance of Word or Word viewer.

Throws:

java.lang.NullPointerException - if response is null

java.lang.Exception - if an error occurs.

setRepeatBlock

public void setRepeatBlock(java.sql.ResultSet rs,
                           java.lang.String bookmark)
                    throws java.lang.NullPointerException,
                           java.lang.Exception

Sets data source for the given repeat block (an arbitrary document fragment to be repeated with each row in a data source) to Resultset passed as a parameter. Resultset gets advanced to the next record before data is read

Parameters:

rs - Resultset to use as a data source for the given repeat block

bookmark - bookmark in the document template that marks the repeat block boundaries

Throws:

java.lang.NullPointerException

java.lang.Exception

setRepeatBlock

public void setRepeatBlock(java.sql.ResultSet rs,
                           java.lang.String bookmark,
                           int maxRows)
                    throws java.sql.SQLException,
                           java.lang.NullPointerException,
                           java.lang.Exception

Sets data source for the given repeat block (an arbitrary document fragment to be repeated with each row in a data source) to Resultset passed as a parameter. Resultset gets advanced to the next record before data is read

Parameters:

rs - Resultset to use as a data source for the given repeat block

bookmark - bookmark in the document template that marks the repeat block boundaries

maxRows - the maximum number of data rows to be fetched from the data source

Throws:

java.sql.SQLException

java.lang.NullPointerException

java.lang.Exception

setRepeatBlock

public void setRepeatBlock(java.lang.Object[] dataRow,
                           java.lang.String[] fieldNames,
                           java.lang.String bookmark)
                    throws java.lang.NullPointerException,
                           java.lang.Exception

Sets data source for the given repeat block to an array of objects. All the MergeFields in the repeat block will bind to this data source. Objects in the array must not be arrays themselves. WordWriter binds MergeFields to data fields by name, so each object in the data array must have a corresponding field name in the array of field names. Objects in the object array can be null

Parameters:

dataRow - array of objects

fieldNames - array of corresponding MergeField names

bookmark - bookmark in the document template that marks the repeat block boundaries

Throws:

java.lang.NullPointerException

java.lang.Exception

setRepeatBlock

public void setRepeatBlock(java.lang.Object[][] jaggedArray,
                           java.lang.String[] columnNames,
                           java.lang.String bookmark)
                    throws java.lang.NullPointerException,
                           java.lang.Exception

Sets data source for the given repeat block to a jagged array of objects. All the MergeFields in the repeat block will bind to this data source.

Parameters:

jaggedArray - array of objects. The first dimension is column index, the second dimension is a row index

columnNames - array of corresponding MergeField names

bookmark - bookmark in the document template that marks the repeat block boundaries

Throws:

java.lang.NullPointerException

java.lang.Exception

setRepeatBlock

public void setRepeatBlock(java.lang.Object[][] jaggedArray,
                           java.lang.String[] columnNames,
                           java.lang.String bookmark,
                           int maxRows,
                           boolean transpose)
                    throws java.lang.NullPointerException,
                           java.lang.Exception

Sets data source for the given repeat block to a jagged array of objects. All the MergeFields in the repeat block will bind to this data source.

Parameters:

jaggedArray - array of objects. The first dimension is column index, the second dimension is a row index

columnNames - array of corresponding MergeField names

bookmark - bookmark in the document template that marks the repeat block boundaries

maxRows - the maximum number of data rows to be fetched from the data source

transpose - set to true to have WordWriter interpret the source array as transposed, i.e. first dimension is row, second dimension is column

Throws:

java.lang.NullPointerException

java.lang.Exception

getVersion

public java.lang.String getVersion()

Returns the exact version of the WordWriter product. The version string has the following format:

  SoftArtisans.ProductName Edition Major.Minor.Patch.Build
  (mmddyyyy-hhmmss-buildMachineId)
 

where:

• ProductName - product name like "SoftArtisans.WordWriter"
• Edition - the edition of the product that has been installed. If a license key cannot be found, this field will be blank.
• Major - major release of the product
• Minor - minor release of the product
• Patch - patch or bugfix number
• Build - build number
• mmddyyyy - the date the build was compiled on
• hhmmss - the exact time this product was compiled on
• buildMachineId - unique computer ID this product was compiled on

Returns:

version String, as described above.

getLicenseKey

public java.lang.String getLicenseKey()
                               throws com.softartisans.wordwriter.LicenseKeyException

Returns:

license key used for this version of WordWriter.

Throws:

LicenseKeyException - if license key is not found or invalid

setLicenseKey

public void setLicenseKey(java.lang.String licenseKey)
                   throws java.lang.Exception

Instructs WordTemplate to use a particular license key for the duration of this instance, rather than obtaining one programatically from the License.jar file in the classpath. This method is included to assist in debugging license-related issues. For general use, you should use the License.jar created at installation time or from the License Key Utility.

For assistance with licensing issues, please contact SoftArtisans Technical Support.

Parameters:

licenseKey - the license key to use for the duration of this instance.

Throws:

java.lang.Exception - if the license key is invalid for any reason.

getContentType

public java.lang.String getContentType()

Returns:

Content type used for streaming the resulting Word document to browser

setContentType

public void setContentType(java.lang.String contentType)

Sets custom content type response parameter string used for streaming the resulting Word document to browser

Parameters:

contentType - new Content Type string

getDocumentsCreatedToday

public int getDocumentsCreatedToday()

Returns:

the total number of documents generated by WordWriter within last 24-hours

getBookmarks

public java.lang.String[] getBookmarks()
                                throws java.lang.Exception

Returns all bookmarks in this template.

Returns:

A String array containing the bookmark names.

Throws:

java.lang.Exception - If open is not called first.

getFieldMarkers

public java.lang.String[] getFieldMarkers()
                                   throws java.lang.Exception

Returns the names of all mergefields in this template.

Returns:

A String array containing the mergefield names.

Throws:

java.lang.Exception - If open is not called first.

getFieldMarkers

public java.lang.String[] getFieldMarkers(java.lang.String aBookmark)
                                   throws java.lang.Exception

Returns the names of all mergefields contained within a specified bookmark

Parameters:

aBookmark - The name of the bookmark that contains the mergefields.

Returns:

A String array containing the names of mergefields contained within the specified bookmark.

Throws:

java.lang.Exception - If open is not called first.