de.infinityloop.upcast

Class UpcastEngine

java.lang.Object

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 /test/in/in.rtf to /test/out/out.xml:

 
  String moduleID;
  UpcastEngine ucInst = new UpcastEngine( "one" );

  ucInst.setPipelineBaseURI( "/path/to/rootfolder/" );
  ucInst.setLicense( "/path/to/upcast.license" );

  ucInst.initializeConversion();
 
    ucInst.setPipelineVariable( "DestinationFolder", "/test/out/" );
    ucInst.setPipelineVariable( "ImageDestinationFolder", "/test/out/" );
 
    moduleID = ucInst.setModuleType( UpcastEngine.kRTFImporterType );
    ucInst.setModuleParameter( moduleID, "OrigNumbering", Boolean.TRUE );
    ucInst.setModuleParameter( moduleID, "SourceFile", "/test/in/in.rtf" );
    ucInst.execute( moduleID );
 
    moduleID = ucInst.setModuleType( UpcastEngine.kXMLRawExporterType );
    ucInst.setModuleParameter( moduleID, "DeleteEmpties", Boolean.FALSE );
    ucInst.setModuleParameter( moduleID, "DestinationFile", "${pipeline:DestinationFolder}/out.xml;" );
    ucInst.execute( moduleID );
 
  ucInst.cleanupConversion();
 
 

Version:

7.0.0

Field Summary

Fields

Modifier and Type	Field and Description
static int	kCommandlineProcessorType selector for the Commandline processor.
static int	kCSSExporterType selector for the CSS Exporter module.
static int	kExternalPipelineProcessorType selector for the External Pipeline Processor module.
static int	kGroupingProcessorType Deprecated. Its functionality has been integrated into the kUPLTreeProcessorType.
static int	kPipelineVariablesProcessorType selector for the Pipeline Variables Processor module.
static int	kRTFExporterType selector for the RTF Exporter module.
static int	kRTFImporterType selector for the RTF 1.6 Specification compliant import module.
static int	kSectionProcessorType selector for the Section Processor module.
static int	kUnicodeTranslationProcessorType selector for the Unicode Translation Processor module.
static int	kUPLProcessorType selector for the UPL Processor module.
static int	kUPLTreeProcessorType selector for the UPL Tree Processor module.
static int	kValidationProcessorType selector for the Validation Processor module.
static int	kXMLExporterType selector for the XML Exporter module.
static int	kXMLImporterType selector for the XML Importer module.
static int	kXMLRawExporterType Deprecated. Use kXMLExporterType instead.
static int	kXSLTProcessorType selector for the XSLT Processor module.

Constructor Summary

Constructors

Constructor and Description
UpcastEngine(boolean debug, java.lang.String userInstanceId) Deprecated. use UpcastEngine(String, String) instead
UpcastEngine(int loggingLevel, java.lang.String userInstanceId) Deprecated. use UpcastEngine(String, String) instead
UpcastEngine(java.lang.String userInstanceId) Creates a new instance of the UpcastEngine object.
UpcastEngine(java.lang.String logfilterspec, java.lang.String userInstanceId) Creates a new instance of the UpcastEngine object.

Method Summary

Methods

