Start Using the Filter API

The Java Filter API is implemented in the package keyview.filter contained in the file filter.jar. In your program code, import the keyview.filter package.

import keyview.filter.*;

Create a Session

To use the Filter API, first create a session:

try (FilterSession session = new FilterSession(binDir, license, false)) {
    // Configure the session and open a document
}

The first parameter to the FilterSession constructor is a String that holds the location of the Filter SDK binaries, and the second is a String that holds your license key. The final parameter is a boolean that specifies whether to run File Content Extraction in-process. OpenText recommends setting this to false - for more information see the security considerations below.

The FilterSession class implements the AutoCloseable interface, so you can enclose your use of the session in a try block to ensure that resources are automatically freed when no longer required.

When you create a session, you might need to consider various impacts on performance and security.

Performance considerations

• Session Lifetime. You can process multiple files in a single session, which can improve performance by reducing costs associated with start-up and shutdown.
• Multi-threading. To maximize throughput when processing multiple files, you can call File Content Extraction from multiple threads. Each thread that uses File Content Extraction must create its own session. You must not share filter sessions or documents between threads. All File Content Extraction functions are thread-safe when called in this manner.

Security considerations

• Privilege Reduction. By default, File Content Extraction performs most of its operations out-of-process, creating a separate process to parse file data. This behavior protects your main application from the effects of rare problems like memory leaks or crashes. For additional protection, run File Content Extraction with reduced privileges. See Run Filter with Minimal Privileges.
• Temp Directory. While processing, File Content Extraction might place sensitive data in the temporary directory. You might want to consider protecting the temporary directory. See Protect the Temporary Directory.

Open a Document

A Document object provides access to the data within a file, including the file format, text, metadata, and any subfiles. Obtain a Document object from a file or stream by calling the open() method on your FilterSession. For example:

String inputFilePath = "InputFile.docx";
try (Document myDoc = session.open(inputFilePath)) {
    // Use the document object to detect the file format, filter text,
    // access metadata and extract subfiles
}

Determine the Format of a Document

File Content Extraction reliably determines the format of almost any document. It does this by analyzing the internal structure and content of the file, ignoring the file extension. Detection prioritizes both accuracy and speed, only processing as much of the file as necessary to rule out false positives.

You can find the format of a document by using the info() method on a Document object. For example:

try (Document myDoc = session.open(inputFilePath)) {
    System.out.println("File format: " + myDoc.info().docClassName());
    System.out.println("File format: " + myDoc.info().docFormat());
    System.out.println("Description: " + myDoc.info().description());
    System.out.println("File version: " + myDoc.info().version());
}

Filter a Document

To filter a document and write the text to a file or stream, call the filter() method on a Document object. For example:

try (Document myDoc = session.open(inputFilePath)) {
    myDoc.filter(inputFilePath + ".filtered.txt");
}
catch (KeyViewException e) {
    System.out.println(e.getMessage());
}

Access Metadata

You can access document metadata through the metadata() method on a Document object. For example:

for (MetadataElement element : myDoc.metadata()) {
    // Process the metadata element
}

Extract Subfiles

You can iterate over subfile information using the subfiles() method on a Document object. Each Subfile returned by the iterator contains information about the subfile, and a method that you can use to extract it:

for (Subfile subfile : myDoc.subfiles()) {
    System.out.println("Subfile " + subfile.index() + ", size: " + subfile.size());
    
    if (subfile.type() != keyview.filter.SubfileType.Folder) {
        subfile.extractToFile(generateOutputPath(subfile));
    }
}