Overview

Document Resources

When opening a document, no matter, if the document is based on a W2ML String, InputStream or file path, the Renderer creates a temporary copy of this document, usually in one of the systems tmp directory. This temporary copy and all resources related to the document (e.g. meta data folder, generated PDFs etc.) is deleted when the document is closed. To persist the document or any of it's artifacts, it must be copied before the document is closed.

It is not allowed (though technically possible) to directly access any of the files in the temporary folder. In future, the background behavior may change, maybe we just keep the document in memory instead of using temporary files or similar. API and client applications depending on file system paths may become unusable then.

Lifecycle of Documents

As soon as a document is opened, we can treat it as a managed object. Just like Entity objects attached to an EntityManager, the OpenedDocument is attached to a native resource, which allows further operations with this document.

As soon as the document is closed, it is detached from the native resource. The behavior of further operations with this document or any objects associated with the document is undefined. Some may work and some not, depending on the status of the document, what has been applied before and therefore is still resident in memory.

You should generally avoid calling methods or accessing resources of documents, that have already been closed.

Document Connections

Each document is associated with a certain environment, connection, data source, or, to put it simply, comet project. These environments (connections, ...) must have been registered at the Renderer with a unique name (this is about the name we enter in the login dialog e.g. in priint suite).

The renderer library ensures, that all document operations are run in the correct environment. This means, if many documents using different connections are opened at the same time, that the connections must be "swapped" frequently between operations.

If a document should be opened without any comet project context, you can use the predefined connection named Constants.ZEROCONF.

Simple opening

Documents are "opened" by calling one of the openDocument factory methods of the com.priint.comet.renderer.Renderer instance.

import com.priint.comet.renderer.Renderer;
import com.priint.comet.renderer.OpenedDocument; 
import com.priint.comet.renderer.exception.RendererException;
import com.priint.comet.renderer.io.providers.TmpCopyFromString;

// ...
try {
    String w2mlString = ""; // read w2ml from file, input stream... 
    OpenedDocument document = Renderer.openDocument("DSN", new TmpCopyFromString(w2mlString, W2MLDocumentType.class));
}
catch (RendererException e) {
    // e.g. 
    //  - InitializationException: if the Renderer has not been initialized properly 
    //  - NamedConnectionUndefinedException: if DSN is unknown 
}
Technically, not much happens when opening a document: a OpenedDocument object is initialized with the W2ML data provided as argument or read from InputStream / file path and attached to a native renderer instance.

Note: The W2ML data of the document is not evaluated and not parsed by simply opening the document, but subsequent document operations will fail, if the data is illegal.
This behavior is by design: all processing is done if and only if required and earliest at the time, it is required. You can explicitly let the renderer parse the document data by calling OpenedDocument.validate, see example "Open and validate" below

Try-with-Resource

Since OpenedDocument extends the AutoClosable interface, you are encouraged to use the try-with-resource pattern: 

String w2mlString = "";
// the try-with-resource pattern guarantees, that the document is closed
// at the end of the try block, no matter, if exceptions occurred or not:
try (OpenedDocument document = Renderer.openDocument("DSN", new TmpCopyFromString(w2mlString, W2MLDocumentType.class)) {
    // document processing...
}
catch (RendererException e) {
    // Exceptions thrown during opening, rendering...
}
catch (Exception e) {
    // Exception thrown during auto-close
}

Open with Options

You can also supply Options to the openDocument method call. Options can be

A common option when opening a document would be the DOCUMENTID as shown below. This will ensure, that the correct ID is available in scripts and context, particularly, if we use a master document or template as W2ML source for the document.

import com.priint.comet.model.KeyValue;
import com.priint.comet.renderer.Option;
import com.priint.comet.renderer.Options;
import com.priint.comet.renderer.Variable;

String w2mlString = "";
OpenedDocument document = Renderer.openDocument(
                               "DSN",
                               new TmpCopyFromString(w2mlString), 
                               Options.create()
                                   .add(Option.XML_ATTRIBUTES, new KeyValue("_language", "deu"))
                                   .add(Option.XML_ATTRIBUTES, new KeyValue("_country", "DE"))
                                   .add(Option.DOCUMENTID, "ABC1415")
                                   .add(Option.GLOBAL_VARIABLES, Variable.intVariable("counter", 17))
);

Note: Options supplied when opening a document are defined for all subsequent operations on this document, unless overridden for certain method calls. E.g. the global cscript variable "counter" is available in all cscripts run by calling document.execScript but will always be initialized with 17.

Open and validate

To validate the W2ML data attached to a document, you can call the OpenedDocument.validate method. Usually, this is not necessary, as the W2ML data is validated as soon as any (real) renderer operation is applied to the document.

Note: The validate method checks, if the documents W2ML data is syntactically and semantically correct - not more. We do not check, if all required fonts, images and whatsoever are available or check for oversets, overlaps, page constraints etc.

String w2mlString = "";
OpenedDocument document = Renderer.openDocument("DSN", new TmpCopyFromString(w2mlString));
try {
  document.validate();
}
catch (RendererException e) {
  // handle illegal W2ML
  throw e;
}
//
// further document processing...
//
document.close();