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.
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:
convert an input file to output file
convert an input file to an output stream
convert an input stream to an output stream
convert an input stream to an output file
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 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.
To convert files using the methods in the HtmlExport
class
Instantiate an HtmlExport
object.
m_objExport = new HtmlExport();
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
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
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
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);
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);
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);
If the call to extGetMainFileInfo()
determined that the source file is a container file, proceed to Step 8; otherwise, proceed to Step 11.
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); ... } }
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);
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.
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(); }
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();
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(); }
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);
Close the file by calling the extCloseDocument()
method.
m_objExport.extCloseDocument(extContextID);
Repeat Step 2 through Step 15 for additional source files.
Terminate the session and free allocated system resources by calling the shutdownExport()
method.
m_objExport.shutdownExport();
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.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();
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
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
.
"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.
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.
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(); objHtmlExport.setCallingContext(cContext); objHtmlExport.setContinueCallback(cci); objHtmlExport.setGetAnchorCallback(gaci); objHtmlExport.setGetAuxOutputCallback(gaoci); objHtmlExport.setUserCBCallback(ucbi);
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 Solaris, Linux, and HP-UX IA-64, add the location of libhtmlexport.so
to the LD_LIBRARY_PATH
environment variable.
On HP-UX PA-RISC, add the location of libhtmlexport.sl
to the SHLIB_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
...
|