What is a Document Event?

A document event occurs any time you open or create a new document using the SDK. In other words, any time you load a document into memory, it is counted as a document event.

Any operations that you make on a document after it's been loaded are not document events. You can perform as many operations on an opened document as you want without incurring additional document events.

The following sections include just a few languages as examples, but the rules apply to all languages that our SDKs support.

Opening files

In WebViewer, loading a new file into the viewer or into memory in any way counts as a document event. Interacting with that document after its loaded will not count as additional document events.

JavaScript

JavaScriptWebViewer({
  // Counts as a document event
  initialDoc: 'https://myserver.com/myfile.pdf',
}, document.getElementById('viewer')).then(instance => {
  // Counts as a document event
  instance.UI.loadDocument('https://myserver.com/myfile.pdf', { filename: 'myfile.pdf' });
  instance.UI.addEventListener(UI.Events.TAB_MANAGER_READY, async () => {
    // Counts as a document event
    await UI.TabManager.addTab('https://myserver.com/myfile.pdf', { setActive: true });
  });
});

In the server-side SDKs, loading a new file into memory in any way counts as a document event.

JavaScript

// Counts as a document event
const doc = await PDFNet.PDFDoc.createFromFilePath(filename);

C++

// Counts as a document event
PDFDoc doc(filename);

Java

// Counts as a document event
PDFDoc doc = new PDFDoc(filename);

Blank files

Creating a new blank file in WebViewer or the server SDKs counts as a document event.

JavaScript

// Counts as a document event
const doc = await PDFNet.PDFDoc.create();

C++

// Counts as a document event
PDFDoc doc;

Java

// Counts as a document event
PDFDoc doc = new PDFDoc();

Converting files

Some APIs allow you to convert a file and write it to disk. In the event where you want to perform additional operations on the converted file, loading it into memory will count as a document event.

JavaScript

// Counts as one document event
await PDFNet.Convert.fileToWord('./input.pdf', 'output.docx');
// Counts as a second document event
const doc = await PDFNet.PDFDoc.createFromFilePath('output.docx');
// This does not count as a document event
await PDFNet.Optimizer.optimize(doc);

C++

Convert::WordOutputOptions wordOutputOptions;
// Counts as a document event
Convert::ToWord(filename, output_filename, wordOutputOptions);
// Counts as a second document event
PDFDoc doc(output_filename);
// This does not count as a document event
Optimizer::Optimize(doc);

Java

Convert.WordOutputOptions wordOutputOptions = new Convert.WordOutputOptions();
// Counts as a document event
Convert.toWord(filename, output_filename, wordOutputOptions);
// Counts as a second document event
PDFDoc doc = new PDFDoc(output_filename);
// This does not count as a document event
Optimizer.optimize(doc);

Operations with multiple files

Operations that input multiple files may count as more than one document event. For example, merging two documents into one will count as two document events.

JavaScript

// This counts as two document events, we are loading two documents into memory.
const firstDoc = await instance.Core.createDocument('url/to/first.pdf');
const secondDoc = await instance.Core.createDocument('url/to/second.pdf');
// This does not count as a document event, we are merging the two already open documents.
await firstDoc.insertPages(secondDoc);
// This is NOT a document event, the document is already loaded in memory.
await instance.UI.loadDocument(firstDoc);

C++

// This counts as two document events, we are loading two documents into memory.
PDFDoc new_doc("file1.pdf");
PDFDoc doc("file2.pdf");
// This does not count as a document event, we are merging the two already open documents.
new_doc.InsertPages(0, doc, 1, doc.GetPageCount(), PDFDoc::e_none);

Java

// This counts as two document events, we are loading two documents into memory.
PDFDoc new_doc = new PDFDoc("file1.pdf");
PDFDoc doc = new PDFDoc("file2.pdf");
// This does not count as a document event, we are merging the two already open documents.
new_doc.insertPages(0, doc, 1, doc.getPageCount(), PDFDoc.InsertBookmarkMode.NONE, null);

In operations like merging, it is recommended that you merge one document into another (2 document events), rather than creating a new blank file and then merging two documents into it (which would be 3 document events).

Saving files

Saving files does not count as a document event. After the document has been loaded into memory, you can save that document as many times as you want without incurring additional document events.

For example, you could load a file into memory (1 document event), and then convert that file to 5 different formats while only incurring 1 document event.

Additional information

If you are still unsure about what counts as a document event, or you're not sure how many document events your project will use, please reach out to our support team for more information.