Accessing downCast functionality is carried out via one instance of a broker object: DowncastEngine. You should create one instance of that object at startup and use it for many subsequent conversions, since creation of this object is rather expensive. There are no problems in reusing that object for subsequent conversions (in contrast e.g. to many XML parser implementations, for example) - to the contrary, it is highly recommended from a performance point of view.
You may create several instances of the DowncastEngine object in order to run multiple conversion threads at the same time in your single application. Please note that the number of parallel threads may be restricted by your license.
We assume that you are familiar with Java programming and its concepts like objects, interfaces and implementations. You should also be fluent with the Java object notion and with Java Streams.
Converting a document with downCast is divided into the following, easy steps:
Register the JAR with a license file.
Instantiate an DowncastEngine object.
Set any required global parameters.
Convert the document.
If we look at these steps in actual Java code, the above would translate into (line numbers and steps corresponding):
DowncastEngine.setLicense( new FileInputStream( "/path/to/downcast.license") );
DowncastEngine dc = new DowncastEngine("instanceOne");
dc.convertFile( "/Dev/src/doc.xml", "/Dev/dest/", "/Dev/xsl/preconvert.xsl" ); Let's have a look at the single steps in more detail.
The first thing you need to do (before any conversion can take place) is to register the application with an appropriate license. This is done via the static method
public static boolean setLicense( InputStream inStream )
It takes an InputStream of the XML based license file.
If you package e.g. your license file into your application JAR at root level, you can use the following line to register your application:
boolean isRegistered = DowncastEngine.setLicense(
DowncastEngine.class.getResourceAsStream( "downcast.license") );If you package the license file at the default location {JAR Resource Location Path}/licenses/downcast.license, you need not call the setLicense() method at all.
To access WordLink functionality also from downCast running with API, you need to tell it where the WordLink component il-gw.exe is to be found before you instantiate an DowncastEngine object. This is done by setting the System Property de.infinityloop.exe.location to the directory where il-gw.exe resides:
System.setProperty( "de.infinityloop.exe.location", "/path/to/il-gw-directory/" );
On a typical Windows installation, this is C:\Documents and Settings\<accountname>\infinity-loop\downCast\Application Support\EXEs , but you are free to move the application file il-gw.exe anwhere in your filesystem where it is convenient for your deployed application.
Using WordLink in a critical server-based unattended environment is not supported and therefore not recommended. WordLink uses an installed copy of Word in component mode. Such use is explicitly warned against by Microsoft for server or server-like applications for technical reasons (letting alone any remaining licensing issues).
You gain access to all functionality of downCast by means of objects of a single class: DowncastEngine. An instance of this object is what you will use in your application in order to access the full range of downCast API functionality.
Before you can do anything (after having registered the API with a license) with downCast, you need to instantiate a DowncastEngine object:
DowncastEngine dc = new DowncastEngine( "instanceOne" );
The DowncastEngine class is located in the de.infinityloop.downcast package.
You should keep this object stored in a variable which you can access from all places inside your program where you need to access downCast functionality.
You should strive to have only one instance of the DowncastEngine object per physical CPU at any time for performance reasons. Also make sure you only instantiate this object once during the life of your application process, as instantiating and disposing of this object is a relatively costly operation.
Document conversion within downCast is a single-step process.
Converting a document is straightforward: a single method call converts an upCast DTD conforming XML file to RTF format, optionally pre-processing it with an XSLT processing sheet:
boolean success = dc.convertFile( "/path/to/src.xml", "/path/to/dest/", "/path/to/preprocess.xsl");
If you do not want any preprocessing to take place, pass null for the last argument in the call to convertFile().
You must specify absolute paths for all parameters.
Any errors during the conversion phase will be reported by returning false from the method call.
For certain features, you need to set global conversion parameters. To set these types of parameters, you use the method
setGlobalParameter(String parameter, Object value)
The API reference is provided in form of javadoc HTML documentation. This assures that the documentation is up-to-date since it is generated directly from the underlying source code. The most recent version of the downCast API documentation is available from our website at http://www.infinity-loop.de/support/documentation/api/.
Besides the parameters described in Section 1, “Basic operations”, the following parameters can be set via the setGlobalParameter() API method only:
When set to true, the frame attribute on CALS tables overrides the cell's border specification on the roght and bottom edges of the right- and bottom-most cells. If false, the cell's rowsep and colsep attributes take precedence over any frame setting.
The default value is true.
CALSFrameOverridesCells Boolean true | false
For debugging purposes, it might be convenient to keep the intermediary .rtf file (if you have selected the option to convert the .rtf result to .doc automatically), and also any intermediate result of an XSLT pre-processing step via the built-in XSLT engine is kept and resides in the {Log Folder}.
If you set this to false, remember to occasionally delete the created temporary files from the respective folders.
DeleteTemporaryFile Boolean true | false
See: Section 1.4, “Generating Word binary (.doc) files”
ConvertToDoc Boolean true | false
See: Section 1.5, “Setting the default image resolution”
DefaultPixmapResolution Integer 20..9999
See: Section 1.6, “Setting the Whitespace Handler”
WhitespaceHandler String fully.qualified.WhitespaceHandler.class
During a single call to an API method, several problems may occur, some of them quite significant, some of them less significant. In every case, the method will throw a single ILException (short for infinity-loop Exception). An ILException is a special descendant of a java.lang.Exception that encapsulates a list of errors and/or warnings that occurred during the last call to an API method.
You can query an ILException for its single constituents, which are objects of type LogEntry. A LogEntry encompasses:
a numerical message code
a message class, one of: FATAL, ERROR, WARN, INFO, DEBUG
a human readable message as String
a (possibly null) array of parameters that were used in constructing the message
The recommended coding style for error handling is to wrap each call to an API method in its own try{}/catch{}-block and catching ILExceptions explicitly. This is useful if e.g. the importFile() call throws an exception, but the severity is not high and you decide to continue processing because it only contains a warning that you do not care about and that does not affect the document integrity. By wrapping each call separately, you get the maximum out of any sequence of API calls by just skipping the portions that did not work.
A typical API call including error handling would look something like:
try {
convertFile( srcfile, destpath, null );
} catch( ILException e ) {
if( e.extractSignificantEntries(
new int[] {
NotificationCollector.FATAL,
NotificationCollector.ERROR
},
null,
null ).size() > 0 ) { // we only react on FATAL or ERROR types, but not WARNings
... do some error handling ...;
}
}Using the extractSignificantEntries()method you can specify in very high detail in what messages you are interested in. For more information on how to use this method, see the javadoc API reference.
The message codes are all constants of a special class, Msg. See the javadoc API reference for a description of the currently possible message codes and the number and semantics of parameters available for a specific message.