Components of Arbortext Publishing Engine

The following list describes the components of Arbortext Publishing Engine. Unless otherwise noted, Java programmers can implement their customized versions of these components.

• Arbortext PE Request Manager — The Arbortext Publishing Engine Java servlet that handles all HTTP and SOAP requests and responses for document conversion and manipulation. It implements the standard init, service, and destroy methods of a servlet.

Incoming requests are passed to active Arbortext Publishing Engine Request Handlers according to configured criteria. When a response is returned to the servlet, the Arbortext PE Request Manager conveys the response to the servlet container, which returns the response to the client making the request.

• Arbortext Publishing Engine Request Context — A Java object that implements the E3RequestContext interface. The Arbortext Publishing Engine Request Context provides services and information about resources available to the context and writes to log files.

The Arbortext Publishing Engine Request Context object is created by the Arbortext PE Request Managerinit method. It provides information to each Arbortext Publishing Engine Request Handler, Arbortext Publishing Engine Request Selector, Arbortext PE sub-process pool, Arbortext Publishing Engine Cache Manager, Arbortext Publishing Engine Queue Manager, and Arbortext Publishing Engine Initializer. The Arbortext Publishing Engine Request Context provides information about the Arbortext Publishing Engine environment such as parameter values, and services such as the location of an Arbortext PE sub-process service pool. It can also write to a servlet log and permits custom code to modify the global state of the Arbortext Publishing Engine environment.

• Arbortext Publishing Engine Request Handler — A Java object that implements the E3RequestHandler interface. The Arbortext PE Request Manager passes an incoming request to each defined Arbortext Publishing Engine Request Handler to determine which one is configured to service it.

A custom Arbortext Publishing Engine Request Handler must implement the init, destroy, and service methods. The init method is called during Arbortext PE Request Manager initialization, and it will receive the Arbortext Publishing Engine Request Context object and the parameters from the Arbortext Publishing Engine configuration file (e3config.xml). The service method is called to process a client request, creating a request object and a response object. The Arbortext PE Request Manager goes to each Arbortext Publishing Engine Request Handler, in the order they're defined, looking for a response that signifies whether it can process the query contained in the request. The Arbortext PE Request Manager calls the Arbortext Publishing Engine Request Handler's destroy method during termination.

• Arbortext Publishing Engine Request Function — A Java object that implements the E3RequestFunction interface. The Arbortext Publishing Engine Request Handler is configured to map query parameters from the request to Arbortext Publishing Engine Request Functions. Each built-in Arbortext Publishing Engine function is mapped to a corresponding built-in Arbortext Publishing Engine Request Function. For example, the f=status function is mapped to the com.arbortext.e3.FunctionStatus interface.

The Arbortext Publishing Engine Request Handler distributed with Arbortext Publishing Engine can be customized to add custom function names and mappings without writing a new Arbortext Publishing Engine Request Handler.

• Arbortext Publishing Engine Request Selector — A Java object that implements the E3RequestSelector interface. Each Arbortext Publishing Engine Request Selector object applies test criteria to a request to help determine routing. If the request matches a predefined condition, the request is accepted by its Arbortext PE sub-process service pool for processing.

A Request Selector has an init and a test method. The init method is called during Arbortext PE Request Manager initialization; and it receives the information in the Arbortext Publishing Engine Request Context object and the parameters from the Arbortext Publishing Engine configuration file (e3config.xml). The test method is called when the Arbortext PE Request Manager needs to evaluate a request against a set of tests associated with an Arbortext PE sub-process pool. For example, a request selector could test a request for an HTTP header content-type: text/xml and return TRUE or FALSE.

Arbortext Publishing Engine Request Selectors can be logically combined using AND or OR in the Arbortext Publishing Engine Request Evaluator, otherwise known as the TestSet defined for each Arbortext PE sub-process pool.

• Arbortext Publishing Engine Request Evaluator — A Java object that implements the E3RequestEvaluator interface. The Arbortext Publishing Engine Request Evaluator can be defined in the TestSet section for each SubprocessPool, QueueManager, Queue, and Notifier defined in the Arbortext Publishing Enginee3config.xml file.

This wrapper-type TestSet object can combine a set of defined Arbortext Publishing Engine Request Selector tests to create test criteria. Two or more tests can be logically combined using AND and OR logic to form more complex criteria. For example, a TestSet might have a test to detect a particular content-type header and another test to detect a particular query parameter that also has a specific value. If an HTTP request meets this criteria, the Arbortext Publishing Engine Request Evaluator returns a boolean value of TRUE and the request would be accepted.

