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.

boolean isRegistered = UpcastEngine.setLicense(
                          UpcastEngine.class.getResourceAsStream( "upcast.license") );

In order to import or read a document (which implies that we understand the language of the document), upCast needs to know in which format a document is stored. Setting the import filter is like telling it.

Currently, only the RTF 1.6 import filter is supported, which reads documents conforming to the Rich Text Format (version 1.6) specification as set forth by Microsoft.

To be open for future upCast development, however, it is needed that you explicitly set the import filter. This is done via the call

String filterID = ucInst.setImportFilterType( UpcastEngine.kRTFImportType);

, with ucInst being an UpcastEngine instance.

The method returns a java.lang.String object which is used to identify this specific filter(-instance) for setting parameters using the setImportFilterParameter() method.

The constant UpcastEngine.kRTFImportType indicates the RTF 1.6 import filter and is the only valid constant to be used as of now.

Setting an import filter discards any previously imported document and sets useful default parameters for the specific filter.

Once you have set an import filter, you can set parameters for that filter. To identify the filter, you use the return value you got from setImportFilterType():

ucInst.setImportFilterParameter( filterID, "IncludeImages", new Boolean( true ) );

This call sets the parameter IncludeImages to true for the filter indicated by the string filterID.

Parameter names for each filter are given in the description of the filters. The parameter value has to be passed as a Java Object. The required object class depends on the specific parameter and is documented for each available parameter.

If you set a parameter more than once, the last value set will be used.

To set several parameters, you need to repeatedly call the method setImportFilterParameter().

You must make sure that you use the filterID you got when you called setImportFilterType() for the last time. Otherwise, the parameter will have no effect.

Once you have set the import filter type and appropriate parameters, you need to tell upCast from where to import the RTF document. This is done using either the method importStream() for importing the data from a java.io.InputStream or using the method importFile()for importing the data from a named file, respectively.

Any errors during the import phase will be reported as Exceptions of the respective type.

After the import, the document will be held in memory in a proprietary, internal format ready for (also multiple) export operations into different output formats.

The importStream() function is very flexible due to the various InputStream implementations that come standard with the JDK. You can e.g. turn the String myRTFString into an InputStream using a construction like

ucInst.importStream( new ByteArrayInputStream( myRTFString.getBytes() ) );

An imported source document replaces any previously read source document in memory. Only one document can be held in internal format at any time per UpcastEngine instance.

For a document to be exported, upCast must be told into which format the export should happen. This is done by specifying one of the built-in export filters or, if you're using a custom filter, your custom filter implementation class name less the package prefix. The built-in filters are the same as found in the GUI of upCast.

Setting the export filter is done via a statement like

String filterID = ucInst.setExportFilterType(
                            filterType );

, where ucInst is the UpcastEngine instance and filterType is one of the following constants as defined in UpcastEngine:

The method setExportFilterType() returns a java.lang.String object which is used to identify this specific filter(-instance) for setting parameters using the method setExportFilterParameter().

Setting an export filter replaces any previously set export filter and automatically sets useful default parameters for the specific export filter.

This works the same as for import filter parameters. To identify the filter, you use the return value you got from the method setExportFilterType():

setExportFilterParameter( filterID, "AllowEmptyCells", new Boolean(true) );

This call sets the parameter AllowEmptyCells to true for the filter indicated by the string filterID.

Available parameter names for each export filter are listed in the export filter reference section. The parameter values are passed as Java objects. The required object class depends on the specific parameter and is documented for each of the available parameters.

If you set a parameter more than once, the last value set will be used.

To set several parameters, you need to repeatedly call setExportFilterParameter() for each parameter you wish to set.

You must make sure that you use the filterID you got when you called setExportFilterType(). Otherwise, the parameter will have no effect.

Once you have set the export filter type and appropriate parameters, you need to tell the upCast where the internally held document should be exported to. This is done either using the exportStream() method for exporting the data to a java.io.OutputStream or using exportFile( destFile ) for exporting the data to the named file destFile, respectively.

Any errors during export will be reported as Exceptions of the respective type.

After an export operation, the source document will still be available unchanged in its internal representation, ready to be exported using e.g. the same filter with different parameter settings or even a different export filter.

As with importStream(), the exportStream() function is very flexible thanks to the various OutputStream sub-classes that come standard with the JDK.

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 {
  exportFile( filename );
} 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.