[xep-support] XEP's COM wrapper?!

[David Tolpin]

> 
> I (and many others) would like to try the COM wrapper before we spend the
> $5000

Hi,

thank you for the input. First, it is $700, not $5000 to try COM; COM is available
with developer stamped. Then, while I cannot make it available for free (because
then I'll be answering for free one too many questions about something broken in
Windows instead of writing code), I can publish the documentation. A description
of the exposed interface follows.


XEP COM Wrapper

1. Overview

XEP COM wrapper provides COM interface to XEP formatter engine,
thus permitting its use in any COM-enabled environment. XEP COM
wrapper is a single Dynamic Link Library, registered as a COM
object in Windows.


2. Contents of the package:

readme.txt - this document

XEP.DLL    - principal DLL for the COM object. Incorporates TLB library.
XEP.IDL    - IDL definition for IXEPFormatter COM inteface.
XEPJNI.JAR - Java stub classes

EXAMPLES\CppClient\ - C++ client sample
EXAMPLES\PHPClient\ - PHP client sample
EXAMPLES\VBClient\  - Visual Basic client sample

UTILS\XEPCOMCFG\xepcomcfg.exe     - GUI utility to configure XEP COM settings
UTILS\XEPCOMCFGCL\xepcomcfgcl.exe - console utility to configure XEP COM settings


3. Requirements

The following software must be installed on your computer in order
to access XEP through COM interface:
- XEP formatter version 3.0 or later, properly installed and activated;
- Sun JDK/JRE version 1.2.2 or later (1.3 or later strongly recommended).

XEP COM depends on JVM.DLL which is a part of Sun Java Runtime Environment;
the path to this DLL must be present in your system-wide PATH. Typically,
JVM.DLL is located in a subdirectory of JRE\BIN in your Java home directory.
For JDK1.3, available subdirectories are HOTSPOT (recommended) or CLASSIC;
for JDK1.4 they are CLIENT (recommended) and SERVER.


4. Installation

To install XEP COM wrapper, follow this procedure:

A. Ensure that a copy of JVM.DLL can be found in one of the directories
   included in the PATH. XEP COM wrapper will refuse to install if it 
   cannot find a Java VM.

B. Ensure that you have write access to HKEY_LOCAL_MACHINE\Software 
   branch of your computer's Registry. Normally, this requires local 
   administrator privileges.

C. Run XEPCOMSETUP.EXE and follow  on-screen instructions.

D. Upon successful completion, configure XEP COM wrapper with one of
   configuration tools (XEPCOMCFG.EXE or XEPCOMCFGCL.EXE); see explanations
   below.


5. Deinstallation

To remove XEP COM wrapper from your system, use 'Add/Remove Programs' 
option in the Control Panel.


6. Configuration

XEP COM wrapper must be configured before use. There are three types 
of configuration options:
  - classpath;
  - Java properties;
  - JVM options.

Classpath is a list of directories and JAR files used by Java virtual
machine to search for Java classes. It should contain all JAR files 
from XEP installation (located in its lib/ subdirectory), and XEPJNI.JAR
stuib file supplied with XEP COM wrapper. Please refer to XEP documentation
for additional details.

Properties are used to set XEP options; their use is described in
XEP documentation (XEP 3.x User Guide). You must set at least a
property to specify the path to an existing XEP 3.x installation: 
ROOT=<xep_path>.

The last type of configuration entries are JVM options, used to control
behaviour of the underlying Java VM. An important example are options that
set Java heap size limits: -Xms and -Xmx. By default, the amount of memory 
available to Java VM is limited to 64 MB regardless of the RAM size
of the host machine. We strongly recommend setting these to higher
values. For a machine with <N> megabytes of RAM, reasonable defaults are
<N - 64> for the upper heap size limit (-Xmx) and <N/2> (or less) for the 
lower limit (-Xms). For instance, the following yields effective memory usage 
on a computer with 512 MB of RAM:

    -Xms128M -Xmx400M 

XEP COM stores its configuration information in the following registry
branch:

    HKEY_LOCAL_MACHINE\SOFTWARE\RenderX\XEP

There are three sub-keys (CLASSPATH, PROPERTIES, JVMOPTIONS) corresponding
to each option type. A simple GUI utility, UTILS\XEPCOMCFG\XEPCOMCFG.EXE, 
provides a means to set up registry entries for the wrapper. Its interface 
is self-explanatory.

You could also use simple command-line utility (UTILS\XEPCOMCFGCL\XEPCOMCFGCL.EXE)
for batch-mode configuration. Here is an example of XEPCOMCFGCL call sequence 
to configure XEP COM wrapper on a machine having 256 MB of RAM, with XEP 3.13 
installed at C:\XEP, and COM wrapper files unpacked to C:\XEPCOM:

xepconfigcl set_classpath C:/XEPCOM/xepjni.jar;C:/XEP/lib/xep313_client.jar;C:/XEP/lib/cryptix32-pgp.jar;C:/XEP/lib/cryptix32.jar;C:/XEP/lib/xt.jar;C:/XEP/lib/saxon.jar

xepconfigcl set_properties ROOT=C:\XEP

xepconfigcl set_jvmoptions -Xms128M -Xmx192M


7. Using XEP COM wrapper

XEP COM wrapper fully conforms to COM specification and can be used in
any COM environment where Sun JVM (JVM.DLL) is available.

The principal COM interface implemented by XEP COM wrapper is IXEPFormatter;
it extends IDispatch. In addition to standard IDispatch methods,
the interface exposes the following methods:

HRESULT setOutputFormat([in] VARIANT vFormat);
HRESULT setStylesheetFile([in] VARIANT vXSLFilename);
HRESULT setStylesheet([in] VARIANT vXSL);
HRESULT renderFile([in] VARIANT vFOFilename, [out, retval] VARIANT* vDataout);
HRESULT render([in] VARIANT vFO, [out, retval] VARIANT* vDataout);
HRESULT transformFile([in] VARIANT vXMLFilename, [out, retval] VARIANT* vDataout);
HRESULT transform([in] VARIANT vXML, [out, retval] VARIANT* vDataout);
HRESULT getDiagnostic([out, retval] VARIANT* vDiagnostic);

All these methods use two types of parameters: BSTR packed in a VARIANT,
and SAFEARRAY of bytes packed in VARIANT. The methods fall into 5 groups:

1) HRESULT setOutputFormat([in] VARIANT vFormat);

     This method should be called before any other methods.
     It sets output format. The argument is a symbolic name of the output
     format; valid names are "PDF", "PostScript", and "XML" (see XEP
     User Guide for details). Parameter type is BSTR string packed in VARIANT.

2) HRESULT setStylesheetFile([in] VARIANT vXSLFilename);
   HRESULT setStylesheet([in] VARIANT vXSL);

     These methods select an XSLT stylesheet to be used in transformation.
     set StylesheetFile or setStylesheet method  must be called before
     transform() method. The first method takes a filename for the stylesheet
     as BSTR VARIANT. The second one takes XSLT stylesheet as an array of
     bytes (SAFEARRAY VARIANT)

3) HRESULT renderFile([in] VARIANT vFOFilename, [out, retval] VARIANT* vDataout);
   HRESULT render([in] VARIANT vFO, [out, retval] VARIANT* vDataout);

     These methods take an XSL FO document at input, and return the result
     as a byte array (SAFEARRAY VARIANT). Output format is defined by
     a previous call to 'setOutputFormat' method. The first method takes
     XSL FO file name as a BSTR VARIANT, while the second one reads
     XSL FO data from an array of bytes (SAFEARRAY VARIANT)

4) HRESULT transformFile([in] VARIANT vXMLFilename, [out, retval] VARIANT* vDataout);
   HRESULT transform([in] VARIANT vXML, [out, retval] VARIANT* vDataout);

     These methods transform its argument XML data using XSLT stylesheet
     previously set by 'setStylesheet/setStylesheetFile' methods,
     render the resulting XSL FO instance to the specified output
     format, and return the result as a byte array (SAFEARRAY VARIANT).
     Output format must be previously set by 'setOutputFormat' method.
     First method takes The first method takes XML filename as a BSTR
     VARIANT, while the second one reads XML data from an array of bytes
     (SAFEARRAY VARIANT)

5) HRESULT getDiagnostic([out, retval] VARIANT* vDiagnostic);	

     This method returns diagnostic messages produced by XEP formatter.
     These messages could stem from exceptions thrown during last method 
     call (in most cases, this is a result of formatter's misconfiguration
     or misbehaviour), or warnings/errors produced during formatting
     as a reaction to incorrect user input.

The distribution includes samples of XEP COM wrapper usage in three
programming languages: C++, Visual Basic, and PHP. All samples are
stored in the EXAMPLES\ subdirectory of the installation target directory.

-------------------
(*) To unsubscribe, send a message with words 'unsubscribe xep-support'
in the body of the message to majordomo at renderx.com from the address
you are subscribed from.
(*) By using the Service, you expressly agree to these Terms of Service http://www.renderx.com/tos.html