Overview

Rendering operations require a certain environment or context. We refer to this environment as a Comet Project.

In the Java Rendering Library context, we associate Comet Projects with a unique name. In the SDK, this association is represented via a NamedConnection object.

Comet Project

A Comet Project configuration can be read from (ODBC) database connections, a SOAP / HTTP service or from a file system folder.

A connection to a Comet Project represents the status of the renderer application.
This includes

• actions to perform, when opening, saving or closing a document
• templates and page templates for generating pages
• placeholders to define access to business data
• layout rules to fine-control page layout
• custom scripts to generate pages, indexes, hyperlinks etc.
• access to other resources (assets, fonts)

By reconnecting to a Comet Project, we can restore all status required to process requests for a certain document.

Named Connections

Connecting to a Comet Project requires appropriate access data and credentials.

We associate these connection data with a unique name and register at the Renderer factory:

((Renderer) renderer).registerConnection (namedConnection, ...);

Connections must be registered at the latest before they are referred (e.g. by calling ((Renderer) renderer).openDocument).
If a connection is registered with a name already register earlier, the latter entry is overwritten.

Define and register SOAP Connections

To register a SOAP project connection, use

((Renderer) renderer).registerConnection(
    NamedConnection.createSOAPConnection(
      "my-soap-project",                                  // unique name
      "http://localhost:40082/CometBridge/Comet3Service", // service endpoint
      "user",                                             // user login
      "passwd",                                           // password
      "aio",                                              // project 
      ""                                                  // language
      ));

Define and register XML Offline Connections

To register a XML Offline project connection, use

((Renderer) renderer).registerConnection(
    NamedConnection.createXMLConnection(
      "my-xml-project",                                   // unique name
      "/path/to/project"                                  // base path of XML folder
));

Define and register ODBC Connections

To register an ODBC project connection, use

((Renderer) renderer).registerConnection(
    NamedConnection.createODBCConnection(
      "my-odbc-project",                                  // unique name
      "service",                                          // user or system dsn
      "login",                                            // user login
      "passwd",                                           // password
      "project"                                           // project / domain
));

Adding, removing and changing Connections

NamedConnections can be added and deleted any time during application lifetime.

• as soon as a NamedConnection is defined and registered, it can be used for processing documents
• if a NamedConnection is deleted, renderer instances can still remain connected to this connection. Subsequent operations may fail, if the connection must be reset and re-established.
• if a NamedConnection is changed, renderers currently refering this connection are not notified. This can lead to inconsistent state of the application: some renderer instances may refer to the updated connection data, while others still refer to the previous version. Use code like shown below to fix this problem.

Example: force (re)connecting all Renderer Instances

Renderer renderer = new Renderer();
renderer.connectAll("myChangedConnection");

This procedure has some drawbacks:

• all renderer instances will establish a connection to the named datasource, no matter, if they were connected to that source before or not.
  This may cause unnecessary load on client and datasource side.
• renderer instances connected to other data sources may require reconnection, when continuing processing a certain document. This also causes unnecessary load and processing time on client and datasource side.

Improved Example: force reconnecting all Renderer Instances

We can improve this behaviour by adding temporarily adding an observer and skip event provessing, if a renderer instance isn't connected to the changed datasource:

String changedConnectionName = "myChangedConnection";

Renderer renderer = new Renderer();

RendererObserver connectionObserver = (event, control, data) -> {
  String connectionName = control.getConnectionName();
  if (changedConnectionName.equals(connectionName)) {
    return EventChain.CONTINUE;
  }
  return EventChain.TERMINATE;
};

renderer.addObserver(connectionObserver, Event.CONNECT_BEFORE);
renderer.connectAll(changedConnectionName);
renderer.removeObserver(connectionObserver);

See the Observer section for details regarding intercepting operations.