Modifier and Type	Method and Description
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	cleanupConversion() Cleans up the engine after a conversion.
void	clearCollectedMessages() Clears any collected messages in this object instance's message collector.
void	debugMessage(java.lang.String msg) Makes debugging output Writes a string to the console when gDebug = true.
void	discardCatalogs() Removes all previously registered catalogs from the pipeline's catalog setup.
void	errorMessage(java.lang.String msg) Makes error output.
static de.infinityloop.upcast.core.AppFacelessLayer	getApplicationObject() The object of the owning application.
org.apache.xml.resolver.tools.CatalogResolver	getCatalogResolver() Returns the Catalog resolver used by the system.
UpcastException	getCollectedMessages() Retrieves the message collector which holds the current list of errors and/or warnings.
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.
protected LogSource	getLogger() Returns the most appropriate logger depending on the current state of this UpcastEngine instance
java.lang.String	getPipelineBaseURI() Retrieve the current value of this UpcastEngine object.
java.lang.Object	getPipelineResult() Returns the (current) pipeline result object, which is the one that was last set by a module during pipeline execution when this function is called.
java.lang.String	getPipelineVariable(java.lang.String name) Retrieve the current value of the specified pipeline variable as a String.
void	infoMessage(java.lang.String msg) Makes info output.
void	initializeConversion() Initializes the engine for a new conversion.
static UpcastPipeline	makePipeline(java.lang.String docPath) This method creates an UpcastPipeline object from an *.ucdoc or *.ucpar file existing on disk.
java.lang.Object	runModule(java.lang.String moduleType) Runs the currently active module.
static java.lang.Object	runPipeline(java.lang.String docPath, java.util.Map parameters) This method lets you run a Pipeline (*.ucdoc or *.ucpar) file existing on disk with the specified set of pipeline parameters.
static java.lang.Object	runPipeline(java.lang.String docPath, java.util.Map parameters, java.lang.String licenseOverride) This method lets you run a Pipeline (*.ucdoc or *.ucpar) file existing on disk with the specified set of pipeline parameters.
static void	setCatalog(java.lang.String catalogFile) Adds an (XML-) Catalog to the system.
void	setCustomFontConfiguration(java.io.Reader customFontConfigReader) Loads a new custom stdfonts.config configuration.
void	setCustomFontConfiguration(java.lang.String customFontConfigName) Loads a new custom font configuration.
void	setDebuggingMode(boolean on) Deprecated. use setLoggingFilter instead
boolean	setLicense(java.io.InputStream inStream) Sets a specified License file for use as license.
boolean	setLicense(java.lang.String licenseFile) Sets a specified License file for use as license.
static void	setLogfile(java.lang.String absolutePath) (Re-)set the destination file to write log messages to.
static void	setLogfile(java.lang.String absolutePath, int sizelimitBytes) (Re-)set the destination file to write log messages to and set the maximum size (in bytes) for that file at the same time.
static void	setLoggingFilter(java.lang.String filterDescription) Lets you set a detailed filter description for filtering logging events that go to the external logger.
void	setLoggingLevel(int level) Deprecated. use setLoggingFilter instead
void	setModuleParameter(java.lang.String moduleInstance, java.lang.String moduleParameter, java.lang.Object parameterValue) Sets a module parameter.
java.lang.String	setModuleType(int moduleType) Instantiates a new, then current module, replacing the previous one.
java.lang.String	setModuleType(java.lang.String moduleTypeName) Instantiates a new, then current module, replacing the previous one.
void	setPipelineBaseURI(java.lang.String url) Sets the pipeline base URL.
void	setPipelineParameter(java.lang.String parameter, java.lang.Object value) Sets a pipeline parameter that controls the behaviour of the pipeline during execution of modules.
void	setPipelineVariable(java.lang.String parameter, java.lang.Object value) Set a pipeline variable for conversion process.
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

kRTFImporterType

public static final int kRTFImporterType

selector for the RTF 1.6 Specification compliant import module.

See Also:

Constant Field Values

kUPLTreeProcessorType

public static final int kUPLTreeProcessorType

selector for the UPL Tree Processor module.

See Also:

Constant Field Values

kUPLProcessorType

public static final int kUPLProcessorType

selector for the UPL Processor module.

See Also:

Constant Field Values

kGroupingProcessorType

@Deprecated
public static final int kGroupingProcessorType

Deprecated. Its functionality has been integrated into the kUPLTreeProcessorType.

selector for the Grouper Processor module.

See Also:

Constant Field Values

kSectionProcessorType

public static final int kSectionProcessorType

selector for the Section Processor module.

See Also:

Constant Field Values

kXMLExporterType

public static final int kXMLExporterType

selector for the XML Exporter module.

See Also:

Constant Field Values

kXMLRawExporterType

@Deprecated
public static final int kXMLRawExporterType

Deprecated. Use kXMLExporterType instead.

selector for the XML Exporter module.

See Also:

Constant Field Values

kCommandlineProcessorType

public static final int kCommandlineProcessorType

selector for the Commandline processor.

See Also:

Constant Field Values

kXSLTProcessorType

public static final int kXSLTProcessorType

selector for the XSLT Processor module.

See Also:

Constant Field Values

