de.infinityloop.downcast
Class DowncastEngine

java.lang.Object
  extended by de.infinityloop.downcast.DowncastEngine

public class DowncastEngine
extends java.lang.Object

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

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

 DownCast.setLicense( "/path/to/downcast.license" );
 
 DowncastEngine dc = new DowncastEngine( true, "downCast" );
 dc.convertFile( "/path/to/in.xml", "/path/to/output/", "/path/to/preprocess.xsl" );
 

Version:
1.1.0

Constructor Summary
DowncastEngine(boolean debug, java.lang.String instanceIDUser)
          Creates a new instance of the DowncastEngine object.
DowncastEngine(java.lang.String instanceIDUser)
          Creates a new instance of the DowncastEngine 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 convertFile(java.lang.String srcFile, java.io.OutputStream destStream, java.lang.Object procSheet, java.lang.String parameters)
          Convert a document from a file into a Java Stream.
 void convertFile(java.lang.String srcFile, java.lang.String destPath, java.lang.Object procSheet, java.lang.String parameters)
          Convert a document from a file into a folder.
 void convertFile(java.lang.String srcFile, java.lang.String destPath, java.lang.String procSheet)
          Convert a document from a file into a folder.
 void debugMessage(java.lang.String msg)
          Makes debugging output.
static void discardCatalogs()
          Removes all previously registered catalogs from the catalog system.
 void errorMessage(java.lang.String msg)
          Makes error output.
 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 proeprty specified by the key integer.
 java.lang.Object getGlobalParameter(java.lang.String parameter, java.lang.Object fallback)
          Retrieves the current value of the specified global parameter.
 java.lang.String getInstanceNameUser()
           
 void infoMessage(java.lang.String msg)
          Makes info output.
 void preprocessFile(java.lang.String srcUrl, java.lang.String destUrl, java.lang.String xslUrl, java.lang.String parameters)
          Only do the XSLT preprocessing of some file and write the result to a specified location.
 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 setGlobalParameter(java.lang.String parameter, java.lang.Object value)
          Set global parameter for conversion process.
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
 

Constructor Detail

DowncastEngine

public DowncastEngine(java.lang.String instanceIDUser)
               throws ILException
Creates a new instance of the DowncastEngine 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

DowncastEngine

public DowncastEngine(boolean debug,
                      java.lang.String instanceIDUser)
               throws ILException
Creates a new instance of the DowncastEngine 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 log, 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
Method Detail

convertFile

public void convertFile(java.lang.String srcFile,
                        java.lang.String destPath,
                        java.lang.String procSheet)
                 throws ILException
Convert a document from a file into a folder.

This method imports an upCast DTD conforming XML document, processes it and writes the result to the specified destination file.

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

The srcFile must be an absolute filename.

The destPath must be an absolute pathname.

Parameters:
srcFile - the (absolute) name (incl. path) of the file to be imported.
destPath - the (absolute) path to where the result should be written to. It will be named basename.rtf.
procSheet - the (absolute) name (incl. path) of the XSLT processing sheet which should be applied to the source file prior to feeding it the RTF converter component. Pass null if you do not want any preprocessing to take place.
Throws:
ILException - Throws an appropriate exception if something goes wrong.

convertFile

public void convertFile(java.lang.String srcFile,
                        java.lang.String destPath,
                        java.lang.Object procSheet,
                        java.lang.String parameters)
                 throws ILException
Convert a document from a file into a folder.

This method imports an upCast DTD conforming XML document, processes it and writes the result to the specified destination file.

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

The srcFile must be an absolute filename.

The destPath must be an absolute pathname.

Parameters:
srcFile - the (absolute) name (incl. path) of the file to be imported.
destPath - the (absolute) path to where the result should be written to. It will be named basename.rtf.
procSheet - the (absolute) name (incl. path) of the XSLT processing sheet which should be applied to the source file prior to feeding it the RTF converter component. Pass null if you do not want any preprocessing to take place. Can be a InputStream, String or InputProxy object.
parameters - a String identifying parameters in the form: 'name1="value1" name2="value2" ...' You may use variables il:srcfilename (full XML source file name), il:destfolder (destination path), il:srcfolder (path to source file).
Throws:
ILException - Throws an appropriate exception if something goes wrong.
Since:
1.5.0

