wiki:CalencoCompilationSpecs
Last modified 13 months ago

Specifications for Calenco Compilation Unit

General Functionalities

This part of Calenco is in charge of converting XML documents into other formats: PDF, (X)HTML, etc.

The transformations to be performed are represented by the Publication object containing the parameters to process the compilation.

Publications can be processed in two ways:

  • "immediate": the compilation process is launched immediately when the publication object is recieved. This one shall only be used for small documents.
  • "queued": the compilation object is stored in a queue, and compilations are processed as they arrive.

The default mode for compilation will be "queued". The "immediate" mode is enabled by a configuration parameter in the Calenco configuration file.

Publication Object

See the REST API specifications for details:
CalencoRestApi#GetPublicationDetails
CalencoRestApi#CreatePublication

Add-Ons

An add-on is a Calenco extension written for a specific XML type: DocBook, Globekid, DITA, etc. It is meant to perform the following specific operations on an XML file:

  • validation
  • dependencies extraction
  • transformation to another format(s): PDF, HTML, etc. These processes are known as toolchains. The add-on provides a list of the toolchains (and their parameters) it can execute.

An add-on extends the abstract class com.calenco.addon.AddOn

An add-on is presented as a JAR archive which is put in a specific place (to be defined) well-known to Calenco and provides the method getName() which returns the name identifying the add-on. XML files stored on the repository have a cco_xmltype property with the value of the add-on name.

Add-on Manager

The add-on manager searches for add-ons at Calenco start-up and builds a map of XML types (namespace or DOCTYPE definition) and add-ons associated with those types. This way it knows which add-on to use to perform processing on an XML file of a specific type.

Publication Worker

This object consumes the queue asking the PublicationManager for publications to publish. The PublicationWorker object asks the AddOnManager for an AddOn instance to perform the needed compilation, providing it with the XML file type to publish.

Publication Manager

The Publication Manager has the following functions:

  • manage (add/remove) the publication queue
  • provide information about the status of a given publication (running, not-in-queue).

Note that the PublicationManager may start multiple PublicationWorker threads to consume the publication queue.

Queue Management Policy

When a publication is submitted to the publications manager:

  • If no publication having the same ID is present in the queue, the publication is added at the end of the queue(it will be the last to be processed).
  • If a publication with the same ID is present in the queue :
    • if the old publication is currently processed the new one is placed at the end of the queue. If the same situation takes place more than once, the new publication replaces the last occurence(same ID) of the publication in the queue.
    • if the old publication is not currently processed the new one replaces it.

This way there cannot be more than 2 publications with the same ID in the queue.

To Be Defined

  • Where are stored the results of compilation? On the JCR? Directly on the file system? IIRC, this is a parameter of the publication itself.
  • Where do we place add-ons? In the installation directory of Calenco? Yes, in a well-known-place, for example: add-ons/ or addons/ We'll have to investigate how to dynamically load them, adding to the classpath, at runtime. Check the ClassLoader Java class.