kUnicodeTranslationProcessorType

public static final int kUnicodeTranslationProcessorType

selector for the Unicode Translation Processor module.

See Also:

Constant Field Values

kCSSExporterType

public static final int kCSSExporterType

selector for the CSS Exporter module.

See Also:

Constant Field Values

kValidationProcessorType

public static final int kValidationProcessorType

selector for the Validation Processor module.

See Also:

Constant Field Values

kPipelineVariablesProcessorType

public static final int kPipelineVariablesProcessorType

selector for the Pipeline Variables Processor module.

See Also:

Constant Field Values

kXMLImporterType

public static final int kXMLImporterType

selector for the XML Importer module.

See Also:

Constant Field Values

kExternalPipelineProcessorType

public static final int kExternalPipelineProcessorType

selector for the External Pipeline Processor module.

See Also:

Constant Field Values

kRTFExporterType

public static final int kRTFExporterType

selector for the RTF Exporter module.

See Also:

Constant Field Values

Constructor Detail

UpcastEngine

public UpcastEngine(java.lang.String userInstanceId)
             throws UpcastException

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:

userInstanceId - you may pass an arbitrary string here which helps to identify the class instance in log file and debug message output.

Throws:

UpcastException

Since:

3.0.0

UpcastEngine

public UpcastEngine(java.lang.String logfilterspec,
            java.lang.String userInstanceId)
             throws UpcastException

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:

userInstanceId - you may pass an arbitrary string here which helps to identify the class instance in log file and debug message output.

Throws:

UpcastException

Since:

7.1.3

UpcastEngine

@Deprecated
public UpcastEngine(boolean debug,
                       java.lang.String userInstanceId)
             throws UpcastException

Deprecated. use UpcastEngine(String, String) instead

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.

userInstanceId - you may pass an arbitrary string here which helps to identify the class instance in log file and debug message output.

Throws:

UpcastException

Since:

3.0.0

UpcastEngine

@Deprecated
public UpcastEngine(int loggingLevel,
                       java.lang.String userInstanceId)
             throws UpcastException

Deprecated. use UpcastEngine(String, String) instead

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:

loggingLevel - Set the logging threshold for the external logger; see also setLoggingLevel

userInstanceId - you may pass an arbitrary string here which helps to identify the server instance in log file and debug message output.

Throws:

UpcastException

Since:

7.0.0

Method Detail

getLogger

protected LogSource getLogger()

Returns the most appropriate logger depending on the current state of this UpcastEngine instance

runModule

public java.lang.Object runModule(java.lang.String moduleType)
                           throws UpcastException

Runs the currently active module.

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

Parameters:

moduleType - the type of the module to run as obtained by setModuleType method.

Returns:

Object Returns the current module result object possibly set by the module upon completion; might be null. The value effectively is ${pipeline:ModuleResult}.

Throws:

UpcastException - Throws an appropriate exception if anything goes wrong.

setModuleType

public java.lang.String setModuleType(int moduleType)
                               throws UpcastException

Instantiates a new, then current module, replacing the previous one.

Parameters:

moduleType - the type of the filter. Use one of the following:

• kRTFImporterType
• kUPLTreeProcessorType
• kUPLProcessorType
• kSectionProcessorType
• kXMLExporterType
• kCommandlineProcessorType
• kXSLTProcessorType
• kUnicodeTranslationProcessorType
• kCSSExporterType
• kValidationProcessorType
• kPipelineVariablesProcessorType
• kXMLImporterType
• kExternalPipelineProcessorType
• kRTFExporterType

Only one module can be installed at any time.

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

Returns:

a String handle to this module instance. Needed for setting parameters using setModuleParameter.

Throws:

UpcastException - thrown if an invalid module type is specified

See Also:

setModuleParameter(java.lang.String, java.lang.String, java.lang.Object)

setModuleType

public java.lang.String setModuleType(java.lang.String moduleTypeName)
                               throws UpcastException

Instantiates a new, then current module, replacing the previous one.

Parameters:

moduleTypeName - the identification name of the module.

TODO

Only one module can be installed at any time.

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

Returns:

a String handle to this module instance. Needed for setting parameters using setModuleParameter.

Throws:

