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

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

## Input/Output Operations

The HTML Export Java API supports several input and output methods. The source data can be a file accessed through a file path, a `com.verity.api.SeekableInputStream`, or a standard `java.io.InputStream`. You can send the output to a file, a `java.io.OutputStream`, or return it one chunk at a time in a byte array. The methods in the HTML Export Java API have multiple signatures in order to support these options.

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.

When the input source is a stream, Micro Focus recommends passing a `SeekableInputStream` into KeyView, so that KeyView can read only the parts of the stream it needs to read. If you use a Java `InputStream`, KeyView must store the stream as it is received, writing to a temporary file if the stream is large.

Sometimes, when the source is a Java `InputStream`, you can improve performance by passing in the stream size. If you do not supply the stream size, KeyView reads the entire stream before processing starts. If you can provide the stream size, KeyView might not need to read the whole stream.

## Convert Files

To convert files

1. Instantiate an `HtmlExport` object.

       LicenseInfo license = new LicenseInfo("YOUR_ORGANIZATION", "YOUR_KEY");

       m_objExport = new HtmlExport(license);

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.

       m_objExport.setIniFileName(m_iniFile);

   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:

   - `HtmlOptionInfo`
   - `HtmlTemplateInfo`
   - `HtmlTOCOptionInfo`
   - `StyleMapping`
   - `HtmlHeadingInfo`

   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:

   - `setOptionInfo`
   - `setTemplateInfo`
   - `setTOCOptionInfo`
   - `setStyleMapping`

   and the following method available in the `HtmlTOCOptionInfo` class:

   - `setHtmlHeadingInfo`

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.

       m_objExport.setExportDirectory(m_exportDirectory);

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();
       odconfig.setUserName(m_userName);
       odconfig.setPassword(m_password);
       odconfig.setUserIDFile(m_userIDFile);
       odconfig.setExtractDirectory(m_extractDir);
       odconfig.setCreateRootNode(m_createRootNode);
       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.setCreateDirectory(true);
       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);
        }
        else
        {
           //input as stream
           File inf = new File(m_extractDir + filename);
           FileInputStream fis = new FileInputStream(inf);
           m_objExport.setInputSource(fis);
           fis.close();
        }

    The `setInputSource` method also accepts a `com.verity.api.SeekableInputStream`. Micro Focus recommends this option, because it allows KeyView to seek in the file, only reading the parts it needs to read. If you need to use a Java `InputStream`, and you know the stream length, there is a method overload that allows the size to be passed in. Using this might allow KeyView to avoid caching the whole file. For more information, see Input/Output Operations.

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.

        m_objExport.startOOPSession();

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);
        }
        else
        {
           //convert to a stream
           File outf = new File(m_extractDir + filename + m_extension);
           FileOutputStream fos = new FileOutputStream(outf);
           m_objExport.convertTo(fos);
           fos.close();
        }

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;
        }
        else
        {
           m_keepServantAlive = true;
        }
        m_objExport.endOOPSession(m_keepServantAlive);

15. Close the file by calling the `extCloseDocument()` method.

        m_objExport.extCloseDocument(extContextID);

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.

          m_objExport.shutdownExport();

## 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(license);

    m_objExport.setIniFileName(m_iniFile);

    m_objExport.setExportDirectory(m_exportDir);

    m_objExport.extOpenDocument(inFile, odconfig);

    m_objExport.extGetMainFileInfo(extContextID)  /* container file */

    m_objExport.extGetSubFileInfo(extContextID, index);

    m_objExport.extExtractSubFile(extContextID, index, extconfig);

    m_objExport.startOOPSession();

    m_objExport.convertTo(outFile);

    m_objExport.endOOPSession(bKeepServantAlive TRUE);

    m_objExport.extCloseDocument();

    m_objExport.extOpenDocument(inFile, odconfig);

    m_objExport.extGetMainFileInfo(extContextID);  /* not a container file */

    m_objExport.startOOPSession();

    m_objExport.convertTo(outFile);

    m_objExport.endOOPSession(bKeepServantAlive TRUE);

    m_objExport.extCloseDocument();

    ...

    m_objExport.shutdownExport();

## 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: 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:

   - `CallbackConstants`
   - `CallingContext`
   - `ContinueCallback`
   - `GetAnchorCallback`
   - `GetAuxOutputCallback`
   - `UserCBCallback`

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

#### Example

    ContinueCallback cci = new ContinueCallbackImpl();
    GetAnchorCallback gaci = new GetAnchorCallbackImpl();
    GetAuxOutputCallback gaoci = new GetAuxOutputCallbackImpl();
    UserCBCallback ucbi = new UserCBCallbackImpl();
    CallingContext cContext = new CallingContextImpl();
    objHtmlExport.setCallingContext(cContext);
    objHtmlExport.setContinueCallback(cci);
    objHtmlExport.setGetAnchorCallback(gaci);
    objHtmlExport.setGetAuxOutputCallback(gaoci);
    objHtmlExport.setUserCBCallback(ucbi);

## Before Running Your Application

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

- On Windows, add the location of `htmlexport.dll` to the `PATH` environment variable.

- On Linux and Solaris, add the location of `libhtmlexport.so` to the `LD_LIBRARY_PATH` environment variable.

- On AIX, add the location of `libhtmlexport.a` to the `LIBPATH` environment variable. You can also specify the library path as a system property as follows:

      java -Djava.library.path=HTML_Export_bin_directory ...

_FT_HTML5_bannerTitle.htm