Use the HTML Export API

The Java version of the API provides an interface to the core functionality of the C API. It contains one primary class (HtmlExport) that wraps the conversion functionality of the C API. The HtmlExport class provides access to a family of methods called convert.

The API is implemented in the com.verity.api.export package, which is contained in the KeyView.jar file. The jar file is in the install\javaapi directory, where install is the path name of the Export installation directory.

For a full description of the Java API classes, see the Javadoc in the directory install\javaapi\javadoc. Sample programs are provided to demonstrate the Java API. See Sample Programs.

You can access the Java API directly or by setting conversion options in template files, which are then passed to the API. For more information on template files, see Set Conversion Options by Using the Template Files.

For information on the C API, see the HTML Export C Programming Guide.

Input/Output Operations

In the Export Java API, input and output can be either a physical file accessed through a file path, or a Java stream. Depending on the convert method signature that you use, you can create the following conversion processes:

You can set the input source by calling the setInputSource method, or when using the convert method. The latter takes the input source as one of its parameters. When you select a convert method, ensure that you use the correct signature for the desired input and output type.

NOTE: Note: When the input source is from a Java stream, Export creates an internal buffer from the stream. If the input is a large file, HPE recommends that you use a file as the input source.

Convert Files

To convert files using the methods in the HtmlExport class

  1. Instantiate an HtmlExport object.

    m_objExport = new HtmlExport();
  2. If you are using a template file to set the conversion options, call the setIniFileName method. It is recommended you set the full path to the template file.


    Conversion options are parameters that determine the content, structure, and appearance of the HTML output. See Set Conversion Options.

  3. If you are using the API to set the conversion options, create instances of the following classes:

    Conversion options are parameters that determine the content, structure, and appearance of the HTML output. Set Conversion Options.

    Set the classes to the current HtmlExport object using the following methods available in the HtmlExport class:

    and the following method available in the HtmlTOCOptionInfo class:

  4. Set the location of the Export libraries by calling the setExportDirectory method. These are normally in the directory install\OS\bin, where install is the path name of the Export installation directory and OS is the name of the operating system.

  5. Open the source file by calling the extOpenDocument method. This call defines the parameters necessary to open a file for extraction.

    ExtOpenDocConfig odconfig = null;
    long extContextID = 0;
    odconfig = new ExtOpenDocConfig();
    extContextID = m_objExport.extOpenDocument(inFile, odconfig); 
  6. Determine whether the main file is a container file (that is, whether it contains subfiles) by calling the extGetMainFileInfo() method.

    ExtMainFileInfo maininfo = null;
    maininfo = m_objExport.extGetMainFileInfo(extContextID);
  7. If the call to extGetMainFileInfo() determined that the source file is a container file, proceed to Step 8; otherwise, proceed to Step 11.

  8. Determine whether the subfile is itself a container (that is, whether it contains subfiles) by calling the extGetSubFileInfo method.

    ExtSubFileInfo subinfo = null;
    if(nSubFiles != 0)
       for(int index = 0; index < nSubFiles; index++)
       subinfo = m_objExport.extGetSubFileInfo(extContextID, index);
  9. Extract the subfile by calling the extExtractSubFile method.

    ExtSubFileExtractConfig extconfig = null;
    extconfig = new ExtSubFileExtractConfig();
    extconfig.setOverWrite(true); extconfig.setExcludeMailHeader(m_excludeMailHeader);
    extinfo = m_objExport.extExtractSubFile(extContextID, index, extconfig);
  10. If the call to extGetSubFileInfo determined that the subfile is a container file, repeat Step 5 through Step 9 until all subfiles are extracted; otherwise, proceed to Step 11.

  11. Optionally, set the input source as either a file or input stream by calling the setInputSource method.

    if(m_inputMethod == Export.IO_METHOD_FILE)
       //input as file
       m_objExport.setInputSource(m_extractDir + filename);
       //input as stream
       File inf = new File(m_extractDir + filename);
       FileInputStream fis = new FileInputStream(inf);
  12. Set up an out-of-process session by calling the startOOPSession method. This initializes the out-of-process session, creates a Servant process, establishes a communication channel between the application thread and the Servant, and sends the data to the Servant.

  13. Convert the input and generate the output files by calling the convertTo method. You cannot use the convert methods that set the input source because the input source must be set before the out-of-process session is initialized. The convertTo method can only be called once in a single out-of-process session.

    if(m_outputMethod == Export.IO_METHOD_FILE)
       //convert to a file
       m_objExport.convertTo(m_extractDir + filename + m_extension);
       //convert to a stream
       File outf = new File(m_extractDir + filename + m_extension);
       FileOutputStream fos = new FileOutputStream(outf);
  14. If you are converting additional files, terminate the out-of-process session by calling the endOOPSession method and setting the Boolean to TRUE. The Servant ends the current conversion session and releases the source data and session resources.

    If you are not converting additional files, terminate the out-of-process session and the Servant process by calling endOOPSession and setting the Boolean to FALSE.

    if(i == (nSubFiles - 1))
       m_keepServantAlive = false;
       m_keepServantAlive = true;
  15. Close the file by calling the extCloseDocument() method.

  16. Repeat Step 2 through Step 15 for additional source files.

  17. Terminate the session and free allocated system resources by calling the shutdownExport() method.


Multithreaded Conversions

To ensure that multithreaded conversions are thread-safe, you must create a unique Export context for every thread by instantiating an HtmlExport object. In addition, threads must not share context objects, and you must use the same context object for all API calls in the same thread. Creating a context object for every thread does not affect performance because the context object uses minimal resources.

For example, your Java code should have the following logic in a thread:

m_objExport = new HtmlExport(); 
m_objExport.extOpenDocument(inFile, odconfig);
m_objExport.extGetMainFileInfo(extContextID)  /* container file */
m_objExport.extGetSubFileInfo(extContextID, index);
m_objExport.extExtractSubFile(extContextID, index, extconfig);
m_objExport.endOOPSession(bKeepServantAlive TRUE);
m_objExport.extOpenDocument(inFile, odconfig);
m_objExport.extGetMainFileInfo(extContextID);  /* not a container file */
m_objExport.endOOPSession(bKeepServantAlive TRUE);

Use Callbacks

Some Export methods enable you to specify a callback, which is called to control the conversion while it is in progress. For example, you can specify a callback to report progress during the conversion.

To use callbacks

  1. If you are using the UserCBCallback interface, include the $USERCB token in a member of KVHTMLTemplateEx. For example, placing “$USERCB=my_callback ” in pszFirstH1Start results in a callback at the point when pszFirstH1Start is processed. The user callback function is identified by the text assigned to $USERCB, which in this example is my_callback.

    NOTE: Note: The callback identifier must be delimited by a trailing white space. For example, "my_callback "

    The callback.ini template file provides an example of how to use callback tokens. The file is in the install\javaapi\ini directory. See Export Tokens for more information on tokens.

  2. Implement the callback interfaces. The callback interfaces are:

    Sample implementations of the callback interfaces are in the install\javaapi\sample\com\verity\api\htmlexport directory, where install is the path name of the Export installation directory.

  3. Declare the objects of the callback procedures you are going to use, and pass them to your instance of HtmlExport.


ContinueCallback cci = new ContinueCallbackImpl();
GetAnchorCallback gaci = new GetAnchorCallbackImpl();
GetAuxOutputCallback gaoci = new GetAuxOutputCallbackImpl();
UserCBCallback ucbi = new UserCBCallbackImpl();
CallingContext cContext = new CallingContextImpl();

Before Running Your Application

Before running your application, set the library path using one of the following methods: