COM Interface

Overview

Xinc is fundamentally a java product. If you need to use Xinc in a Microsoft COM environment you will need to use the Xinc COM API. This section describes the process of configuring and using the API.

The Xinc COM server runs as a LocalServer. This means that a single instance of XincServer.exe is in memory. That instance will service requests from multiple client processes and threads. A single instance of the Java Virtual Machine is loaded when the XincServer gets loaded. The COM server is configured to unload itself after one minute of inactivity. This value may be configurable in a future release. The Xinc server uses a threading model of 'Both'. This allows clients to use any threading model you choose and still perform well.

The Xinc COM interface is automatically installed if you installed the product on a Windows machine. A simple configuration utility can be invoked from the start menu by selecting 'XincCom/ComConfig'. This utility will allow you to configure the JRE to use, as well as VM options such as the java heap size. The configuration for the COM server is stored in the registry under HKEY_LOCAL_MACHINE/SOFTWARE/Lunasil/Xinc/COM.

Configuration

A simple Configuration utility is provided to allow you to modify the configuration created during the install. Modifying the default configuration is not recommended unless absolutely necessary. If you do need to modify the configuration, start up the ComConfig utiltity.

The first field in the ComConfig utility allows you to select a Java VM to be used when running the Xinc COM server. If you don't see the VM you want to use in the list, you can type in a path to the JVM you want. The Jvm must implement the JNI Invocation API, Version 1.2 or higher. The actual file is generally called jvm.dll.

The next field allows you to set different options for the JVM. Each option is in a separate line. Some of the options you might wish to change or add are:

-Xms32m

Sets the initial heap size. Increasing this value may improve performance somewhat. It may also increase memory usage.

-Xmx400m

Sets the maximum heap size. Increasing this value may improve performance significantly if you are formatting lots of files or large files. You would generally increase this value if you are getting out of memory exceptions at runtime.

-Djava.class.path=

Sets the classpath. This should be set correctly for you. You might need to change it if you are replacing the default JAXP (Sax and XSLT components) implementation.

-Djava.endorsed.dirs=

This option allows default packages in the JRE to be overidden. By default, this is used to specify XALAN-J 2.5.1 as the default JAXP implementation instead of the Sun 1.4.x JAXP implementation.

-Djava.awt.headless=true

This option is not set by default.

-esa

This option is not set by default. It may be specified to enable System Assertions.

Other Options

The COM interface supports the ability to set the location of configuration files using Java system properties. System properties are set using the -D style of option shown above. See the Configuration section of the Xinc documentation for more details.

The API

The API is fairly straightforward, but some familiarity with COM is necessary.

Return Values

The following return values are applicable for all of the Xinc COM calls:

0 The call completed successfully.
0x80042001 Failed to load the Java VM dll.
0x80042002 GetProcAddress failed.
0x80042003 CreateVM failed.
0x80042004 Invalid registry Entry. The COM Configuration is incorrect. Run ComConfig and correct your settings
0x80042005 AttachThread failed.
0x80042006 ClassNotFound. Check your classpath setting in ComConfig.
0x80042007 MethodNotFound
0x80042008 Out of Memory. Try running ComConfig and setting the -Xmx value to be larger.
0x80042009 General Exception.
0x8004200a Formatting Error. There is an error in your XSL-FO input.


HRESULT formatToFile([in] BSTR docName, [in] BSTR styleName, [in] BSTR outputFileName)

The formatToFile method formats creates a PDF file from the specified XML document and XSLT stylesheet.

Parameters

docName

[in] Specifies the source XML document. If the stylesheet name is NULL, the docName parameter must refer to a valid XSL-FO file. The docName parameter should be a valid URL. Windows filenames will also be accepted, but are not recommended.

styleName

[in] Specifies the XSLT stylesheet to be used. If the styleName is not NULL, an XSLT transformation will be applied to the XML file specified by docName. The XML resulting from the XSLT transform must be valid XSL-FO.

outputFileName

[in] Specifies the name of the PDF output file. If the file exists, it is overwritten. If it does not exist, it is created. The outputFileName parameter should be a Windows filename.


HRESULT format([in] VARIANT foBytes, [out,retval] VARIANT *pdfBytes)

The format method formats the XSL-FO passed in foBytes and returns the pdf file as a SAFEARRAY of bytes. This method is useful when you want to use the MSXML XSLT engines to do the stylesheet processing and pass the resultant XSL-FO to the Xinc Formatter. It is also convenient to be able to write the pdf bytes directly to a Response if you are running Xinc in an ASP on IIS.

If images are being included in the document, and their URL's are not absolute, you MUST make a call to setBaseUrl before formatting the file! If you don't, Xinc will not be able to locate the image.

Parameters

foBytes

[in] Specifies the source XSL-FO document as a SAFEARRAY of bytes.

pdfBytes

[out,retval] The return value is a SAFEARRAY of bytes containing the PDF output.


HRESULT formatToMem([in] BSTR docName, [in] BSTR styleName, [out,retval] VARIANT *pdfBytes)

The formatToMem method creates a PDF from the specified XML document and XSLT stylesheet. The resultant PDF file is returned as a SAFEARRAY of bytes. The XSLT transformation is done in Xinc using the Apache XALAN engine.

Parameters

docName

[in] Specifies the source XML document. If the stylesheet name is NULL, the docName parameter must refer to a valid XSL-FO file. The docName parameter should be a valid URL. Windows filenames will also be accepted, but are not recommended.

styleName

[in] Specifies the XSLT stylesheet to be used. If the styleName is not NULL, an XSLT transformation will be applied to the XML file specified by docName. The XML resulting from the XSLT transform must be valid XSL-FO.

pdfBytes

[out,retval] The return value is a SAFEARRAY of bytes containing the PDF output.


HRESULT setBaseUrl([in] BSTR baseUrl)

The setBaseUrl method needs to be used when formatting a document using the format(foBytes, pdfBytes) method. It is required when trying to resolve relative URL's which occur in the XSL-FO document. A relative reference to an external-graphic or a dtd cannot be resolved if Xinc has no idea idea where the document came from. This method lets you specify a directory from which to locate these 'referred to' files.

Parameters

baseUrl

[in] A URL which refers to a directory to be used as a 'root' when resolving relative URL's.


HRESULT getErrorMsg([out,retval] BSTR* errMsg)

The getErrorMsg method is used to get any additional information which may be available after calling the formatToFile method. This method is typically called after getting a non-zero return value from the formatToFile method.

Parameters

errMsg

[out, retval] Any additional information regarding the status of the last invocation of formatToFile(). The value is a BSTR which may have multiple text lines separated by CR/LF pairs.

Sample Code

All of the sample code can be found in your Xinc installation at '\Program Files\Xinc\examplecode\'. The COM API examples are located in the 'com' subdirectory.

View sample VBScript

View sample VB App

View sample ASP and the HTML that goes with it