UpcastException - thrown if an invalid module type name is specified

See Also:

setModuleParameter(java.lang.String, java.lang.String, java.lang.Object)

setModuleParameter

public void setModuleParameter(java.lang.String moduleInstance,
                      java.lang.String moduleParameter,
                      java.lang.Object parameterValue)
                        throws UpcastException

Sets a module parameter. Sets the value of a parameter for the specified module. For available parameter names and values, see the upCast manual.

Parameters:

moduleInstance - the module instance for which this parameter is to be set. The module instance is retrieved from setModuleType.

moduleParameter - the name of the parameter to be set. For available parameter names of each module, 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:

UpcastException - Throws an appropriate exception if anything goes wrong.

setPipelineParameter

public void setPipelineParameter(java.lang.String parameter,
                        java.lang.Object value)
                          throws UpcastException

Sets a pipeline parameter that controls the behaviour of the pipeline during execution of modules.

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:

UpcastException - Throws an appropriate exception if anything goes wrong.

Since:

7.0.0

setPipelineVariable

public void setPipelineVariable(java.lang.String parameter,
                       java.lang.Object value)
                         throws UpcastException

Set a pipeline variable for conversion process. Sets the value of a parameter shared by any module. 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:

UpcastException - Throws an appropriate exception if anything goes wrong.

Since:

7.0.0

getPipelineVariable

public java.lang.String getPipelineVariable(java.lang.String name)
                                     throws UpcastException

Retrieve the current value of the specified pipeline variable as a String.

Parameters:

name - the name of the variable to be queried.

Returns:

the variable's value as a String or null, if no value can be determined (e.g. because the parameter does not exist or has not yet been set)

Throws:

UpcastException - Throws an appropriate exception if anything goes wrong.

Since:

7.0.0

getPipelineBaseURI

public java.lang.String getPipelineBaseURI()
                                    throws UpcastException

Retrieve the current value of this UpcastEngine object. Throws a NPE when not set yet.

Returns:

the base URI of this UpcastEngine object in URL format with trailing '/'

Throws:

UpcastException - Throws an appropriate exception if anything goes wrong.

Since:

7.0.0

setPipelineBaseURI

public void setPipelineBaseURI(java.lang.String url)
                        throws UpcastException

Sets the pipeline base URL. When this is a folder (ending in '/'), this is used as-is; when this is a file, only the path component to its location is used for the base URL. This value can be referenced in parameter values using the reserved ${pipeline:base} variable reference notation.

Note that this also sets the variable ${pipeline:ParamBase} to the same value, as UpcastEngine instances cannot and do not differentiate between those two kinds of files and therefore paths.

You should set this at the beginning of a conversion, directly after the instantiation of a new UpcastEngine object if you use that specific variable in your pipelines to keep them portable. In GUI mode, this value is established by the save location of the pipeline document (*.ucdoc). Since this does not exist in the API, a value must be specified explicitly using this function.

The default (when not explicitly set) is the highly unreliable and unpredictable (especially in a server environment) Java current directory.

Parameters:

url - the base url for that pipeline

Throws:

UpcastException - Throws an appropriate exception if anything goes wrong.

Since:

7.0.0

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

@Deprecated
public void setDebuggingMode(boolean on)

Deprecated. use setLoggingFilter instead

Sets debugging mode.

Parameters:

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

setLoggingLevel

@Deprecated
public void setLoggingLevel(int level)

Deprecated. use setLoggingFilter instead

Set the logging threshold for the external logger.

Parameters:

level - the logging level in the range from {0..7}, with higher numbers being more verbose. The default (INFO level) is 3.

setLoggingFilter

public static void setLoggingFilter(java.lang.String filterDescription)

Lets you set a detailed filter description for filtering logging events that go to the external logger. When the filterDescription is null or the empty string, the current configuration of the logger is not changed.

Parameters:

filterDescription - a textual filter description conforming to the following syntax: The syntax is an arbitrary sequence of the following, whitespace- or comma-separated tokens, which are executed in the specified sequence: +off, +fatal, +error, +warn, +info, +debug, +verbose, +detail, +all : enable the respective message type -off, -fatal, -error, -warn, -info, -debug, -verbose, -detail, -all : disable the respective message type +msgconstantname : enable that message -msgconstantname : disable that message

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 org.apache.xml.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 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 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 UpcastException

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:

