Foxit Developer

Foxit PDF SDK Java Object Management: Ensuring Timely Resource Release ​

When using the Foxit PDF SDK Java API to process PDF documents, understanding and correctly managing the lifecycle of SDK objects is essential. Because Java's garbage collection differs from the underlying C++ resource management, improper object management can lead to issues such as memory leaks, ultimately affecting application performance and stability. This article explains how Foxit PDF SDK Java objects are managed and provides best-practice recommendations to help developers release resources promptly.

Background: Java Wrapper Classes and GSDK C++ Objects ​

The Foxit PDF SDK Java API is implemented through wrapper classes generated by tools such as SWIG. These wrappers act as a bridge between Java code and the underlying GSDK C++ objects. Each Java wrapper instance is typically associated with one or more GSDK C++ objects. To release these underlying C++ resources, wrapper classes usually provide a delete() method.

However, Java garbage collection is not immediate. When a Java object goes out of scope, the garbage collector reclaims it at some unpredictable point in the future. This means that even after a Java object is no longer referenced, its associated GSDK C++ object may remain in memory until the garbage collector runs and eventually calls the wrapper's finalize() method (if implemented).

finalize() is a protected method defined in java.lang.Object that allows an object to perform cleanup before the garbage collector reclaims it. In Foxit PDF SDK Java wrapper classes, finalize() is typically implemented to call delete(), thereby releasing the memory of the associated GSDK C++ object.

java
protected void finalize() {
    delete();
}

Nevertheless, relying on the garbage collector to invoke finalize() to release GSDK C++ objects is strongly discouraged. Reasons include:

  • Unpredictable timing: When the garbage collector runs and when it reclaims a specific object cannot be predicted. It may be triggered when memory is low, long after the object goes out of scope, or in some cases may never be called.
  • Prolonged resource usage: Because of delayed garbage collection, GSDK C++ objects may continue to occupy memory long after they are no longer needed—especially when object lifetimes are short or resources are scarce—potentially exhausting memory.
  • Increased complexity: Depending on an unpredictable garbage collection mechanism for resource release makes program behavior harder to predict and debug.

Best Practice: Manually Release GSDK C++ Objects ​

To ensure timely release of GSDK C++ objects and avoid potential memory leaks, developers should manually call the delete() method provided by wrapper classes. This keeps resource release under developer control and enables better memory management.

Key points to follow during development:

Follow the Correct Release Order When Calling delete() ​

When multiple related GSDK C++ objects are involved, they must be released in the correct order to avoid dependency issues and potential crashes. The general rules are:

  • Release child objects before parent objects: If one object is created inside another or owned by it, release the child first, then the parent. For example, a Link object is typically associated with an Annot object—release Link first, then Annot.
  • Release page-related objects before document objects: PDFPage objects are created within a PDFDoc object. Release PDFPage before PDFDoc. If PDFDoc is released while PDFPage is still held, PDFDoc may not be released promptly because it still depends on the unreleased PDFPage.

Example Comparison ​

java
PDFDoc doc = new PDFDoc(absolutePath);
doc.load(null);
PDFPage page = doc.getPage(0);
Annot annot = page.addAnnot(Annot.e_Link, rectF);
Link link = new Link(annot);
annot.delete(); // Parent annot released after child link
link.delete();
doc.delete();
page.delete();
java
PDFDoc doc = new PDFDoc(absolutePath);
doc.load(null);
PDFPage page = doc.getPage(0);
Annot annot = page.addAnnot(Annot.e_Link, rectF);
Link link = new Link(annot);
link.delete(); // Release child link first
annot.delete(); // Then release parent annot
page.delete();
doc.delete();

In summary, proactive object management is essential in Foxit PDF SDK Java development. Developers should follow these principles:

  • Prefer manually calling delete() to release GSDK C++ objects that are no longer needed.
  • Follow the correct release order: release child objects and page-related objects before parent objects and document objects.
  • Avoid using chained methods on objects that require explicit release.
  • After removing a Field from a Form, always call Field.delete().
  • For special objects such as PDFObject, PDFStream, PDFArray, and PDFDictionary, if they have not been set into a PDFDoc, call release() to release them.

By following these best practices, you can effectively manage Foxit PDF SDK Java objects, ensure application stability and efficiency, avoid potential memory leaks, and build more robust PDF processing solutions.