de.infinityloop.upcast
Class UpcastEngine

java.lang.Object
  extended by de.infinityloop.upcast.UpcastEngine

public class UpcastEngine
extends java.lang.Object

This class provides all necessary methods to access upCast functionality programmatically via a simple Java API.

Follows a minimal skeleton showing how to do a single conversion from file in.rtf to out.xml (debugging turned on):

 
  String filterID;
  UpcastEngine.setLicense( "/path/to/upcast.license" );
 
  UpcastEngine ucInst = new UpcastEngine( true, "one" );
 
  ucInst.setGlobalParameter( "outputDir", new String( "/someproject/somefolder/someoutputdir/" );
 
  filterID = ucInst.setImportFilterType( UpcastEngine.kRTFImportType );
  ucInst.setImportFilterParameter( filterID, "OrigNumbering", new Boolean( true ) );
  ucInst.importFile( "in.rtf" );
 
  filterID = ucInst.setExportFilterType( UpcastEngine.kXMLExportType );
  ucInst.setExportFilterParameter( filterID, "DeleteEmpties", new Boolean( false ) );
  ucInst.exportFile( "out.xml" );
 
 

Version:
5.2.1

Field Summary
static int kCommandlineExportType
          selector for the Command Line Export Filter.
static int kCSSExportType
          selector for the CSS2 Export Filter Export style information to CSS2 ( Cascading Style Sheet Level 2 ).
static int kDocBookExportType
          selector for the DocBook 4.2 Export Filter.
static int kNoopImportType
          selector for the No-op (None) import filter.
static int kRawTreeDumperExportType
          selector for the Raw Tree Dumper.
static int kRTFImportType
          selector for the RTF 1.6 Specification compliant import filter.
static int kUnicodeTranslatorExportType
          selector for the Unicode Mapper post processing export filter.
static int kXHTMLExportType
          selector for the XHTML Export Filter.
static int kXHTMLTransitionalExportType
          selector for the XHTML Transitional Export Filter.
static int kXMLExportType
          selector for the XML (upCast DTD) Export Filter.
static int kXMLRawExportType
          selector for the XML Raw export filter.
static int kXMLValidatorExportType
          selector for the Validator Export Filter.
static int kXSLTProcessorExportType
          selector for the XSLT post processing Export Filter.
 
Constructor Summary
UpcastEngine(boolean debug, java.lang.String instanceIDUser)
          Creates a new instance of the UpcastEngine object.
UpcastEngine(java.lang.String instanceIDUser)
          Creates a new instance of the UpcastEngine object.
 
Method Summary
static void addCatalog(java.lang.String catalogFile)
          Adds an (XML-) Catalog to the system.
 void addCustomEncoding(java.io.InputStream customEncodingStream)
          Adds a custom encoding to the collection of known encodings.
 void addCustomEncoding(java.lang.String customEncodingName)
          Adds a custom encoding to the collection of known encodings.
 void convertDocumentWithConfiguration(java.lang.String srcFile, java.lang.String destDir, java.lang.String configFile)
          Convert a document using the settings as defined in a specified upCast Configuration file.
 void debugMessage(java.lang.String msg)
          Makes debugging output Writes a string to the console when gDebug = true.
static void discardCatalogs()
          Removes all previously registered catalogs from the catalog system.
 void dispose()
          **BROKEN** This method is broken.
 void errorMessage(java.lang.String msg)
          Makes error output.
 void exportFile(java.lang.String outFile)
          Exports a document to a file.
 void exportStream(java.io.OutputStream outStream)
          Exports a document to a stream.
 com.sun.resolver.tools.CatalogResolver getCatalogResolver()
          Returns the Catalog resolver used by the system.
 java.lang.String getEnvironmentValue(java.lang.String key)
          Returns the value of the environment property specified by the key integer.
 java.lang.String getInstanceNameUser()
          Returns the user instance id/name passed in on construction time for this object.
 void importFile(java.lang.String srcFile)
          Reads document from file.
 void importStream(java.io.InputStream inStream)
          Reads document from stream.
 void infoMessage(java.lang.String msg)
          Makes info output.
 void setCustomFontConfiguration(java.io.InputStream customFontConfigStream)
          Loads a new custom stdfonts.config configuration.
 void setCustomFontConfiguration(java.lang.String customFontConfigName)
          Loads a new custom stdfonts.config configuration.
 void setDebuggingMode(boolean on)
          Sets debugging mode.
 void setExportFilterParameter(java.lang.String filterInstance, java.lang.String filterParameter, java.lang.Object parameterValue)
          Sets an export filter parameter.
 java.lang.String setExportFilterType(int filterType)
          Set export filter Type Sets the type of the export filter for exporting the internally held document.
 void setGlobalParameter(java.lang.String parameter, java.lang.Object value)
          Set global parameter for conversion process.
 void setImportFilterParameter(java.lang.String filterInstance, java.lang.String filterParameter, java.lang.Object parameterValue)
          Set import filter parameter.
 java.lang.String setImportFilterType(int filterType)
          Set import filter Type Sets the type of the import filter for data to be read by importStreamor importFile.
static boolean setLicense(java.io.InputStream inStream)
          Sets a specified License file for use as license.
static boolean setLicense(java.lang.String licenseFile)
          Sets a specified License file for use as license.
 void warningMessage(java.lang.String msg)
          Makes warning output.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

kRTFImportType

public static final int kRTFImportType
selector for the RTF 1.6 Specification compliant import filter.

See Also:
setImportFilterType(int), Constant Field Values

kNoopImportType

public static final int kNoopImportType
selector for the No-op (None) import filter.

Since:
5.2.1
See Also:
setImportFilterType(int), Constant Field Values

kXHTMLExportType

public static final int kXHTMLExportType
selector for the XHTML Export Filter.

Export to XHTML, optionally including detailed visual markup (works in tandem with kCSSExportType)

See Also:
setExportFilterType(int), Constant Field Values

kCSSExportType

public static final int kCSSExportType
selector for the CSS2 Export Filter

Export style information to CSS2 ( Cascading Style Sheet Level 2 ).

See Also:
setExportFilterType(int), Constant Field Values

kXMLValidatorExportType

public static final int kXMLValidatorExportType
selector for the Validator Export Filter.

validate the specified file

See Also:
setExportFilterType(int), Constant Field Values

kXMLExportType

public static final int kXMLExportType
selector for the XML (upCast DTD) Export Filter.

Export to XML, logical/visual markup selectable, valid according to the upCast DTD.

See Also:
setExportFilterType(int), Constant Field Values

kCommandlineExportType

public static final int kCommandlineExportType
selector for the Command Line Export Filter.

Runs a command at command line level.

See Also:
setExportFilterType(int), Constant Field Values

kXSLTProcessorExportType

public static final int kXSLTProcessorExportType
selector for the XSLT post processing Export Filter.

Runs a stylesheet on the specified file output. Does not work with streaming data.

See Also:
setExportFilterType(int), Constant Field Values

kDocBookExportType

public static final int kDocBookExportType
selector for the DocBook 4.2 Export Filter.

Export to DocBook 4.2 DTD (XML)

See Also:
setExportFilterType(int), Constant Field Values

kXMLRawExportType

public static final int kXMLRawExportType
selector for the XML Raw export filter.

Export to a raw tree to be processed with a custom XSLT stylesheet (inline transformation).

See Also:
setExportFilterType(int), Constant Field Values

kUnicodeTranslatorExportType

public static final int kUnicodeTranslatorExportType
selector for the Unicode Mapper post processing export filter.

Translate a given XML document using the specified Unicode Translation Map.

See Also:
setExportFilterType(int), Constant Field Values

kXHTMLTransitionalExportType

public static final int kXHTMLTransitionalExportType
selector for the XHTML Transitional Export Filter.

Export to XHTML, optionally including detailed visual markup (works in tandem with kCSSExportType)

See Also:
setExportFilterType(int), Constant Field Values

kRawTreeDumperExportType

public static final int kRawTreeDumperExportType
selector for the Raw Tree Dumper.

Export to text, showing tree to expect when working on custom export filters.

Important: The output is not valid XML!

See Also:
setExportFilterType(int), Constant Field Values
Constructor Detail

UpcastEngine

public UpcastEngine(java.lang.String instanceIDUser)
             throws ILException
Creates a new instance of the UpcastEngine object.

Debugging mode is automatically set to false.

If your license allows, you may instantiate several objects of this kind. They are completely independent from each other, so you may run them in separate threads. However, they share some synchronized code sequences and each instance keeps its document in memory for processing. We recommend serializing any conversion jobs you might have pending (except when you have multi-processor machines).

Parameters:
instanceIDUser - you may pass an arbitrary string here which helps to identify the server instance in log file and debug message output.
Throws:
ILException
Since:
3.0.0

UpcastEngine

public UpcastEngine(boolean debug,
                    java.lang.String instanceIDUser)
             throws ILException
Creates a new instance of the UpcastEngine object. If your license allows, you may instantiate several objects of this kind. They are completely independent from each other, so you may run them in separate threads. However, they share some synchronized code sequences and each instance keeps its document in memory for processing. We recommend serializing any conversion jobs you might have pending (except when you have multi-processor machines).

Parameters:
debug - pass true if you want debug messages output to the logging system, false otherwise.
instanceIDUser - you may pass an arbitrary string here which helps to identify the server instance in log file and debug message output.
Throws:
ILException
Since:
3.0.0
Method Detail

convertDocumentWithConfiguration

public void convertDocumentWithConfiguration(java.lang.String srcFile,
                                             java.lang.String destDir,
                                             java.lang.String configFile)
                                      throws ILException
Convert a document using the settings as defined in a specified upCast Configuration file. This is a convenience method only with several limitations and restrictions. You should use it only if calling several other API methods poses some problems.

This method sets up the current UpcastEngine object according to the definitions found in the UpcastConfiguration file.

Important: You may only use the kRTFImportType as import filter, the 'None' or 'Batch' variants are not allowed and will be automatically reset to kRTFImportType on reading the configuration. Also note that you cannot override any parameters since you do not have any handles to the filter instances. If you need more flexibility, you should use the more granular API methods provided.

Parameters:
srcFile - full path to the RTF source file to be converted
destDir - full path to the destination directory/base directory for the results
configFile - full path to the upCast Configuration file to be used for this conversion
Throws:
ILException
Since:
4.0.0b116

importStream

public void importStream(java.io.InputStream inStream)
                  throws ILException
Reads document from stream.

This method actually imports a document and stores it in a proprietary format in memory. For this it uses the import filter as earlier set by setImportFilterTypewith parameters as set by setImportFilterParameter.

Any previously read document is replaced by the newly imported one.

The inStream can be any of the many predefined sub-classes/implementations of InputStream.

Note: To have WordLink function also when passing a .doc binary file in the stream, the InputStream implementation must support the mark() operation.

The imported document is held in memory until one of the following happens:

Parameters:
inStream - the stream that contains the input data.
Throws:
ILException - Throws an appropriate exception if anything goes wrong.

importFile

public void importFile(java.lang.String srcFile)
                throws ILException
Reads document from file.

This method actually imports a document and stores it in a proprietary format in memory. For this it uses the import filter as earlier set by setImportFilterTypewith parameters as set by setImportFilterParameter.

Any previously read document is replaced by the newly imported one.

The srcFile should be an absolute filename.

The imported document is held in memory until one of the following happens:

Parameters:
srcFile - the (absolute) name (incl. path) of the file to be imported.
Throws:
ILException - Throws an appropriate exception if anything goes wrong.

exportStream

public void exportStream(java.io.OutputStream outStream)
                  throws ILException
Exports a document to a stream.

Export a document from the internal representation to a stream, using the export filter and settings as previously determined by calls to setExportFilterTypeand setExportFilterParameter.

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

After an export operation, the document exported will still be available unchanged in its internal representation, ready to be exported using e.g. a different filter or different parameters.

Parameters:
outStream - the stream where the output gets written to.
Throws:
ILException - Throws an appropriate exception if anything goes wrong.

exportFile

public void exportFile(java.lang.String outFile)
                throws ILException
Exports a document to a file.

Export a document from the internal representation to a file, using the export filter and settings as previously determined by calls to setExportFilterTypeand setExportFilterParameter. The file will be created if it does not already exist (incl. all intermediate subdirectories, if necessary).

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

After an export operation, the document exported will still be available unchanged in its internal representation, ready to be exported using e.g. a different filter or different parameters.

Parameters:
outFile - the filename (absolute, incl. path) of the file where the output should get written.
Throws:
ILException - Throws an appropriate exception if anything goes wrong.
See Also:
OutputStream

setImportFilterType

public java.lang.String setImportFilterType(int filterType)
                                     throws ILException
Set import filter Type Sets the type of the import filter for data to be read by importStreamor importFile.

Parameters:
filterType - the type of the filter. Use one of the following: Only one filter can be installed at any time.

A previously installed filter will be replaced by the newly set one.

Returns:
a String handle to this import filter instance. Needed for setting parameters using setImportFilterParameter.
Throws:
ILException - thrown if an invalid import filter type is specified

setExportFilterType

public java.lang.String setExportFilterType(int filterType)
                                     throws ILException
Set export filter Type Sets the type of the export filter for exporting the internally held document.

Parameters:
filterType - the type of the filter. Use one of the following: Only one filter can be installed at any time.

A previously installed filter will be replaced by the newly set one.

Returns:
a String handle to this export filter instance. Needed for setting parameters using setExportFilterParameter.
Throws:
ILException - thrown if an invalid export filter type is specified
See Also:
setExportFilterParameter(java.lang.String, java.lang.String, java.lang.Object)

setExportFilterParameter

public void setExportFilterParameter(java.lang.String filterInstance,
                                     java.lang.String filterParameter,
                                     java.lang.Object parameterValue)
                              throws ILException
Sets an export filter parameter. Sets the value of a parameter for the specified export filter. For available parameter names and values, see the upCast manual.

Parameters:
filterInstance - the filter instance for which this parameter is to be set. The filter instance is retrieved from setExportFilterType.
filterParameter - the name of the parameter to be set. For available parameter names of each filter, see the upCast manual.
parameterValue - the value of the parameter. For valid parameter values and value ranges as well as Object types, see the upCast manual.
Throws:
ILException - Throws an appropriate exception if anything goes wrong.

setImportFilterParameter

public void setImportFilterParameter(java.lang.String filterInstance,
                                     java.lang.String filterParameter,
                                     java.lang.Object parameterValue)
                              throws ILException
Set import filter parameter. Sets the value of an parameter for the specified import filter. For available parameter names and values, see the upCast manual.

Parameters:
filterInstance - the filter instance for which this parameter is to be set. The filter instance is retrieved from setImportFilterType.
filterParameter - the name of the parameter to be set. For available parameter names of each filter, see the upCast manual.
parameterValue - the value of the parameter. For valid parameter values and value ranges as well as Object types, see the upCast manual.
Throws:
ILException - Throws an appropriate exception if anything goes wrong.

setGlobalParameter

public void setGlobalParameter(java.lang.String parameter,
                               java.lang.Object value)
                        throws ILException
Set global parameter for conversion process. Sets the value of a parameter used by both, Import and Export filters alike. For appropriate and available parameter names and values and the specific support by filters, see the upCast manual.

Parameters:
parameter - the name of the parameter to be set. For available parameter names, see the upCast manual.
value - the value of the parameter. For valid parameter values and value ranges and Object types, see the upCast manual.
Throws:
ILException - Throws an appropriate exception if anything goes wrong.

debugMessage

public void debugMessage(java.lang.String msg)
Makes debugging output Writes a string to the console when gDebug = true. Does nothing otherwise.

Since:
5.3.3

errorMessage

public void errorMessage(java.lang.String msg)
Makes error output.

Writes a string to the log file.

Parameters:
msg - the error message
Since:
5.3.3

warningMessage

public void warningMessage(java.lang.String msg)
Makes warning output.

Writes a string to the log file.

Parameters:
msg - the warning message
Since:
5.3.3

infoMessage

public void infoMessage(java.lang.String msg)
Makes info output.

Writes a string to the log file.

Parameters:
msg - the info message
Since:
5.3.3

setDebuggingMode

public void setDebuggingMode(boolean on)
Sets debugging mode.

Parameters:
on - if true, debugging output to the log file is turned on, if false, it is turned off.

dispose

public void dispose()
**BROKEN** This method is broken. You currently cannot dispose of an UpcastEngine object immediately.

Prepares this UpcastEngine object for disposing. Clears all references to itself it has created so that when the variable that holds the reference to this object is set to null, the object becomes available to the garbage collector.

This is when you need to create a new instance of this object. Procedure:

 
  theServer.dispose();
  theServer = null;
  System.gc():
 
 

Since:
2.2

getInstanceNameUser

public java.lang.String getInstanceNameUser()
Returns the user instance id/name passed in on construction time for this object.

Returns:
the user instance id/name as String
Since:
2.2.3

getCatalogResolver

public com.sun.resolver.tools.CatalogResolver getCatalogResolver()
Returns the Catalog resolver used by the system. You may then modify its configuration. upCast uses the resolver class library from sun.

Returns:
com.sun.resolver.tools.CatalogResolver instance
Since:
5.0

setLicense

public static boolean setLicense(java.io.InputStream inStream)
Sets a specified License file for use as license.

Parameters:
inStream - an input stream containing the license data. This might be a FileInputStream if you read from a file or some other stream (e.g. from getResourceAsStream() when reading from the application's Jar file).
Returns:
true, when the license was found and could be set (this does not mean it is valid!); false otherwise.
Since:
4.0.0

setLicense

public static boolean setLicense(java.lang.String licenseFile)
Sets a specified License file for use as license.

Parameters:
licenseFile - an absolute path to the license file. This is a convenience function for setLicense( new FileInputStream( inStream ) );
Returns:
true, when the license was found and could be set (this does not mean it is valid!); false otherwise.
Since:
4.0.1

addCustomEncoding

public void addCustomEncoding(java.io.InputStream customEncodingStream)
                       throws ILException
Adds a custom encoding to the collection of known encodings. This must be an ASCII file or stream conforming to the rules as laid out in the upCast manual for custom encoding files. There is no way to forget or unload a custom encoding. Encodings with the same value for codepage override already existing mappings.

Encodings are global and shared by all concurrent UpcastEngine instances.

Parameters:
customEncodingStream - the custom encoding
Throws:
ILException
Since:
4.0.2b10

addCustomEncoding

public void addCustomEncoding(java.lang.String customEncodingName)
                       throws ILException
Adds a custom encoding to the collection of known encodings. See addCustomEncodingfor details.

Parameters:
customEncodingName - file name of a custom encoding file
Throws:
ILException
Since:
5.0.0b12

setCustomFontConfiguration

public void setCustomFontConfiguration(java.io.InputStream customFontConfigStream)
                                throws ILException
Loads a new custom stdfonts.config configuration.

Information is not added to existing mappings and definitions, but replaces any existing configuration. The character stream must be all-ASCII and conform to the specification laid out in the upCast manual. The data is prepended to the default font configuration delivered with the application internally. This gives the custom configuration higher precedence with still the default fallbacks and definitions in place.

This configuration is held separately per UpcastEngine instance.

Parameters:
customFontConfigStream - the custom stdfonts.config file resp. stream
Throws:
ILException
Since:
4.0.2b10

setCustomFontConfiguration

public void setCustomFontConfiguration(java.lang.String customFontConfigName)
                                throws ILException
Loads a new custom stdfonts.config configuration. See setCustomFontConfigurationfor details.

Parameters:
customFontConfigName - the custom stdfonts.config file name
Throws:
ILException
Since:
5.0.0b12

addCatalog

public static void addCatalog(java.lang.String catalogFile)
Adds an (XML-) Catalog to the system. Previously set catalogs remain intact, the new catalog is appended in the search order. The catalog system is global to the application.

Parameters:
catalogFile - the absolute path to the catalog file
Since:
5.0.1b4

discardCatalogs

public static void discardCatalogs()
Removes all previously registered catalogs from the catalog system. Note that the catalog system is global to the application and changes take effect immediately for all instances of the Engine.

Since:
5.0.1b4

getEnvironmentValue

public java.lang.String getEnvironmentValue(java.lang.String key)
Returns the value of the environment property specified by the key integer. Available bits of information are:
de.infinityloop.application.version
the version in format "M.m.r" of the current application
de.infinityloop.application.build
the build number
de.infinityloop.application.buildtimestamp
the timestamp when this version of the application binary was built
de.infinityloop.application.name
the user-readable name of the application, i.e. "upCast" or "downCast"
de.infinityloop.application.license.features
names of all features in that license, separated by a space. Features that have expired are enclosed in parantheses, e.g. " gui (batch) java-api"
de.infinityloop.application.license.features.valid
names of all currently valid features in that license, separated by a space
de.infinityloop.application.license.features.expdays= feature
the number of days until the specified feature expires
de.infinityloop.application.dir.installation
the installation directory of the application
de.infinityloop.application.xmlcatalogs
a list of paths to the catalog files currently registered with this application, separated by the platform-dependent path separator character
de.infinityloop.application.xml.xerces.version
the version of the Xerces parser used
de.infinityloop.application.xslt.xalan.version
the version of the Xalan XSLT processor used
de.infinityloop.application.xslt.saxon.version
the version of the Saxon XSLT processor used
de.infinityloop.application.wordlink.version
the version of the WordLink gateway; returns null when WordLink is not available
de.infinityloop.application.wordlink.wordversion
the version of Word WordLink links to; returns null when WordLink is not available or no installed Word application can be found
de.infinityloop.application.wordlink.binarypath
the path to the WordLink gateway application il-gw.exe
de.infinityloop.application.api.native.dllversion
the version of the iloop.dll servicing the C/C++/VB/VBA APIs
de.infinityloop.application.mathlink.version
the version of the MathLink implementation; returns null when MathLink is not available
de.infinityloop.application.mathlink.dllversion
the version of the MathType mt.dll used; returns null when MathLink is not available or the mt.dll is not found
de.infinityloop.application.dir.support
the application's support file directory
de.infinityloop.application.dir.licenses
the application's licenses file directory
de.infinityloop.application.dir.encodings
the application's custom encoding files directory
de.infinityloop.application.file.log
the file that the application uses for logging
de.infinityloop.application.dir.tmp
the directory this application uses for temporary files
de.infinityloop.application.version.latest
the latest publicly released build number, or the empty string "" if this is the most recent build, or null if the latest build information could not be determined
de.infinityloop.progress.task.count
the number of tasks in the current progress meter
de.infinityloop.progress.task.current
the current task n in the current progress meter; n is 1-based.
de.infinityloop.progress.task.current.max
the total number of subdivisions of progress in the current task
de.infinityloop.progress.task.current.value
the current subdivision of the current task
de.infinityloop.progress.task.current.label
the label of the current task, intended for display to the user
de.infinityloop.progress.task.current.sublabel
the sub label for the current task, intended for display to the user
java.system.property
the value of the arbitrary, named java.system.property

Parameters:
key - a String indicating the desired bit of information.
Returns:
a string with the value of the requested environment value, or null if it cannot be determined
Since:
5.4