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 your license file into your application JAR, you can use the following line to register your application:
boolean isRegistered =
DowncastEngine.setLicense(
DowncastEngine.class.getResourceAsStream( "downcast.license") );
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 DowncastEngineobject:
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.
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/techpub/api/downcast/1.0/.