This object's init method is called after all other objects are initialized. An initializer can execute startup tasks, such as retrieving and caching publishing configuration reports or transforming and caching stylesheets.

• Arbortext Publishing Engine Request Object — A Java object that implements the E3ApplicationRequest interface and contains all information being submitted in an HTTP or SOAP request to Arbortext Publishing Engine.

• Arbortext Publishing Engine Response Object — A Java object that implements the E3ApplicationResponse interface and contains the response to the HTTP or SOAP client making a request.

• Arbortext PE sub-process — An individual Arbortext Publishing Engine process, similar to Arbortext Editor, that performs document formatting, conversion, or other document manipulation for the Arbortext PE Request Manager as requested by an HTTP or SOAP client.

• Arbortext PE sub-process Pool — A Java object that implements the com.arbortext.E3SubprocessPool interface and controls a group of Arbortext PE sub-processes that are identical and interchangeable. The Arbortext PE Request Manager evaluates an HTTP or SOAP request against each Arbortext PE sub-process pool in the order they're defined in the Arbortext Publishing Enginee3config.xml configuration file.

Each Arbortext PE sub-process pool is uniquely identified and has its own parameters, such as minimum and maximum number of processes, time-out values, and so on. If you have more than one, each Arbortext PE sub-process pool must have an Arbortext Publishing Engine Request Evaluator TestSet defined in e3config.xml to specify the criteria for assigning HTTP requests to it.

One Arbortext PE sub-process pool must always be configured as the default pool; the default pool allocates an Arbortext PE sub-process to service any HTTP request if no other pool is configured or available. Because a request is assigned to the first Arbortext PE sub-process pool with matching criteria, the order in which pools are defined is important. Because the default pool is designed to service any HTTP request, put the default pool last to be sure that all other enabled pools are evaluated.

The Arbortext PE sub-process Pool can't be customized.

An Arbortext PE sub-process Context object contains any parameters specified in the SubprocessContext element for a SubprocessPool, along with the Arbortext PE sub-process pool name and the Arbortext PE sub-process number (taken from the range of minimum to maximum number of Arbortext PE sub-processes).

Arbortext PE sub-process Context serves two purposes:

◦ The Arbortext PE sub-process Context object is passed to the individual Arbortext PE sub-process taking the request, making it available to Arbortext Publishing Engine custom applications (ACL, Java, JavasScript, and VBScript).

An Arbortext Publishing Engine Queue Manager determines whether an HTTP request should be queued. The Arbortext PE Request Manager offers the request to each queue manager in the order in which they are defined in the Arbortext Publishing Engine configuration file. When a queue manager accepts the request, Arbortext PE Request Manager stops and takes the HTTP response from the Queue Manager and passes it to the client.

The Arbortext Publishing Engine Queue is a container of ordered transactions that are awaiting execution. Transactions are placed on a queue by an Arbortext Publishing Engine Queue Manager. The Queue Manager offers the request to each queue in the order in which they are defined in the Arbortext Publishing Engine configuration file. When a queue accepts the request, it holds it until the Queued Transaction Scheduler selects it for processing. After completion, a queued transaction is deleted from its queue.

A notifier is called by the Arbortext PE Request Manager each time a transaction changes from one state to another. A notifier can be implemented and configured to respond to a transaction state change by performing an action, such as send an email.

• Arbortext Publishing Engine Transaction — A transaction is a request and response pair processed by the Arbortext Publishing Engine. The transaction includes the request transmitted to Arbortext PE Request Manager by a client, the response returned, and any intermediate files or logs generated when producing the response. The transaction is created upon receiving the request, and associated files are placed in the active transaction directory to wait for processing. There are two types of transactions:

Arbortext Publishing Engine transmits the response to the waiting client immediately after processing is complete. The immediate transaction will then be deleted from the active transaction directory. You can configure an immediate transaction to be archived in the Transaction Archive directory afterward.

Arbortext Publishing Engine places a transaction on a queue (provided the request meets queuing criteria) until it can be processed. After the transaction is processed, the client can retrieve the resulting output from the active transaction directory using the transaction ID. The transaction will be deleted from the active transaction directory according to the configuration settings for duration and retrieval by the client. You can configure a queued transaction to be archived in the Transaction Archive directory afterward.