convertFile

public void convertFile(java.lang.String srcFile,
                        java.io.OutputStream destStream,
                        java.lang.Object procSheet,
                        java.lang.String parameters)
                 throws ILException
Convert a document from a file into a Java Stream.

This convenience method wrapper imports an upCast DTD conforming XML document, processes it and writes the result to the specified destination Stream.

This is done using temporary files invisible to the user, so the application needs write access to the temporary directory (which it also needs for XSLT pre-conversion, so nothing is lost here). The magic folder location for this is the "Temporary Items Folder". It can be set at startup using the system property de.infinityloop.application.tmpdir.

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

The srcFile must be an absolute filename.

The destStream is the OutputStream the data should be written to.

Parameters:
srcFile - the (absolute) name (incl. path) of the file to be imported.
destStream - the OutputStream where the result should be written to.
procSheet - the (absolute) name (incl. path) of the XSLT processing sheet which should be applied to the source file prior to feeding it the RTF converter component. Pass null if you do not want any preprocessing to take place. Can be a InputStream, String or InputProxy object.
parameters - a String identifying parameters in the form: 'name1="value1" name2="value2" ...' You may use variables il:srcfilename (full XML source file name), il:destfolder (destination path), il:srcfolder (path to source file).
Throws:
ILException - Throws an appropriate exception if something goes wrong.
Since:
1.5.4

preprocessFile

public void preprocessFile(java.lang.String srcUrl,
                           java.lang.String destUrl,
                           java.lang.String xslUrl,
                           java.lang.String parameters)
                    throws ILException
Only do the XSLT preprocessing of some file and write the result to a specified location.

Parameters:
srcUrl - the source XML document
destUrl - the destination XML document
xslUrl - the XSLT processing sheet
parameters - parameter string passed (after parsing it out into individual parameters) as parameters to the transformation
Throws:
ILException

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 global conversion parameter.

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

getGlobalParameter

public java.lang.Object getGlobalParameter(java.lang.String parameter,
                                           java.lang.Object fallback)
                                    throws ILException
Retrieves the current value of the specified global parameter.

Parameters:
parameter - the name of the parameter to be retrieved. For any available parameter names, see the downCast manual.
fallback - the value to be returned when the requested parameter is not available.
Throws:
ILException
Since:
1.5.4

debugMessage

public void debugMessage(java.lang.String msg)
Makes debugging output.

Writes a string to the log file when debug = true. Does nothing otherwise.

Since:
1.6.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:
1.6.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:
1.6.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:
1.6.3

setDebuggingMode

public void setDebuggingMode(boolean on)
Sets debugging mode.

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

getCatalogResolver

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

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

getInstanceNameUser

public java.lang.String getInstanceNameUser()
Returns:
contains the user instance id/name passed on construction time.

setLicense

public static boolean setLicense(java.io.InputStream inStream)
                          throws ILException
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.
Throws:
ILException

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:
1.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 downCast manual for custom encoding files. There is no way to forget or unload a custom encoding. Encodings with the same value for codepage specified override already existing mappings.

Encodings are global and shared by all concurrent DowncastEngine instances.

Parameters:
customEncodingStream - the custom encoding
Throws:
ILException
Since:
1.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:
1.5.0b20

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 downCast 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 DowncastEngine instance.

Parameters:
customFontConfigStream - the custom stdfonts.config file resp. stream
Throws:
ILException
Since:
1.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:
1.5.0b20

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:
1.5.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:
1.5.1b4

getEnvironmentValue

public java.lang.String getEnvironmentValue(java.lang.String key)
Returns the value of the environment proeprty 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 identifying the desired bit of information.
Returns:
a string with the value of the requested information, or null if it could not be determined
Since:
1.7