UpcastException

Since:

4.0.2b10

addCustomEncoding

public void addCustomEncoding(java.lang.String customEncodingName)
                       throws UpcastException

Adds a custom encoding to the collection of known encodings. See addCustomEncoding(java.io.InputStream)for details.

Parameters:

customEncodingName - file name of a custom encoding file

Throws:

UpcastException

Since:

5.0.0b12

setCustomFontConfiguration

public void setCustomFontConfiguration(java.io.Reader customFontConfigReader)
                                throws UpcastException

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:

customFontConfigReader - the custom font configuration file resp. character stream

Throws:

UpcastException

Since:

4.0.2b10

setCustomFontConfiguration

public void setCustomFontConfiguration(java.lang.String customFontConfigName)
                                throws UpcastException

Loads a new custom font 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:

customFontConfigName - the custom font configuration file name

Throws:

UpcastException

Since:

5.0.0b12

addCatalog

public 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.

Parameters:

catalogFile - the absolute path to the catalog file

Since:

5.0.1b4

setCatalog

public static void setCatalog(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.

Parameters:

catalogFile - the absolute path to the catalog file

Since:

7.5.3

discardCatalogs

public void discardCatalogs()

Removes all previously registered catalogs from the pipeline's catalog setup.

Since:

5.0.1b4

getCollectedMessages

public UpcastException getCollectedMessages()

Retrieves the message collector which holds the current list of errors and/or warnings. This collector object is cleared automatically on each call to cleanupConversion(), but can be cleared manually also using the clearCollectedMessages() method. For convenience, the result is wrapped into an UpcastException object, so you can re-use the code already existing for real exception handling.

Returns:

an UpcastException object wrapping the messages collected until now.

clearCollectedMessages

public void clearCollectedMessages()

Clears any collected messages in this object instance's message collector. You will not be able to retrieve any of them after a call to this method, so you should be sure to not be any longer insterested in any error and/or warning messages that have been generated up to this point in execution. This method is automatically called by a call to cleanupConversion().

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.upcast.version

the version in format "M.m.r" of the current application

de.infinityloop.upcast.build

the build number

de.infinityloop.upcast.buildtimestamp

the timestamp when this version of the application binary was built

de.infinityloop.upcast.name

the user-readable name of the application, i.e. "upCast" or "downCast"

de.infinityloop.upcast.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.upcast.license.features.valid

names of all currently valid features in that license, separated by a space

de.infinityloop.upcast.license.features.expdays= feature

the number of days until the specified feature expires

de.infinityloop.upcast.dir.installation

the installation directory of the application

de.infinityloop.upcast.xmlcatalogs

a list of paths to the catalog files currently registered with this application, separated by the platform-dependent path separator character

de.infinityloop.upcast.xml.xerces.version

the version of the Xerces parser used

de.infinityloop.upcast.xslt.xalan.version

the version of the Xalan XSLT processor used

de.infinityloop.upcast.xslt.saxon.version

the version of the Saxon XSLT processor used

de.infinityloop.upcast.wordlink.version

the version of the WordLink gateway; returns null when WordLink is not available

de.infinityloop.upcast.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.upcast.wordlink.binarypath

the path to the WordLink gateway application il-gw.exe

de.infinityloop.upcast.api.native.dllversion

the version of the iloop.dll servicing the C/C++/VB/VBA APIs

de.infinityloop.upcast.mathlink.version

the version of the MathLink implementation; returns null when MathLink is not available

de.infinityloop.upcast.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.upcast.dir.support

the application's support file directory

de.infinityloop.upcast.dir.licenses

the application's licenses file directory

de.infinityloop.upcast.dir.encodings

the application's custom encoding files directory

de.infinityloop.upcast.file.log

the file that the application uses for logging

de.infinityloop.upcast.dir.tmp

the directory this application uses for temporary files

de.infinityloop.upcast.pipeline.info

returns the contents of the pipeline information window as string

de.infinityloop.upcast.pipeline.version

returns the compatibility version of the pipeline as string (or the empty string when not existing)

de.infinityloop.upcast.pipeline.build

returns the build number of the pipeline as string (or the empty string when not existing)

de.infinityloop.upcast.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

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

initializeConversion

public void initializeConversion()
                          throws UpcastException

Initializes the engine for a new conversion. Call every time you start a new conversion pipeline for a new document. Clears (among many other things) the pipeline variable store.

Throws:

UpcastException

Since:

7.0.0

cleanupConversion

public void cleanupConversion()

Cleans up the engine after a conversion. Call every time you have finished processing a document. This is used to delete any temporary files that modules may have created on their way etc.

Since:

7.0.0

makePipeline

public static UpcastPipeline makePipeline(java.lang.String docPath)
                                   throws UpcastException

This method creates an UpcastPipeline object from an *.ucdoc or *.ucpar file existing on disk. Note that the pipeline document must bring its complete configuration, catalogs and encodings must all be set in the ucdoc itself. Parameters and (if required) a license override can be set later on the created object itself with respective member methods.

Parameters:

docPath - the (possibly relative to user.dir) path to the ucdoc or ucpar file to run

Returns:

an UpcastPipeline object representing the loaded pipeline

Throws:

UpcastException - when errors occurred during creation

Since:

7.5.3

runPipeline

public static java.lang.Object runPipeline(java.lang.String docPath,
                           java.util.Map parameters)
                                    throws UpcastException

This method lets you run a Pipeline (*.ucdoc or *.ucpar) file existing on disk with the specified set of pipeline parameters. Note that the pipeline document must bring its complete configuration, i.e. license info, catalogs and encodings must all be set in the ucdoc itself.

Parameters:

docPath - the full, absolute path to the ucdoc file to run

parameters - a Map of parameters, with the key being the name of the pipeline parameter as String and the value being the (Java-) object to set, i.e. a String, Boolean or an ArrayList.

Returns:

the return value of the pipeline (may be null!)

Throws:

UpcastException - when errors occurred during execution

runPipeline

public static java.lang.Object runPipeline(java.lang.String docPath,
                           java.util.Map parameters,
                           java.lang.String licenseOverride)
                                    throws UpcastException

This method lets you run a Pipeline (*.ucdoc or *.ucpar) file existing on disk with the specified set of pipeline parameters. Note that the pipeline document must bring its complete configuration, i.e. license info, catalogs and encodings must all be set in the ucdoc itself. To use the evaluation license file embedded in the upcast.jar file instead of the license specified in the pipeline document, use the following absolute URL for the licenseOverride parameter: "jar:file:!/de/infinityloop/upcast/resources/licenses/upcast-eval.uclicense"

Parameters:

docPath - the full, absolute path to the ucdoc or ucpar file to run

parameters - a Map of parameters, with the key being the name of the pipeline parameter as String and the value being the (Java-) object to set, i.e. a String, Boolean or an ArrayList.

licenseOverride - an absolute path to an alternate license file to use instead of the one supplied by the pipeline document

Returns:

the return value of the pipeline (may be null!)

Throws:

UpcastException - when errors occurred during execution

Since:

7.5.3

getPipelineResult

public java.lang.Object getPipelineResult()

Returns the (current) pipeline result object, which is the one that was last set by a module during pipeline execution when this function is called.

Returns:

the result object (which effectively is ${pipeline:ModuleResult}). This may be null. It is also null when there's no current pipeline at calling time.

Since:

7.1.8

getApplicationObject

public static de.infinityloop.upcast.core.AppFacelessLayer getApplicationObject()

The object of the owning application. We need this in those instances where we must set global catalogs and/or debug levels.

Returns:

the owning application object

setLogfile

public static void setLogfile(java.lang.String absolutePath)

(Re-)set the destination file to write log messages to. Can be called anytime and takes effect immediately.

Parameters:

absolutePath - the absolute path to the log file

setLogfile

public static void setLogfile(java.lang.String absolutePath,
              int sizelimitBytes)

(Re-)set the destination file to write log messages to and set the maximum size (in bytes) for that file at the same time. Can be called anytime and takes effect immediately.

Parameters:

absolutePath - the absolute path to the log file

sizelimitBytes - the maximum size limit in bytes for the log file

Since:

7.6.2